Durable Streams

HTTP-based streaming of NATS JetStream data to web/mobile clients. Implements the Durable Streams Protocol.

Architecture

Client (Browser/CLI)
    ↓ HTTP/SSE
Streams Service (port 52012)
    ↓ JetStream
NATS

Key design: Predefined streams only. The service handles auth and userID injection into subject filters.

Endpoints

# List available streams
GET /api/streams/

# Subscribe to a stream (auth required)
GET /api/streams/{name}

CLI Usage

# List available streams
orbital str ls

# Subscribe to a stream
orbital str sub heartbeat
orbital str sub wallet

SSE Protocol

Response format:

event: data
data: {"seq":1,"timestamp":"2025-12-14T10:00:00Z"}

event: control
data: {"streamNextOffset":"00000000000000000042"}

: heartbeat

Headers:

• Stream-Next-Offset: Resume cursor for next request
• Stream-Cursor: Current position
• Stream-Up-To-Date: true: Caught up to head of stream

Code Structure

Package	Purpose
internal/dstreams	Generic SSE protocol layer
services/streams/api	Service (auth, mappings, handlers)
internal/cli/stream.go	CLI commands

Adding Streams

Edit services/streams/api/mappings.go:

var streamMappings = map[string]StreamMapping{
    "wallet": {
        Stream:        "wallet",
        SubjectFilter: "wallet.{userID}.>",
        Description:   "Wallet events",
    },
}

Each mapping creates a GET /api/streams/{name} endpoint.