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,58 @@
+# RVBox v1 control plane
+
+[`../protos/rvbox/v1/control.proto`](../protos/rvbox/v1/control.proto) defines
+the canonical control API. `rvc` uses the `Control` gRPC service over the local
+Unix-domain socket. The server also exposes the same unary operations through
+an optional JSON-RPC 2.0 HTTP adapter for local debugging and batch automation.
+
+## Endpoints
+
+- Unix socket: enabled by default, mode `0600`, owned by the server account.
+- HTTP JSON-RPC: disabled unless enabled; default bind `127.0.0.1:6900`.
+  It has no authentication by design. Binding it beyond loopback is an explicit
+  deployment choice and requires external protection.
+
+gRPC can stream `RunCommandAndFollow` and `FollowCommand`. JSON-RPC remains
+simple: callers issue work, query command state, poll event/output pages after
+an event sequence, append stdin, close stdin, or signal a command. It does not
+invent a separate event-stream protocol.
+
+The JSON-RPC method names are the lower-camel protobuf operation names:
+`listClients`, `getClient`, `listCommands`, `getCommand`, `runCommand`,
+`appendStdin`, `closeStdin`, `signalCommand`, and `getOutput`. Parameters and
+results use protobuf JSON mapping (including base64 strings for `bytes` and UTC
+RFC 3339 strings for timestamps); JSON-RPC errors carry the corresponding
+`ControlError` code/data. `getOutput` and `getCommand` are the polling path for
+what gRPC exposes as follow streams.
+
+## CLI semantics
+
+`rvc stat` maps to `ListClients`, `GetClient`, `ListCommands`, and `GetCommand`.
+History pages default to 20 commands and may request at most 100. Output pages
+default to 100 lines; a line is a display operation over ordered chunks, not a
+protocol boundary. Output can be filtered by stream and timestamped with the
+server's recorded client-observed timestamp plus stream name.
+
+`rvc run` creates a command. Foreground mode runs `RunCommandAndFollow`, which
+streams output and stops on a terminal event. `--background` uses `RunCommand`
+and returns the UUID immediately. Interrupting the CLI, timing out its local
+wait, or losing the local control connection never cancels remote work. The
+explicit `rvc kill` operation is the only termination path.
+
+`rvc append` turns a string into `StdinWrite` with `append_newline=true` unless
+the caller selects raw mode; `--file` supplies raw bytes; `--attach` streams
+local standard input. `CloseStdin` is available separately. All stdin actions
+are acknowledged and idempotent.
+
+## Query behavior
+
+Command details expose persisted request fields, effective execution metadata,
+lifecycle, terminal result, output availability/truncation, current resource
+snapshot, and `suspected_hung` diagnostics. The latter is informational and
+must not be shown as a terminal state. Pagination response cursors are stable
+within their declared ordering (newest issue time for command lists; increasing
+`event_seq` for events/output).
+
+The service returns `ControlError` codes for not found, offline, capacity,
+invalid request, unsupported platform feature, conflict, truncation, and
+internal/transient errors. It never encodes errors only as CLI text.