Ursulav0.1.0

v1 compatibility

Flat Durable Streams protocol routes under /v1/stream/.

Ursula provides a compatibility layer under /v1/stream/ that implements the Durable Streams Protocol, defined by the durable-streams community, with a flat path model. This is useful when you want a simpler path structure without explicit bucket management.

Path mapping

The v1 path is mapped to the bucket/stream model using the first / as the separator:

v1 pathBucketStream
/v1/stream/mystream_defaultmystream
/v1/stream/workspace/mystreamworkspacemystream
/v1/stream/a/b/cab/c

Paths without a / are placed in the _default bucket.

Routes

These routes accept the same headers, query parameters, and body formats as their /{bucket}/{stream} equivalents:

MethodPathEquivalent
PUT/v1/stream/{path}Create stream
POST/v1/stream/{path}Append
GET/v1/stream/{path}Read
HEAD/v1/stream/{path}Head stream
DELETE/v1/stream/{path}Delete stream

Differences from bucketed routes

  • Buckets do not need to be created beforehand. Streams are created without bucket-existence validation.
  • No bucket-level operations (create/get/delete bucket, list streams). Use the / routes for those.
  • No snapshot or bootstrap routes. Use the / equivalents.
  • Stream close uses the Stream-Closed: true header on POST, not a path suffix.
curl -X PUT http://127.0.0.1:4437/v1/stream/mystream
curl -X POST http://127.0.0.1:4437/v1/stream/mystream \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello'
curl 'http://127.0.0.1:4437/v1/stream/mystream?offset=-1'
curl 'http://127.0.0.1:4437/v1/stream/mystream?offset=-1&live=sse'