api.proto

syntax = "proto3";

package centrifugal.centrifugo.api;

option go_package = "./;apiproto";

// CentrifugoApi is the Centrifugo server API. HTTP and GRPC API share this
// schema. API-level errors are returned in the error field of each response,
// not as transport errors (unless transport error mode is enabled).
service CentrifugoApi {
    rpc Batch(BatchRequest) returns (BatchResponse) {}
    rpc Publish (PublishRequest) returns (PublishResponse) {}
    rpc Broadcast (BroadcastRequest) returns (BroadcastResponse) {}
    rpc Subscribe (SubscribeRequest) returns (SubscribeResponse) {}
    rpc Unsubscribe (UnsubscribeRequest) returns (UnsubscribeResponse) {}
    rpc Disconnect (DisconnectRequest) returns (DisconnectResponse) {}
    rpc Presence (PresenceRequest) returns (PresenceResponse) {}
    rpc PresenceStats (PresenceStatsRequest) returns (PresenceStatsResponse) {}
    rpc History (HistoryRequest) returns (HistoryResponse) {}
    rpc HistoryRemove (HistoryRemoveRequest) returns (HistoryRemoveResponse) {}
    rpc Info (InfoRequest) returns (InfoResponse) {}
    rpc RPC (RPCRequest) returns (RPCResponse) {}
    rpc Refresh (RefreshRequest) returns (RefreshResponse) {}
    rpc Channels (ChannelsRequest) returns (ChannelsResponse) {}
    rpc Connections (ConnectionsRequest) returns (ConnectionsResponse) {}
    rpc UpdateUserStatus (UpdateUserStatusRequest) returns (UpdateUserStatusResponse) {}
    rpc GetUserStatus (GetUserStatusRequest) returns (GetUserStatusResponse) {}
    rpc DeleteUserStatus (DeleteUserStatusRequest) returns (DeleteUserStatusResponse) {}
    rpc BlockUser (BlockUserRequest) returns (BlockUserResponse) {}
    rpc UnblockUser (UnblockUserRequest) returns (UnblockUserResponse) {}
    rpc RevokeToken (RevokeTokenRequest) returns (RevokeTokenResponse) {}
    rpc InvalidateUserTokens (InvalidateUserTokensRequest) returns (InvalidateUserTokensResponse) {}
    rpc DeviceRegister (DeviceRegisterRequest) returns (DeviceRegisterResponse) {}
    rpc DeviceUpdate (DeviceUpdateRequest) returns (DeviceUpdateResponse) {}
    rpc DeviceRemove (DeviceRemoveRequest) returns (DeviceRemoveResponse) {}
    rpc DeviceList (DeviceListRequest) returns (DeviceListResponse) {}
    rpc DeviceTopicList (DeviceTopicListRequest) returns (DeviceTopicListResponse) {}
    rpc DeviceTopicUpdate (DeviceTopicUpdateRequest) returns (DeviceTopicUpdateResponse) {}
    rpc UserTopicList (UserTopicListRequest) returns (UserTopicListResponse) {}
    rpc UserTopicUpdate (UserTopicUpdateRequest) returns (UserTopicUpdateResponse) {}
    rpc SendPushNotification (SendPushNotificationRequest) returns (SendPushNotificationResponse) {}
    rpc UpdatePushStatus (UpdatePushStatusRequest) returns (UpdatePushStatusResponse) {}
    rpc CancelPush (CancelPushRequest) returns (CancelPushResponse) {}
    rpc MapPublish (MapPublishRequest) returns (MapPublishResponse) {}
    rpc MapRemove (MapRemoveRequest) returns (MapRemoveResponse) {}
    rpc MapReadState (MapReadStateRequest) returns (MapReadStateResponse) {}
    rpc MapReadStream (MapReadStreamRequest) returns (MapReadStreamResponse) {}
    rpc MapStats (MapStatsRequest) returns (MapStatsResponse) {}
    rpc MapClear (MapClearRequest) returns (MapClearResponse) {}
    rpc SharedPollPublish (SharedPollPublishRequest) returns (SharedPollPublishResponse) {}
}

// Command is a single command inside a BatchRequest. Set exactly one of its
// request fields; a command with none of them set gets a not found error.
message Command {
    reserved 1,2,3;

    // publish is a publish command, see PublishRequest.
    PublishRequest publish = 4;
    // broadcast is a broadcast command, see BroadcastRequest.
    BroadcastRequest broadcast = 5;
    // subscribe is a subscribe command, see SubscribeRequest.
    SubscribeRequest subscribe = 6;
    // unsubscribe is an unsubscribe command, see UnsubscribeRequest.
    UnsubscribeRequest unsubscribe = 7;
    // disconnect is a disconnect command, see DisconnectRequest.
    DisconnectRequest disconnect = 8;
    // presence is a presence command, see PresenceRequest.
    PresenceRequest presence = 9;
    // presence_stats is a presence stats command, see PresenceStatsRequest.
    PresenceStatsRequest presence_stats = 10;
    // history is a history command, see HistoryRequest.
    HistoryRequest history = 11;
    // history_remove is a history remove command, see HistoryRemoveRequest.
    HistoryRemoveRequest history_remove = 12;
    // info is an info command, see InfoRequest.
    InfoRequest info = 13;
    // rpc is an RPC command, see RPCRequest.
    RPCRequest rpc = 14;
    // refresh is a refresh command, see RefreshRequest.
    RefreshRequest refresh = 15;
    // channels is a channels command, see ChannelsRequest.
    ChannelsRequest channels = 16;
    // connections is a connections command, see ConnectionsRequest.
    // Centrifugo PRO only.
    ConnectionsRequest connections = 17;
    // update_user_status is an update user status command, see
    // UpdateUserStatusRequest. Centrifugo PRO only.
    UpdateUserStatusRequest update_user_status = 18;
    // get_user_status is a get user status command, see GetUserStatusRequest.
    // Centrifugo PRO only.
    GetUserStatusRequest get_user_status = 19;
    // delete_user_status is a delete user status command, see
    // DeleteUserStatusRequest. Centrifugo PRO only.
    DeleteUserStatusRequest delete_user_status = 20;
    // block_user is a block user command, see BlockUserRequest.
    // Centrifugo PRO only.
    BlockUserRequest block_user = 21;
    // unblock_user is an unblock user command, see UnblockUserRequest.
    // Centrifugo PRO only.
    UnblockUserRequest unblock_user = 22;
    // revoke_token is a revoke token command, see RevokeTokenRequest.
    // Centrifugo PRO only.
    RevokeTokenRequest revoke_token = 23;
    // invalidate_user_tokens is an invalidate user tokens command, see
    // InvalidateUserTokensRequest. Centrifugo PRO only.
    InvalidateUserTokensRequest invalidate_user_tokens = 24;
    // device_register is a device register command, see
    // DeviceRegisterRequest. Centrifugo PRO only.
    DeviceRegisterRequest device_register = 25;
    // device_update is a device update command, see DeviceUpdateRequest.
    // Centrifugo PRO only.
    DeviceUpdateRequest device_update = 26;
    // device_remove is a device remove command, see DeviceRemoveRequest.
    // Centrifugo PRO only.
    DeviceRemoveRequest device_remove = 27;
    // device_list is a device list command, see DeviceListRequest.
    // Centrifugo PRO only.
    DeviceListRequest device_list = 28;
    // device_topic_list is a device topic list command, see
    // DeviceTopicListRequest. Centrifugo PRO only.
    DeviceTopicListRequest device_topic_list = 29;
    // device_topic_update is a device topic update command, see
    // DeviceTopicUpdateRequest. Centrifugo PRO only.
    DeviceTopicUpdateRequest device_topic_update = 30;
    // user_topic_list is a user topic list command, see
    // UserTopicListRequest. Centrifugo PRO only.
    UserTopicListRequest user_topic_list = 31;
    // user_topic_update is a user topic update command, see
    // UserTopicUpdateRequest. Centrifugo PRO only.
    UserTopicUpdateRequest user_topic_update = 32;
    // send_push_notification is a send push notification command, see
    // SendPushNotificationRequest. Centrifugo PRO only.
    SendPushNotificationRequest send_push_notification = 33;
    // update_push_status is an update push status command, see
    // UpdatePushStatusRequest. Centrifugo PRO only.
    UpdatePushStatusRequest update_push_status = 34;
    // cancel_push is a cancel push command, see CancelPushRequest.
    // Centrifugo PRO only.
    CancelPushRequest cancel_push = 35;
    // map_publish is a map publish command, see MapPublishRequest.
    MapPublishRequest map_publish = 36;
    // map_remove is a map remove command, see MapRemoveRequest.
    MapRemoveRequest map_remove = 37;
    // map_read_state is a map read state command, see MapReadStateRequest.
    MapReadStateRequest map_read_state = 38;
    // map_read_stream is a map read stream command, see
    // MapReadStreamRequest.
    MapReadStreamRequest map_read_stream = 39;
    // map_stats is a map stats command, see MapStatsRequest.
    MapStatsRequest map_stats = 40;
    // map_clear is a map clear command, see MapClearRequest.
    MapClearRequest map_clear = 41;
    // shared_poll_publish is a shared poll publish command, see
    // SharedPollPublishRequest.
    SharedPollPublishRequest shared_poll_publish = 42;
}

// Error is a Centrifugo API error. It has the same structure in every API
// response.
message Error {
    // code is the Centrifugo error code: 100 (internal error), 102 (unknown
    // channel), 104 (not found), 107 (bad request), 108 (not available),
    // 111 (too many requests), 112 (unrecoverable position) or 113
    // (conflict).
    uint32 code = 1;
    // message is a human-readable description of the error.
    string message = 2;
    // temporary is true when the same request may succeed if retried later:
    // the error came from a temporary condition, such as a broker being
    // unavailable or a rate limit, not from the request itself. It does not
    // mean nothing was done: a publication may have happened despite the
    // error. Retry a publication with the same idempotency_key, so that it
    // is not published twice.
    bool temporary = 3;
}

// Reply is the reply to a single Command of a BatchRequest. It carries
// either error or the result field matching the command.
message Reply {
    reserved 1, 3;

    // error is set if the command failed.
    Error error = 2;

    // publish is the result of a publish command.
    PublishResult publish = 4;
    // broadcast is the result of a broadcast command.
    BroadcastResult broadcast = 5;
    // subscribe is the result of a subscribe command.
    SubscribeResult subscribe = 6;
    // unsubscribe is the result of an unsubscribe command.
    UnsubscribeResult unsubscribe = 7;
    // disconnect is the result of a disconnect command.
    DisconnectResult disconnect = 8;
    // presence is the result of a presence command.
    PresenceResult presence = 9;
    // presence_stats is the result of a presence stats command.
    PresenceStatsResult presence_stats = 10;
    // history is the result of a history command.
    HistoryResult history = 11;
    // history_remove is the result of a history remove command.
    HistoryRemoveResult history_remove = 12;
    // info is the result of an info command.
    InfoResult info = 13;
    // rpc is the result of an RPC command.
    RPCResult rpc = 14;
    // refresh is the result of a refresh command.
    RefreshResult refresh = 15;
    // channels is the result of a channels command.
    ChannelsResult channels = 16;
    // connections is the result of a connections command.
    // Centrifugo PRO only.
    ConnectionsResult connections = 17;
    // update_user_status is the result of an update user status command.
    // Centrifugo PRO only.
    UpdateUserStatusResult update_user_status = 18;
    // get_user_status is the result of a get user status command.
    // Centrifugo PRO only.
    GetUserStatusResult get_user_status = 19;
    // delete_user_status is the result of a delete user status command.
    // Centrifugo PRO only.
    DeleteUserStatusResult delete_user_status = 20;
    // block_user is the result of a block user command.
    // Centrifugo PRO only.
    BlockUserResult block_user = 21;
    // unblock_user is the result of an unblock user command.
    // Centrifugo PRO only.
    UnblockUserResult unblock_user = 22;
    // revoke_token is the result of a revoke token command.
    // Centrifugo PRO only.
    RevokeTokenResult revoke_token = 23;
    // invalidate_user_tokens is the result of an invalidate user tokens
    // command. Centrifugo PRO only.
    InvalidateUserTokensResult invalidate_user_tokens = 24;
    // device_register is the result of a device register command.
    // Centrifugo PRO only.
    DeviceRegisterResult device_register = 25;
    // device_update is the result of a device update command.
    // Centrifugo PRO only.
    DeviceUpdateResult device_update = 26;
    // device_remove is the result of a device remove command.
    // Centrifugo PRO only.
    DeviceRemoveResult device_remove = 27;
    // device_list is the result of a device list command.
    // Centrifugo PRO only.
    DeviceListResult device_list = 28;
    // device_topic_list is the result of a device topic list command.
    // Centrifugo PRO only.
    DeviceTopicListResult device_topic_list = 29;
    // device_topic_update is the result of a device topic update command.
    // Centrifugo PRO only.
    DeviceTopicUpdateResult device_topic_update = 30;
    // user_topic_list is the result of a user topic list command.
    // Centrifugo PRO only.
    UserTopicListResult user_topic_list = 31;
    // user_topic_update is the result of a user topic update command.
    // Centrifugo PRO only.
    UserTopicUpdateResult user_topic_update = 32;
    // send_push_notification is the result of a send push notification
    // command. Centrifugo PRO only.
    SendPushNotificationResult send_push_notification = 33;
    // update_push_status is the result of an update push status command.
    // Centrifugo PRO only.
    UpdatePushStatusResult update_push_status = 34;
    // cancel_push is the result of a cancel push command.
    // Centrifugo PRO only.
    CancelPushResult cancel_push = 35;
    // map_publish is the result of a map publish command.
    MapPublishResult map_publish = 36;
    // map_remove is the result of a map remove command.
    MapRemoveResult map_remove = 37;
    // map_read_state is the result of a map read state command.
    MapReadStateResult map_read_state = 38;
    // map_read_stream is the result of a map read stream command.
    MapReadStreamResult map_read_stream = 39;
    // map_stats is the result of a map stats command.
    MapStatsResult map_stats = 40;
    // map_clear is the result of a map clear command.
    MapClearResult map_clear = 41;
    // shared_poll_publish is the result of a shared poll publish command.
    SharedPollPublishResult shared_poll_publish = 42;
}

// BatchRequest sends many commands in one request, which avoids paying a
// round trip per command. Check the error of each reply individually.
message BatchRequest {
    // commands to execute. Replies come back in the same order.
    repeated Command commands = 1;
    // parallel makes Centrifugo process the commands concurrently instead of
    // one after another. This may reduce latency (especially with the Redis
    // engine), but gives no ordering guarantee between commands.
    bool parallel = 2;
}

// BatchResponse contains the replies to a BatchRequest.
message BatchResponse {
    // replies to the commands, in the order of BatchRequest.commands.
    repeated Reply replies = 1;
}

// PublishRequest publishes data into a channel.
message PublishRequest {
    // channel is the name of the channel to publish into. Required.
    string channel = 1;
    // data is the payload to publish. Required unless b64data is set. In the
    // HTTP API it is any JSON value; over GRPC it may be binary.
    bytes data = 2;
    // b64data is a base64-encoded binary payload, an alternative to `data` to
    // send binary over the HTTP API. Centrifugo decodes it before publishing.
    string b64data = 3;
    // skip_history skips adding this publication to the channel history.
    bool skip_history = 4;
    // tags is a map of arbitrary string keys and values attached to the
    // publication and delivered to clients.
    map<string, string> tags = 5;
    // idempotency_key drops duplicate publications upon retries. It acts per
    // channel; results are cached for 5 minutes. Supported only by Memory and
    // Redis engines.
    string idempotency_key = 6;
    // delta tells Centrifugo to construct a delta update, if possible, when
    // broadcasting the publication to subscribers.
    bool delta = 7;
    // version, when > 0, is the version of the document being sent:
    // publications with a version less than or equal to one already seen are
    // ignored. Only works in channels with history enabled.
    uint64 version = 8;
    // version_epoch is the epoch of version. When it changes, Centrifugo
    // accepts the publication even if its version is lower than before.
    string version_epoch = 9;
}

// PublishResponse is the response to a PublishRequest.
message PublishResponse {
    // error is set if the publish failed.
    Error error = 1;
    // result is set on success.
    PublishResult result = 2;
}

// PublishResult is the result of a successful publish.
message PublishResult {
    // offset is the offset of the publication in the channel history stream.
    uint64 offset = 1;
    // epoch is the epoch of the channel history stream.
    string epoch = 2;
}

// BroadcastRequest publishes the same data into many channels.
message BroadcastRequest {
    // channels is the list of channels to publish into. Required.
    repeated string channels = 1;
    // data is the payload to publish into each channel. Required unless
    // b64data is set. In the HTTP API it is any JSON value; over GRPC it may
    // be binary.
    bytes data = 2;
    // b64data is a base64-encoded binary payload, an alternative to `data` to
    // send binary over the HTTP API. Centrifugo decodes it before publishing.
    string b64data = 3;
    // skip_history skips adding the publications to the channels' history.
    bool skip_history = 4;
    // tags is a map of arbitrary string keys and values attached to each
    // publication and delivered to clients.
    map<string, string> tags = 5;
    // idempotency_key drops duplicate publications upon retries. It acts per
    // channel; results are cached for 5 minutes.
    string idempotency_key = 6;
    // delta tells Centrifugo to construct a delta update, if possible, when
    // broadcasting the publications to subscribers.
    bool delta = 7;
    // version, when > 0, is the version of the document being sent:
    // publications with a version less than or equal to one already seen are
    // ignored. Only works in channels with history enabled.
    uint64 version = 8;
    // version_epoch is the epoch of version. When it changes, Centrifugo
    // accepts the publication even if its version is lower than before.
    string version_epoch = 9;
}

// BroadcastResponse is the response to a BroadcastRequest.
message BroadcastResponse {
    // error is set if the whole broadcast failed.
    Error error = 1;
    // result is set on success. Check the error of each response in it.
    BroadcastResult result = 2;
}

// BroadcastResult is the result of a broadcast.
message BroadcastResult {
    // responses is a publish response for each channel, in the order of
    // BroadcastRequest.channels. Each may carry its own error.
    repeated PublishResponse responses = 1;
}

// FilterNode is a tree describing a predicate over client labels. Used as
// label_filter on Subscribe, Unsubscribe, Disconnect, Refresh and
// Connections requests. A node is either a leaf comparison (key, cmp, val or
// vals) or a logical operation (op) over child nodes.
// Centrifugo PRO only: defined here for protocol-surface consistency,
// Centrifugo OSS parses it but ignores it.
message FilterNode {
    // op is the logical operation of a non-leaf node: "and", "or" or "not".
    // Empty for a leaf node.
    string op = 1;
    // key is the label key a leaf node compares.
    string key = 2;
    // cmp is the comparison of a leaf node: "eq", "neq", "in", "nin", "ex",
    // "nex", "sw", "ew", "ct", "gt", "gte", "lt" or "lte".
    string cmp = 3;
    // val is the value to compare with, for single-value comparisons.
    string val = 4;
    // vals are the values to compare with, for "in" and "nin".
    repeated string vals = 5;
    // nodes are the child nodes of a logical operation.
    repeated FilterNode nodes = 6;
}

// SubscribeRequest subscribes active sessions of a user to a channel
// (server-side subscription). It does not create a streaming subscription
// for the caller.
message SubscribeRequest {
    // channel is the name of the channel to subscribe to. Required.
    string channel = 1;
    // user is the ID of the user to subscribe. Required, unless all_users is
    // used in Centrifugo PRO.
    string user = 2;
    // expire_at is the Unix time in seconds when the subscription expires.
    int64 expire_at = 3;
    // info is custom channel info attached to the subscription, used in
    // presence and join/leave messages.
    bytes info = 4;
    // b64info is info as base64, for binary. Centrifugo decodes it.
    string b64info = 5;
    // client limits the call to the connection with this client ID. user is
    // still required.
    string client = 6;
    // data is custom subscription data sent to the client in the Subscribe
    // push.
    bytes data = 7;
    // b64data is data as base64, for binary. Centrifugo decodes it.
    string b64data = 8;
    // recover_since is the stream position to recover publications from.
    StreamPosition recover_since = 9;
    // override dynamically overrides some channel options set in the
    // Centrifugo configuration.
    SubscribeOptionOverride override = 10;
    // session limits the call to the connection with this session ID. user
    // is still required.
    string session = 11;
    // label_filter restricts the call to clients whose labels match this
    // filter. Centrifugo PRO only.
    FilterNode label_filter = 12;
    // all_users, when user is empty, targets every connection on every node
    // instead of the anonymous-only bucket. No effect when user is non-empty.
    // Without label_filter it acts on every connection. Centrifugo PRO only.
    bool all_users = 13;
}

// SubscribeResponse is the response to a SubscribeRequest.
message SubscribeResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    SubscribeResult result = 2;
}

// BoolValue wraps a bool so that an unset value can be told apart from
// false.
message BoolValue {
    // value is the wrapped value.
    bool value = 1;
}

// Int32Value wraps an int32 so that an unset value can be told apart from
// zero.
message Int32Value {
    // value is the wrapped value.
    int32 value = 1;
}

// SubscribeOptionOverride overrides channel options for a server-side
// subscription. Unset fields keep the value from the channel configuration.
message SubscribeOptionOverride {
    // presence overrides the presence channel option.
    BoolValue presence = 1;
    // join_leave overrides the join_leave channel option.
    BoolValue join_leave = 2;
    // force_recovery overrides the force_recovery channel option.
    BoolValue force_recovery = 3;
    // force_positioning overrides the force_positioning channel option.
    BoolValue force_positioning = 4;
    // force_push_join_leave overrides the force_push_join_leave channel
    // option.
    BoolValue force_push_join_leave = 5;
}

// SubscribeResult is the result of a subscribe call. Empty at the moment.
message SubscribeResult {}

// UnsubscribeRequest unsubscribes a user from a channel.
message UnsubscribeRequest {
    // channel is the name of the channel to unsubscribe from. Required.
    string channel = 1;
    // user is the ID of the user to unsubscribe. Required, unless all_users
    // is used in Centrifugo PRO.
    string user = 2;
    // client limits the call to the connection with this client ID. user is
    // still required.
    string client = 3;
    // session limits the call to the connection with this session ID. user
    // is still required.
    string session = 4;
    // label_filter restricts the call to clients whose labels match this
    // filter. Centrifugo PRO only.
    FilterNode label_filter = 5;
    // all_users works as SubscribeRequest.all_users. Centrifugo PRO only.
    bool all_users = 6;
}

// UnsubscribeResponse is the response to an UnsubscribeRequest.
message UnsubscribeResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UnsubscribeResult result = 2;
}

// UnsubscribeResult is the result of an unsubscribe call. Empty at the
// moment.
message UnsubscribeResult {}

// Disconnect describes the code and reason clients are disconnected with.
message Disconnect {
    reserved 3;

    // code is the disconnect code.
    uint32 code = 1;
    // reason is the disconnect reason.
    string reason = 2;
}

// DisconnectRequest disconnects a user's connections.
message DisconnectRequest {
    // user is the ID of the user to disconnect. Required, unless all_users is
    // used in Centrifugo PRO.
    string user = 1;
    // disconnect is a custom disconnect code and reason. If not set, clients
    // are disconnected with a force no-reconnect disconnect.
    Disconnect disconnect = 2;
    // client limits the call to the connection with this client ID. user is
    // still required.
    string client = 3;
    // whitelist is a list of client IDs to keep connected.
    repeated string whitelist = 4;
    // session limits the call to the connection with this session ID. user
    // is still required.
    string session = 5;
    // label_filter restricts the call to clients whose labels match this
    // filter. Centrifugo PRO only.
    FilterNode label_filter = 6;
    // all_users works as SubscribeRequest.all_users. Centrifugo PRO only.
    bool all_users = 7;
}

// DisconnectResponse is the response to a DisconnectRequest.
message DisconnectResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DisconnectResult result = 2;
}

// DisconnectResult is the result of a disconnect call. Empty at the moment.
message DisconnectResult {}

// PresenceRequest returns the online presence of a channel: all clients
// currently subscribed to it. Presence must be enabled for the channel.
message PresenceRequest {
    // channel is the name of the channel. Required.
    string channel = 1;
}

// PresenceResponse is the response to a PresenceRequest.
message PresenceResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    PresenceResult result = 2;
}

// ClientInfo describes a client connection.
message ClientInfo {
    // user is the user ID.
    string user = 1;
    // client is the client ID.
    string client = 2;
    // conn_info is optional connection info.
    bytes conn_info = 3;
    // chan_info is optional channel info.
    bytes chan_info = 4;
}

// PresenceResult is the result of a presence call.
message PresenceResult {
    // presence maps client ID to information about the client.
    map<string, ClientInfo> presence = 1;
}

// PresenceStatsRequest returns short presence information of a channel: the
// number of clients and of unique users. Presence must be enabled for the
// channel.
message PresenceStatsRequest {
    // channel is the name of the channel. Required.
    string channel = 1;
}

// PresenceStatsResponse is the response to a PresenceStatsRequest.
message PresenceStatsResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    PresenceStatsResult result = 2;
}

// PresenceStatsResult is the result of a presence stats call.
message PresenceStatsResult {
    // num_clients is the total number of clients in the channel.
    uint32 num_clients = 1;
    // num_users is the number of unique users in the channel.
    uint32 num_users = 2;
}

// StreamPosition is a position in a channel stream.
message StreamPosition {
    // offset is the offset in the stream.
    uint64 offset = 1;
    // epoch is the stream epoch.
    string epoch = 2;
}

// HistoryRequest returns publications from the history of a channel.
// History must be enabled for the channel.
message HistoryRequest {
    // channel is the name of the channel. Required.
    string channel = 1;
    // limit is the maximum number of publications to return; -1 returns all
    // the channel keeps. If not set, only the current stream position is
    // returned, without publications.
    int32 limit = 2;
    // since returns publications after this stream position.
    StreamPosition since = 3;
    // reverse iterates in reverse order, from latest to earliest.
    bool reverse = 4;
}

// HistoryResponse is the response to a HistoryRequest.
message HistoryResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    HistoryResult result = 2;
}

// Publication is a publication in a channel history.
message Publication {
    // Removed: string uid = 1;

    // data is the publication payload.
    bytes data = 2;
    // info is information about the client that published, if any.
    ClientInfo info = 3;
    // offset is the offset of the publication in the history stream.
    uint64 offset = 4;
    // tags are the publication tags.
    map<string, string> tags = 5;
}

// HistoryResult is the result of a history call.
message HistoryResult {
    // publications is the list of publications.
    repeated Publication publications = 1;
    // epoch is the epoch of the current stream.
    string epoch = 2;
    // offset is the top offset of the history stream.
    uint64 offset = 3;
}

// HistoryRemoveRequest removes publications from the history of a channel.
// The current top stream position is kept, so clients do not get
// disconnected because of insufficient state.
message HistoryRemoveRequest {
    // channel is the name of the channel. Required.
    string channel = 1;
}

// HistoryRemoveResponse is the response to a HistoryRemoveRequest.
message HistoryRemoveResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    HistoryRemoveResult result = 2;
}

// HistoryRemoveResult is the result of a history remove call. Empty at the
// moment.
message HistoryRemoveResult {}

// InfoRequest returns information about the running Centrifugo nodes.
message InfoRequest {}

// InfoResponse is the response to an InfoRequest.
message InfoResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    InfoResult result = 2;
}

// InfoResult is the result of an info call.
message InfoResult {
    // nodes is information about all nodes of the cluster.
    repeated NodeResult nodes = 1;
}

// RPCRequest calls a custom server API method registered as an RPC
// extension.
message RPCRequest {
    // method is the name of the method to call. Required.
    string method = 1;
    // params are the method parameters.
    bytes params = 2;
}

// RPCResponse is the response to an RPCRequest.
message RPCResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    RPCResult result = 2;
}

// RPCResult is the result of an RPC call.
message RPCResult {
    // data is the data returned by the method.
    bytes data = 1;
}

// RefreshRequest refreshes a user's connections, mostly useful with
// unidirectional transports. Without expire_at the connections become
// non-expiring.
message RefreshRequest {
    // user is the ID of the user to refresh. Required, unless all_users is
    // used in Centrifugo PRO.
    string user = 1;
    // client limits the call to the connection with this client ID. user is
    // still required.
    string client = 2;
    // expired marks the connections as expired and closes them with an
    // expired disconnect reason.
    bool expired = 3;
    // expire_at is the Unix time in seconds when the connections expire.
    int64 expire_at = 4;
    // info attaches or replaces the connection info.
    bytes info = 5;
    // session limits the call to the connection with this session ID. user
    // is still required.
    string session = 6;
    // label_filter restricts the call to clients whose labels match this
    // filter. Centrifugo PRO only.
    FilterNode label_filter = 7;
    // all_users works as SubscribeRequest.all_users. Centrifugo PRO only.
    bool all_users = 8;
}

// RefreshResponse is the response to a RefreshRequest.
message RefreshResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    RefreshResult result = 2;
}

// RefreshResult is the result of a refresh call. Empty at the moment.
message RefreshResult {}

// NodeResult is information about a Centrifugo node.
message NodeResult {
    // uid is the unique ID of the node.
    string uid = 1;
    // name is the node name.
    string name = 2;
    // version is the Centrifugo version of the node.
    string version = 3;
    // num_clients is the number of clients connected to the node.
    uint32 num_clients = 4;
    // num_users is the number of unique users connected to the node.
    uint32 num_users = 5;
    // num_channels is the number of active channels on the node.
    uint32 num_channels = 6;
    // uptime is the node uptime in seconds.
    uint32 uptime = 7;
    // metrics are aggregated node metrics, if available.
    Metrics metrics = 8;
    // process is CPU and memory usage of the node process.
    // Centrifugo PRO only.
    Process process = 9;
    // num_subs is the number of subscriptions on the node.
    uint32 num_subs = 10;
}

// Metrics are aggregated metrics of a node.
message Metrics {
    // interval is the metrics aggregation interval in seconds.
    double interval = 1;
    // items maps metric name to value.
    map<string, double> items = 2;
}

// Process is resource usage of a node process. Centrifugo PRO only.
message Process {
    // cpu is the CPU usage of the process in percent.
    double cpu = 1;
    // rss is the resident set size of the process in bytes.
    int64 rss = 2;
}

// ChannelsRequest returns active channels (with one or more subscribers).
// It can be heavy on large deployments: there is no pagination.
message ChannelsRequest {
    // pattern filters channels by name, using gobwas/glob syntax.
    string pattern = 1;
}

// ChannelsResponse is the response to a ChannelsRequest.
message ChannelsResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    ChannelsResult result = 2;
}

// ChannelsResult is the result of a channels call.
message ChannelsResult {
    // channels maps channel name to information about the channel.
    map<string, ChannelInfo> channels = 1;
}

// ChannelInfo is information about an active channel.
message ChannelInfo {
    // num_clients is the number of connections subscribed to the channel.
    uint32 num_clients = 1;
}

// ConnectionsRequest returns information about active connections, without
// the need to enable presence. At least one of user, expression or
// label_filter must be set. Centrifugo PRO only.
message ConnectionsRequest {
    // user returns only the connections of this user ID.
    string user = 1;
    // expression is a CEL expression to filter connections.
    string expression = 2;
    // label_filter restricts the listing to clients whose labels match this
    // filter. Centrifugo PRO only.
    FilterNode label_filter = 3;
}

// ConnectionsResponse is the response to a ConnectionsRequest.
// Centrifugo PRO only.
message ConnectionsResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    ConnectionsResult result = 2;
}

// ConnectionsResult is the result of a connections call.
// Centrifugo PRO only.
message ConnectionsResult {
    // connections maps client ID to information about the connection.
    map<string, ConnectionInfo> connections = 1;
}

// ConnectionInfo is information about a client connection.
// Centrifugo PRO only.
message ConnectionInfo {
    reserved 5, 7;

    // app_name is the client application name, if provided by the client.
    string app_name = 1;
    // app_version is the client application version, if provided by the
    // client.
    string app_version = 2;
    // transport is the name of the connection transport.
    string transport = 3;
    // protocol is the connection protocol: json or protobuf.
    string protocol = 4;
    // user is the user ID of the connection.
    string user = 8;
    // state is the connection state.
    ConnectionState state = 9;
    // connected_at_ms is the Unix time in milliseconds when the connection
    // was established.
    int64 connected_at_ms = 10;
    // ping_pong_latency_ms is the last measured client ping/pong round-trip
    // latency in milliseconds. Can be -1 if not available.
    int64 ping_pong_latency_ms = 11;
    // labels are the client labels attached to the connection.
    map<string, string> labels = 12;
}

// ConnectionState is the state of a client connection.
// Centrifugo PRO only.
message ConnectionState {
    // channels maps the channels the client is subscribed to to their
    // context.
    map<string, ChannelContext> channels = 1;
    // connection_token is information about the connection token.
    ConnectionTokenInfo connection_token = 2;
    // subscription_tokens maps channel to information about the subscription
    // token used to subscribe to it.
    map<string, SubscriptionTokenInfo> subscription_tokens = 3;
    // meta is the meta information attached to the connection. It is not
    // visible to the client.
    bytes meta = 4;
}

// ChannelContext is context of a channel subscription.
// Centrifugo PRO only.
message ChannelContext {
    // source is the source of the channel subscription (for example,
    // subscription token, subscribe proxy or server API).
    uint32 source = 1;
}

// ConnectionTokenInfo is information about a connection token.
// Centrifugo PRO only.
message ConnectionTokenInfo {
    // uid is the unique token ID (jti claim).
    string uid = 1;
    // issued_at is the Unix time in seconds when the token was issued.
    int64 issued_at = 2;
}

// SubscriptionTokenInfo is information about a subscription token.
// Centrifugo PRO only.
message SubscriptionTokenInfo {
    // uid is the unique token ID (jti claim).
    string uid = 1;
    // issued_at is the Unix time in seconds when the token was issued.
    int64 issued_at = 2;
}

// UpdateUserStatusRequest marks users as active and online now, and sets
// their state when one is given. Centrifugo PRO only.
message UpdateUserStatusRequest {
    // users is the list of user IDs to update the status for. Required.
    repeated string users = 1;
    // state is an optional custom state to store in the user status. It can
    // be restricted by the user_status.state_regex option.
    string state = 2;
}

// UpdateUserStatusResponse is the response to an UpdateUserStatusRequest.
// Centrifugo PRO only.
message UpdateUserStatusResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UpdateUserStatusResult result = 2;
}

// UpdateUserStatusResult is the result of an update user status call. Empty
// at the moment. Centrifugo PRO only.
message UpdateUserStatusResult {}

// GetUserStatusRequest returns the status of users. Centrifugo PRO only.
message GetUserStatusRequest {
    // users is the list of user IDs to get the status for. Required.
    repeated string users = 1;
}

// GetUserStatusResponse is the response to a GetUserStatusRequest.
// Centrifugo PRO only.
message GetUserStatusResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    GetUserStatusResult result = 2;
}

// GetUserStatusResult is the result of a get user status call.
// Centrifugo PRO only.
message GetUserStatusResult {
    // statuses are the statuses of the requested users, in the same order.
    repeated UserStatus statuses = 1;
}

// UserStatus is the status of a user. Centrifugo PRO only.
message UserStatus {
    // user is the user ID.
    string user = 1;
    // active is the last active time as Unix seconds. Not set if unknown.
    int64 active = 2;
    // online is the last online time as Unix seconds, updated by Centrifugo
    // while the user is connected. Not set if unknown.
    int64 online = 3;
    // state is the custom state set with UpdateUserStatusRequest.state, if
    // any.
    string state = 4;
}

// DeleteUserStatusRequest deletes the status of users. Centrifugo PRO only.
message DeleteUserStatusRequest {
    // users is the list of user IDs to delete the status for. Required.
    repeated string users = 1;
}

// DeleteUserStatusResponse is the response to a DeleteUserStatusRequest.
// Centrifugo PRO only.
message DeleteUserStatusResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeleteUserStatusResult result = 2;
}

// DeleteUserStatusResult is the result of a delete user status call. Empty
// at the moment. Centrifugo PRO only.
message DeleteUserStatusResult {
}

// BlockUserRequest blocks a user: the user is disconnected and can not
// connect again until unblocked or the block expires. Centrifugo PRO only.
message BlockUserRequest {
    // expire_at is the Unix time in seconds when the block expires. Optional,
    // but a reasonably small value is recommended to keep the set of blocked
    // users small.
    int64 expire_at = 1;
    // user is the ID of the user to block. Required.
    string user = 2;
}

// BlockUserResult is the result of a block user call. Empty at the moment.
// Centrifugo PRO only.
message BlockUserResult {}

// BlockUserResponse is the response to a BlockUserRequest.
// Centrifugo PRO only.
message BlockUserResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    BlockUserResult result = 2;
}

// UnblockUserRequest unblocks a user. Centrifugo PRO only.
message UnblockUserRequest {
    // user is the ID of the user to unblock. Required.
    string user = 1;
}

// UnblockUserResult is the result of an unblock user call. Empty at the
// moment. Centrifugo PRO only.
message UnblockUserResult {}

// UnblockUserResponse is the response to an UnblockUserRequest.
// Centrifugo PRO only.
message UnblockUserResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UnblockUserResult result = 2;
}

// RevokeTokenRequest revokes a token by its unique ID (jti claim of a JWT).
// Clients using the token are disconnected shortly, and can not connect
// with it again. Centrifugo PRO only.
message RevokeTokenRequest {
    // expire_at is the Unix time in seconds when the revocation expires.
    // Optional, but a value matching the token expiration is recommended.
    int64 expire_at = 1;
    // uid is the unique ID of the token to revoke (jti claim). Required.
    string uid = 2;
}

// RevokeTokenResult is the result of a revoke token call. Empty at the
// moment. Centrifugo PRO only.
message RevokeTokenResult {}

// RevokeTokenResponse is the response to a RevokeTokenRequest.
// Centrifugo PRO only.
message RevokeTokenResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    RevokeTokenResult result = 2;
}

// InvalidateUserTokensRequest revokes all tokens of a user issued before a
// certain time (based on the iat claim of a JWT). Centrifugo PRO only.
message InvalidateUserTokensRequest {
    // expire_at is the Unix time in seconds when the invalidation expires.
    // Optional, but a value matching the token expiration is recommended.
    int64 expire_at = 1;
    // user is the ID of the user whose tokens to invalidate. Required.
    string user = 2;
    // issued_before is the Unix time in seconds: tokens issued before it are
    // considered revoked. If not set, the current time is used.
    int64 issued_before = 3;
    // channel limits the invalidation to subscription tokens for this
    // channel.
    string channel = 4;
}

// InvalidateUserTokensResult is the result of an invalidate user tokens
// call. Empty at the moment. Centrifugo PRO only.
message InvalidateUserTokensResult {}

// InvalidateUserTokensResponse is the response to an
// InvalidateUserTokensRequest. Centrifugo PRO only.
message InvalidateUserTokensResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    InvalidateUserTokensResult result = 2;
}

// DeviceRegisterRequest registers a device for push notifications, or
// updates a registered one. Centrifugo PRO only.
message DeviceRegisterRequest {
    // id is the device ID. Omit it on first registration: Centrifugo
    // generates one and returns it. Pass the stored value to update the
    // device.
    string id = 1;
    // provider is the provider of the device token: fcm, hms, apns or
    // webpush. Required.
    string provider = 2;
    // token is the push token of the device. For webpush, it is the browser
    // PushSubscription serialized as a JSON string. Required.
    string token = 3;
    // platform is the device platform: ios, android or web. Required.
    string platform = 4;
    // user is the user associated with the device.
    string user = 5;
    // meta is additional custom metadata of the device.
    map<string, string> meta = 6;
    // topics is the full list of the device's topic subscriptions, replacing
    // the previous one. The user's topics are attached automatically.
    repeated string topics = 7;
    // timezone is the IANA time zone of the device user, for example
    // Europe/Nicosia.
    string timezone = 8;
    // locale is the locale of the device user as an IETF BCP 47 language
    // tag, for example en-US.
    string locale = 9;
}

// DeviceUpdateRequest updates registered devices, selected by ids and/or
// users. Centrifugo PRO only.
message DeviceUpdateRequest {
    // ids selects devices by ID.
    repeated string ids = 1;
    // users selects devices by user.
    repeated string users = 2;

    // user_update changes the user ID of the devices. It does not re-sync
    // user-bound topics; use DeviceRegisterRequest to assign a device to
    // another user.
    DeviceUserUpdate user_update = 4;
    // meta_update updates the device meta.
    DeviceMetaUpdate meta_update = 5;
    // topics_update updates the device topics.
    DeviceTopicsUpdate topics_update = 6;
    // timezone_update updates the device timezone.
    DeviceTimezoneUpdate timezone_update = 7;
    // locale_update updates the device locale.
    DeviceLocaleUpdate locale_update = 8;
}

// DeviceRemoveRequest removes devices, selected by ids and/or users.
// Centrifugo PRO only.
message DeviceRemoveRequest {
    // ids selects devices to remove by ID.
    repeated string ids = 1;
    // users selects devices to remove by user.
    repeated string users = 2;
}

// DeviceUserUpdate sets the user of devices. Centrifugo PRO only.
message DeviceUserUpdate {
    // user is the user ID to set. Required.
    string user = 1;
}

// DeviceTimezoneUpdate sets the timezone of devices. Centrifugo PRO only.
message DeviceTimezoneUpdate {
    // timezone is the IANA time zone to set. Required.
    string timezone = 1;
}

// DeviceLocaleUpdate sets the locale of devices. Centrifugo PRO only.
message DeviceLocaleUpdate {
    // locale is the locale to set. Required.
    string locale = 1;
}

// DeviceMetaUpdate sets the meta of devices. Centrifugo PRO only.
message DeviceMetaUpdate {
    // meta is the meta to set. Required.
    map<string, string> meta = 1;
}

// DeviceTopicsUpdate changes the topics of devices. Centrifugo PRO only.
message DeviceTopicsUpdate {
    // op is the operation: add, remove or set. Required.
    string op = 1;
    // topics are the topics for the operation.
    repeated string topics = 2;
}

// DeviceFilter selects devices. Centrifugo PRO only.
message DeviceFilter {
    // ids selects devices by ID.
    repeated string ids = 1;
    // users selects devices by user.
    repeated string users = 2;
    // topics selects devices by subscribed topic.
    repeated string topics = 3;
    // providers selects devices by token provider.
    repeated string providers = 4;
    // platforms selects devices by platform.
    repeated string platforms = 5;
}

// DeviceListRequest returns a paginated list of registered devices.
// Centrifugo PRO only.
message DeviceListRequest {
    // filter selects the devices to list. Required.
    DeviceFilter filter = 1;

    // include_total_count includes the total count for the filter in the
    // result.
    bool include_total_count = 2;
    // include_meta includes meta of each device.
    bool include_meta = 3;
    // include_topics includes topics of each device.
    bool include_topics = 4;
    // include_webpush_keys includes webpush_keys of each device (webpush
    // only).
    bool include_webpush_keys = 5;

    // cursor is the pagination cursor: next_cursor of the previous page,
    // empty for the first page.
    string cursor = 10;
    // limit is the maximum number of devices to return.
    int32 limit = 11;
}

// DeviceTopicFilter selects device topic subscriptions. Centrifugo PRO only.
message DeviceTopicFilter {
    // device_ids selects by device ID.
    repeated string device_ids = 1;
    // device_providers selects by device token provider.
    repeated string device_providers = 2;
    // device_platforms selects by device platform.
    repeated string device_platforms = 3;
    // device_users selects by device user.
    repeated string device_users = 4;
    // topics selects by topic.
    repeated string topics = 5;
    // topic_prefix selects by topic prefix.
    string topic_prefix = 6;
}

// DeviceTopicListRequest returns a paginated list of device topic
// subscriptions. Centrifugo PRO only.
message DeviceTopicListRequest {
    // filter selects the device topics to list.
    DeviceTopicFilter filter = 1;

    // include_total_count includes the total count for the filter in the
    // result.
    bool include_total_count = 2;
    // include_device includes the Device of each item.
    bool include_device = 3;

    // cursor is the pagination cursor: next_cursor of the previous page,
    // empty for the first page.
    string cursor = 10;
    // limit is the maximum number of items to return.
    int32 limit = 11;
}

// UserTopicFilter selects user topic subscriptions. Centrifugo PRO only.
message UserTopicFilter {
    // users selects by user.
    repeated string users = 1;
    // topics selects by topic.
    repeated string topics = 2;
    // topic_prefix selects by topic prefix.
    string topic_prefix = 3;
}

// UserTopicListRequest returns a paginated list of user topic
// subscriptions. Centrifugo PRO only.
message UserTopicListRequest {
    // filter selects the user topics to list.
    UserTopicFilter filter = 1;

    // include_total_count includes the total count for the filter in the
    // result.
    bool include_total_count = 2;

    // cursor is the pagination cursor: next_cursor of the previous page,
    // empty for the first page.
    string cursor = 10;
    // limit is the maximum number of items to return.
    int32 limit = 11;
}

// DeviceTopicUpdateRequest changes the topics of a device. The device topic
// list is what decides who gets a push sent to a topic.
// Centrifugo PRO only.
message DeviceTopicUpdateRequest {
    // device_id is the ID of the device. Required.
    string device_id = 1;
    // op is the operation: add, remove or set. Required.
    string op = 2;
    // topics are the topics for the operation.
    repeated string topics = 3;
    // user is an optional ownership guard: the update is applied only if the
    // device currently belongs to this user. Otherwise the call fails with a
    // conflict error (or not found if there is no such device).
    string user = 4;
}

// UserTopicUpdateRequest changes the topics of a user. The change is also
// applied to the user's registered devices. Centrifugo PRO only.
message UserTopicUpdateRequest {
    // user is the user ID. Required.
    string user = 1;
    // op is the operation: add, remove or set. Required.
    string op = 2;
    // topics are the topics for the operation.
    repeated string topics = 3;
}

// DeviceRegisterResponse is the response to a DeviceRegisterRequest.
// Centrifugo PRO only.
message DeviceRegisterResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceRegisterResult result = 2;
}

// DeviceUpdateResponse is the response to a DeviceUpdateRequest.
// Centrifugo PRO only.
message DeviceUpdateResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceUpdateResult result = 2;
}

// DeviceRemoveResponse is the response to a DeviceRemoveRequest.
// Centrifugo PRO only.
message DeviceRemoveResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceRemoveResult result = 2;
}

// DeviceListResponse is the response to a DeviceListRequest.
// Centrifugo PRO only.
message DeviceListResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceListResult result = 2;
}

// DeviceTopicListResponse is the response to a DeviceTopicListRequest.
// Centrifugo PRO only.
message DeviceTopicListResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceTopicListResult result = 2;
}

// UserTopicListResponse is the response to a UserTopicListRequest.
// Centrifugo PRO only.
message UserTopicListResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UserTopicListResult result = 2;
}

// DeviceTopicUpdateResponse is the response to a DeviceTopicUpdateRequest.
// Centrifugo PRO only.
message DeviceTopicUpdateResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    DeviceTopicUpdateResult result = 2;
}

// UserTopicUpdateResponse is the response to a UserTopicUpdateRequest.
// Centrifugo PRO only.
message UserTopicUpdateResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UserTopicUpdateResult result = 2;
}

// DeviceRegisterResult is the result of a device register call.
// Centrifugo PRO only.
message DeviceRegisterResult {
    // id is the ID of the registered or updated device.
    string id = 1;
}

// DeviceUpdateResult is the result of a device update call. Empty at the
// moment. Centrifugo PRO only.
message DeviceUpdateResult {
}

// DeviceRemoveResult is the result of a device remove call. Empty at the
// moment. Centrifugo PRO only.
message DeviceRemoveResult {
}

// DeviceListResult is the result of a device list call.
// Centrifugo PRO only.
message DeviceListResult {
    // items are the devices of this page.
    repeated Device items = 1;
    // next_cursor is the cursor of the next page. Empty if there is no next
    // page.
    string next_cursor = 2;
    // total_count is the total count for the filter, if include_total_count
    // was set.
    int64 total_count = 3;
}

// Device is a device registered for push notifications. Centrifugo PRO only.
message Device {
    // id is the device ID.
    string id = 1;
    // platform is the device platform.
    string platform = 2;
    // provider is the device token provider.
    string provider = 3;
    // token is the device token. For webpush, it is the subscription
    // endpoint.
    string token = 4;
    // user is the user associated with the device.
    string user = 5;
    // created_at is the Unix time in milliseconds when the device was
    // created.
    int64 created_at = 6;
    // updated_at is the Unix time in milliseconds when the device was last
    // updated.
    int64 updated_at = 7;

    // meta is the device meta. Only set if include_meta was requested.
    map<string, string> meta = 10;
    // topics are the device topics. Only set if include_topics was
    // requested.
    repeated string topics = 11;
    // timezone is the device timezone.
    string timezone = 12;
    // locale is the device locale.
    string locale = 13;
    // webpush_keys is the Web Push subscription keys JSON ({p256dh, auth}).
    // Only set if include_webpush_keys was requested.
    string webpush_keys = 14;
}

// DeviceTopicListResult is the result of a device topic list call.
// Centrifugo PRO only.
message DeviceTopicListResult {
    // items are the device topics of this page.
    repeated DeviceTopic items = 1;
    // next_cursor is the cursor of the next page. Empty if there is no next
    // page.
    string next_cursor = 2;
    // total_count is the total count for the filter, if include_total_count
    // was set.
    int64 total_count = 3;
}

// DeviceTopic is a topic subscription of a device. Centrifugo PRO only.
message DeviceTopic {
    // id is the ID of the device topic.
    string id = 1;
    // topic is the topic.
    string topic = 2;
    // device is the device. Only set if include_device was requested.
    Device device = 3;
}

// UserTopicListResult is the result of a user topic list call.
// Centrifugo PRO only.
message UserTopicListResult {
    // items are the user topics of this page.
    repeated UserTopic items = 1;
    // next_cursor is the cursor of the next page. Empty if there is no next
    // page.
    string next_cursor = 2;
    // total_count is the total count for the filter, if include_total_count
    // was set.
    int64 total_count = 3;
}

// DeviceTopicUpdateResult is the result of a device topic update call.
// Empty at the moment. Centrifugo PRO only.
message DeviceTopicUpdateResult {
}

// UserTopicUpdateResult is the result of a user topic update call. Empty at
// the moment. Centrifugo PRO only.
message UserTopicUpdateResult {
}

// UserTopic is a topic subscription of a user. Centrifugo PRO only.
message UserTopic {
    // id is the ID of the user topic.
    string id = 1;
    // user is the user ID.
    string user = 2;
    // topic is the topic.
    string topic = 3;
}

// PushRecipient describes who receives a push notification. Set only one
// of its fields. Centrifugo PRO only.
message PushRecipient {
    // filter sends to devices from Centrifugo device storage that match the
    // filter.
    DeviceFilter filter = 1;

    // fcm_tokens sends to a list of FCM native tokens.
    repeated string fcm_tokens = 2;
    // fcm_topic sends to an FCM native topic.
    string fcm_topic = 3;
    // fcm_condition sends to an FCM native condition.
    string fcm_condition = 4;

    // hms_tokens sends to a list of HMS native tokens.
    repeated string hms_tokens = 5;
    // hms_topic sends to an HMS native topic.
    string hms_topic = 6;
    // hms_condition sends to an HMS native condition.
    string hms_condition = 7;

    // apns_tokens sends to a list of APNs native tokens.
    repeated string apns_tokens = 8;

    // webpush_tokens sends to a list of raw Web Push subscriptions, each a
    // PushSubscription JSON string.
    repeated string webpush_tokens = 9;
}

// PushNotification is a push notification in the format of each provider.
// Centrifugo PRO only.
message PushNotification {
    // fcm is the notification for FCM.
    FcmPushNotification fcm = 1;
    // hms is the notification for HMS.
    HmsPushNotification hms = 2;
    // apns is the notification for APNs.
    ApnsPushNotification apns = 3;
    // webpush is the notification for Web Push.
    WebPushPushNotification webpush = 4;

    // expire_at is the Unix time in seconds when Centrifugo stops trying to
    // send the notification. Not related to the providers' TTL fields.
    int64 expire_at = 5;
}

// FcmPushNotification is a notification for FCM. Centrifugo PRO only.
message FcmPushNotification {
    // message is the FCM Message object as JSON. Required.
    bytes message = 1;
}

// HmsPushNotification is a notification for HMS. Centrifugo PRO only.
message HmsPushNotification {
    // message is the HMS Message object as JSON. Required.
    bytes message = 1;
}

// ApnsPushNotification is a notification for APNs. Centrifugo PRO only.
message ApnsPushNotification {
    // headers are the APNs request headers.
    map<string, string> headers = 1;
    // payload is the APNs payload as JSON. Required.
    bytes payload = 2;
}

// WebPushPushNotification is a notification for Web Push.
// Centrifugo PRO only.
message WebPushPushNotification {
    // headers are Web Push HTTP headers. Recognized keys: TTL (seconds,
    // default 4 weeks), Urgency (very-low, low, normal, high) and Topic.
    map<string, string> headers = 1;
    // payload is the JSON payload delivered to the browser service worker.
    // Required.
    bytes payload = 2;
}

// SendPushNotificationRequest sends a push notification. The request is
// queued and sent to the provider by Centrifugo workers.
// Centrifugo PRO only.
message SendPushNotificationRequest {
    // recipient is who receives the notification. Required.
    PushRecipient recipient = 1;
    // notification is the notification to send. Required.
    PushNotification notification = 2;
    // uid is a unique identifier of the request, can be used to cancel the
    // push. UUID v4 is recommended; different requests must use different
    // uids.
    string uid = 3;
    // send_at is the Unix time in seconds when to send the notification. If
    // not set, the notification is sent immediately.
    int64 send_at = 4;
    // optimize_for_reliability makes processing heavier, but tolerates edge
    // cases, like not losing inflight pushes when the queue is briefly
    // unavailable.
    bool optimize_for_reliability = 5;
    // limit_strategy sets time constraints and rate limits. Only applies
    // with a filter recipient; devices are then processed one by one
    // instead of in batches.
    PushLimitStrategy limit_strategy = 6;
    // analytics_uid is the identifier for push notification analytics. If
    // not set, uid is used.
    string analytics_uid = 7;
    // localizations are optional per language/locale localizations. Setting
    // them enables templating.
    map<string, PushLocalization> localizations = 8;
    // use_templating enables templating of the notification. Only works
    // with a filter recipient.
    bool use_templating = 9;
    // use_meta additionally loads device meta while sending, making it
    // available in templating.
    bool use_meta = 10;
}

// PushLocalization holds translations for one language/locale.
// Centrifugo PRO only.
message PushLocalization {
    // translations maps variable name to value for the language/locale.
    map<string, string> translations = 1;
}

// PushLimitStrategy limits when and how often pushes are sent.
// Centrifugo PRO only.
message PushLimitStrategy {
    // rate_limit sets rate limit policies.
    PushRateLimitStrategy rate_limit = 1;
    // time_limit sets a time limit policy based on the device timezone.
    PushTimeLimitStrategy time_limit = 2;
}

// PushTimeLimitStrategy sends pushes within a window of the device local
// time. Centrifugo PRO only.
message PushTimeLimitStrategy {
    // send_after_time is the local time, as HH:MM:SS, after which the push
    // may be sent. Required.
    string send_after_time = 1;
    // send_before_time is the local time, as HH:MM:SS, before which the push
    // must be sent. Required.
    string send_before_time = 2;
    // no_tz_send_now sends the push immediately if the device timezone is
    // not set. By default such pushes are dropped.
    bool no_tz_send_now = 3;
}

// PushRateLimitStrategy rate limits pushes per device. Centrifugo PRO only.
message PushRateLimitStrategy {
    // key is an optional key for the rate limit policy. Supports variables
    // (device.id and device.user).
    string key = 1;
    // policies are the rate limit policies to apply.
    repeated RateLimitPolicy policies = 2;
    // drop_if_rate_limited drops a rate limited push instead of queuing it
    // for later.
    bool drop_if_rate_limited = 3;
}

// RateLimitPolicy allows rate pushes per interval_ms. Centrifugo PRO only.
message RateLimitPolicy {
    // rate is the allowed number of pushes per interval. Required.
    int64 rate = 1;
    // interval_ms is the interval in milliseconds. Required.
    int32 interval_ms = 2;
}

// SendPushNotificationResponse is the response to a
// SendPushNotificationRequest. Centrifugo PRO only.
message SendPushNotificationResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    SendPushNotificationResult result = 2;
}

// SendPushNotificationResult is the result of a send push notification
// call. Centrifugo PRO only.
message SendPushNotificationResult {
    // uid is the unique identifier of the send request (not a provider
    // message ID). Matches the request uid if it was set.
    string uid = 1;
}

// UpdatePushStatusRequest saves the delivery or interaction status of a
// push notification to analytics. Experimental. Centrifugo PRO only.
message UpdatePushStatusRequest {
    // analytics_uid is the analytics_uid of the push notification (as in
    // SendPushNotificationRequest). Required.
    string analytics_uid = 1;
    // status is the status of the push notification: delivered or
    // interacted. Required.
    string status = 2;
    // device_id is the Centrifugo device ID. Required.
    string device_id = 3;
    // msg_id is the message ID issued by the provider.
    string msg_id = 4;
}

// UpdatePushStatusResponse is the response to an UpdatePushStatusRequest.
// Centrifugo PRO only.
message UpdatePushStatusResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    UpdatePushStatusResult result = 2;
}

// UpdatePushStatusResult is the result of an update push status call.
// Empty at the moment. Centrifugo PRO only.
message UpdatePushStatusResult {}

// CancelPushRequest cancels a delayed push notification (sent with
// send_at). Centrifugo PRO only.
message CancelPushRequest {
    // uid is the uid of the push notification to cancel. Required.
    string uid = 1;
}

// CancelPushResponse is the response to a CancelPushRequest.
// Centrifugo PRO only.
message CancelPushResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    CancelPushResult result = 2;
}

// CancelPushResult is the result of a cancel push call. Empty at the
// moment. Centrifugo PRO only.
message CancelPushResult {}

// MapPublishRequest publishes or updates a key in a map channel.
message MapPublishRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
    // key is the entry key. Required.
    string key = 2;
    // data is the entry data. In the HTTP API it is any JSON value; over GRPC
    // it may be binary.
    bytes data = 3;
    // b64data is data as base64, for binary over the HTTP API. Centrifugo
    // decodes it.
    string b64data = 4;
    // stream_data is currently not used by the server API.
    bytes stream_data = 5;
    // b64stream_data is currently not used by the server API.
    string b64stream_data = 6;
    // tags are key-value metadata attached to the publication.
    map<string, string> tags = 7;
    // idempotency_key is a duplicate detection key for safe retries.
    // Duplicates are suppressed in the result.
    string idempotency_key = 8;
    // delta enables delta compression for this publication.
    bool delta = 9;
    // version is a per-key version: publications with a version not higher
    // than the key's current one are suppressed.
    uint64 version = 10;
    // version_epoch scopes version. A different epoch resets version
    // comparison.
    string version_epoch = 11;
    // score is currently not used by the server API.
    int64 score = 12;
    // key_mode makes the publish conditional: "if_new" writes only if the
    // key does not exist, "if_exists" only if it exists. Empty always
    // writes.
    string key_mode = 13;
}

// MapPublishResponse is the response to a MapPublishRequest.
message MapPublishResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapPublishResult result = 2;
}

// MapPublishResult is the result of a map publish call.
message MapPublishResult {
    // offset is the offset in the channel stream.
    uint64 offset = 1;
    // epoch is the epoch of the channel stream.
    string epoch = 2;
    // suppressed is true if the publish was not applied, see
    // suppress_reason.
    bool suppressed = 3;
    // suppress_reason explains why the publish was suppressed, for example
    // "idempotency", "version", "key_exists" or "key_not_found".
    string suppress_reason = 4;
}

// MapRemoveRequest removes a key from a map channel.
message MapRemoveRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
    // key is the key to remove. Required.
    string key = 2;
    // idempotency_key is a duplicate detection key for safe retries.
    string idempotency_key = 3;
}

// MapRemoveResponse is the response to a MapRemoveRequest.
message MapRemoveResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapRemoveResult result = 2;
}

// MapRemoveResult is the result of a map remove call.
message MapRemoveResult {
    // offset is the offset in the channel stream.
    uint64 offset = 1;
    // epoch is the epoch of the channel stream.
    string epoch = 2;
    // suppressed is true if the removal was not applied, see
    // suppress_reason.
    bool suppressed = 3;
    // suppress_reason explains why the removal was suppressed, for example
    // "idempotency" or "key_not_found".
    string suppress_reason = 4;
}

// MapReadStateRequest reads the current state of a map channel, with
// optional pagination.
message MapReadStateRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
    // cursor is the pagination cursor from the previous page. Empty starts
    // from the beginning.
    string cursor = 2;
    // limit is the maximum number of entries per page: -1 means no limit, 0
    // returns only the stream position. Page sizes may exceed it with the
    // Redis map broker.
    int32 limit = 3;
    // key reads a single entry by exact key. cursor and limit are ignored
    // when it is set.
    string key = 4;
    // asc sorts ordered state by score ascending instead of descending.
    // Ignored for unordered channels.
    bool asc = 5;
    // revision_offset is the offset of the position from a previous state
    // read, used with revision_epoch.
    uint64 revision_offset = 6;
    // revision_epoch is the epoch of the position from a previous state
    // read. If the epoch changed, the call fails with an unrecoverable
    // position error.
    string revision_epoch = 7;
}

// MapReadStateResponse is the response to a MapReadStateRequest.
message MapReadStateResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapReadStateResult result = 2;
}

// MapReadStateResult is the result of a map read state call.
message MapReadStateResult {
    // entries are the state entries of this page.
    repeated MapEntry entries = 1;
    // offset is the offset of the channel stream position.
    uint64 offset = 2;
    // epoch is the epoch of the channel stream position.
    string epoch = 3;
    // cursor is the cursor of the next page. Empty if there are no more
    // entries.
    string cursor = 4;
}

// MapEntry is an entry of a map channel state or stream.
message MapEntry {
    // key is the entry key.
    string key = 1;
    // data is the entry data.
    bytes data = 2;
    // tags are the entry tags.
    map<string, string> tags = 3;
    // offset is the offset of the entry in the channel stream.
    uint64 offset = 4;
    // score is the sort value of the entry in ordered map channels.
    int64 score = 5;
    // removed is true for a removal event.
    bool removed = 6;
    // time is the time of the publication as Unix milliseconds, if known.
    int64 time = 7;
}

// MapReadStreamRequest reads the change stream of a map channel.
message MapReadStreamRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
    // since_offset returns entries after this offset, used with
    // since_epoch.
    uint64 since_offset = 2;
    // since_epoch is the epoch of the since position. It must match the
    // current stream epoch.
    string since_epoch = 3;
    // limit is the maximum number of entries: -1 means no limit, 0 returns
    // only the stream position.
    int32 limit = 4;
    // reverse returns entries newest first.
    bool reverse = 5;
}

// MapReadStreamResponse is the response to a MapReadStreamRequest.
message MapReadStreamResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapReadStreamResult result = 2;
}

// MapReadStreamResult is the result of a map read stream call.
message MapReadStreamResult {
    // entries are the stream entries.
    repeated MapEntry entries = 1;
    // offset is the top offset of the channel stream.
    uint64 offset = 2;
    // epoch is the epoch of the channel stream.
    string epoch = 3;
}

// MapStatsRequest returns statistics about a map channel.
message MapStatsRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
}

// MapStatsResponse is the response to a MapStatsRequest.
message MapStatsResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapStatsResult result = 2;
}

// MapStatsResult is the result of a map stats call.
message MapStatsResult {
    // num_keys is the number of entries in the channel state.
    int32 num_keys = 1;
}

// MapClearRequest removes all state and stream data of a map channel.
message MapClearRequest {
    // channel is the name of the map channel. Required.
    string channel = 1;
}

// MapClearResponse is the response to a MapClearRequest.
message MapClearResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    MapClearResult result = 2;
}

// MapClearResult is the result of a map clear call. Empty at the moment.
message MapClearResult {}

// SharedPollPublishRequest pushes data for a key directly to clients of a
// shared poll channel, without waiting for the next poll cycle. Requires
// versioned mode and publish_enabled on the namespace.
message SharedPollPublishRequest {
    // channel is the name of the shared poll channel. Required.
    string channel = 1;
    // key is the item key. Required.
    string key = 2;
    // data is the item data, delivered to clients as is.
    bytes data = 3;
    // b64data is data as base64, for binary payloads. Centrifugo decodes it.
    string b64data = 4;
    // version is the item version, must be >= 1. Required. A version not
    // higher than the current one within the same epoch is silently dropped.
    uint64 version = 5;
    // epoch is the channel-level publisher epoch. A change resets per-key
    // versions and unsubscribes current subscribers with insufficient state.
    string epoch = 6;
}

// SharedPollPublishResponse is the response to a SharedPollPublishRequest.
message SharedPollPublishResponse {
    // error is set if the call failed.
    Error error = 1;
    // result is set on success.
    SharedPollPublishResult result = 2;
}

// SharedPollPublishResult is the result of a shared poll publish call.
// Empty at the moment.
message SharedPollPublishResult {}