the great protocol refactor

stable/Ids.md

@@ -0,0 +1,43 @@
+# IDs
+
+## User ID
+
+A `uint64` ID. Represents a user.
+This must be unique in a server.
+
+## Guild ID
+
+A `uint64` ID. Represents a guild.
+This must be unique in a server.
+
+## Channel ID
+
+A `uint64` ID. Represents a channel.
+This must be unique in a *Guild*.
+
+## Message ID
+
+A `uint64` ID. Represents a message.
+This must be unique in a channel.
+
+## Emote Pack ID
+
+A `uint64` ID. Represents an emote pack.
+This must be unique in a server.
+
+## File ID
+
+A `string` ID. Represents a file on a server.
+This must be unique in a server.
+
+For clients, this means that they should download
+from the server they got the file ID from.
+
+## HarMony Content (HMC)
+
+A URL in the format `hmc://server:port/id`.
+Represents a file on a server.
+
+- The `server` part is the domain of the server and must always be provided.
+- The `id` part is a file ID and must always be provided.
+- The `port` part is the port and must always be provided.

stable/auth/v1/auth.proto

@@ -19,23 +19,21 @@ message BeginAuthRequest {
   optional string for_guest_token = 1;
 }
 
-// BeginAuthResponse
 // The return type of BeginAuth, containing the
 // auth_id that will be used for the authentication
-// section
+// section.
 message BeginAuthResponse {
-  // auth_id: the ID of this auth session
+  // auth_id: the ID of this auth session.
   string auth_id = 1;
 }
 
-// Session
 // Session contains the information for a new session;
 // the user_id you logged in as and the session_token
-// which should be passed to authorisation
+// which should be passed to authorisation.
 message Session {
-  // user_id: the ID of the user you logged in as
+  // user_id: the ID of the user you logged in as.
   uint64 user_id = 1;
-  // session_token: the session token to use in authorization
+  // session_token: the session token to use in authorization.
   string session_token = 2;
   // A token allowing for this account to be upgraded to a
   // "full" account by beginning an auth session and providing
@@ -55,28 +53,25 @@ message Session {
   optional string guest_token = 3;
 }
 
-// AuthStep
-// A step in the authentication process
-// Contains a variety of different types of views
+// A step in the authentication process.
+// Contains a variety of different types of views.
+//
 // It is recommended to have a fallback_url specified
-// For non-trivial authentication procedures (such as captchas)
+// for non-trivial authentication procedures (such as captchas).
 message AuthStep {
-  // Choice
   // A step which allows the user to choose from a range of options
-  // Allows you to show a heading by specifying title
+  // Allows you to show a heading by specifying title.
   message Choice {
-    // title: the title of the list of choices
+    // title: the title of the list of choices.
     string title = 1;
     // options: a list of choices, one of these
-    // should be sent in nextstep
+    // should be sent in nextstep.
     repeated string options = 2;
   }
 
-  // Form
   // A step which requires the user to input information
-  // Allows you to show a heading by specifying title
+  // Allows you to show a heading by specifying title.
   message Form {
-    // FormField
     // A field in the form, containing information on how it should
     // be rendered
     // Here is a list of form types that need to be supported:
@@ -86,128 +81,125 @@ message AuthStep {
     // text: a field type that has to contain text
     // number: a field type that has to contain a number
     message FormField {
-      // name: the identifier for the form field
+      // name: the identifier for the form field.
       string name = 1;
-      // type: the type of the form field, as documented above
+      // type: the type of the form field, as documented above.
       string type = 2;
     }
 
-    // title: the title of this form
+    // title: the title of this form.
     string title = 1;
 
-    // fields: all the fields in this form
+    // fields: all the fields in this form.
     repeated FormField fields = 2;
   }
 
   // Waiting
   // A step which requires the user to perform an external action
   // The title and description should explain to the user
-  // what they should do to complete this step
+  // what they should do to complete this step.
   message Waiting {
-    // title: the title of this waiting screen
+    // title: the title of this waiting screen.
     string title = 1;
-    // description: the explanation of what's being waited on
+    // description: the explanation of what's being waited on.
     string description = 2;
   }
 
-  // fallback_url: unused
+  // fallback_url: unused.
   string fallback_url = 1;
   // can_go_back: whether or not the client can request the
-  // server to send the previous step
+  // server to send the previous step.
   bool can_go_back = 2;
 
   // step: the current step
   oneof step {
-    // choice: the user must pick a thing out of a list of options
+    // choice: the user must pick a thing out of a list of options.
     Choice choice = 3;
-    // form: the user must complete a form
+    // form: the user must complete a form.
     Form form = 4;
-    // session: you've completed auth, and have a session
+    // session: you've completed auth, and have a session.
     Session session = 5;
-    // waiting: you're waiting on something
+    // waiting: you're waiting on something.
     Waiting waiting = 6;
   }
 }
 
-// NextStepRequest
 // contains the client's response to the server's challenge
 // This needs to be called first with no arguments to
-// receive the first step
+// receive the first step.
 message NextStepRequest {
   // auth_id: the authentication session you want
-  // the next step of
+  // the next step of.
   string auth_id = 1;
 
-  // A simple choice string indicating which option the user chose
+  // A simple choice string indicating which option the user chose.
   message Choice {
-    // choice: the choice the user picked
+    // choice: the choice the user picked.
     string choice = 1;
   }
 
   // Form fields can either be bytes, string, or int64.
   message FormFields {
-    // field: the data for a form field
+    // field: the data for a form field.
     oneof field {
-      // bytes: the form field's data is a byte array
+      // bytes: the form field's data is a byte array.
       bytes bytes = 1;
-      // string: the form field's data is a string
+      // string: the form field's data is a string.
       string string = 2;
-      // number: the form field's data is a number
+      // number: the form field's data is a number.
       int64 number = 3;
     }
   }
 
-  // An array of form fields, in the same order they came in from the server
+  // An array of form fields, in the same order they came in from the server.
   message Form {
-    // fields: the fields the user filled out
+    // fields: the fields the user filled out.
     repeated FormFields fields = 1;
   }
 
-  // step: the user's response to a step
+  // step: the user's response to a step.
   oneof step {
-    // choice: the choice the user picked
+    // choice: the choice the user picked.
     Choice choice = 2;
-    // form: the form the user filled out
+    // form: the form the user filled out.
     Form form = 3;
   }
 }
 
 // Used in `NextStep` endpoint.
 message NextStepResponse {
-  // step: the next step in the authentication process
+  // step: the next step in the authentication process.
   AuthStep step = 1;
 }
 
-// StepBackRequest
-// A request to go back 1 step
+// A request to go back 1 step.
 message StepBackRequest {
   // auth_id: the authentication session the user
-  // wants to go back in
+  // wants to go back in.
   string auth_id = 1;
 }
 // Used in `StepBack` endpoint.
 message StepBackResponse {
-  // step: the previous step in the authentication process
+  // step: the previous step in the authentication process.
   AuthStep step = 1;
 }
 
-// StreamStepsRequest
 // Required to be initiated by all authenticating clients
-// Allows the server to send steps
+// Allows the server to send steps.
 message StreamStepsRequest {
   // auth_id: the authorization session
-  // who's steps you want to stream
+  // who's steps you want to stream.
   string auth_id = 1;
 }
 // Used in `StreamSteps` endpoint.
 message StreamStepsResponse {
-  // step: the next step in the authentication process
+  // step: the next step in the authentication process.
   AuthStep step = 1;
 }
 
 // The request to federate with a foreign server.
 message FederateRequest {
-  // The server ID foreign server you want to federate with
+  // The server ID foreign server you want to federate with.
   string server_id = 1;
 }
 
@@ -229,8 +221,8 @@ message KeyResponse {
   bytes key = 1;
 }
 
-// Log into a foreignserver using a token
-// from your homeserver, obtained through a FederateRequest
+// Log into a foreignserver using a token from your homeserver,
+// obtained through a FederateRequest.
 message LoginFederatedRequest {
   // A `harmonytypes.v1.Token` whose `data` field is a serialized `TokenData` message.
   // It is signed with the homeserver's private key.
@@ -254,7 +246,7 @@ message TokenData {
   string server_id = 2;
   // The username of the client.
   string username = 3;
-  // The avatar of the client.
+  // The avatar of the client. This must be a HMC that points to an image.
   optional string avatar = 4;
 }
 
@@ -288,28 +280,26 @@ message CheckLoggedInResponse {}
 //
 // TODO: finish
 
-// The service containing authorization/entication methods
+// The service containing authorization/entication methods.
 service AuthService {
   // Federate with a foreignserver, obtaining a token
-  // you can use to call LoginFederated on it
+  // you can use to call LoginFederated on it.
   rpc Federate(FederateRequest) returns (FederateResponse);
   // Present a token to a foreignserver from a Federate call
-  // on your homeserver in order to login
+  // on your homeserver in order to login.
   rpc LoginFederated(LoginFederatedRequest) returns (LoginFederatedResponse);
-  // Returns the public key of this server
+  // Returns the public key of this server.
   rpc Key(KeyRequest) returns (KeyResponse);
-  // Begins an authentication session
+  // Begins an authentication session.
   rpc BeginAuth(BeginAuthRequest) returns (BeginAuthResponse);
   // Goes to the next step of the authentication session,
-  // possibly presenting user input
+  // possibly presenting user input.
   rpc NextStep(NextStepRequest) returns (NextStepResponse);
-  // Goes to the previous step of the authentication session
-  // if possible
+  // Goes to the previous step of the authentication session if possible.
   rpc StepBack(StepBackRequest) returns (StepBackResponse);
-  // Consume the steps of an authentication session
-  // as a stream
+  // Consume the steps of an authentication session as a stream.
   rpc StreamSteps(StreamStepsRequest) returns (stream StreamStepsResponse);
-  // Check whether or not you're logged in and the session is valid
+  // Check whether or not you're logged in and the session is valid.
   rpc CheckLoggedIn(CheckLoggedInRequest) returns (CheckLoggedInResponse) {
     option (harmonytypes.v1.metadata).requires_authentication = true;
     option (harmonytypes.v1.metadata).requires_permission_node = "";

stable/batch/v1/batch.proto

@@ -36,14 +36,42 @@ message BatchSameResponse {
 }
 
 // Service to batch requests.
+//
+// Note that:
+//
+// - This does not support batching stream requests.
+// - Responses will be returned in the order the requests were given.
+// - If an error occurs, the endpoint will short-circuit and return
+// an error.
+//
+// Not all endpoints can be batched. A list of endpoints that can be
+// batched is given below:
+//
+// - Endpoints that do not modify data:
+//   - "protocol.profile.v1.ProfileService.GetProfile"
+//   - "protocol.chat.v1.ChatService.QueryHasPermission"
+//   - "protocol.chat.v1.ChatService.GetUserRoles"
+//   - "protocol.chat.v1.ChatService.GetGuildRoles"
+//   - "protocol.chat.v1.ChatService.GetGuild"
+//   - "protocol.chat.v1.ChatService.GetGuildChannels"
+//   - "protocol.chat.v1.ChatService.GetPermissions"
+//   - "protocol.chat.v1.ChatService.GetGuildMembers"
+//   - "protocol.mediaproxy.v1.MediaProxyService.FetchLinkMetadata"
+//   - "protocol.mediaproxy.v1.MediaProxyService.InstantView"
+//   - "protocol.mediaproxy.v1.MediaProxyService.CanInstantView"
 service BatchService {
   // Batch requests.
-  // Does not support batching stream requests.
-  // Batched requests should be verified and an error should be thrown if they
-  // are invalid.
+  //
+  // Servers should limit the amount of requests that can be batched
+  // to 20.
   rpc Batch(BatchRequest) returns (BatchResponse) {}
-  // BatchSame allows batching for requests using the same endpoint.
+  // Allows batching for requests using the same endpoint.
+  //
   // This allows for additional network optimizations since the endpoint doesn't
   // have to be sent for every request.
+  //
+  // Servers should limit the amount of requests that can be batched
+  // to 100 for endpoints that do not modify data, and 20 for endpoints
+  // that modify data.
   rpc BatchSame(BatchSameRequest) returns (BatchSameResponse) {}
 }