Protocol Overview

The Unbroken Protocol is an HTTP-based protocol for creating, reading, and writing to durable, append-only byte streams. This page provides a complete reference of all protocol operations.

Communication Model

The protocol uses standard HTTP methods applied to stream URLs:

┌────────┐                           ┌────────┐
│ Client │                           │ Server │
└───┬────┘                           └───┬────┘
    │                                    │
    │  PUT /stream (create)              │
    │───────────────────────────────────▶│
    │                                    │
    │  201 Created                       │
    │◀───────────────────────────────────│
    │                                    │
    │  POST /stream (append)             │
    │───────────────────────────────────▶│
    │                                    │
    │  204 No Content                    │
    │◀───────────────────────────────────│
    │                                    │
    │  GET /stream?offset=x (read)       │
    │───────────────────────────────────▶│
    │                                    │
    │  200 OK + data                     │
    │◀───────────────────────────────────│

URL Structure

The protocol does not mandate a specific URL structure. Servers may organize streams using any scheme:

/v1/streams/{id}
/api/conversations/{user}/{conversation}
/sync/{database}/changes
/{tenant}/events/{stream}

The protocol is defined by HTTP methods, query parameters, and headers applied to any stream URL.

Operations Summary

Write Operations

Method	Path	Description	Required
`PUT`	`{stream}`	Create a new stream	Baseline
`POST`	`{stream}`	Append data to stream	Optional
`DELETE`	`{stream}`	Delete stream	Optional

Read Operations

Method	Path	Description	Required
`GET`	`{stream}?offset=x`	Catch-up read	Baseline
`GET`	`{stream}?offset=x&live=long-poll`	Long-poll read	Optional
`GET`	`{stream}?offset=x&live=sse`	SSE streaming	Optional
`HEAD`	`{stream}`	Get stream metadata	Baseline

Implementation Notes

Servers MAY implement read and write paths independently:

A database sync server might only implement reads, using internal mechanisms for writes
A log aggregation service might only implement writes, with reads handled by a separate system
A full-featured server implements both paths

Request Format

Common Headers

All requests may include:

Header	Description
`Authorization`	Authentication credentials
`Content-Type`	Media type of request body

Query Parameters

Parameter	Operations	Description
`offset`	GET	Starting position for read
`live`	GET	Live mode: `long-poll` or `sse`
`cursor`	GET (long-poll)	CDN collapsing cursor

Response Format

Success Responses

Code	Meaning	Used By
`200 OK`	Success with body	GET, PUT (idempotent)
`201 Created`	Stream created	PUT
`204 No Content`	Success, no body	POST, DELETE, GET (timeout)

Error Responses

Code	Meaning
`400 Bad Request`	Invalid parameters or body
`404 Not Found`	Stream does not exist
`405 Method Not Allowed`	Operation not supported
`409 Conflict`	Sequence regression or config mismatch
`410 Gone`	Offset before retention window
`413 Payload Too Large`	Request body exceeds limit
`429 Too Many Requests`	Rate limit exceeded

Response Headers

Header	Description	Operations
`Stream-Next-Offset`	Next offset for reads	All successful reads/writes
`Stream-Up-To-Date`	At end of stream	GET (when caught up)
`Stream-Cursor`	CDN collapsing key	GET
`Content-Type`	Stream content type	GET, HEAD, PUT
`Location`	Stream URL	PUT (201)

Default Port

The default port for standalone Unbroken Protocol servers is 9999/tcp.

When integrated into an existing application server, use the host server’s port.

Versioning

The protocol uses a single-integer major version. Non-breaking changes are added through:

New optional headers
New optional query parameters
Additional response headers

Breaking changes require a new major version.

Detailed Documentation

For complete details on each operation:

Stream Model - Stream lifecycle and properties
Reading Operations - Catch-up, long-poll, and SSE reads
Writing Operations - Create, append, and delete
Offsets - Offset semantics and usage
Content Types - Content type handling and JSON mode
Caching - CDN and proxy considerations