diff --git a/pkg/grpc/cli/api.proto b/pkg/grpc/cli/api.proto new file mode 100644 index 000000000..90e080d1e --- /dev/null +++ b/pkg/grpc/cli/api.proto @@ -0,0 +1,124 @@ +syntax = "proto3"; + +package pomerium.cli; +option go_package = "github.com/pomerium/pomerium/pkg/grpc/cli"; + +service Config { + rpc List(Selector) returns (ListRecordsResponse); + rpc Delete(Selector) returns (DeleteRecordsResponse); + rpc Upsert(Record) returns (Record); + rpc Export(ExportRequest) returns (ConfigData); + rpc Import(ImportRequest) returns (ImportResponse); +} + +message Record { + // if omitted, a new record would be created + optional string id = 1; + repeated string tags = 2; + // connection data may be omitted if i.e. just manipulating the tags data + optional Connection conn = 3; +} + +message Selector { + message IdFilter { repeated string ids = 1; } + message TagFilter { repeated string tags = 2; } + + oneof filter { + // all records + bool all = 1; + // only return connections matching tag(s) + TagFilter tag = 2; + // only return specific connection(s) + IdFilter id_filter = 3; + } +} +message ListRecordsResponse { repeated Record records = 1; } +message DeleteRecordsResponse {} + +// Export dumps configuration (or subset of, based on provided tag filter) +// in the JSON format +message ExportRequest { + Selector selector = 1; + // remove_tags to strip tags from output + bool remove_tags = 2; + enum Format { + EXPORT_FORMAT_UNDEFINED = 0; + EXPORT_FORMAT_JSON_COMPACT = 1; + EXPORT_FORMAT_JSON_PRETTY = 2; + } + Format format = 3; +} + +message ConfigData { bytes data = 1; } + +// ImportRequest would consume the previously exported data back, +// merging it with existing configuration, +// and performing de-duplication of the records so that multiple imports would +// yield the same result +message ImportRequest { + // if set, all connections would receive that tag instead + optional string override_tag = 1; + bytes data = 2; +} + +message ImportResponse {} + +// Listener service controls listeners +service Listener { + // Listen starts connection listener + rpc Update(ListenerUpdateRequest) returns (ListenerStatus); + // StatusUpdates opens a stream to listen to connection status updates + // a client has to subscribe and continuously + // listen to the broadcasted updates + rpc StatusUpdates(Selector) returns (stream ConnectionStatusUpdates); +} + +message ListenerUpdateRequest { + // omit connection ids to connect all connections + repeated string connection_ids = 1; + bool connected = 2; +} + +message ListenerStatus { + // active listeners with their current ports + map active = 1; + // if some listeners were unable to start up + map errors = 2; +} + +message StatusUpdatesRequest {} + +// ConnectionStatusUpdates represent connection state changes +message ConnectionStatusUpdates { + // record this event relates to + string id = 1; + // peer_addr represents connecting party remote address and may be used to + // distinguish between individual TCP connections + string peer_addr = 2; + enum ConnectionStatus { + CONNECTION_STATUS_UNDEFINED = 0; + CONNECTION_STATUS_CONNECTING = 1; + CONNECTION_STATUS_AUTH_REQUIRED = 2; + CONNECTION_STATUS_CONNECTED = 3; + CONNECTION_STATUS_DISCONNECTED = 4; + } + ConnectionStatus status = 3; + // in case the connection failed or terminated, last error may be available + optional string last_error = 4; +} + +// Connection +message Connection { + // name is a user friendly connection name that a user may define + optional string name = 1; + // remote_addr is a remote pomerium host:port + string remote_addr = 2; + // listen_address, if not provided, will assign a random port each time + optional string listen_addr = 3; + // the URL of the pomerium server to connect to + optional string pomerium_url = 4; + oneof tls_options { + bool disable_tls_verification = 5; + bytes ca_cert = 6; + } +} diff --git a/pkg/grpc/protoc.bash b/pkg/grpc/protoc.bash index 4764ec193..e42ae0e4a 100755 --- a/pkg/grpc/protoc.bash +++ b/pkg/grpc/protoc.bash @@ -112,3 +112,7 @@ _import_paths=$(join_by , "${_imports[@]}") ../../scripts/protoc -I ./events/ -I ./ \ --go_out="$_import_paths,plugins=grpc,paths=source_relative:./events/." \ ./events/xds.proto + +../../scripts/protoc -I ./cli/ -I ./ \ + --go_out="$_import_paths,plugins=grpc,paths=source_relative:./cli/." \ + ./cli/api.proto