0021: Cloud wire protocol foundation and module configuration
- Status: accepted
- Date: 2026-09-25
Context
The cloud spec (add-cloud-service) requires a versioned protocol negotiated on the first frame of every relay and blob connection, one binary whose four modules are enabled by environment variables, and a first run with no configuration that serves the relay and blob modules. It does not fix the version syntax, the frame encoding, the refusal reason names beyond those its scenarios use, or the configuration variables. Task group 1 had to choose them; this records the choices (ticket DECISION of the test author, accepted by the orchestrator).
Decision
- Version. The wire form is the text
"MAJOR.MINOR": semantic versioning without the patch component, which never changes the wire. Components are 0 to 65535, ASCII digits, no leading zeros. - Negotiation. The client's first frame is
hello{type, service, version}; the service answersaccept{type, version}orrefuse{type, reason, supported}. The same major is required; the served minor is the lower of the offered minor and the highest served. Every refuse lists the supported versions ascending, one entry per major carrying its highest minor.hello's field set is frozen for all versions and unknown keys are malformed. - Encoding. Frames are canonical CBOR maps with text keys, produced
and checked with
core/canon;cloudimportscorethrough the workspace. Control frames are at most 4096 bytes. - Reasons. A fixed registry of 14 lowercase tokens in
cloud/protocol/reason.go, documented in docs/protocol/relay-v1.md, includingwrong-serviceandunexpected-framefor negotiation failures andunauthorised-authorspelled as in the cloud spec. - Modules. The modules are
relay,sync,shareandaccounts. The spec's "blob module" issync, which speaks the service nameblobon the wire. Defaults: relay and sync on, share and accounts off; enabling no module is an error. - Configuration. Environment variables
VAULTFOLD_CLOUD_RELAY,_SYNC,_SHARE,_ACCOUNTS(on/off, true/false, 1/0),VAULTFOLD_CLOUD_LISTEN(defaultlocalhost:8080),VAULTFOLD_CLOUD_ORIGIN(https, or http only on a loopback host) andVAULTFOLD_CLOUD_DATA_DIR(defaultdata). Without an origin the startup line nameshttp://localhost:<port>. - Disabled modules. A request under
/<module>/of a disabled module is answered 404 with{"module": "<module>", "reason": "not-enabled"}.
Consequences
- Protocol documents under docs/protocol/ are normative for these
frames, and the Go package
cloud/protocolis their reference implementation. - A new major version must keep
hellounchanged, so old services can refuse new clients with a useful supported list.
Alternatives considered
- Integer version pairs on the wire. Rejected: the text form reads the same in logs, documents and error messages.
- Build tags for module selection. Rejected by design.md: one binary and one container image.