From 966e4c6211d9ca64973e847938e9cc1edce03dd1 Mon Sep 17 00:00:00 2001 From: zaaarf Date: Thu, 5 Sep 2024 00:08:07 +0200 Subject: [PATCH] docs: written docs Co-authored-by: alemi --- README.md | 11 +++++++++++ proto/auth.proto | 12 +++++++++--- proto/buffer.proto | 9 +++++++-- proto/common.proto | 11 ++++++++--- proto/cursor.proto | 22 ++++++++++++---------- proto/files.proto | 4 ++++ proto/session.proto | 15 ++++++++++++++- proto/workspace.proto | 25 +++++++++++++++++++++++-- src/lib.rs | 13 +++++++++++++ 9 files changed, 101 insertions(+), 21 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..938876d --- /dev/null +++ b/README.md @@ -0,0 +1,11 @@ +

codemp logo

+ +# 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). diff --git a/proto/auth.proto b/proto/auth.proto index 67d43b6..1f79acc 100644 --- a/proto/auth.proto +++ b/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; } diff --git a/proto/buffer.proto b/proto/buffer.proto index 826bc9b..6947e8b 100644 --- a/proto/buffer.proto +++ b/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; } diff --git a/proto/common.proto b/proto/common.proto index 3a48a39..172fc7f 100644 --- a/proto/common.proto +++ b/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 { } diff --git a/proto/cursor.proto b/proto/cursor.proto index 93a1592..320de1d 100644 --- a/proto/cursor.proto +++ b/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; } diff --git a/proto/files.proto b/proto/files.proto index 5df3461..055ea72 100644 --- a/proto/files.proto +++ b/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; } diff --git a/proto/session.proto b/proto/session.proto index d6099c9..39996c1 100644 --- a/proto/session.proto +++ b/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; } diff --git a/proto/workspace.proto b/proto/workspace.proto index b5fcee7..712a3f5 100644 --- a/proto/workspace.proto +++ b/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; diff --git a/src/lib.rs b/src/lib.rs index de32518..546d3d7 100644 --- a/src/lib.rs +++ b/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"); }