@namespace("gregor.1")
@compression_type("gzip")
protocol incoming {
  record SyncResult {
    array<InBandMessage> msgs;
    bytes hash;
  }
  SyncResult sync(UID uid, DeviceID deviceid, Time ctime);
  void consumeMessage(Message m);
  void consumePublishMessage(Message m);

  /**
    consumeMessageMulti will take msg and consume it for all the users listed
    in uids. This is so a gregor client can send the same message to many UIDs
    with one call, as opposed to calling consumeMessage for each UID.
   */
  void consumeMessageMulti(Message msg, array<UID> uids);
  @compression_type("none")
  string ping();
  string version(UID uid);

  State state(UID uid, DeviceID deviceid, TimeOrOffset timeOrOffset);

  /**
    StateByCategoryPrefix loads the messages of the user's state whose
    categories are prefixed by the given prefix
   */
  State stateByCategoryPrefix(UID uid, DeviceID deviceid, TimeOrOffset timeOrOffset, Category categoryPrefix);

  /**
    DescribeConnectedUsers will take a list of users, and return the list of users
    which are connected to any Gregor in the cluster, and what devices (and device type)
    those users are connected with.
  */
  record ConnectedDevice {
    DeviceID deviceID;
    string deviceType;
    string devicePlatform;
    string userAgent;
  }

  record ConnectedUser {
    UID uid;
    array<ConnectedDevice> devices;
  }

  array<ConnectedUser> describeConnectedUsers(array<UID> uids);
  array<ConnectedUser> describeConnectedUsersInternal(array<UID> uids);
}