docs: written docs

Co-authored-by: alemi <me@alemi.dev>

README.md

@@ -0,0 +1,11 @@
+<p align="center"><a href="https://github.com/hexedtech/codemp"><img alt="codemp logo" src="https://codemp.dev/static/codemp-banner.png" height="100"/></a></p>
+
+# Protocol
+gRPC protocol specification for [codemp](https://github.com/hexedtech/codemp).
+
+This is a [prost](https://github.com/tokio-rs/prost) crate: it will generated Rust code based on the protobuf defintions contained in the `proto/` directory.
+
+From protobuf definition, `prost` will compile structs for all protocol messages but also server and client service implementations.
+
+## Building
+To compile this crate, `protoc` must be installed: [`prost` requires it to compile the protocol definition](https://docs.rs/prost/latest/prost/#protoc).

proto/auth.proto

@@ -4,21 +4,27 @@ package auth;
 
 import "common.proto";
 
-// service entrypoint, authenticate users and grant initial token
+// Server entrypoint, authenticates users and grants initial session token.
 service Auth {
-	// send credentials, returns empty valid token
+	// Send credentials, returns valid session token.
 	rpc Login (LoginRequest) returns (LoginResponse);
 
-	// if given token has just expired, get a new valid one
+	// If the given token has recently expired, get a new valid one.
 	rpc Refresh (common.Token) returns (common.Token);
 }
 
+// The login request message.
 message LoginRequest {
+	// The username to log in with.
 	required string username = 1;
+	// The password to log in with.
 	required string password = 2;
 }
 
+// The login response message.
 message LoginResponse {
+	// The newly created session token.
 	required common.Token token = 1;
+	// The user profile that has been authenticated.
 	required common.User user = 2;
 }

proto/buffer.proto

@@ -4,17 +4,22 @@ import "common.proto";
 
 package buffer;
 
-// handle buffer changes, keep in sync users
+// Handles buffer changes and keeps users in sync.
 service Buffer {
-	// attach to a buffer and receive operations
+	// Attach to a buffer and receive operations.
 	rpc Attach (stream Operation) returns (stream BufferEvent);
 }
 
+// Message representing an operation that has occurred.
 message Operation {
+	// The data of this operation.
 	required bytes data = 1;
 }
 
+// Message representing an event that happened in a buffer.
 message BufferEvent {
+	// The operation that occurred.
 	required Operation op = 1;
+	// The user that sent this event.
 	required common.Identity user = 2;
 }

proto/common.proto

@@ -2,21 +2,26 @@ syntax = "proto2";
 
 package common;
 
-// authentication token, probably a JWT but should be treated as a raw string
+// The authentication token, as a string.
 message Token {
 	required string token = 1;
 }
 
-// a wrapper payload representing an uuid
+// Message representing a UUID.
 message Identity {
+	// The most significant bits of the UUID.
 	required uint64 hi = 1;
+	// The least significant bits of the UUID.
 	required uint64 lo = 2;
 }
 
+// Message representing a user.
 message User {
+	// The UUID of the user.
 	required Identity id = 1;
+	// The name of a user.
 	required string name = 2;
 }
 
-// generic Empty message
+// A generic empty message.
 message Empty { }

proto/cursor.proto

@@ -4,32 +4,34 @@ package cursor;
 import "common.proto";
 import "files.proto";
 
-// handle cursor events and broadcast to all users
+// Handles cursor events and broadcasts them to all users.
 service Cursor {
-	// subscribe to a workspace's cursor events
+	// Subscribe to a workspace's cursor events.
 	rpc Attach (stream cursor.CursorPosition) returns (stream cursor.CursorEvent);
 }
 
-// a tuple indicating row and column
+// A message representing a position in a buffer.
 message RowCol {
+	// The row.
 	required int32 row = 1;
+	// The column.
 	required int32 col = 2;
 }
 
-// cursor position object
+// A message representing cursor position.
 message CursorPosition {
-	// path of current buffer this cursor is into
+	// The buffer where the cursor is located.
 	required files.BufferNode buffer = 1;
-	// cursor start position
+	// The cursor's start position.
 	required RowCol start = 2;
-	// cursor end position
+	// The cursor's end position.
 	required RowCol end = 3;
 }
 
-// cursor event, with user id and cursor position
+// A message representing a cursor event.
 message CursorEvent {
-	// user moving the cursor
+	// The user moving the cursor.
 	required common.Identity user = 1;
-	// new cursor position
+	// The new cursor position.
 	required CursorPosition position = 2;
 }

proto/files.proto

@@ -2,10 +2,14 @@ syntax = "proto2";
 
 package files;
 
+// A message representing a node in the filetree.
 message BufferNode {
+	// The path of a buffer.
 	required string path = 1;
 }
 
+// A message representing a filetree.
 message BufferTree {
+	// A vector of buffer nodes.
 	repeated BufferNode buffers = 1;
 }

proto/session.proto

@@ -4,25 +4,38 @@ package session;
 
 import "common.proto";
 
-// manage user workspaces, refresh tokens
+// Manages user workspaces and refreshes tokens.
 service Session {
+	// Handle a workspace access request and return a workspace token.
 	rpc AccessWorkspace (WorkspaceRequest) returns (common.Token);
+	// Create a workspace.
 	rpc CreateWorkspace (WorkspaceRequest) returns (common.Empty);
+	// Delete a workspace.
 	rpc DeleteWorkspace (WorkspaceRequest) returns (common.Empty);
+	// List all available workspaces.
 	rpc ListWorkspaces (common.Empty) returns (WorkspaceList);
+	// Handle a workspace invite request.
 	rpc InviteToWorkspace (InviteRequest) returns (common.Empty);
 }
 
+// A message representing a request for specific workspace.
 message WorkspaceRequest {
+	// The name of the workspace.
 	required string workspace = 1;
 }
 
+// A message representing a list of workspaces.
 message WorkspaceList {
+	// A vector of workspaces owned by the user.
 	repeated string owned = 1;
+	// A vector of workspaces the user is invited to.
 	repeated string invited = 2;
 }
 
+// A message representing an invitation to a workspace.
 message InviteRequest {
+	// The user the invitation is for.
 	required string user = 1;
+	// the workspace the invitation is for
 	required string workspace = 2;
 }

proto/workspace.proto

@@ -5,40 +5,61 @@ package workspace;
 import "common.proto";
 import "files.proto";
 
+// Handles workspace state management.
 service Workspace {
+	// Attach to a workspace.
 	rpc Attach (common.Empty) returns (stream WorkspaceEvent);
-
+	// Create a buffer within the workspace.
 	rpc CreateBuffer (files.BufferNode) returns (common.Empty);
+	// Access a buffer within the workspace and returns a buffer token for it.
 	rpc AccessBuffer (files.BufferNode) returns (common.Token);
+	// Delete a buffer.
 	rpc DeleteBuffer (files.BufferNode) returns (common.Empty);
-
+	// List buffers in the workspace.
 	rpc ListBuffers (common.Empty) returns (files.BufferTree); 
+	// List users in the workspace.
 	rpc ListUsers (common.Empty) returns (UserList);
+	// List users within a given buffer.
 	rpc ListBufferUsers (files.BufferNode) returns (UserList);
 }
 
+// A message representing a list of users.
 message UserList {
+	// A vector of users.
 	repeated common.User users = 1;
 }
 
+// A message representing a workspace event.
 message WorkspaceEvent {
+	// Event that occurs when a user joins a workspace.
 	message UserJoin {
+		// The user that joined.
 		required common.User user = 1;
 	}
+	// Event that occurs when a user leaves a workspace.
 	message UserLeave {
+		// The user that left.
 		required common.User user = 1;
 	}
+	// Event that occurs when a file is created in a workspace.
 	message FileCreate {
+		// The path of the created file.
 		required string path = 1;
 	}
+	// Event that occurs when a file is renamed in a workspace.
 	message FileRename {
+		// The old path of the file.
 		required string before = 1;
+		// The new path of the file.
 		required string after = 2;
 	}
+	// Event that occurs when a file is deleted in a workspace.
 	message FileDelete {
+		// The path of the deleted file
 		required string path = 1;
 	}
 
+	// The union containing actual event.
 	oneof event {
 		UserJoin join = 1;
 		UserLeave leave = 2;

src/lib.rs

@@ -1,3 +1,10 @@
+//! # CodeMP Protocol - cooperative development
+//! `codemp-proto` is the gRPC protocol specification powering [`codemp`](https://codemp.dev).
+//!
+//! This is built on top of [tonic] and provides both clientside and serverside service
+//! implementations.
+
+/// common types across services
 #[allow(non_snake_case)]
 pub mod common {
 	tonic::include_proto!("common");
@@ -35,6 +42,7 @@ pub mod common {
 	}
 }
 
+/// filetree related types
 pub mod files {
 	tonic::include_proto!("files");
 
@@ -59,10 +67,12 @@ pub mod files {
 	}
 }
 
+/// buffer synchronisation protocol types and procedures
 pub mod buffer {
 	tonic::include_proto!("buffer");
 }
 
+/// cursor position protocol types and procedures
 pub mod cursor {
 	tonic::include_proto!("cursor");
 
@@ -89,14 +99,17 @@ pub mod cursor {
 	}
 }
 
+/// workspace state protocol types and procedures
 pub mod workspace {
 	tonic::include_proto!("workspace");
 }
 
+/// session management protocol types and procedures
 pub mod session {
 	tonic::include_proto!("session");
 }
 
+/// authentication and authorization protocol types and procedures
 pub mod auth {
 	tonic::include_proto!("auth");
 }