Ursula

https://ursula.tonbo.io
Admin
A self-hosted, distributed server for append-only event timelines with HTTP-native API,...
Tokens:77,294
Snippets:903
Trust Score:7.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Prerequisites on macOS

Source: https://ursula.tonbo.io/docs/install

Installs Rust and pkg-config using Homebrew on macOS.

```bash
brew install rust pkg-config
```

--------------------------------

### Install Prerequisites on Debian/Ubuntu

Source: https://ursula.tonbo.io/docs/install

Installs build essentials, pkg-config, curl, and Rust using apt-get and a script on Debian/Ubuntu.

```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### SSE Request Example

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Use this GET request to initiate a live Server-Sent Events (SSE) stream from a specified offset. Ensure the 'live=sse' query parameter is included.

```http
GET {stream-url}?offset=<offset>&live=sse
```

--------------------------------

### WAL-Backed Single Node Ursula Example

Source: https://ursula.tonbo.io/docs/configuration

A minimal example for running Ursula in a single-node configuration using Write-Ahead Logging (WAL).

```bash
ursula \
  --listen 127.0.0.1:4437 \
  --core-count 4 \
  --raft-group-count 64 \
  --wal-dir ./data/wal
```

--------------------------------

### Start Backend Services for Benchmark

Source: https://ursula.tonbo.io/benchmark

Starts the backend services for the benchmark, including Ursula, S2 Lite, and Durable Streams. Requires identical hardware for fair comparison.

```bash
# 2. Bring up each backend on identical hardware
python3 scripts/ursula_ec2.py --config <manifest>.json start
~/.cargo/bin/s2 lite --port 4438 # S2 Lite on one node
# DS: clone github.com/durable-streams/durable-streams + run example server
```

--------------------------------

### In-Memory Single Node Ursula Example

Source: https://ursula.tonbo.io/docs/configuration

A minimal example for running Ursula in an in-memory single-node configuration.

```bash
ursula \
  --listen 127.0.0.1:4437 \
  --core-count 4 \
  --raft-group-count 64 \
  --raft-memory
```

--------------------------------

### Offset Formatting Example

Source: https://ursula.tonbo.io/llms-full.txt

Shows the expected format for offsets returned to clients, which are zero-padded decimal strings.

```text
00000000000000000042
```

--------------------------------

### Three-Node Durable Cluster Ursula Example

Source: https://ursula.tonbo.io/docs/configuration

An example for setting up a three-node durable Ursula cluster using S3 for cold storage and a cluster configuration file. This command should be run on each host, with the 'node_id' adjusted in the cluster config file.

```bash
URSULA_COLD_BACKEND=s3 \
URSULA_COLD_S3_BUCKET=my-ursula-bucket \
URSULA_COLD_S3_REGION=us-east-1 \
ursula \
  --listen 0.0.0.0:4437 \
  --core-count 16 \
  --raft-group-count 256 \
  --raft-log-dir /var/lib/ursula/raft \
  --raft-cluster-config /etc/ursula/cluster.json
```

--------------------------------

### Start Node 1 Command

Source: https://ursula.tonbo.io/docs/deploy-cluster

Command to start the first node of the Ursula cluster. 'init_membership_per_group' is only needed on the initial start.

```bash
ursula \
  --listen 0.0.0.0:4437 \
  --core-count 16 \
  --raft-group-count 256 \
  --raft-log-dir /var/lib/ursula/raft \
  --raft-cluster-config /etc/ursula/cluster.json
```

--------------------------------

### Start Node 1 with Raft Log Directory

Source: https://ursula.tonbo.io/llms-full.txt

Command to start the first node of a Ursula cluster using a specified Raft log directory for durable storage. The 'init_membership_per_group' should be true only on the initial cluster start.

```bash
ursula \
  --listen 0.0.0.1:4437 \
  --core-count 16 \
  --raft-group-count 256 \
  --raft-log-dir /var/lib/ursula/raft \
  --raft-cluster-config /etc/ursula/cluster.json
```

--------------------------------

### Bootstrap Response Example

Source: https://ursula.tonbo.io/docs/specs/extensions

An example of a successful HTTP response for a bootstrap request, including headers and a multipart/mixed body containing a snapshot and subsequent updates.

```http
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=rr-bootstrap-9f1c2e7a
Stream-Snapshot-Offset: 0000000000000012
Stream-Next-Offset: 0000000000000026
Stream-Up-To-Date: true
Cache-Control: no-store

--rr-bootstrap-9f1c2e7a
Content-Type: application/octet-stream

<snapshot-bytes>
--rr-bootstrap-9f1c2e7a
Content-Type: application/json

{"op":"set","path":["title"],"value":"hello"}
--rr-bootstrap-9f1c2e7a
Content-Type: application/json

{"op":"insert","path":["body",0],"value":"world"}
--rr-bootstrap-9f1c2e7a--
```

--------------------------------

### Verify Ursula Installation

Source: https://ursula.tonbo.io/docs/install

Checks the Ursula installation by running the binary with the --help flag and performing a smoke test.

```bash
./target/release/ursula --help
```

--------------------------------

### List Bucket Streams Response Example

Source: https://ursula.tonbo.io/docs/specs/extensions

Example JSON response when listing streams in a bucket. It includes bucket details, stream information, and pagination controls.

```json
{
  "bucket_id": "agents",
  "prefix": "user-",
  "stream_count": 2,
  "streams": [
    {
      "stream_id": "user-1",
      "status": "Open",
      "content_type": "text/plain",
      "tail_offset": 42,
      "created_at_ms": 1735689600000,
      "last_write_at_ms": 1735689601000
    }
  ],
  "next_cursor": "user-2",
  "has_more": true
}
```

--------------------------------

### EC2 Helper: Start Cluster

Source: https://ursula.tonbo.io/docs/operations

Starts the Ursula cluster based on the provided configuration. This command initiates the Ursula processes on all configured nodes.

```bash
python3 scripts/ursula_ec2.py --config cluster.json start
```

--------------------------------

### Python: Create Bucket, Stream, and Append Data

Source: https://ursula.tonbo.io/llms-full.txt

Python example using the requests library to create a bucket, a stream, and append data. It demonstrates basic HTTP interactions with Ursula.

```python
import requests

base = "http://127.0.0.1:4437"

requests.put(f"{base}/demo")
requests.put(f"{base}/demo/hello")

requests.post(
    f"{base}/demo/hello",
    headers={"Content-Type": "application/octet-stream"},
    data=b"hello world",
)
```

--------------------------------

### JSON Mode: Client-Side Batching Example

Source: https://ursula.tonbo.io/llms-full.txt

Shows how client libraries might automatically wrap individual values in arrays to enable batching, which the server then flattens.

```json
[{"x": 1}]
```

--------------------------------

### Run Ursula Smoke Server and Test Endpoints

Source: https://ursula.tonbo.io/docs/install

Starts the Ursula server in the background and sends sample requests to test its functionality.

```bash
./target/release/ursula &

curl -X PUT http://127.0.0.1:4437/demo
curl -X PUT http://127.0.0.1:4437/demo/hello
curl -X POST -H 'Content-Type: text/plain' --data 'hi' http://127.0.0.1:4437/demo/hello
curl 'http://127.0.0.1:4437/demo/hello?offset=-1'
```

--------------------------------

### Start In-Memory Raft Ursula Server

Source: https://ursula.tonbo.io/docs/run-locally

Starts Ursula with an in-memory Raft log. This configuration exercises the Raft path for fast iteration without data persistence, ideal for development.

```bash
cargo run --bin ursula -- --raft-memory
```

--------------------------------

### Start Default Ursula Server

Source: https://ursula.tonbo.io/docs/run-locally

Launches a single-node Ursula server with default in-process, non-replicated settings. This is suitable for basic smoke tests and initial exploration as it does not persist any data.

```bash
cargo run --bin ursula
```

--------------------------------

### Publish Snapshot Example

Source: https://ursula.tonbo.io/docs/api/publish-snapshot

Use this curl command to upload a snapshot blob at a specific stream offset. Ensure the Content-Type header matches the data being sent.

```bash
curl -X PUT 'http://127.0.0.1:4437/demo/hello/snapshot/00000000000000000042' \
  -H 'Content-Type: application/json' \
  --data-binary '{"state": "aggregated snapshot data"}'
```

--------------------------------

### Python examples for bucket and stream operations

Source: https://ursula.tonbo.io/docs/clients

This Python script uses the requests library to interact with Ursula, demonstrating bucket creation, data streaming, catch-up reads, and live tailing with SSE.

```python
import requests

base = "http://127.0.0.1:4437"

requests.put(f"{base}/demo")
requests.put(f"{base}/demo/hello")

requests.post(
    f"{base}/demo/hello",
    headers={"Content-Type": "application/octet-stream"},
    data=b"hello world",
)

# catch-up read
resp = requests.get(f"{base}/demo/hello", params={"offset": -1})
print(resp.content)

# live tail with SSE
with requests.get(
    f"{base}/demo/hello",
    params={"offset": -1, "live": "sse"},
    stream=True,
) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode())
```

--------------------------------

### SSE Data and Control Events Example

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Illustrates the Server-Sent Events format for normal data streams, showing both 'data' and 'control' events.

```text
event: data
data: [
data: {"k":"v"},
data: {"k":"w"},
data: ]

event: control
data: {"streamNextOffset":"123456_789","streamCursor":"abc"}
```

--------------------------------

### Live Tail with SSE (Python)

Source: https://ursula.tonbo.io/llms-full.txt

Demonstrates how to perform a live tail of a stream using Server-Sent Events (SSE) with the requests library in Python. Ensure the 'requests' library is installed.

```python
import requests

base = "http://127.0.0.1:4437"

with requests.get(
    f"{base}/demo/hello",
    params={\"offset\": -1, \"live\": \"sse\"},
    stream=True,
) as r:
    for line in r.iter_lines():
        if line:
            print(line.decode())

```

--------------------------------

### Python: Catch-up Read from Stream

Source: https://ursula.tonbo.io/llms-full.txt

Python example using the requests library to perform a catch-up read from a stream. It fetches content from a specified offset.

```python
# catch-up read
resp = requests.get(f"{base}/demo/hello", params={"offset": -1})
print(resp.content)
```

--------------------------------

### Start WAL-Backed Single Node Ursula Server

Source: https://ursula.tonbo.io/docs/run-locally

Launches Ursula with persistent local storage using a Write-Ahead Log (WAL). This configuration ensures that streams survive server restarts.

```bash
cargo run --bin ursula -- --wal-dir ./data/wal
```

--------------------------------

### List Streams in a Bucket

Source: https://ursula.tonbo.io/docs/concepts/buckets

Use GET to list all streams within a bucket. Supports optional prefix filtering and cursor-based pagination with a maximum page size of 1000.

```shell
GET /{bucket}/streams
```

--------------------------------

### Write and Read Operations (TypeScript)

Source: https://ursula.tonbo.io/llms-full.txt

Shows how to perform write operations (PUT, POST) and a catch-up read from a stream using the fetch API in TypeScript. This example assumes a running Ursula instance.

```typescript
const base = "http://127.0.0.1:4437";

await fetch(`${base}/demo`, { method: "PUT" });
await fetch(`${base}/demo/hello`, { method: "PUT" });

await fetch(`${base}/demo/hello`, {
  method: "POST",
  headers: { "Content-Type": "application/octet-stream" },
  body: "hello world",
});

// catch-up read
const data = await (await fetch(`${base}/demo/hello?offset=-1`)).text();

```

--------------------------------

### ETag Header Example

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Servers MUST generate ETag headers for GET responses (excluding offset=now) to allow clients to use If-None-Match for conditional requests.

```http
ETag: "some-etag-value"
```

--------------------------------

### Read Stream - Live (Long-poll) Request URL

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Example of a GET request URL for live stream reading using the long-poll method. Include the offset and optionally a cursor for CDN collapsing.

```http
GET {stream-url}?offset=<offset>&live=long-poll[&cursor=<cursor>]
```

--------------------------------

### Configure Filesystem Backend

Source: https://ursula.tonbo.io/docs/configure-s3

Set the filesystem backend for cold storage. This is intended for single-node testing only. An optional root directory can be specified.

```bash
export URSULA_COLD_BACKEND=fs
export URSULA_COLD_ROOT=./data/cold   # optional; defaults to data/cold
```

--------------------------------

### Read Stream from Offset

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Use a GET request with an optional 'offset' query parameter to retrieve stream data starting from a specific point. If the offset is omitted, the read defaults to the beginning of the stream (offset -1). This is primarily used for catch-up reads.

```http
GET {stream-url}?offset=<offset>
```

--------------------------------

### Run Benchmark Scenarios (Multi-Stream and Fan-Out)

Source: https://ursula.tonbo.io/benchmark

Executes the multi-stream and fan-out benchmark scenarios against Ursula, Durable Streams, and S2 Lite. Adjust NODE and PORT as necessary.

```bash
# 3. Run the same three scenarios against each
for api in ursula durable s2; do
 ursula-bench multi-stream --target http://NODE:PORT --api-style "$api" \
 --streams 500 --duration-secs 30 --payload-bytes 256
 ursula-bench fan-out --target http://NODE:PORT --api-style "$api" \
 --subscribers 1000 --writer-rate 50 --duration-secs 30
done
```

--------------------------------

### Bootstrap

Source: https://ursula.tonbo.io/llms-full.txt

Provides single-request initialization with a snapshot (if any) plus all retained updates.

```APIDOC
## GET {stream_url}/bootstrap

### Description
Bootstrap provides single-request initialization: a snapshot (if any) plus all retained updates after the snapshot point, returned as a single ordered response that preserves per-message content types.

### Method
GET

### Endpoint
`{stream_url}/bootstrap`

### Parameters
#### Query Parameters
- `/bootstrap` is a one-shot initialization endpoint. It does not define any query parameters of its own.
- Servers SHOULD reject any `live` query parameter on `/bootstrap` with `400 Bad Request`.

### Response
#### Success Response (200 OK)
**Response Headers:**
- **Content-Type** (string) - `multipart/mixed; boundary=<token>`
- **Stream-Snapshot-Offset** (string) - The snapshot offset, or `-1` if no snapshot exists.
- **Stream-Next-Offset** (string) - The next offset after all returned data.
- **Stream-Up-To-Date** (boolean) - Boolean.

**Response Body:**
The body is an RFC 2046 `multipart/mixed` entity. Each MIME part is one logical bootstrap message. The multipart boundary, not any outer binary framing, defines the bootstrap message boundaries.
1. **First part**: Snapshot message. If a snapshot exists, the part body MUST be the raw snapshot bytes and the part `Content-Type` MUST equal the snapshot blob's stored content type. If no snapshot exists, the server MUST still emit an empty first part, `Stream-Snapshot-Offset` MUST be `-1`, and that empty part's `Content-Type` MUST be `application/octet-stream`.
2. **Subsequent parts**: Retained updates after the snapshot point, one update message per part. Each part body MUST be exactly one retained update message, and the part `Content-Type` MUST be the content type of that update.

#### Response Example
```http
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=rr-bootstrap-9f1c2e7a
Stream-Snapshot-Offset: 0000000000000012
Stream-Next-Offset: 0000000000000026
Stream-Up-To-Date: true
Cache-Control: no-store

--rr-bootstrap-9f1c2e7a
Content-Type: application/octet-stream

<snapshot-bytes>
--rr-bootstrap-9f1c2e7a
Content-Type: application/json

{"op":"set","path":["title"],"value":"hello"}
--rr-bootstrap-9f1c2e7a
Content-Type: application/json

{"op":"insert","path":["body",0],"value":"world"}
--rr-bootstrap-9f1c2e7a--
```

#### Error Response (404 Not Found)
- Stream does not exist.
```

--------------------------------

### Get Bucket Metadata

Source: https://ursula.tonbo.io/docs/concepts/buckets

Use GET to retrieve metadata associated with a specific bucket.

```shell
GET /{bucket}
```

--------------------------------

### Bootstrap

Source: https://ursula.tonbo.io/docs/specs/extensions

Provides single-request initialization by returning a snapshot (if any) plus all retained updates after the snapshot point.

```APIDOC
## GET {stream_url}/bootstrap

### Description
Bootstrap provides single-request initialization: a snapshot (if any) plus all retained updates after the snapshot point, returned as a single ordered response that preserves per-message content types.

### Method
GET

### Endpoint
`{stream_url}/bootstrap`

### Parameters
#### Query Parameters
- **live** (boolean) - Optional - Servers SHOULD reject this parameter on `/bootstrap` with `400 Bad Request`.
```

--------------------------------

### Minimal curl examples for bucket and stream operations

Source: https://ursula.tonbo.io/docs/clients

Use these curl commands to create buckets, stream data, perform catch-up reads, and live tail streams using Server-Sent Events.

```bash
# create a bucket and stream
curl -X PUT http://127.0.0.1:4437/demo
curl -X PUT http://127.0.0.1:4437/demo/hello

# append
curl -X POST http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/octet-stream' \
  --data-binary 'hello world'

# catch-up read
curl 'http://127.0.0.1:4437/demo/hello?offset=-1'

# live tail
curl 'http://127.0.0.1:4437/demo/hello?offset=-1&live=sse'
```

--------------------------------

### Start and Wait for Ursula Cluster

Source: https://ursula.tonbo.io/llms-full.txt

Starts the Ursula cluster and waits for all Raft groups to elect a leader. This is essential before performing other cluster operations.

```bash
python3 scripts/ursula_ec2.py --config cluster.json start
python3 scripts/ursula_ec2.py --config cluster.json wait-ready
```

--------------------------------

### Create Bucket and Stream

Source: https://ursula.tonbo.io/docs/api/overview

Use PUT requests to create a bucket and then a stream within that bucket.

```bash
curl -X PUT http://127.0.0.1:4437/demo
curl -X PUT http://127.0.0.1:4437/demo/hello
```

--------------------------------

### Build Bench Client and Ursula HTTP Server

Source: https://ursula.tonbo.io/benchmark

Builds the release versions of the Ursula bench client and the Ursula HTTP server using Cargo. This is the first step in reproducing the benchmark.

```bash
# 1. Build the bench client and the Ursula HTTP server
cargo build --release -p ursula -p ursula-bench
```

--------------------------------

### JSON Mode: Empty GET Response

Source: https://ursula.tonbo.io/docs/specs/durable-stream

If no messages exist within the requested range for an application/json stream, the GET response must be an empty JSON array.

```http
HTTP/1.1 200 OK
Content-Type: application/json

[]
```

--------------------------------

### Create Bucket and Stream

Source: https://ursula.tonbo.io/llms-full.txt

Use PUT requests to create a bucket namespace and then a stream within that bucket. Bucket creation is idempotent.

```bash
curl -X PUT http://127.0.0.1:4437/demo

```

```bash
curl -X PUT http://127.0.0.1:4437/demo/hello

```

--------------------------------

### JSON Mode: GET Response Format

Source: https://ursula.tonbo.io/docs/specs/durable-stream

GET responses for application/json streams must return a Content-Type of application/json and a body containing a JSON array of all messages within the requested range.

```http
HTTP/1.1 200 OK
Content-Type: application/json

[{"event":"created"},{"event":"updated"}]
```

--------------------------------

### Catch-up Read Mode

Source: https://ursula.tonbo.io/docs/api/read

Use this mode to retrieve all available data from a specified offset immediately. No 'live' parameter is needed.

```bash
curl 'http://127.0.0.1:4437/demo/hello?offset=-1'
```

--------------------------------

### SSE Binary Stream with Base64 Encoding Example

Source: https://ursula.tonbo.io/docs/specs/durable-stream

Shows an example of a binary stream using Server-Sent Events, where data is automatically base64 encoded. The 'data' lines contain the encoded bytes.

```text
event: data
data: AQIDBAUG
data: BwgJCg==

event: control
data: {"streamNextOffset":"123456_789","streamCursor":"abc"}
```

--------------------------------

### Bootstrap Endpoint

Source: https://ursula.tonbo.io/docs/concepts/bootstrap

Initializes a new client by fetching the latest snapshot and all post-snapshot updates in a single request. The response is a multipart/mixed body containing the snapshot (if available) followed by incremental updates.

```APIDOC
## GET /{bucket}/{stream}/bootstrap

### Description
Initializes a new client by fetching the latest snapshot and all post-snapshot updates in a single request. The response is a multipart/mixed body containing the snapshot (if available) followed by incremental updates.

### Method
GET

### Endpoint
`/{bucket}/{stream}/bootstrap`

### Parameters
#### Path Parameters
- **bucket** (string) - Required - The name of the bucket.
- **stream** (string) - Required - The name of the stream.

### Response
- **First part**: The snapshot. If no snapshot exists, this part is present but empty.
- **Subsequent parts**: Incremental updates from the snapshot offset (or from the earliest retained offset, if no snapshot exists).
Each part has its own `Content-Type`: the snapshot part uses `snapshot_content_type`. Update parts use the stream's content type.
```

--------------------------------

### Run Catch-up Replay Benchmark Scenario

Source: https://ursula.tonbo.io/benchmark

Executes the catch-up replay benchmark scenario against Ursula, Durable Streams, and S2 Lite. This scenario tests the ability of clients to replay data.

```bash
# 4. Replay (apples-to-apples on all three backends)
for api in ursula durable s2; do
 ursula-bench bootstrap --target http://NODE:PORT --api-style "$api" \
 --clients 1000 --pre-events 200 --per-client-stream
done
```

--------------------------------

### Get Snapshot at Offset

Source: https://ursula.tonbo.io/llms-full.txt

Retrieves the snapshot blob at a specific offset within a stream.

```APIDOC
## GET /{bucket}/{stream}/snapshot/{offset}

### Description
Returns the snapshot blob at a specific offset.

### Method
GET

### Endpoint
`/{bucket}/{stream}/snapshot/{offset}`

### Parameters
#### Path Parameters
- **offset** (string) - Required - Snapshot offset: the 20-character zero-padded decimal token returned by previous reads or `Stream-Snapshot-Offset` headers.

### Response
#### Success Response (200)
- **Content-Type** (string) - Description of the content type.
- **Stream-Next-Offset** (string) - The next offset in the stream.
- **Stream-Snapshot-Offset** (string) - The offset of the snapshot.
- **Stream-Up-To-Date** (string) - Indicates if the stream is up to date.
- **Stream-Closed** (string) - Indicates if the stream is closed.

#### Response Example
(No specific response body example provided in source, but headers are documented)
```

--------------------------------

### Get stream metadata

Source: https://ursula.tonbo.io/docs/api/overview

Retrieves metadata for a specific stream, such as its current state or size.

```APIDOC
## HEAD /{bucket}/{stream}

### Description
Retrieves metadata for a specific stream.

### Method
HEAD

### Endpoint
`/{bucket}/{stream}`

### Parameters
#### Path Parameters
- **bucket** (string) - Required - The name of the bucket containing the stream.
- **stream** (string) - Required - The name of the stream to get metadata for.
```

--------------------------------

### Get Bucket Metadata

Source: https://ursula.tonbo.io/docs/specs/extensions

Retrieves metadata for a specified bucket, including its ID and the count of streams it contains.

```APIDOC
## GET /{bucket_id}

### Description
Retrieves metadata for a specified bucket.

### Method
GET

### Endpoint
`/{bucket_id}`

### Parameters
#### Path Parameters
- **bucket_id** (string) - Required - The identifier for the bucket.

### Response
#### Success Response (200 OK)
Returns a JSON object with bucket metadata.
```json
{
  "bucket_id": "agents",
  "streams": 2
}
```
- **bucket_id** (string) - The identifier of the bucket.
- **streams** (integer) - The count of streams in the bucket.

#### Error Response
- **400 Bad Request**: `bucket_id` is invalid.
- **404 Not Found**: Bucket does not exist.
```

--------------------------------

### Idempotent Producer Bootstrap and Restart Flow

Source: https://ursula.tonbo.io/llms-full.txt

Describes the flow for initial producer startup and subsequent restarts, including how epochs are managed to ensure continuity and prevent zombie fencing.

```APIDOC
## Bootstrap and Restart Flow

1. **Initial start (epoch=0)**:
 - Producer sends `(epoch=0, seq=0)`
 - Server accepts, establishes producer state

2. **Producer restart**:
 - Producer increments local epoch (0 -> 1), resets seq to 0
 - Sends `(epoch=1, seq=0)`
 - Server sees epoch > state.epoch, accepts, updates state

3. **Zombie fencing**:
 - Old producer (zombie) still sending `(epoch=0, seq=N)` gets 403 Forbidden
 - Response includes `Producer-Epoch: 1` header
```

--------------------------------

### Get Bucket Metadata Endpoint

Source: https://ursula.tonbo.io/docs/specs/extensions

Retrieve metadata for an existing bucket, including its ID and the count of streams it contains.

```http
GET /{bucket_id}
```

--------------------------------

### Build and Test Entire Workspace

Source: https://ursula.tonbo.io/llms-full.txt

Compiles all crates in the workspace, runs tests, and lints with clippy, showing warnings.

```bash
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
```

--------------------------------

### Read Stream from Beginning

Source: https://ursula.tonbo.io/docs/quick-start

Retrieves all data from a stream starting from the earliest offset. The response includes stream metadata headers.

```bash
curl -i 'http://127.0.0.1:4437/demo/hello?offset=-1'
```

--------------------------------

### Configure Cold Storage Backend

Source: https://ursula.tonbo.io/docs/troubleshooting

If `URSULA_COLD_BACKEND` is set to `s3`, the `URSULA_COLD_S3_BUCKET` environment variable is required. If no cold storage is desired, leave `URSULA_COLD_BACKEND` unset.

```bash
URSULA_COLD_S3_BUCKET
URSULA_COLD_BACKEND=s3
```

--------------------------------

### Read Stream (Catch-up Mode)

Source: https://ursula.tonbo.io/docs/api/read

Reads all available data from the stream immediately starting from the specified offset. Use `offset=-1` to read from the beginning.

```APIDOC
## GET /demo/hello

### Description
Reads all available data from the stream immediately.

### Method
GET

### Endpoint
/demo/hello

### Parameters
#### Path Parameters
- **bucket** (string) - Required - Bucket ID.
- **stream** (string) - Required - Stream ID within the bucket.

#### Query Parameters
- **offset** (string) - Optional - Starting offset. Use `-1` to read from the beginning, or a numeric offset.
- **cursor** (string) - Optional - Opaque cursor token returned by a previous read. Alternative to `offset`.
- **stream-cursor** (string) - Optional - Alias for `cursor`.
- **max-bytes** (number) - Optional - Maximum bytes to return in a single response (catch-up and long-poll only).

### Request Example
```bash
curl 'http://127.0.0.1:4437/demo/hello?offset=-1'
```

### Response
#### Success Response (200)
- **Data** - The stream payload.
- **Stream-Next-Offset** (string) - The offset of the next available data.
- **Stream-Cursor** (string) - An opaque cursor token for subsequent reads.
- **ETag** (string) - Entity tag for caching.
- **Stream-Up-To-Date** (string) - Indicates if the stream is up-to-date.
- **Stream-Closed** (string) - Indicates if the stream is closed.
- **Content-Type** (string) - The content type of the stream data.

#### Response Example
```json
{
  "data": "..."
}
```

#### Error Responses
- **204** - No new data at the requested offset.
- **400** - Invalid offset or live mode.
- **404** - Stream not found or expired.
- **410** - Requested offset has been trimmed (data no longer available).
```

--------------------------------

### JSON Mode: Single Message POST Example

Source: https://ursula.tonbo.io/llms-full.txt

Illustrates how a single JSON object in a POST request body is stored as a distinct message.

```json
{"event": "created"}
```
Tokens:
Raw