upstream-centrifugo/internal/proxyproto/proxy.proto

syntax = "proto3";

package centrifugal.centrifugo.proxy;

option go_package = "./;proxyproto";

service CentrifugoProxy {
  // Connect to proxy connection authentication and communicate initial state.
  rpc Connect(ConnectRequest) returns (ConnectResponse);
  // Refresh to proxy decision about connection expiration to the app backend.
  rpc Refresh(RefreshRequest) returns (RefreshResponse);
  // Subscribe to proxy subscription attempts to channels.
  rpc Subscribe(SubscribeRequest) returns (SubscribeResponse);
  // Publish to proxy publication attempts to channels.
  rpc Publish(PublishRequest) returns (PublishResponse);
  // RPC to execute custom logic on the backend over request through the real-time connection.
  rpc RPC(RPCRequest) returns (RPCResponse);
  // SubRefresh to proxy decision about subscription expiration to the app backend.
  rpc SubRefresh(SubRefreshRequest) returns (SubRefreshResponse);
  // SubscribeUnidirectional is an EXPERIMENTAL method which allows handling unidirectional
  // subscription streams. Stream starts with SubscribeRequest similar to Subscribe rpc,
  // then expects StreamSubscribeResponse with SubscribeResponse as first message, and
  // StreamSubscribeResponse with Publication afterwards.
  rpc SubscribeUnidirectional(SubscribeRequest) returns (stream StreamSubscribeResponse);
  // SubscribeBidirectional is an EXPERIMENTAL method which allows handling bidirectional
  // subscription streams. Stream receives StreamSubscribeRequest. First StreamSubscribeRequest
  // always contains SubscribeRequest, then StreamSubscribeRequest will contain data published
  // by client. Reverse direction works the same way as in SubscribeUnidirectional.
  rpc SubscribeBidirectional(stream StreamSubscribeRequest) returns (stream StreamSubscribeResponse);
  // NotifyCacheEmpty is an EXPERIMENTAL method which allows to load documents from the backend.
  rpc NotifyCacheEmpty(NotifyCacheEmptyRequest) returns (NotifyCacheEmptyResponse);
  // NotifyChannelState can be used to receive channel events such as channel "occupied" and "vacated".
  // This is a feature in a preview state and is only available in Centrifugo PRO.
  rpc NotifyChannelState(NotifyChannelStateRequest) returns (NotifyChannelStateResponse);
  // MapPublish to proxy map publish attempts to channels.
  rpc MapPublish(MapPublishRequest) returns (MapPublishResponse);
  // MapRemove to proxy map remove attempts from channels.
  rpc MapRemove(MapRemoveRequest) returns (MapRemoveResponse);
  // SharedPollRefresh to proxy shared poll refresh requests to the app backend.
  rpc SharedPollRefresh(SharedPollRefreshRequest) returns (SharedPollRefreshResponse);
}

message FilterNode {
  string op = 1;
  string key = 2;
  string cmp = 3;
  string val = 4;
  repeated string vals = 5;
  repeated FilterNode nodes = 6;
}

message Disconnect {
  reserved 3;
  uint32 code = 1;
  string reason = 2;
}

message Error {
  uint32 code = 1;
  string message = 2;
  bool temporary = 3;
}

message ConnectRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  bytes data = 10;
  string b64data = 11;
  string name = 12;
  string version = 13;
  repeated string channels = 14;
}

message SubscribeOptions {
  int64 expire_at = 1;
  bytes info = 2;
  string b64info = 3;
  bytes data = 4;
  string b64data = 5;
  SubscribeOptionOverride override = 6;
  FilterNode server_tags_filter = 7;
  // cache_recover, when set, makes Centrifugo initiate cache recovery for the
  // server-side subscription without requiring the client to provide a recover
  // flag/position itself. This is the server-side equivalent of subscribing with an
  // empty `since` on the client. Mostly useful for unidirectional clients which do
  // not know channel names. Requires recovery to be enabled for the channel and only
  // applies in cache recovery mode, where it delivers the latest publication on
  // (re)subscribe.
  bool cache_recover = 8;
}

message ConnectResult {
  string user = 1;
  int64 expire_at = 2;
  bytes info = 3;
  string b64info = 4;
  bytes data = 5;
  string b64data = 6;
  repeated string channels = 7;
  map<string, SubscribeOptions> subs = 8;
  bytes meta = 9;
  repeated ChannelsCapability caps = 10;
  // PRO only — client labels attached to the centrifuge.Client by Centrifugo PRO.
  // Parsed by OSS but not used (OSS does not populate centrifuge.ConnectReply.Labels).
  map<string, string> labels = 11;
}

message ChannelsCapability {
  repeated string channels = 1;
  repeated string allow = 2;
  string match = 3;
}

message ConnectResponse {
  ConnectResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message RefreshRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  bytes meta = 11;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 12;
}

message RefreshResult {
  bool expired = 1;
  int64 expire_at = 2;
  bytes info = 3;
  string b64info = 4;
  bytes meta = 5;
  repeated ChannelsCapability caps = 6;
}

message RefreshResponse {
  RefreshResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message SubscribeRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string channel = 11;
  string token = 12;
  bytes meta = 13;
  bytes data = 14;
  string b64data = 15;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 16;
}

message BoolValue {
  bool value = 1;
}

message Int32Value {
  int32 value = 1;
}

message SubscribeOptionOverride {
  BoolValue presence = 1;
  BoolValue join_leave = 2;
  BoolValue force_recovery = 3;
  BoolValue force_positioning = 4;
  BoolValue force_push_join_leave = 5;
}

message SubscribeResult {
  int64 expire_at = 1;
  bytes info = 2;
  string b64info = 3;
  bytes data = 4;
  string b64data = 5;
  SubscribeOptionOverride override = 6;
  repeated string allow = 7;
  FilterNode server_tags_filter = 8;
}

message SubscribeResponse {
  SubscribeResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message PublishRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string channel = 11;
  bytes data = 12;
  string b64data = 13;
  bytes meta = 14;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 15;
}

message PublishResult {
  bytes data = 1;
  string b64data = 2;
  bool skip_history = 3;
  map<string, string> tags = 4;
  string idempotency_key = 5;
  bool delta = 6;
  uint64 version = 7;
  string version_epoch = 8;
}

message PublishResponse {
  PublishResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message MapPublishRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string channel = 11;
  string key = 12;
  bytes data = 13;
  string b64data = 14;
  bytes meta = 15;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 16;
}

message MapPublishResult {
  string key = 1;
  bytes data = 2;
  string b64data = 3;
  map<string, string> tags = 4;
  int64 score = 5;
  string key_mode = 6;
  bytes stream_data = 7;
  string b64stream_data = 8;
  string idempotency_key = 9;
  bool delta = 10;
  uint64 version = 11;
  string version_epoch = 12;
}

message MapPublishResponse {
  MapPublishResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message MapRemoveRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string channel = 11;
  string key = 12;
  bytes meta = 13;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 14;
}

message MapRemoveResult {
  string key = 1;
  map<string, string> tags = 2;
  string idempotency_key = 3;
}

message MapRemoveResponse {
  MapRemoveResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message RPCRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string method = 11;
  bytes data = 12;
  string b64data = 13;
  bytes meta = 14;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 15;
}

message RPCResult {
  bytes data = 1;
  string b64data = 2;
}

message RPCResponse {
  RPCResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

message SubRefreshRequest {
  string client = 1;
  string transport = 2;
  string protocol = 3;
  string encoding = 4;

  string user = 10;
  string channel = 11;
  bytes meta = 12;
  // PRO only — connection labels attached to the originating centrifuge.Client.
  // Centrifugo PRO always populates this from Client.Labels() (no opt-in toggle).
  map<string, string> labels = 13;
}

message SubRefreshResult {
  bool expired = 1;
  int64 expire_at = 2;
  bytes info = 3;
  string b64info = 4;
}

message SubRefreshResponse {
  SubRefreshResult result = 1;
  Error error = 2;
  Disconnect disconnect = 3;
}

// Publication is an event to be sent to a client.
// We intentionally make it use the same Protobuf numbers for fields as our client protocol
// Publication - for now only for consistency.
message Publication {
  reserved 1, 2, 3, 5, 6;
  bytes data = 4;
  map<string, string> tags = 7;
}

message StreamSubscribeRequest {
  // Centrifugo always sends this within the first message upon user subscription request.
  // It's always not set in the following StreamRequest messages from Centrifugo.
  SubscribeRequest subscribe_request = 1;
  // Publication may be set when client publishes to the on-demand stream. If you are using
  // bidirectional stream then Centrifugo assumes publications from client-side are allowed.
  Publication publication = 2;
}

message StreamSubscribeResponse {
  // SubscribeResponse may optionally be set in the first message from backend to Centrifugo.
  SubscribeResponse subscribe_response = 1;
  // Publication goes to client. Can't be set in the first message from backend to Centrifugo.
  Publication publication = 2;
}

message NotifyCacheEmptyRequest {
  string channel = 1;
}

message NotifyCacheEmptyResponse {
  NotifyCacheEmptyResult result = 1;
}

message NotifyCacheEmptyResult {
  bool populated = 1;
}

message NotifyChannelStateRequest {
  repeated ChannelEvent events = 1;
}

message ChannelEvent {
  int64 time_ms = 1;
  string channel = 2;
  string type = 3;  // "occupied" | "vacated" | could be more in the future. Not using enums for better JSON interop.
}

message NotifyChannelStateResponse {
  NotifyChannelStateResult result = 1;
  Error error = 2;
}

message NotifyChannelStateResult {}

message SharedPollRefreshRequest {
  string channel = 1;
  repeated SharedPollRefreshItem items = 2;
}

message SharedPollRefreshItem {
  string key = 1;
  uint64 version = 2;
}

message SharedPollRefreshResult {
  repeated SharedPollRefreshResultItem items = 1;
  string epoch = 2;
}

message SharedPollRefreshResultItem {
  string key = 1;
  bytes data = 2;
  uint64 version = 3;
  bool removed = 4;
  bytes prev_data = 5;
}

message SharedPollRefreshResponse {
  SharedPollRefreshResult result = 1;
  Error error = 2;
}