SuperbeeDocs
v0.1.4Source repository

Reference

Wire protocol and reference server

Implemented v0 endpoints, preconditions, transport behavior, security limits, and RemoteBackend mapping.

Last updated

View Markdown

Scope

This reference summarizes the implemented /v0 HTTP storage protocol, the reference server, and RemoteBackend client behavior in the current stable release. It is for integrators implementing a gated host or diagnosing explicit --remote operations.

The complete protocol authority is the tagged docs/WIRE-PROTOCOL.md. Current stable release evidence establishes the package identity.

Start the reference server

superbee serve --dir .superbee --host 127.0.0.1 --port 4818

serve defaults to loopback and CLI port 4818. The library-level serve() API can request an ephemeral port. The server closes over one backend; the {bundle} path segment is validated but does not select among multiple bundles.

The reference server has no authentication or authorization. Passing a non-loopback host exposes the unauthenticated protocol. Production deployment requires an authentication and authorization gate, transport security, request limits, and trusted principal attribution.

Conventions

  • Route prefix: /v0.

  • Base member path: /v0/bundles/{bundle}/....

  • IDs and blob keys encode each path segment independently.

  • JSON success uses application/json; charset=utf-8; blob reads return raw bytes.

  • Versioned responses send a bare X-Version and the same token as a quoted ETag.

  • If-None-Match: * means expect-absent create.

  • If-Match accepts a bare token and quoted or weak ETag forms.

  • Document and blob deletes are idempotent and return { "deleted": true|false }.

  • Except for HEAD, failures use { "error": { "code", "message", "details" } }.

A client must reject a successful versioned read that lacks both version headers. An empty expected version is invalid input. X-Actor is advisory; X-Agent is reserved for a trusted gate and is client-controlled on the reference server.

Endpoint table

MethodPathSuccess
GET/v0/capabilitiesCapability booleans for history, CAS, projections, backlinks, and blobs
GET/v0/bundles/{bundle}/docsFiltered document heads with count and cursor
POST/v0/bundles/{bundle}/docs:read-manyAll requested documents or one missing-ID failure
GET/v0/bundles/{bundle}/docs/{id...}Parsed document plus version headers
PUT/v0/bundles/{bundle}/docs/{id...}Versioned create or write receipt
HEAD/v0/bundles/{bundle}/docs/{id...}Bodyless existence and version result
DELETE/v0/bundles/{bundle}/docs/{id...}Idempotent delete receipt
GET/v0/bundles/{bundle}/docs/{id...}/versionsVersion, actor, timestamp, and optional agent history
GET/v0/bundles/{bundle}/reserved/{name}index.md or log.md content and version
PUT/v0/bundles/{bundle}/reserved/{name}Versioned reserved-file write
GET/v0/bundles/{bundle}/blobsBlob keys with count and cursor
GET/v0/bundles/{bundle}/blobs/{key...}Raw bytes, content type, and version
PUT/v0/bundles/{bundle}/blobs/{key...}Raw-byte create or write receipt
HEAD/v0/bundles/{bundle}/blobs/{key...}Bodyless existence, type, and version result
DELETE/v0/bundles/{bundle}/blobs/{key...}Idempotent delete receipt

There is no collection delete or reserved-file delete route.

Lists and cursors

Document list accepts prefix, type, repeated tag, fields, limit, and cursor. Filters are ANDed. Default page size is 50, including for a missing, non-positive, or unparsable limit. count is the total filtered count before pagination. fields=frontmatter selects full frontmatter; the default row is { id, version, type, title, timestamp }.

Blob list accepts prefix, limit, and cursor with the same page envelope. A cursor is the last returned ID or key. If it disappears, the next page resumes according to backend ordering.

Documents and raw bytes

Document routes transport parsed frontmatter and body as JSON. RemoteBackend reconstructs and exports canonical OKF Markdown, so an external file's YAML formatting and whitespace are not an original-byte guarantee. The server's version header identifies state; clients must not replace it with a hash of reconstructed Markdown.

Blob routes carry exact bytes and content type in the HTTP body and headers. Blob keys ending in .md are rejected so raw storage cannot bypass document validation.

Client mapping and retry

RemoteBackend maps absent document reads to an ENOENT-shaped error, absent blob reads to null, and HTTP 412 to VersionConflict. Other non-2xx results become RemoteError with the wire code and status.

Network failures and HTTP 500, 502, 503, and 504 are retried with bounded exponential backoff and jitter. Real 4xx responses, including 401 and 412, are not retried. A guarded write whose response was lost can conservatively surface as a conflict on retry. Callers that need lost-update safety must use expect-absent or If-Match rather than an unconditional write.

Known limits

  • No authentication, authorization, or trusted attribution in the reference server.

  • No multi-bundle selection behind the {bundle} segment.

  • No original-document-byte endpoint.

  • No wire expression for arbitrary core field-equality filters.

  • No backlinks endpoint; clients derive edges from documents.

  • No body-size cap is supplied by the default serve() wrapper.

  • A final document path segment named versions is ambiguous with history.

Verification and recovery

Probe capabilities before depending on optional behavior. Use a disposable bundle and loopback server to test create, read, guarded update, list, history, blob byte integrity, and delete. If a version header is missing, stop the integration. If a write response is ambiguous, read current state before deciding whether to retry.

See Artifacts and byte channels for CLI routing and Security and trust boundaries before exposing a server.