mirror of
https://github.com/bherbruck/solidcraft.git
synced 2026-11-19 15:10:51 +00:00
295a5e1410
client::Connection is the app-independent half of the MCP bridge's Remote: a connection to an app's loopback control port with the app's token (auth::App::client_token) on every request, one write and one bounded read (MAX_REPLY) per request, a fresh connection after a lost one (a request sent once more, or never twice for Request::once), and the wait for a request the app says is still running, through control.pending, with the waits as parameters. CallError tells an app that is not running (with how to start it, from the App's name and the port) from one lost during the call, a request still running, the app's refusal and a bad reply. Remote keeps only what is the MCP bridge's: the agent's folders on every request, the engine's names and effects for requests, the param-check handshake and engine.batch sent once. Its messages are unchanged, except the "did not answer" one, which lost a run of spaces in the middle. Tests against a server::Hub on an ephemeral port: a round trip with the token, a wrong or missing token refused, not running, lost mid-call and reached again once back, a connection closed without a reply, and a request still running waited for through control.pending. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DtL5M2MmcDrkcWhQeHS2K8 Co-authored-by: jyviko <2501648+jyviko@users.noreply.github.com> Co-authored-by: bherbruck <brennen.herbruck@gmail.com>
2.4 KiB
2.4 KiB
solidcraft-control
The control channel any app may share (docs/control-protocol.md). An app that listens for
control makes a random token per launch, writes it to a file only the user can read and refuses
every connection whose first request doesn't carry it; a client finds the token the same way.
Which app the files belong to, its environment, its name in messages and its default port come
from an App value the app defines. No app types and no engine.
API
| Item | What it does |
|---|---|
auth::App |
An app's identity: name, data_dir, env (its prefixed variables), utc, default_port |
App::token_path(port), App::current_port_path() |
<data folder>/control/<port>.token and the discovery file (CONTROL_DIR replaces the folder) |
App::write_token_file(path, token) |
Write a token readable only by the user, with its <port>.pid file beside it |
App::write_current_port, App::read_current_port, App::remove_current_port |
The discovery file of the most recently started app |
App::env_token(), App::client_token(port, explicit) |
The token a client sends: explicit, CONTROL_TOKEN, else the token file |
auth::ClientToken::explain_error(error) |
A refusal with the token file named and whether it is stale; never the token |
auth::plan, auth::Listen, auth::bind_with_fallback, auth::PORT_TRIES |
Where a launch listens; a loopback listener on the first free port |
auth::tokens_match, auth::remove_token_file, auth::TokenFile, auth::pid_path, auth::MIN_TOKEN_LEN |
Constant-time compare and token file housekeeping |
Effect |
What a request still running does when it finishes: reads only, writes a file, or changes; when_done(document) says it |
server::Hub, server::Protocol, server::Summary, server::Waits, server::new_token |
The loopback JSON-lines server behind the token (desktop only); the app says what its requests mean |
client::Connection, client::Request, client::CallError, client::Waits |
The client (desktop only): the app's token on every request, one bounded round trip, a fresh connection after a lost one, the wait for a request still running (control.pending); "not running" told from "lost during the call" |
ControlRequest, ControlResponse, DocumentWatch, DOCUMENT_WATCH |
A request as the window gets it; the document id and revision subscribed connections wait on |