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);
}

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;
}

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;
}

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;
}

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;
}

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;
}

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;
}

message PublishResult {
  bytes data = 1;
  string b64data = 2;
  bool skip_history = 3;
}

message PublishResponse {
  PublishResult 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;
}

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;
}

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 {}