consul/proto/pbpeering/peering.proto

syntax = "proto3";

package peering;

import "google/protobuf/timestamp.proto";
import "google/protobuf/any.proto";
// TODO(peering): Handle this some other way
import "proto/pbstatus/status.proto";

// PeeringService handles operations for establishing peering relationships
// between disparate Consul clusters.
service PeeringService {
  rpc GenerateToken(GenerateTokenRequest) returns (GenerateTokenResponse);
  rpc Establish(EstablishRequest) returns (EstablishResponse);
  rpc PeeringRead(PeeringReadRequest) returns (PeeringReadResponse);
  rpc PeeringList(PeeringListRequest) returns (PeeringListResponse);
  rpc PeeringDelete(PeeringDeleteRequest) returns (PeeringDeleteResponse);

  // TODO(peering): As of writing, this method is only used in tests to set up Peerings in the state store.
  // Consider removing if we can find another way to populate state store in peering_endpoint_test.go
  rpc PeeringWrite(PeeringWriteRequest) returns (PeeringWriteResponse);

  // TODO(peering): Rename this to PeeredServiceRoots? or something like that?
  rpc TrustBundleListByService(TrustBundleListByServiceRequest) returns (TrustBundleListByServiceResponse);

  rpc TrustBundleRead(TrustBundleReadRequest) returns (TrustBundleReadResponse);

  // StreamResources opens an event stream for resources to share between peers, such as services.
  // Events are streamed as they happen.
  // buf:lint:ignore RPC_REQUEST_STANDARD_NAME
  // buf:lint:ignore RPC_RESPONSE_STANDARD_NAME
  // buf:lint:ignore RPC_REQUEST_RESPONSE_UNIQUE
  rpc StreamResources(stream ReplicationMessage) returns (stream ReplicationMessage);
}

// PeeringState enumerates all the states a peering can be in
enum PeeringState {
  // Undefined represents an unset value for PeeringState during
  // writes.
  UNDEFINED = 0;

  // Initial means a Peering has been initialized and is awaiting
  // acknowledgement from a remote peer.
  INITIAL = 1;

  // Active means that the peering connection is active and healthy.
  ACTIVE = 2;

  // Failing means the peering connection has been interrupted but has not yet
  // been terminated.
  FAILING = 3;

  // Terminated means the peering relationship has been removed.
  TERMINATED = 4;
}

// Peering defines a peering relationship between two disparate Consul clusters
//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.Peering
// output=peering.gen.go
// name=API
message Peering {
  // ID is a datacenter-scoped UUID for the peering.
  // The ID is generated when a peering is first written to the state store.
  string ID = 1;

  // Name is the local alias for the peering relationship.
  string Name = 2;

  // Partition is the local partition connecting to the peer.
  string Partition = 3;

  // DeletedAt is the time when the Peering was marked for deletion
  // This is nullable so that we can omit if empty when encoding in JSON
  // mog: func-to=TimePtrFromProto func-from=TimePtrToProto
  google.protobuf.Timestamp DeletedAt = 4;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 5;

  // State is one of the valid PeeringState values to represent the status of
  // peering relationship.
  //
  // mog: func-to=PeeringStateToAPI func-from=PeeringStateFromAPI
  PeeringState State = 6;

  // PeerID is the ID that our peer assigned to this peering.
  // This ID is to be used when dialing the peer, so that it can know who dialed it.
  string PeerID = 7;

  // PeerCAPems contains all the CA certificates for the remote peer.
  repeated string PeerCAPems = 8;

  // PeerServerName is the name of the remote server as it relates to TLS.
  string PeerServerName = 9;

  // PeerServerAddresses contains all the the connection addresses for the remote peer.
  repeated string PeerServerAddresses = 10;

  // CreateIndex is the Raft index at which the Peering was created.
  uint64 CreateIndex = 11;

  // ModifyIndex is the latest Raft index at which the Peering. was modified.
  uint64 ModifyIndex = 12;
}

// PeeringTrustBundle holds the trust information for validating requests from a peer.
message PeeringTrustBundle {
  // TrustDomain is the domain for the bundle, example.com, foo.bar.gov for example. Note that this must not have a prefix such as "spiffe://".
  string TrustDomain = 1;

  // PeerName associates the trust bundle with a peer.
  string PeerName = 2;

  // Partition isolates the bundle from other trust bundles in separate local partitions.
  string Partition = 3;

  // RootPEMs holds ASN.1 DER encoded X.509 certificate data for the trust bundle.
  repeated string RootPEMs = 4;

  // ExportedPartition references the remote partition of the peer
  // which sent this trust bundle. Used for generating SpiffeIDs.
  string ExportedPartition = 5;

  // CreateIndex is the Raft index at which the trust domain was created.
  uint64 CreateIndex = 6;

  // ModifyIndex is the latest Raft index at which the trust bundle was modified.
  uint64 ModifyIndex = 7;
}

// @consul-rpc-glue: Datacenter,ReadTODO
message PeeringReadRequest {
  string Name = 1;
  string Partition = 2;

  string Datacenter = 3;

//TODO(peering) query metadata
}

message PeeringReadResponse {
  Peering Peering = 1;

//TODO(peering) query metadata
}

// @consul-rpc-glue: Datacenter,ReadTODO
message PeeringListRequest {
  string Partition = 1;

  string Datacenter = 2;

//TODO(peering) query metadata
}

message PeeringListResponse {
  repeated Peering Peerings = 1;

//TODO(peering) query metadata
}

// @consul-rpc-glue: Datacenter,WriteTODO
message PeeringWriteRequest {
  Peering Peering = 1;

  //TODO(peering): what to do with embedded write request?
  string Datacenter = 2;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 3;
}

// TODO(peering): Consider returning Peering if we keep this endpoint around
message PeeringWriteResponse {}

// @consul-rpc-glue: Datacenter,WriteTODO
message PeeringDeleteRequest {
  string Name = 1;

  string Partition = 2;

  //TODO(peering): what to do with embedded write request?
  string Datacenter = 3;
}

message PeeringDeleteResponse {}

// @consul-rpc-glue: Datacenter,ReadTODO
message TrustBundleListByServiceRequest {
  string ServiceName = 1;
  string Namespace = 2;
  string Partition = 3;

  // these are common fields required for implementing structs.RPCInfo methods
  // that are used to forward requests
  string Datacenter = 4;
}

message TrustBundleListByServiceResponse {
  uint64 Index = 1;
  repeated PeeringTrustBundle Bundles = 2;
}

// @consul-rpc-glue: Datacenter,ReadTODO
message TrustBundleReadRequest {
  string Name = 1;
  string Partition = 2;

  // these are common fields required for implementing structs.RPCInfo methods
  // that are used to forward requests
  string Datacenter = 3;
}

message TrustBundleReadResponse {
  uint64 Index = 1;
  PeeringTrustBundle Bundle = 2;
}

message PeeringTerminateByIDRequest {
  string ID = 1;
}

message PeeringTerminateByIDResponse {}

// @consul-rpc-glue: Datacenter
message PeeringTrustBundleWriteRequest {
  PeeringTrustBundle PeeringTrustBundle = 1;

  //TODO(peering): what to do with embedded write request?
  string Datacenter = 2;
}

message PeeringTrustBundleWriteResponse {}

// @consul-rpc-glue: Datacenter
message PeeringTrustBundleDeleteRequest {
  string Name = 1;

  string Partition = 2;

  //TODO(peering): what to do with embedded write request?
  string Datacenter = 3;
}

message PeeringTrustBundleDeleteResponse {}

// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringGenerateTokenRequest
// output=peering.gen.go
// name=API
message GenerateTokenRequest {
  // Name of the remote peer.
  string PeerName = 1;

  // Partition is the local partition being peered.
  string Partition = 2;

  // these are common fields required for implementing structs.RPCInfo methods
  // that are used to forward requests
  string Datacenter = 3;
  string Token = 4;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 5;
}

// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringGenerateTokenResponse
// output=peering.gen.go
// name=API
message GenerateTokenResponse {
  // PeeringToken is an opaque string provided to the remote peer for it to complete
  // the peering initialization handshake.
  string PeeringToken = 1;
}

// @consul-rpc-glue: Datacenter
//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringEstablishRequest
// output=peering.gen.go
// name=API
message EstablishRequest {
  // Name of the remote peer.
  string PeerName = 1;

  // The peering token returned from the peer's GenerateToken endpoint.
  string PeeringToken = 2;

  // Partition is the local partition being peered.
  string Partition = 3;

  // these are common fields required for implementing structs.RPCInfo methods
  // that are used to forward requests
  string Datacenter = 4;
  string Token = 5;

  // Meta is a mapping of some string value to any other string value
  map<string, string> Meta = 6;
}

//
// mog annotation:
//
// target=github.com/hashicorp/consul/api.PeeringEstablishResponse
// output=peering.gen.go
// name=API
message EstablishResponse {}

message ReplicationMessage {
  oneof Payload {
    Request request = 1;
    Response response = 2;
    Terminated terminated = 3;
  }

  // A Request requests to subscribe to a resource of a given type.
  message Request {
    // An identifier for the peer making the request.
    // This identifier is provisioned by the serving peer prior to the request from the dialing peer.
    string PeerID = 1;

    // Nonce corresponding to that of the response being ACKed or NACKed.
    // Initial subscription requests will have an empty nonce.
    // The nonce is generated and incremented by the exporting peer.
    string Nonce = 2;

    // The type URL for the resource being requested or ACK/NACKed.
    string ResourceURL = 3;

    // The error if the previous response was not applied successfully.
    // This field is empty in the first subscription request.
    status.Status Error = 4;
  }

  // A Response contains resources corresponding to a subscription request.
  message Response {
    // Nonce identifying a response in a stream.
    string Nonce = 1;

    // The type URL of resource being returned.
    string ResourceURL = 2;

    // An identifier for the resource being returned.
    // This could be the SPIFFE ID of the service.
    string ResourceID = 3;

    // The resource being returned.
    google.protobuf.Any Resource = 4;

    // Operation enumerates supported operations for replicated resources.
    enum Operation {
      Unknown = 0;

      // UPSERT represents a create or update event.
      UPSERT = 1;

      // DELETE indicates the resource should be deleted.
      // In DELETE operations no Resource will be returned.
      // Deletion by an importing peer must be done with the type URL and ID.
      DELETE = 2;
    }

    // REQUIRED. The operation to be performed in relation to the resource.
    Operation operation = 5;
  }

  // Terminated is sent when a peering is deleted locally.
  // This message signals to the peer that they should clean up their local state about the peering.
  message Terminated {}
}

// LeaderAddress is sent when the peering service runs on a consul node
// that is not a leader. The node either lost leadership, or never was a leader.
message LeaderAddress {
  // address is an ip:port best effort hint at what could be the cluster leader's address
  string address = 1;
}