### Install Prerequisites on Debian/Ubuntu

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/install.mdx

Installs build essentials, pkg-config, and curl, then sets up Rust using rustup on Debian or Ubuntu systems.

```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
```

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

### Install Prerequisites on macOS

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/install.mdx

Installs Rust and pkg-config using Homebrew on macOS.

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

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

### SSE Request Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Example of a GET request to read a stream in Server-Sent Events (SSE) mode. Requires an offset and the 'live=sse' query parameter.

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

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

### Read Stream Examples (Multiple Modes)

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/read.mdx

Demonstrates the curl command for initiating stream reads in catch-up, long-poll, and SSE modes. These examples show how to specify the offset and live mode parameters.

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

```bash
curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'
```

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

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

### Bootstrap Response Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/extensions.mdx

An example of a successful bootstrap response, 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://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/install.mdx

Checks the Ursula installation by printing its help message.

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

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

### Bootstrap API Request Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/bootstrap.mdx

This example shows how to make a curl request to the bootstrap endpoint to retrieve the stream's state. Ensure the correct host, port, bucket, and stream are specified.

```bash
curl 'http://127.0.0.1:4437/demo/hello/bootstrap'
```

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

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

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

This example demonstrates a GET request for live tailing using the long-poll mechanism. It includes optional cursor for CDN collapsing.

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

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

### WAL-Backed Single Node Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configuration.mdx

Configures Ursula for single-node operation using Write-Ahead Logging (WAL) for persistence. This example sets the listening address, core count, Raft group count, and specifies a directory for WAL files.

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

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

### Start Local Ursula Node (WAL-Backed)

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/quick-start.mdx

Run the Ursula node locally with Write-Ahead Log (WAL) backed persistence. Point `--wal-dir` to an empty directory to enable this mode.

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

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

### Start Node 1

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/deploy-cluster.mdx

Command to start the first node of the Ursula cluster. The `init_membership_per_group` flag is only needed for the initial cluster startup.

```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
```

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

### EC2 Helper: Start Cluster

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/operations.mdx

Start the Ursula cluster and wait for all Raft groups to elect a leader.

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

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

### Get Ursula Metrics

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/operations.mdx

Fetch JSON metrics from the local Ursula instance. Start here when triaging performance issues or errors.

```bash
curl http://127.0.0.1:4437/__ursula/metrics | jq .
```

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

### Publish Snapshot Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/publish-snapshot.mdx

Use this cURL command to publish a new snapshot blob at a specific stream offset. Ensure the offset is zero-padded and the Content-Type matches the data.

```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"}'
```

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

### Three-Node Durable Cluster Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configuration.mdx

Deploys a three-node durable Raft cluster using S3 for cold storage. This example sets environment variables for S3 bucket and region, and configures Ursula with a listening address, core count, Raft group count, durable Raft log directory, and a cluster configuration 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
```

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

### Create Bucket Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/create-bucket.mdx

Use this command to create a bucket namespace. The bucket ID must conform to the Durable Streams Protocol regex: [a-z0-9_-]{4,64}. The current implementation is a no-op acknowledgement and always returns 201.

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

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

### Run Ursula Smoke Server and Test Endpoints

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/install.mdx

Starts the Ursula server in the background and sends requests to test its basic 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'
```

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

### SSE Example: Binary Stream with Base64 Encoding

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Demonstrates how binary data is transmitted using Server-Sent Events, with base64 encoding applied to the data payloads.

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

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

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

### List Streams in a Bucket

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/concepts/buckets.mdx

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

```bash
GET /{bucket}/streams
```

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

### Create Stream, Append, and Read Data with cURL

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/introduction.mdx

Demonstrates creating a stream, appending bytes to it, and reading the data back using cURL. This example interacts with a locally running Ursula instance.

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

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

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

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

### Run In-Memory Raft Server

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/run-locally.mdx

Starts Ursula with an in-memory log for OpenRaft. This configuration is fast for iteration and exercises the Raft path without persistence.

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

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

### Run Ursula In-Memory Node

Source: https://github.com/tonbo-io/ursula/blob/main/README.md

Starts a single in-memory Ursula node for testing. It binds to localhost:4437 and uses an in-memory engine. Configuration can be overridden using command-line flags.

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

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

### SSE Example: Final Data and Stream Closure

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Shows the Server-Sent Events format for the final data batch and the subsequent control event indicating stream closure.

```text
event: data
data: [
data: {"k":"final"}
data: ]

event: control
data: {"streamNextOffset":"123456_999","streamClosed":true}
```

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

### Tail Stream Live via SSE

Source: https://github.com/tonbo-io/ursula/blob/main/README.md

Tails the 'demo/hello' stream live using Server-Sent Events (SSE). New appends are received immediately as 'event: data' lines. Starts reading from the last event.

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

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

### SSE Example: Normal Data and Control Events

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Illustrates the Server-Sent Events format for regular data batches and control signals, including JSON arrays streamed across multiple data lines.

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

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

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

### In-Memory Single Node Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configuration.mdx

Launches Ursula in an in-memory mode, suitable for single-node development or testing. It configures listening address, core count, Raft group count, and enables in-memory Raft logging.

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

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

### Read Stream Data with v1 Path

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/v1-compatibility.mdx

Read data from a stream using the v1 compatibility path. You can specify an `offset` to start reading from a particular position. An offset of -1 reads from the end.

```bash
curl 'http://127.0.0.1:4437/v1/stream/mystream?offset=-1'
```

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

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

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/bootstrap.mdx

Recovers the full stream state from a snapshot plus retained updates in a single request. This is the recommended method for initializing a client with the complete current state of a stream.

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

### Description
Recovers the full stream state from a snapshot plus retained updates in a single request. This is the recommended method for initializing a client with the complete current state of a stream.

### Method
GET

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

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

#### Query Parameters
Bootstrap does not accept `?live=sse`. Combining the multipart body with an SSE event stream is rejected with `400`.

### Response
#### Success Response (200)
- **Content-Type** (string) - `multipart/mixed; boundary=...`
- **Stream-Next-Offset** (string) - The offset after the last included update.
- **Stream-Snapshot-Offset** (string) - The snapshot offset (or `none` if no snapshot exists).
- **Stream-Up-To-Date** (string) - `true` if the response includes all data up to the tail.
- **Stream-Closed** (string) - Present and `true` if the stream is closed and fully caught up.

The body is a `multipart/mixed` message containing the snapshot part (if any) followed by individual update parts.

#### Response Example
```bash
curl 'http://127.0.0.1:4437/demo/hello/bootstrap'
```
```

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

### Configure Filesystem Backend

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configure-s3.mdx

Set the filesystem backend and specify the root directory for cold storage. This is intended for single-node testing only.

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

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

### Read Stream - Catch-up

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Send a GET request to the stream's URL with an optional 'offset' query parameter to retrieve bytes starting from a specified position. This is used for catch-up reads when a client needs to replay stream content from a known position. If 'offset' is omitted, it defaults to the stream start (offset -1).

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

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

### EC2 Helper: Run Benchmark

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/operations.mdx

Drive the benchmark workload from a configured client host, rotating entrypoints by default.

```bash
python3 scripts/ursula_ec2.py --config cluster.json perf-many \
  --processes 4 --bucket-prefix benchcmp-mp
```

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

### Get Bucket Metadata

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/concepts/buckets.mdx

Use GET to retrieve metadata associated with a specific bucket.

```bash
GET /{bucket}
```

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

### Bootstrap Request

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/extensions.mdx

Initiates a one-shot initialization request for a stream, providing a snapshot and all retained updates after it. Servers SHOULD reject any 'live' query parameter.

```http
GET {stream_url}/bootstrap
```

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

### Create Bucket and Stream

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/overview.mdx

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
```

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

### JSON Mode: Empty GET Response

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

If no messages are found within the requested range for an `application/json` stream, the GET response body will be an empty JSON array `[]`.

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

[]
```

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

### Configure Cold Storage Environment Variables

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/deploy-cluster.mdx

Set environment variables on each node to configure the shared cold storage backend, recommended for multi-node deployments.

```bash
URSULA_COLD_BACKEND=s3
URSULA_COLD_S3_BUCKET=my-ursula-bucket
URSULA_COLD_S3_REGION=us-east-1
URSULA_COLD_ROOT=ursula-prod-20260518
```

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

### JSON Mode: GET Response Format

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

GET responses for `application/json` streams return a `Content-Type: application/json` header and a JSON array containing all messages within the requested range.

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

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

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

### Get Bucket Metadata

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/extensions.mdx

Retrieve metadata for an existing bucket using a GET request. The response includes the bucket ID, stream count, and other details. Handles cases where the bucket is invalid or not found.

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

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

### Create Stream with v1 Path

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/v1-compatibility.mdx

Use this command to create a stream using the v1 compatibility path. The stream will be created in the `_default` bucket if no bucket is specified in the path.

```bash
curl -X PUT http://127.0.0.1:4437/v1/stream/mystream
```

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

### Create Bucket and Stream with curl

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/clients.mdx

Use `curl` to create a bucket and a stream within that bucket. These are the initial steps before appending data.

```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
```

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

### Bootstrap

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/extensions.mdx

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.

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

### Description
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

### 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`.
```

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

### Get Bucket Metadata

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/concepts/buckets.mdx

Retrieves metadata associated with a specific bucket.

```APIDOC
## GET /{bucket}

### Description
Returns metadata for the specified bucket.

### Method
GET

### Endpoint
`/{bucket}`

### Parameters
#### Path Parameters
- **bucket** (string) - Required - The ID of the bucket to retrieve metadata for.
```

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

### Configure S3 Backend

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configure-s3.mdx

Set the S3 backend and specify the bucket and region. An optional prefix can be used for organizing data.

```bash
export URSULA_COLD_BACKEND=s3
export URSULA_COLD_S3_BUCKET=my-ursula-bucket
export URSULA_COLD_S3_REGION=us-east-1
export URSULA_COLD_ROOT=ursula-prod-20260518   # optional prefix
```

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

### GET /{bucket}/{stream}

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/read.mdx

Read data from a stream using catch-up, long-poll, or SSE modes.

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

### Description
Read data from a stream using catch-up, long-poll, or SSE modes.

### Method
GET

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

### 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`.
- **live** (string) - Optional - Live mode: `sse` for Server-Sent Events, `long-poll` for long-polling. Omit for catch-up read.
- **max-bytes** (number) - Optional - Maximum bytes to return in a single response (catch-up and long-poll only).

### Response
#### Success Response (200)
- **Data returned** (catch-up or long-poll with data).

#### Success Response (204)
- **No new data** at the requested offset (catch-up only).

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

Response headers include `Stream-Next-Offset`, `Stream-Cursor`, `ETag`, `Stream-Up-To-Date`, `Stream-Closed`, and `Content-Type`.

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

```bash
curl 'http://127.0.0.1:4437/demo/hello?offset=42&live=long-poll'
```

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

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

### Read Stream - Catch-up

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Reads data from a stream starting at a specified offset. This is used for catching up on historical data.

```APIDOC
## GET /streams/{stream-id}

### Description
Reads bytes from the stream starting at the specified offset, up to a server-defined maximum chunk size. Servers SHOULD return `200 OK` with an empty body if no data is available beyond the requested offset. If the stream is closed, this response MUST also include `Stream-Closed: true` to signal EOF.

### Method
GET

### Endpoint
`{stream-url}`

### Query Parameters
- **offset** (string) - Required - The offset to read from.

### Response Codes
- `200 OK`: Data available (or empty body if offset equals tail)
- `400 Bad Request`: Malformed offset or invalid parameters
- `404 Not Found`: Stream does not exist
- `410 Gone`: Offset is before the earliest retained position (retention/compaction)
- `429 Too Many Requests`: Rate limit exceeded

### Response Headers (on 200)
- **Cache-Control** (string) - Derived from TTL/expiry
- **ETag** (string) - `{internal_stream_id}:{start_offset}:{end_offset}` - Entity tag for cache validation
- **Stream-Cursor** (string) - Optional - Cursor to echo on subsequent long-poll requests
- **Stream-Next-Offset** (string) - The next offset to read from
- **Stream-Up-To-Date** (string) - `true` if all data available at response generation time is included
- **Stream-Closed** (string) - `true` if the stream is closed and the client has reached the final offset

### Response Body
Bytes from the stream starting at the specified offset, up to a server-defined maximum chunk size.
```

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

### HEAD /{bucket}/{stream}

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/head-stream.mdx

Get stream metadata without reading its content. Supports conditional requests using the If-None-Match header.

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

### Description
Get stream metadata without reading its content.

### Method
HEAD

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

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

#### Header Parameters
- **If-None-Match** (string) - Optional - ETag for conditional request. Returns `304` if the stream state has not changed.

### Response
#### Success Response (200)
- **Content-Type** (string) - The stream's content type.
- **Stream-Next-Offset** (string) - The next writable offset (= current length).
- **ETag** (string) - Stream state ETag (encodes offset and open/closed state).
- **Stream-Closed** (string) - Present and `true` if the stream is closed.
- **Stream-Snapshot-Offset** (string) - Present if a snapshot exists, showing its offset.
- **Stream-TTL** (string) - Remaining TTL in seconds (if a TTL was set).
- **Stream-Expires-At** (string) - Expiration timestamp (if set).
- **Cache-Control** (string) - `no-store`.

#### Error Responses
- **404** - Stream not found or expired.

#### Response Example (200 OK)
```http
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Stream-Next-Offset: 1024
ETag: "abcdef12345"
Cache-Control: no-store
```

#### Response Example (304 Not Modified)
```http
HTTP/1.1 304 Not Modified
ETag: "abcdef12345"
Cache-Control: no-store
```

<Tip>
Use `If-None-Match` with a previously received `ETag` to efficiently poll for state changes without transferring data.
</Tip>
```

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

### Read All Data from Stream

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/quick-start.mdx

Read all data from a stream starting from the beginning (offset -1). The response includes stream metadata headers.

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

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

### Get Ursula Metrics Snapshot

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/troubleshooting.mdx

Fetch the JSON metrics snapshot from a Ursula node. This is the primary source of truth for diagnosing operational issues.

```bash
curl http://NODE:4437/__ursula/metrics | jq .
```

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

### Follow redirect to latest snapshot

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/read-snapshot.mdx

Use this command to retrieve the latest published snapshot by following redirects. Ensure the server is running and accessible at the specified address.

```bash
curl -L 'http://127.0.0.1:4437/demo/hello/snapshot'
```

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

### Configure S3-Compatible Endpoint

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/configure-s3.mdx

Specify the endpoint for S3-compatible object storage services like MinIO or R2.

```bash
export URSULA_COLD_S3_ENDPOINT=http://127.0.0.1:9000
```

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

### Read Stream - Catch-up

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/durable-stream.mdx

Reads bytes from a stream starting from a specified offset. This is used for catch-up reads when a client needs to replay stream content from a known position.

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

### Description
Returns bytes from the stream starting from the specified offset. Used for catch-up reads.

### Method
GET

### Endpoint
`{stream-url}`

### Query Parameters
- **offset** (integer) - Optional - Start offset token. If omitted, defaults to the stream start (offset -1).
```

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

### Read Stream (Catch-up Mode)

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/read.mdx

Use this mode to retrieve all available data from a specified offset immediately. Useful for initial data loading or when you need all historical data.

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

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

### Recommended Deployment Architecture

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/security.mdx

This diagram illustrates a secure deployment pattern for Ursula, emphasizing the role of a reverse proxy for handling external security concerns like TLS termination and client authentication.

```text
                    Untrusted internet
                            │
                            v
                  ┌─────────────────────┐
                  │   Reverse proxy     │  TLS, authn, per-client
                  │ (nginx / Envoy / …) │  rate limiting, CORS
                  └──────────┬──────────┘
                             │ plain HTTP, private network
                ┌────────────┼────────────┐
                v            v            v
           ┌────────┐   ┌────────┐   ┌────────┐
           │ Ursula │   │ Ursula │   │ Ursula │
           │  node  │   │  node  │   │  node  │
           └────────┘   └────────┘   └────────┘
                             ↕ gRPC h2c on private network
                          (Raft replication)
```

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

### Create a Bucket

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/concepts/buckets.mdx

Use PUT to create a bucket. This operation is idempotent, meaning it can be called multiple times with the same result.

```bash
PUT /{bucket}
```

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

### Get Stream Metadata

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/head-stream.mdx

Use this command to retrieve the headers (metadata) for a specific stream within a bucket. This is useful for checking stream status or ETag without downloading the actual data.

```bash
curl -I http://127.0.0.1:4437/demo/hello
```

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

### Create Bucket and Stream with Python requests

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/clients.mdx

Use the `requests` library in Python to create a bucket and a stream. This mirrors the `curl` PUT operations.

```python
import requests

base = "http://127.0.0.1:4437"

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

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

### List Bucket Streams Response

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/specs/extensions.mdx

Example JSON response structure for listing streams in a bucket. Includes bucket information, stream count, a list of streams with their metadata, and pagination details.

```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
}
```

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

### Create Stream with Initial Payload

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/create-stream.mdx

Create a stream and immediately add an initial payload. The `Content-Type` header determines the stream's content type.

```bash
curl -X PUT http://127.0.0.1:4437/demo/hello \
  -H 'Content-Type: application/json' \
  --data-binary '{"msg": "first entry"}'
```

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

### Clone Ursula Repository and Build Release Binary

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/install.mdx

Clones the Ursula repository from GitHub and builds the release binary for the Ursula server.

```bash
git clone https://github.com/tonbo-io/ursula.git
cd ursula
cargo build --release -p ursula --bin ursula
```

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

### Delete Stream Example

Source: https://github.com/tonbo-io/ursula/blob/main/docs/web/src/content/docs/pages/api/delete-stream.mdx

Use this cURL command to delete a specific stream from a bucket. Ensure you replace 'demo' and 'hello' with your actual bucket and stream IDs. Deletion is permanent and data will be garbage-collected asynchronously.

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