KangandClaude Opus 5
049a5a4329
The page layout still reflected the Tauri-era docs, where RDP and VNC were a table row and terminal.md absorbed whatever did not have a home. Sidebar: - Drop sidebar_position from all 46 pages. sidebars.ts enumerates every entry explicitly, so the values never affected ordering, and four of them collided (guide had two 2s, three 5s, two 6s, two 8s) while implying an order that did not match the real one. - Reorder the guide by workflow: session types, per-protocol configuration, workspace, terminal, monitoring, files, commands, AI, network, auth, security, appearance, sync, shortcuts. New pages: - guide/rdp.md and guide/vnc.md. RDP and VNC are two of the six session types and had no page of their own. Both document the real config fields, the validation ranges, the certificate/security policies, and the error kinds, and both note the helper-process requirement. - guide/remote-monitoring.md, extracted from terminal.md, covering all five panels. Deduplication: - terminal.md drops from 345 to 253 lines. Its AI, provider, translation, and risk-tier sections restated ai-assistant.md and translation.md; they are now the terminal-specific entry points plus a link. The risk tier table moves to ai-assistant.md, which owns the setting that gates it. - session-types.md keeps the comparison table and links out for RDP/VNC detail instead of carrying a second copy of it. - The migration format list appeared verbatim in four pages. ssh-connection.md is now the single source; installation.md, quick-start.md, and faq.md link to it. - installation.md drops from 112 to 63 lines: its workspace tour, settings checklist, and "suggested first run" were quick-start.md again. Verified with `pnpm --dir docs-site build` (both locales) and by resolving every cross-page anchor against the generated heading ids, since onBrokenAnchors is set to ignore. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.2 KiB
Runtime, Transport, and Storage Development
NyaTerm has no separate Web backend. Domain logic, protocol runtimes, and persistence are split across Rust crates and communicate with the GPUI desktop layer through typed interfaces.
Crate boundaries
| Crate | Behavior it owns |
|---|---|
nyaterm-core |
Pure models, parsing, policies, compatibility formats, schema-neutral serialization |
nyaterm-transport |
PTY, SSH, SFTP, Telnet, Serial, tunnels, remote operations, and transfer runtimes |
nyaterm-store |
redb, transactions, storage workers, encryption adapters, compatibility readers |
nyaterm-terminal |
Terminal state, snapshots, control sequences, encodings, and graphics protocols |
nyaterm-remote-desktop |
RDP/VNC session management, framebuffer and input models, certificate policy, clipboard state, and the helper IPC contracts |
nyaterm-rdp-helper / nyaterm-vnc-helper |
Isolated helper processes owning their protocol decoders |
nyaterm-otp |
HOTP/TOTP compatibility implementation |
Low-level crates do not import GPUI or desktop presentation types. Use a small typed adapter at a boundary instead of pushing application-wide models into transport or storage code.
Protocol decoders that parse server-controlled bytes live only in the helper crates. nyaterm-remote-desktop owns no decoder, and both helpers must translate a decoder panic into a fatal IPC error. See Architecture → RDP / VNC process isolation.
Session and transport runtime
The SessionManager in nyaterm-transport manages active sessions and provides a common lifecycle entry point for local PTY, SSH, Telnet, raw TCP, Serial, RDP, and VNC sessions.
Session output returns through SessionEvent variants:
Output/OutputDroppedCwdChangedCommandAcceptedExitedError
The event queue coalesces and bounds high-throughput output. The desktop drains events in batches instead of allowing background threads to mutate GPUI state. New session events use typed enum variants and include tests for ordering, queue limits, and close behavior.
SSH, SFTP, tunnel, remote-process, and Docker operations also remain asynchronous or run on dedicated workers. Transport code does not depend on windows, dialogs, or desktop feature types.
Terminal runtime
Transport wire bytes enter nyaterm-terminal. That crate maintains the grid, scrollback, modes, OSC marks, search results, and graphics-protocol state, then produces UI-neutral snapshots.
Terminal-semantic keyboard and mouse protocol encoding stays at the terminal/core boundary. Pixel sizing, GPUI key events, and painting stay in nyaterm-terminal-gpui.
StoreRuntime and persistence
nyaterm_store::StoreRuntime owns the database worker. The desktop submits typed StoreRequest implementations through StoreUiClient or StoreBlockingClient, then updates UI state from the task result.
Database implementation is grouped under nyaterm-store/src/storage/. Storage changes preserve:
- Existing redb table names, keys, and document keys
- Serialized field names and unknown-field handling
- Master-key wrapping, encryption prefixes, and fallback decryption
.nyabackups, portable snapshots, and Dragonfly compatibility readers- Existing user data until replacement data has passed validation
Pure compatibility models and policies belong in nyaterm-core; database transactions, file I/O, and compatibility readers belong in nyaterm-store.
AI, sync, and native HTTP
AI providers, translation, cloud sync, and update checks use native HTTP adapters. Request construction, risk policy, and schema-neutral provider settings stay in nyaterm-core where practical. The desktop owns secret masking, interaction state, and task coordination.
Cloud sync treats portable snapshots as a compatibility contract. Pulled data is decrypted, parsed, and validated before it is applied; conflicts, retries, and errors return to the UI as typed results.
Errors and security
Low-level libraries return typed errors, and desktop adapters decide how to present them. Errors, logs, and Debug output must never include passwords, private keys, OTP values, API secrets, or unredacted terminal context.
Background tasks handle cancellation, window closure, and runtime shutdown. On exit, AppShell requests a store flush and shutdown so database writes do not outlive the UI lifecycle.
Tests
- Pure parsing, policy, and compatibility-format tests live in
nyaterm-core. - PTY, SSH, SFTP, Telnet, Serial, tunnel, and event-queue tests live in
nyaterm-transport. - Terminal parsing, snapshots, graphics, and encoding tests live in
nyaterm-terminal. - Storage changes include new-data round trips, representative legacy data, invalid-password cases, and corrupted data.
- RDP/VNC protocol, framebuffer, input mapping, IPC, certificate, clipboard, and reconnect tests belong in
nyaterm-remote-desktop,nyaterm-rdp-helper, ornyaterm-vnc-helper. Both helper crates'tests/lifecycle.rscover the handshake, an ordinary disconnect, and crash/hang reaping; keep them in step when the IPC contract changes. - Cross-crate behavior is tested through small adapters without real credentials or production services.