syntax = "proto3";

package protocol.sync.v1;

option go_package = "github.com/harmony-development/legato/gen/sync/v1";

// Authentication data that will be sent in a `harmonytypes.v1.Token`.
message AuthData {
  // The server ID of the server initiating the transaction. For Pull,
  // this tells the server being connected to which homeservers' events it should send.
  // For Push, this tells the server being connected to which homeservers' events it is
  // receiving.
  string server_id = 1;
  // The UTC UNIX time in seconds of when the request is started. Servers should reject
  // tokens with a time too far from the current time, at their discretion. A recommended
  // variance is 1 minute.
  uint64 time = 2;
}

// Object representing a postbox event.
message Event {
  // Event sent when a user is removed from a guild.
  message UserRemovedFromGuild {
    // User ID of the user that was removed.
    uint64 user_id = 1;
    // Guild ID of the guild where the user was.
    uint64 guild_id = 2;
  }
  // Event sent when a user is added to a guild.
  message UserAddedToGuild {
    // User ID of the user that was added.
    uint64 user_id = 1;
    // Guild ID of the guild where the user will be.
    uint64 guild_id = 2;
  }
  // Event sent when a user is invited to a guild.
  message UserInvited {
    // User ID of the invitee.
    uint64 user_id = 1;
    // User ID of the user that invited.
    uint64 inviter_id = 2;
    // The invite for the guild.
    string invite_id = 3;
  }
  // Event sent when a user rejects a guild invitation.
  message UserRejectedInvite {
    // Guild ID of the guild the invitee rejected an invite for.
    uint64 guild_id = 1;
    // User ID of the invitee that rejected the invitation.
    uint64 user_id = 2;
    // Invite ID of the invite that was rejected.
    string invite_id = 3;
  }

  // The kind and data of this event.
  oneof kind {
    // User removed from a guild.
    UserRemovedFromGuild user_removed_from_guild = 1;
    // User added to a guild.
    UserAddedToGuild user_added_to_guild = 2;
    // User invited to a guild.
    UserInvited user_invited = 3;
    // User rejected a guild invitation.
    UserRejectedInvite user_rejected_invite = 4;
  }
}

// Used in `Pull` endpoint.
message PullRequest {}
// Used in `Pull` endpoint.
message PullResponse {
  // The events that were not processed yet.
  repeated Event event_queue = 1;
}

// Used in `Push` endpoint.
message PushRequest {
  // The event to push to the server.
  Event event = 1;
}
// Used in `Push` endpoint.
message PushResponse {}

// Used in `NotifyNewId` endpoint.
message NotifyNewIdRequest {
  // The new server ID of the server.
  string new_server_id = 1;
}
// Used in `NotifyNewId` endpoint.
message NotifyNewIdResponse {}

// # Postbox
//
// The postbox service forms the core of Harmony's server <-> server communications.
//
// It concerns the transfer of Events between servers, as well as ensuring reliable
// delivery of them.
//
// The semantics of events are documented in the event types. The postbox service
// is solely reliable for reliable pushing and pulling.
//
// ## Server Identification
//
// Servers are identified using their domain, and the port which they serve. This is
// called the "server ID", and must be formatted as `domain:port`. The port is NOT
// optional. Converting this ID to a URL for communicating can simply be done via
// prefixing the ID with a protocol, eg. `https://`.
//
// ## Authorisation
//
// Requests are authorised using a serialized `harmonytypes.v1.Token` in the Authorization HTTP header.
// The `data` field of the token will be a serialized `AuthData` message.
// The private key used to sign is the homeserver's private key.
//
// ## Events
//
// In this section, we will use sender and recipient to refer to the servers
// sending the events and the server receiving the events respectively.
//
// At PostboxService startup, a sender should first Pull all receivers it had
// federated from before. If a receiver makes a Push to the sender while a Pull
// is going on, the Push should be processed after the Pull is completed.
//
// The sender will attempt to Push to the receiver. If the Push RPC fails more
// than X times (a recommended retry count is 5), the event will be dispatched
// to the sender's queue for the receiver. Unless the receiver pulls these events,
// all new events should be dispatched to the queue. No new Push RPC should be made
// before the queue is emptied. This ensures that events are always received in the
// right order.
//
// It is recommended that receivers try pulling periodically, for example, every
// 1 minute after the last Push RPC by the sender. This ensures that events are recieved.
service PostboxService {
  // Endpoint to pull events.
  rpc Pull(PullRequest) returns (PullResponse) {}
  // Endpoint to push events.
  rpc Push(PushRequest) returns (PushResponse) {}
  // Endpoint to notify a server of a server ID change. It is called by the server
  // that had it's server ID changed for all servers it has federated with.
  rpc NotifyNewId(NotifyNewIdRequest) returns (NotifyNewIdResponse) {}
}