All 47 libraries

SugarServeProtocol

candy-code.v1 wire contract — constants, discovery and token readers, URL rule

first-party websocket protocol no-io-writes

SugarServeProtocol code coverage

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

Try the quickstart →

API

API surface
ClassMethodDescription
ProtocolMAJOR, SUBPROTOCOL, AUTH_SUBPROTOCOL_PREFIX, MAX_SERVER_FRAME_BYTES, ASK_EXPIRY_SECONDSThe wire constants (candy-code.v1, 4 MiB frame cap, 1800 s ask expiry)
WebsocketUrlstatic from(string $address): ?stringhttp(s) or ws(s) address to its /ws URL; null for anything else
StateDirReaderstatic existing(string $path): ?stringAn existing private state directory; null when absent; throws when present but not private
DiscoveryRecordReaderstatic read(string $path): ?arrayThe raw server.json record; null when absent, a symbolic link, or not a JSON object
TokenFilestatic read(string $stateDir): ?stringThe 64-hex bearer token; null when there is no usable token; throws when unreadable