docs: finalize rvbox v1 design and implementation plan

docs/examples/server.toml

@@ -0,0 +1,109 @@
+# RVBox v1 server example. Integer sizes are bytes; durations are quoted strings.
+
+[server]
+# Durable SQLite, command payload, output, audit, and incident root.
+data_dir = "/var/lib/rvbox-server"
+# HTTP listener receiving WebSocket upgrades from nginx.
+agent_listen = "127.0.0.1:6899"
+# Exact WebSocket request path accepted on agent_listen.
+agent_path = "/v1/agent"
+# Local gRPC control socket used by rvc; RVBox forces mode 0600.
+control_socket = "/run/rvbox/server.sock"
+# Grace allowed for daemon workers to finish reserved closeout on shutdown.
+shutdown_grace = "30s"
+
+[json_rpc]
+# Enable the intentionally unauthenticated JSON-RPC debugging adapter.
+enabled = false
+# HTTP bind for JSON-RPC; non-loopback use emits a prominent warning.
+listen = "127.0.0.1:6900"
+
+[queue]
+# Default wait for server-confirmed client acceptance; "0s" means indefinite.
+default_ttl = "15m"
+# Maximum server-side queued commands for one client before rejection.
+max_per_client = 1000
+# Maximum server-side queued commands across all clients before rejection.
+max_server = 10000
+# Initial delay after a transient client rejection before redispatch.
+retry_initial = "1s"
+# Maximum full-jitter delay after repeated transient client rejection.
+retry_max = "30s"
+
+[storage]
+# Maximum rolling compressed output retained for one command (10 MiB).
+command_output_limit_bytes = 10485760
+# Maximum charged data, including metadata/script/stdin/output, per command (32 MiB).
+command_total_limit_bytes = 33554432
+# Maximum charged command data for one target client on the server (256 MiB).
+client_total_limit_bytes = 268435456
+# Maximum charged command data across the server, excluding audit/tombstones (4 GiB).
+server_total_limit_bytes = 4294967296
+# Reclaim whole terminal commands after this age; "0s" disables age rotation.
+terminal_retention = "720h"
+# Separate compressed audit plus resolved-incident history budget (100 MiB).
+audit_limit_bytes = 104857600
+# Optional audit age rotation; "0s" keeps entries until the byte budget rolls them.
+audit_retention = "0s"
+# Compact global completed-command replay ledger entry cap.
+tombstone_max_entries = 1000000
+# Per-active-command quota held for terminal and loss metadata (64 KiB).
+command_closeout_reserve_bytes = 65536
+# Reject new unreserved writes below this filesystem free space (256 MiB).
+free_space_floor_bytes = 268435456
+# Target size for a sealed append-only payload/output segment (256 KiB).
+segment_target_bytes = 262144
+# Maximum time a group-commit waits before fsync; acknowledgements wait too.
+durability_interval = "100ms"
+# SQLite busy timeout before an operation returns a transient error.
+sqlite_busy_timeout = "5s"
+# Maximum operator incident acknowledgement note encoded as UTF-8 (4 KiB).
+incident_note_max_bytes = 4096
+# Maximum protocol error/detail/reason text encoded as UTF-8 (4 KiB).
+protocol_detail_max_bytes = 4096
+
+[flow]
+# Stop admitting raw server validation/persistence work at this backlog (64 MiB).
+raw_output_high_bytes = 67108864
+# Leave raw-output loss mode only below this backlog (32 MiB).
+raw_output_low_bytes = 33554432
+# Maximum assigned but unacknowledged encoded bytes per command (1 MiB).
+unacknowledged_per_command_bytes = 1048576
+# Maximum assigned but unacknowledged encoded bytes per client session (8 MiB).
+unacknowledged_per_session_bytes = 8388608
+# Deadline for an individual WebSocket data-frame write.
+write_deadline = "10s"
+
+[protocol]
+# Send WebSocket Ping after this period without inbound activity.
+heartbeat_idle = "10s"
+# Close a session after this total period without inbound activity.
+liveness_timeout = "30s"
+# One-shot live client-instance collision override lifetime.
+takeover_ttl = "5m"
+# Hard decoded AgentEnvelope ceiling (1 MiB).
+max_agent_envelope_bytes = 1048576
+# Hard serialized ExecutionSpec ceiling (768 KiB).
+max_execution_spec_bytes = 786432
+# Hard uncompressed stdout/stderr chunk ceiling (64 KiB).
+max_raw_chunk_bytes = 65536
+# Hard raw uploaded-script ceiling (10 MiB).
+max_script_bytes = 10485760
+# Hard decoded local gRPC request ceiling (16 MiB).
+max_control_request_bytes = 16777216
+# Hard JSON-RPC HTTP body ceiling including base64 expansion (24 MiB).
+max_json_rpc_body_bytes = 25165824
+
+[observability]
+# Loopback HTTP listener for liveness, readiness, and Prometheus metrics.
+listen = "127.0.0.1:6901"
+# Liveness route, available before asynchronous storage recovery completes.
+liveness_path = "/livez"
+# Readiness route; false while required storage scopes are unavailable.
+readiness_path = "/readyz"
+# Prometheus metrics route.
+metrics_path = "/metrics"
+# Structured logging threshold: debug, info, warn, or error.
+log_level = "info"
+# Structured log encoding: json or text.
+log_format = "json"