Skip to content

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 answers accept{type, version} or refuse{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; cloud imports core through 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, including wrong-service and unexpected-frame for negotiation failures and unauthorised-author spelled as in the cloud spec.
  • Modules. The modules are relay, sync, share and accounts. The spec's "blob module" is sync, which speaks the service name blob on 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 (default localhost:8080), VAULTFOLD_CLOUD_ORIGIN (https, or http only on a loopback host) and VAULTFOLD_CLOUD_DATA_DIR (default data). Without an origin the startup line names http://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/protocol is their reference implementation.
  • A new major version must keep hello unchanged, 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.