docs: add initial RVBox design and protocol contracts

2026-08-21 09:02:57 +00:00
commit 97c2d5cf45
10 changed files with 1138 additions and 0 deletions
@@ -0,0 +1,148 @@
+syntax = "proto3";
+
+package rvbox.v1;
+
+option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";
+
+import "rvbox/v1/common.proto";
+
+service Control {
+  rpc ListClients(ListClientsRequest) returns (ListClientsResponse);
+  rpc GetClient(GetClientRequest) returns (GetClientResponse);
+  rpc ListCommands(ListCommandsRequest) returns (ListCommandsResponse);
+  rpc GetCommand(GetCommandRequest) returns (GetCommandResponse);
+  rpc RunCommand(RunCommandRequest) returns (RunCommandResponse);
+  rpc RunCommandAndFollow(RunCommandRequest) returns (stream CommandEvent);
+  rpc FollowCommand(FollowCommandRequest) returns (stream CommandEvent);
+  rpc AppendStdin(AppendStdinRequest) returns (AppendStdinResponse);
+  rpc CloseStdin(CloseStdinRequest) returns (CloseStdinResponse);
+  rpc SignalCommand(ControlSignalCommandRequest) returns (ControlSignalCommandResponse);
+  rpc GetOutput(GetOutputRequest) returns (GetOutputResponse);
+}
+
+message ClientSummary {
+  string client_id = 1;
+  bool connected = 2;
+  google.protobuf.Timestamp connected_at = 3;
+  google.protobuf.Timestamp last_seen_at = 4;
+  uint32 running_commands = 5;
+  uint32 queued_commands = 6;
+  Platform platform = 7;
+  string architecture = 8;
+  string daemon_version = 9;
+  string daemon_cwd = 10;
+  repeated ShellType supported_shells = 11;
+}
+
+message ListClientsRequest {
+  uint32 page_size = 1;
+  string page_token = 2;
+}
+
+message ListClientsResponse {
+  repeated ClientSummary clients = 1;
+  string next_page_token = 2;
+}
+
+message GetClientRequest {
+  string client_id = 1;
+}
+
+message GetClientResponse {
+  ClientSummary client = 1;
+  ControlError error = 2;
+}
+
+message ListCommandsRequest {
+  string client_id = 1;
+  bool include_terminal = 2;
+  uint32 page_size = 3;
+  string page_token = 4;
+}
+
+message ListCommandsResponse {
+  repeated CommandRecord commands = 1;
+  string next_page_token = 2;
+  ControlError error = 3;
+}
+
+message GetCommandRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+}
+
+message GetCommandResponse {
+  CommandRecord command = 1;
+  ResourceSnapshot latest_resource = 2;
+  ControlError error = 3;
+}
+
+// For script execution, script_content contains the bytes whose descriptor is
+// placed in spec.script. The server chunks it for the Agent protocol.
+message RunCommandRequest {
+  string target_client_id = 1;
+  ExecutionSpec spec = 2;
+  bytes script_content = 3;
+}
+
+message RunCommandResponse {
+  string issue_uuid = 1;
+  CommandLifecycle lifecycle = 2;
+  ControlError error = 3;
+}
+
+message FollowCommandRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+  uint64 after_event_seq = 3;
+  bool include_existing = 4;
+}
+
+message AppendStdinRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+  bytes data = 3;
+  bool append_newline = 4;
+}
+
+message AppendStdinResponse {
+  uint64 write_seq = 1;
+  ControlError error = 2;
+}
+
+message CloseStdinRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+}
+
+message CloseStdinResponse {
+  uint64 write_seq = 1;
+  ControlError error = 2;
+}
+
+message ControlSignalCommandRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+  SignalKind signal = 3;
+}
+
+message ControlSignalCommandResponse {
+  uint64 command_revision = 1;
+  ControlError error = 2;
+}
+
+message GetOutputRequest {
+  string client_id = 1;
+  string issue_uuid = 2;
+  repeated StreamKind streams = 3;
+  uint64 after_event_seq = 4;
+  uint32 page_size = 5;
+}
+
+message GetOutputResponse {
+  repeated CommandEvent events = 1;
+  string next_page_token = 2;
+  bool output_truncated = 3;
+  ControlError error = 4;
+  repeated OutputTruncation truncations = 5;
+}