SugarServeProtocol
candy-code.v1 wire contract — constants, discovery and token readers, URL rule
The wire contract for the candy-code.v1 serve protocol, in one small package. Clients that talk to a running candy-code serve read the same discovery record, token file and WebSocket URL through it, so the rule lives in one place. It only reads: writing the token, creating the state directory and running the server stay with the host. First-party: original work, with no upstream Go port.
Install
composer require sugarcraft/sugar-serve-protocol
Quickstart
use SugarCraft\ServeProtocol\Auth\TokenFile;
use SugarCraft\ServeProtocol\Discovery\StateDirReader;
use SugarCraft\ServeProtocol\Url\WebsocketUrl;
$dir = StateDirReader::existing('/home/me/.local/state/candy-code');
$token = $dir === null ? null : TokenFile::read($dir);
$url = WebsocketUrl::from('http://127.0.0.1:7420'); // "ws://127.0.0.1:7420/ws"
The laws
Read side onlyDiscovery, token and URL helpers read and normalise. A missing file answers null; an unreadable one throws, so a token is never silently replaced.
Private stateA state directory that is a symbolic link, a file, the wrong owner or a mode other than 0700 is refused, not followed.
Bounded parsingDiscovery records are decoded to a bounded depth and returned raw, so field-level checks stay with the host.
One envelope, in progressThis package's tests pin against the JSON-RPC 2.0 codec of
sugar-mcp-client, a dev-only requirement. The running candy-code serve still uses its own copy of that codec, so the two are not yet one shared implementation: a fix made in one does not reach the other until the host delegates to this package. Install sugarcraft/sugar-mcp-client yourself to call JsonRpc from your own code.Use it for
- Attaching to a running server — the TUI and the bundles that reach
candy-code serve. - Discovery tooling — anything that needs the server's URL or token without starting it.
Source
API
| Class | Method | Description |
|---|---|---|
| Protocol | MAJOR, SUBPROTOCOL, AUTH_SUBPROTOCOL_PREFIX, MAX_SERVER_FRAME_BYTES, ASK_EXPIRY_SECONDS | The wire constants (candy-code.v1, 4 MiB frame cap, 1800 s ask expiry) |
| WebsocketUrl | static from(string $address): ?string | http(s) or ws(s) address to its /ws URL; null for anything else |
| StateDirReader | static existing(string $path): ?string | An existing private state directory; null when absent; throws when present but not private |
| DiscoveryRecordReader | static read(string $path): ?array | The raw server.json record; null when absent, a symbolic link, or not a JSON object |
| TokenFile | static read(string $stateDir): ?string | The 64-hex bearer token; null when there is no usable token; throws when unreadable |