routes.proto

syntax = "proto3";

option go_package = "github.com/signadot/routesapi/routesapi-go;routesapi";

package routes;


// The Routes API provides access to in-cluster routing configuration set up by
// the Signadot Operator.
service Routes {
  // GetWorkloadRoutingRules returns a set of WorkloadRoutingRules, keyed by
  // baseline workload and routing key, each of which contains a
  // destinationSandbox and mappings for each port.  Each request query
  // parameter represents a different filter on the set of returned routing
  // rules.
  //
  // In the response, for each returned `WorkloadRoutingRule`, the
  // `destinationSandbox` represents the override destination to which traffic
  // will be routed in the presence of the associated routing key
  // (https://www.signadot.com/docs/context-propagation). Message queue
  // consumers may use this field to discover if a message is intended for
  // their consumption.
  //
  // `mappings` provide the association between baseline workload ports and
  // corresponding TCP addresses belonging to the `destinationSandbox`. The
  // `mappings` are used by the DevMesh sidecar
  // (https://www.signadot.com/docs/request-routing/devmesh) to implement
  // "Destination Routing", and may not be relevant to clients unless they are
  // implementing request routing in the application layer.
  rpc GetWorkloadRoutingRules(WorkloadRoutingRulesRequest) returns (GetWorkloadRoutingRulesResponse) {}

  // WatchWorkloadRoutingRules is a reactive version of GetWorkloadRoutingRules
  // that provides a stream of modifications to the set of WorkloadRoutingRules
  // (keyed by the pair baseline, routingKey), in near real-time.
  rpc WatchWorkloadRoutingRules(WorkloadRoutingRulesRequest) returns (stream WorkloadRoutingRuleOp) {}

  // Returns a list of in-cluster services including headless addressable hosts,
  // providing information about their IP, hostname, and exposed ports
  rpc GetClusterServices(GetClusterServicesRequest) returns (GetClusterServicesResponse) {}
}


// Common
// ----------------------------------------------------------------------------

// A WorkloadRoutingRule defines for a given baseline and a routing key, a single
// `destinationSandbox` and `mappings`. The mappings map each port of the
// baseline workload with corresponding TCP addresses belonging to the
// `destinationSandbox` where traffic is routed instead.
message WorkloadRoutingRule {
  string routing_key = 1;
  // baseline indicates the corresponding baseline workload.
  BaselineWorkload baseline = 2;
  // destination_sandbox indicates the sandbox associated with the destination
  // sandboxed workloads.
  DestinationSandbox destination_sandbox = 3;
  // mappings represents a mapping from a port on the workload to a set of
  // destinations.
  repeated WorkloadPortMapping mappings = 4;
}

// A DestinationSandbox represents a sandbox that will receive traffic intended
// for a baseline workload in the presence of a routing key.
message DestinationSandbox {
  // Sandbox name
  string name = 1;
}

// A BaselineWorkload identifies a given baseline workload. In the context of a
// WorkloadRoutingRuleRequest, all the fields are optional. In the context of a
// response from the server, all the fields are filled in.
message BaselineWorkload {
  string kind = 1;
  string namespace = 2;
  string name = 3;
}

// A WorkloadPortMapping provides a mapping from a port on the workload to a set
// of destinations. Each destination in the response corresponds to a sandbox
// service matching the sandboxed workload. As a result, any of the destinations
// can be used.
message WorkloadPortMapping {
  uint32 workload_port = 1;
  repeated Location destinations = 2;
}

// Location gives a TCP address as a host, port pair.
message Location {
  string host = 1;
  uint32 port = 2;
}

// ClusterServicePort provides information about a service port
message ClusterServicePort {
  string name = 1;
  uint32 port = 2;
  string protocol = 3;
  string app_protocol = 4;
}

message SandboxedClusterService {
  // Routing key of the sandbox who created the service
  string sandbox_routing_key = 1;
  // Hostname of the baseline service
  string baseline_hostname = 2;
}

// ClusterService provides information about a kubernetes service
message ClusterService {
  string service_ip = 1;
  string hostname = 2;
  repeated ClusterServicePort ports = 3;
  // This information is only available for sandboxed services, being empty in
  // any other case
  SandboxedClusterService sandbox_info = 4;
}



// GetWorkloadRoutingRules
// ----------------------------------------------------------------------------

// WorkloadRoutingRulesRequest is a request for a set of WorkloadRoutingRules,
// which give information about how to route requests when they are intercepted
// at a given workload. Each field is optional and constrains the the set of
// WorkloadRoutingRules returned accordingly.
message WorkloadRoutingRulesRequest {
  // baseline_workload specifies the kind, namespace, and name of the baseline
  // workload to which requests are directed. Each field is optional.
  BaselineWorkload baseline_workload = 1;

  // routing_key specifies the routing key associated with the request.
  string routing_key = 2;

  // destination_sandbox specifies the sandbox associated with the destination
  // sandboxed workloads.
  DestinationSandbox destination_sandbox = 3;
}

// a GetWorkloadRoutingRulesResponse gives the set of WorkloadRoutingRules which match a
// given WorkloadRoutingRulesRequest.
message GetWorkloadRoutingRulesResponse {
  repeated WorkloadRoutingRule routingRules = 1;
}


// WatchWorkloadRoutes
// ----------------------------------------------------------------------------


// A WatchOp indicates what operation is to be performed on the set of
// WorkloadRoutingRules specified in a WorkloadRoutingRulesRequest.
enum WatchOp {
  ADD = 0;
  REMOVE = 1;
  REPLACE = 2;
  // In any WatchWorkloadRoutingRules rpc call, the returned stream will send at most
  // 1 SYNCED WatchOp, indicating the client has all the information about
  // Sandboxes and RouteGroups available in the cluster. Prior to sending a
  // SYNCED WatchOp, all WatchOps are ADDs.
  SYNCED = 3;
}

// WorkloadRouteOp describes a diff operation against a set of workload routes:
// adding, removing, and replacing WorkloadRoutes are possible. Additionally,
// there is a SYNCED operation to indicate when the client has received all
// relevant WorkloadRoutes.
message WorkloadRoutingRuleOp {
  WatchOp op = 1;
  WorkloadRoutingRule route = 2;
}


// GetClusterServices
// ----------------------------------------------------------------------------

message GetClusterServicesRequest {
}

message GetClusterServicesResponse {
  repeated ClusterService services = 1;
}