client.proto

syntax = "proto3";

package centrifugal.centrifuge.protocol;

option go_package = "./;protocol";

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

message EmulationRequest {
  string node = 1;
  string session = 2;
  bytes data = 3;
}

// Command sent from a client to a server.
// ProtocolVersion2 uses id and one of the possible request messages.
message Command {
  // Id of command to let client match replies to commands.
  uint32 id = 1;

  reserved 2, 3;

  // ProtocolVersion2 client can send one of the following requests. Server will
  // only take the first non-null request out of these and may return an error if
  // client passed more than one request. We are not using oneof here due to JSON
  // interoperability concerns.
  ConnectRequest connect = 4;
  SubscribeRequest subscribe = 5;
  UnsubscribeRequest unsubscribe = 6;
  PublishRequest publish = 7;
  PresenceRequest presence = 8;
  PresenceStatsRequest presence_stats = 9;
  HistoryRequest history = 10;
  PingRequest ping = 11;
  SendRequest send = 12;
  RPCRequest rpc = 13;
  RefreshRequest refresh = 14;
  SubRefreshRequest sub_refresh = 15;
}

// Reply sent from a server to a client.
// ProtocolVersion2 uses id and one of the possible concrete result messages.
message Reply {
  // Id will only be set to a value > 0 for replies to commands. For pushes
  // it will have zero value.
  uint32 id = 1;
  // Error can only be set in replies to commands. For pushes it will have zero value.
  Error error = 2;

  reserved 3;

  // ProtocolVersion2 server can send one of the following fields. We are not using
  // oneof here due to JSON interoperability concerns.
  Push push = 4;
  ConnectResult connect = 5;
  SubscribeResult subscribe = 6;
  UnsubscribeResult unsubscribe = 7;
  PublishResult publish = 8;
  PresenceResult presence = 9;
  PresenceStatsResult presence_stats = 10;
  HistoryResult history = 11;
  PingResult ping = 12;
  RPCResult rpc = 13;
  RefreshResult refresh = 14;
  SubRefreshResult sub_refresh = 15;
}

// Push can be sent to a client as part of Reply in case of bidirectional transport or
// without additional wrapping in case of unidirectional transports.
// ProtocolVersion2 uses channel and one of the possible concrete push messages.
message Push {
  reserved 1, 3;
  string channel = 2;

  // ProtocolVersion2 server can push one of the following fields to the client. We are
  // not using oneof here due to JSON interoperability concerns.
  Publication pub = 4;
  Join join = 5;
  Leave leave = 6;
  Unsubscribe unsubscribe = 7;
  Message message = 8;
  Subscribe subscribe = 9;
  Connect connect = 10;
  Disconnect disconnect = 11;
  Refresh refresh = 12;
}

message ClientInfo {
  string user = 1;
  string client = 2;
  bytes conn_info = 3;
  bytes chan_info = 4;
}

message Publication {
  reserved 1, 2, 3;
  bytes data = 4;
  ClientInfo info = 5;
  uint64 offset = 6;
  map<string, string> tags = 7;
  bool delta = 8;  // When set indicates that data in Publication is a delta from previous data.
  int64 time = 9;  // Optional time of publication as Unix timestamp milliseconds.
  string channel = 10; // Optional channel name if Publication relates to wildcard subscription.
}

message Join {
  ClientInfo info = 1;
}

message Leave {
  ClientInfo info = 1;
}

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

message Subscribe {
  bool recoverable = 1;
  reserved 2, 3;
  string epoch = 4;
  uint64 offset = 5;
  bool positioned = 6;
  bytes data = 7;
}

message Message {
  bytes data = 1;
}

message Connect {
  string client = 1;
  string version = 2;
  bytes data = 3;
  map<string, SubscribeResult> subs = 4;
  bool expires = 5;
  uint32 ttl = 6;
  uint32 ping = 7;
  bool pong = 8;
  string session = 9;
  string node = 10;
  int64 time = 11; // Server time as Unix timestamp in milliseconds (not sent by default).
}

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

message Refresh {
  bool expires = 1;
  uint32 ttl = 2;
}

message ConnectRequest {
  string token = 1;
  bytes data = 2;
  map<string, SubscribeRequest> subs = 3;
  string name = 4;
  string version = 5;
  map<string, string> headers = 6;
}

message ConnectResult {
  string client = 1;
  string version = 2;
  bool expires = 3;
  uint32 ttl = 4;
  bytes data = 5;
  map<string, SubscribeResult> subs = 6;
  uint32 ping = 7;
  bool pong = 8;
  string session = 9;
  string node = 10;
  int64 time = 11; // Server time as Unix timestamp in milliseconds (not sent by default).
}

message RefreshRequest {
  string token = 1;
}

message RefreshResult {
  string client = 1;
  string version = 2;
  bool expires = 3;
  uint32 ttl = 4;
}

message SubscribeRequest {
  string channel = 1;
  string token = 2;
  bool recover = 3;
  reserved 4, 5;
  string epoch = 6;
  uint64 offset = 7;
  bytes data = 8;
  bool positioned = 9;
  bool recoverable = 10;
  bool join_leave = 11;
  string delta = 12;
}

message SubscribeResult {
  bool expires = 1;
  uint32 ttl = 2;
  bool recoverable = 3;
  reserved 4, 5;
  string epoch = 6;
  repeated Publication publications = 7;
  bool recovered = 8;
  uint64 offset = 9;
  bool positioned = 10;
  bytes data = 11;
  bool was_recovering = 12;
  bool delta = 13;
}

message SubRefreshRequest {
  string channel = 1;
  string token = 2;
}

message SubRefreshResult {
  bool expires = 1;
  uint32 ttl = 2;
}

message UnsubscribeRequest {
  string channel = 1;
}

message UnsubscribeResult {}

message PublishRequest {
  string channel = 1;
  bytes data = 2;
}

message PublishResult {}

message PresenceRequest {
  string channel = 1;
}

message PresenceResult {
  map<string, ClientInfo> presence = 1;
}

message PresenceStatsRequest {
  string channel = 1;
}

message PresenceStatsResult {
  uint32 num_clients = 1;
  uint32 num_users = 2;
}

message StreamPosition {
  uint64 offset = 1;
  string epoch = 2;
}

message HistoryRequest {
  string channel = 1;
  reserved 2, 3, 4, 5, 6;
  int32 limit = 7;
  StreamPosition since = 8;
  bool reverse = 9;
}

message HistoryResult {
  repeated Publication publications = 1;
  string epoch = 2;
  uint64 offset = 3;
}

message PingRequest {}

message PingResult {}

message RPCRequest{
  bytes data = 1;
  string method = 2;
}

message RPCResult {
  bytes data = 1 ;
}

message SendRequest{
  bytes data = 1;
}