ursuladurable streams
v0.9.0 · apache-2.0

Buckets

Streams are organized into buckets. A bucket is a namespace, like a folder that holds related streams under one URL prefix:

/{bucket}/{stream}

A collaborative editing app might use one bucket per workspace, with one stream per document: /workspace-a/doc-1, /workspace-a/doc-2. An agent platform might use one bucket per tenant: /tenant-acme/run-xyz.

Naming

Bucket IDs match the regex [a-z0-9_-]{4,64}: 4–64 bytes, lowercase ASCII letters and digits plus _ and -. Uppercase letters, /, ., and most punctuation are rejected with 400.

The combined bucket-plus-stream URL path also has a 122-byte ceiling. With a 64-byte bucket name, you have 57 bytes left for the stream ID.

Lifecycle

Buckets are implicit. A bucket exists once a stream is created in it; there is no separate create step.

  • PUT /{bucket} validates the bucket ID and changes nothing: 201 for a valid ID, 400 for an invalid one. Clients that create the bucket first can keep doing so.
  • There is no bucket metadata read, stream listing, or bucket delete. Track your streams in your own application.
  • Removing a bucket and every stream in it is an operator action: the admin-plane bucket purge, which permanently fences the bucket ID: later stream creates in it answer 404.