# Ursula

> Open-source Distributed Durable Streams over HTTP, backed by S3.

Customer-facing documentation. Each page is also available as raw markdown at
https://opendurability.github.io/ursula/docs/<slug>.md (e.g. https://opendurability.github.io/ursula/docs/quick-start.md). For all docs
concatenated, fetch https://opendurability.github.io/ursula/llms-full.txt.

## Getting Started

- [Ursula](https://opendurability.github.io/ursula/docs/introduction.md): Distributed Durable Streams over HTTP, backed by S3.
- [Why Ursula](https://opendurability.github.io/ursula/docs/why-ursula.md): Where Ursula fits as a durable, replayable stream layer for application state.
- [Quick Start](https://opendurability.github.io/ursula/docs/quick-start.md): Run Ursula locally, create a bucket, append data, and subscribe with SSE.

## Install & Deploy

- [Install](https://opendurability.github.io/ursula/docs/install.md): Build Ursula from source and prepare a host to run the server.
- [Run locally](https://opendurability.github.io/ursula/docs/run-locally.md): Start a single-node Ursula server and verify the HTTP API.
- [Deploy a cluster](https://opendurability.github.io/ursula/docs/deploy-cluster.md): Run a three-node Ursula cluster with Raft replication and shared cold storage.
- [Configure S3](https://opendurability.github.io/ursula/docs/configure-s3.md): Configure Ursula cold storage with S3-compatible object storage.
- [Control CLI](https://opendurability.github.io/ursula/docs/control-cli.md): Use ursulactl to inspect, bootstrap, and operate Ursula clusters.
- [Operations](https://opendurability.github.io/ursula/docs/operations.md): Health, capacity, snapshots, backup, and upgrades for Ursula clusters.

## Concepts

- [Streams](https://opendurability.github.io/ursula/docs/concepts/streams.md): Ursula's core append-only stream primitive, with naming, content type, and lifecycle.
- [Buckets](https://opendurability.github.io/ursula/docs/concepts/buckets.md): Buckets group related streams into namespaces.
- [Offsets](https://opendurability.github.io/ursula/docs/concepts/offsets.md): Position tokens inside a stream, with how to read, resume, and follow safely.
- [Read Modes](https://opendurability.github.io/ursula/docs/concepts/read-modes.md): Compare catch-up, long-poll, and SSE reads for Ursula clients.
- [Snapshots](https://opendurability.github.io/ursula/docs/concepts/snapshots.md): Compact stream history and accelerate first-load for new clients.
- [Bootstrap](https://opendurability.github.io/ursula/docs/concepts/bootstrap.md): Initialize a new client with one request, fetching snapshot plus post-snapshot updates.
- [Exactly-Once Writes](https://opendurability.github.io/ursula/docs/concepts/exactly-once-writes.md): Producer identifiers, epochs, and sequence numbers deliver deduplicated appends.
- [Conditional Writes](https://opendurability.github.io/ursula/docs/concepts/conditional-writes.md): Coordinate multiple writers using If-Match and Stream-Seq without adding locks or transactions.
- [Durability and Consistency](https://opendurability.github.io/ursula/docs/concepts/durability-and-consistency.md): Understand Ursula's durability guarantees, linearizable writes, and hot-cold storage model.
- [Length-Prefixed Framing](https://opendurability.github.io/ursula/docs/concepts/len-prefixed-framing.md): A simple convention for delimiting messages inside raw byte streams.
- [Binary SSE](https://opendurability.github.io/ursula/docs/concepts/binary-sse.md): How Ursula delivers binary payloads over the Server-Sent Events transport.

## Architecture

- [Overview](https://opendurability.github.io/ursula/docs/architecture/overview.md)

## API

- [API overview](https://opendurability.github.io/ursula/docs/api/overview.md): Learn the public Ursula HTTP routes for creating, appending, reading, and replaying streams.
- [Create bucket](https://opendurability.github.io/ursula/docs/api/create-bucket.md): Create a new bucket to organize streams.
- [Get bucket](https://opendurability.github.io/ursula/docs/api/get-bucket.md): Retrieve metadata for a bucket.
- [Delete bucket](https://opendurability.github.io/ursula/docs/api/delete-bucket.md): Delete an empty bucket.
- [List streams](https://opendurability.github.io/ursula/docs/api/list-streams.md): List streams within a bucket with optional prefix filtering and pagination.
- [Create stream](https://opendurability.github.io/ursula/docs/api/create-stream.md): Create a new append-only stream within a bucket.
- [Append](https://opendurability.github.io/ursula/docs/api/append.md): Append data to an existing stream, or close it.
- [Read stream](https://opendurability.github.io/ursula/docs/api/read.md): Read data from a stream using catch-up, long-poll, or SSE modes.
- [Head stream](https://opendurability.github.io/ursula/docs/api/head-stream.md): Get stream metadata without reading its content.
- [Delete stream](https://opendurability.github.io/ursula/docs/api/delete-stream.md): Delete a stream and its data.
- [Bootstrap](https://opendurability.github.io/ursula/docs/api/bootstrap.md): Recover full stream state from snapshot plus retained updates in a single request.
- [Read snapshot](https://opendurability.github.io/ursula/docs/api/read-snapshot.md): Read the latest snapshot or a snapshot at a specific offset.
- [Publish snapshot](https://opendurability.github.io/ursula/docs/api/publish-snapshot.md): Upload a snapshot blob at a specific stream offset.
- [v1 compatibility](https://opendurability.github.io/ursula/docs/api/v1-compatibility.md): Flat Durable Streams protocol routes under /v1/stream/.

## Protocol Specification

- [Durable Streams Protocol](https://opendurability.github.io/ursula/docs/specs/durable-stream.md): The base HTTP protocol specification for creating, appending to, and reading from durable, append-only byte streams.
- [Durable Streams Extensions](https://opendurability.github.io/ursula/docs/specs/extensions.md): Extensions to the Durable Streams Protocol: bucket namespacing, snapshot semantics, and bootstrap delivery.

## Comparisons

- [Comparisons](https://opendurability.github.io/ursula/docs/competitive-comparison.md): How Ursula relates to other stream and storage systems for application-facing timelines.

## Reference

- [Clients](https://opendurability.github.io/ursula/docs/clients.md): Talking to Ursula from any HTTP client.
- [Configuration](https://opendurability.github.io/ursula/docs/configuration.md): Every Ursula configuration key, with TOML sections, environment variables, CLI flags, and precedence.
- [Security](https://opendurability.github.io/ursula/docs/security.md): What Ursula does and does not handle in the security model, and how to deploy it safely.
- [Troubleshooting](https://opendurability.github.io/ursula/docs/troubleshooting.md): Common Ursula failure modes, what they look like, how to diagnose them, and what to do.