docs: finalize rvbox v1 design and implementation plan

docs/examples/client.toml

@@ -0,0 +1,205 @@
+# RVBox v1 client example. Integer sizes are bytes; durations are quoted strings.
+
+[client]
+# Reverse WebSocket endpoint exposed by nginx.
+server_url = "wss://rvbox.example.test/v1/agent"
+# Private durable accepted-command, event-spool, and tombstone root.
+state_dir = "/var/lib/rvbox"
+# Empty selects the local hostname; otherwise use an opaque 1-128 ASCII ID.
+client_id = ""
+# Default absolute CWD when a request omits cwd.
+daemon_cwd = "/"
+# Maximum simultaneously running supervised process trees.
+max_running_commands = 16
+# Maximum durably accepted commands waiting to start.
+max_queued_commands = 100
+# Grace for reserved terminal cleanup during orderly daemon shutdown.
+shutdown_grace = "30s"
+
+[tls]
+# Optional PEM CA bundle; empty uses the operating-system trust store.
+ca_file = ""
+# Optional certificate name override; empty derives it from server_url.
+server_name = ""
+
+[shells]
+# Default shell enum on Unix; the matching path must validate at startup.
+default_unix = "sh"
+# Default shell enum on Windows; the matching path must validate at startup.
+default_windows = "powershell"
+# Absolute executable used for SHELL_SH; empty marks it unsupported.
+sh = "/bin/sh"
+# Absolute executable used for SHELL_BASH; empty marks it unsupported.
+bash = "/bin/bash"
+# Absolute executable used for SHELL_CMD on Windows; empty marks it unsupported.
+cmd = "C:\\Windows\\System32\\cmd.exe"
+# Absolute executable used for SHELL_POWERSHELL; may instead point to pwsh.exe.
+powershell = "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
+# Absolute CWD roots permitted by local policy; empty allows any accessible path.
+allowed_cwd_roots = []
+
+[network]
+# Send WebSocket Ping after this period without inbound activity.
+heartbeat_idle = "10s"
+# Close and reconnect after this total period without inbound activity.
+liveness_timeout = "30s"
+# Initial full-jitter reconnect backoff.
+reconnect_initial = "1s"
+# Maximum full-jitter reconnect backoff.
+reconnect_max = "60s"
+# Continuous session duration that resets reconnect backoff.
+stable_session_reset = "60s"
+# Timeout for DNS/TCP/TLS/WebSocket establishment.
+connect_timeout = "15s"
+# Deadline for an individual WebSocket data-frame write.
+write_deadline = "10s"
+
+[storage]
+# Maximum rolling compressed output retained for one command (10 MiB).
+command_output_limit_bytes = 10485760
+# Maximum charged data, including raw execution wrapper, per command (32 MiB).
+command_total_limit_bytes = 33554432
+# Maximum charged command data across this client daemon (256 MiB).
+client_total_limit_bytes = 268435456
+# Compact 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 (64 MiB).
+free_space_floor_bytes = 67108864
+# Target size for a sealed append-only spool segment (256 KiB).
+segment_target_bytes = 262144
+# Maximum time a group-commit waits before fsync; acknowledgements wait too.
+durability_interval = "100ms"
+
+[flow]
+# Enter per-command raw-output loss mode at this backlog (1 MiB).
+raw_output_command_high_bytes = 1048576
+# Leave per-command raw-output loss mode below this backlog (256 KiB).
+raw_output_command_low_bytes = 262144
+# Enter client-wide raw-output loss mode at this backlog (8 MiB).
+raw_output_client_high_bytes = 8388608
+# Leave client-wide raw-output loss mode below this backlog (4 MiB).
+raw_output_client_low_bytes = 4194304
+# Maximum assigned but unacknowledged encoded bytes per command (1 MiB).
+unacknowledged_per_command_bytes = 1048576
+# Maximum assigned but unacknowledged encoded bytes for the session (8 MiB).
+unacknowledged_per_session_bytes = 8388608
+
+[execution]
+# Wait after root exit for descendants and capture EOF before forced cleanup.
+descendant_drain_grace = "5s"
+# Wait after Windows CTRL_BREAK before terminating the complete Job Object.
+windows_term_grace = "10s"
+# Mark suspected_hung after no observable progress for this duration.
+hung_threshold = "10m"
+# Interval for best-effort process/resource diagnostic snapshots.
+diagnostic_interval = "30s"
+# Maximum raw uploaded script or generated script body (10 MiB).
+max_script_bytes = 10485760
+# Maximum serialized command ExecutionSpec accepted from the server (768 KiB).
+max_execution_spec_bytes = 786432
+# Maximum decoded AgentEnvelope accepted from the server (1 MiB).
+max_agent_envelope_bytes = 1048576
+# Maximum uncompressed stdout/stderr chunk emitted to the protocol (64 KiB).
+max_raw_chunk_bytes = 65536
+# Maximum protocol detail/reason text encoded as UTF-8 (4 KiB).
+protocol_detail_max_bytes = 4096
+
+[observability]
+# Loopback HTTP listener for local liveness, storage, and supervisor health.
+listen = "127.0.0.1:6902"
+# Liveness route.
+liveness_path = "/livez"
+# Readiness route; false while reconciliation or essential recovery is pending.
+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"
+
+# Resource profiles are administrator policy. These illustrative values are not
+# protocol guarantees. LIGHT is exclusive; otherwise combine at most one tier
+# from each cpu_*, mem_*, and disk_* family.
+
+[profiles.light]
+# Advertise this profile when all required controls validate.
+enabled = true
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["cpu", "memory", "pids"]
+# CPU allowance as percent of one logical CPU; zero omits CPU control.
+cpu_percent = 50
+# Hard resident/commit memory allowance (512 MiB); zero omits memory control.
+memory_max_bytes = 536870912
+# Maximum processes in the supervised tree; zero omits process-count control.
+pids_max = 64
+# Windows whole-Job read rate; zero omits it.
+windows_io_read_bps = 0
+# Windows whole-Job write rate; zero omits it.
+windows_io_write_bps = 0
+# Linux cgroup read rates keyed by device major:minor.
+linux_io_read_bps = {}
+# Linux cgroup write rates keyed by device major:minor.
+linux_io_write_bps = {}
+
+[profiles.cpu_medium]
+# Advertise the CPU_MEDIUM allowance class.
+enabled = true
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["cpu"]
+# CPU allowance as percent of one logical CPU.
+cpu_percent = 200
+
+[profiles.cpu_heavy]
+# Advertise the CPU_HEAVY allowance class.
+enabled = true
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["cpu"]
+# CPU allowance as percent of one logical CPU.
+cpu_percent = 800
+
+[profiles.mem_medium]
+# Advertise the MEM_MEDIUM allowance class.
+enabled = true
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["memory"]
+# Hard memory allowance (2 GiB).
+memory_max_bytes = 2147483648
+
+[profiles.mem_heavy]
+# Advertise the MEM_HEAVY allowance class.
+enabled = true
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["memory"]
+# Hard memory allowance (8 GiB).
+memory_max_bytes = 8589934592
+
+[profiles.disk_medium]
+# Advertise DISK_MEDIUM only after device/rate controls validate.
+enabled = false
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["io"]
+# Windows whole-Job read bandwidth allowance (100 MiB/s).
+windows_io_read_bps = 104857600
+# Windows whole-Job write bandwidth allowance (50 MiB/s).
+windows_io_write_bps = 52428800
+# Linux cgroup read allowances; replace 8:0 with an actual delegated device.
+linux_io_read_bps = { "8:0" = 104857600 }
+# Linux cgroup write allowances; replace 8:0 with an actual delegated device.
+linux_io_write_bps = { "8:0" = 52428800 }
+
+[profiles.disk_heavy]
+# Advertise DISK_HEAVY only after device/rate controls validate.
+enabled = false
+# Controls that must be applied atomically or the request is rejected.
+required_controls = ["io"]
+# Windows whole-Job read bandwidth allowance (500 MiB/s).
+windows_io_read_bps = 524288000
+# Windows whole-Job write bandwidth allowance (250 MiB/s).
+windows_io_write_bps = 262144000
+# Linux cgroup read allowances; replace 8:0 with an actual delegated device.
+linux_io_read_bps = { "8:0" = 524288000 }
+# Linux cgroup write allowances; replace 8:0 with an actual delegated device.
+linux_io_write_bps = { "8:0" = 262144000 }