Crate ursula_runtime 

Per-core actor runtime for Ursula.

Module map:

• [cold_store]: opendal-backed cold tier handle and object path helpers.
• [request]: HTTP/gRPC request and response value types for each engine op.
• [command]: the replicated GroupWriteCommand envelope around the canonical ursula_stream::StreamCommand, plus From conversions from request values into that command.
• [error]: runtime-level error type RuntimeError.
• [engine]: the GroupEngine trait, factory, metrics, and the boxed-future type aliases that form the replaceable per-group engine boundary, plus the in-memory implementation under [engine::in_memory].
• [runtime]: ShardRuntime, RuntimeConfig, and per-core worker spawn.
• [core_worker]: single-thread actor that owns groups for one core.
• [group_actor]: per-group mailbox actor running inside a core worker.
• [ops]: declarative manifest of the uniform runtime operations; expands into the per-operation actor and client plumbing.
• [metrics]: runtime metrics shared across cores; lock-free counters.

Re-exports

pub use cold_index::ColdIndexPage;

pub use cold_index::ColdIndexPageCache;

pub use cold_index::ColdIndexPageKey;

pub use cold_index::ColdIndexPageStore;

pub use cold_index::ColdStoreColdIndexPageStore;

pub use cold_index::InMemoryColdIndexPageStore;

pub use cold_index::cold_index_prefix;

pub use cold_index::load_cold_chunks_from_pages;

pub use cold_index::replace_cold_chunk_index_pages;

pub use cold_index::replace_cold_chunk_index_pages_with_rollback;

pub use cold_index::rollback_cold_index_pages;

pub use cold_index::select_cold_chunk_compaction;

pub use cold_index::write_cold_chunk_index_pages;

pub use cold_index::write_external_segment_index_pages;

pub use cold_worker::spawn_cold_compaction_worker_if_configured;

pub use cold_worker::spawn_cold_flush_worker_if_configured;

pub use cold_worker::spawn_cold_gc_worker_if_configured;

Modules

cold_index

cold_worker

Cold-tier background workers.

journal

Append-only framed journal.

Structs

AckColdGcResponse

AdvanceRetentionRequest

AdvanceRetentionResponse

AppendBatchRequest

AppendBatchResponse

AppendExternalRequest

AppendRequest

AppendResponse

BootstrapStreamRequest

BootstrapStreamResponse

BootstrapUpdate

CloseStreamRequest

CloseStreamResponse

ColdConfig

Cold-tier flush, GC, and cache configuration.

ColdFlushCandidate

ColdGcEntry

One unit of deferred cold-storage reclamation. Enqueued deterministically in the state machine when a stream’s cold objects become unreferenced, drained asynchronously by the leader’s background GC worker.

ColdHotBacklog

ColdReadCacheParams

Runtime parameters for the optional cold-read cache.

ColdStore

ColdStoreFault

ColdStoreFaultContext

ColdStoreFaultEffect

ColdStoreInfo

ColdWriteAdmission

CompactColdRequest

CompactColdResponse

CreateStreamExternalRequest

CreateStreamRequest

CreateStreamResponse

DeleteSnapshotRequest

DeleteStreamRequest

DeleteStreamResponse

FlushColdRequest

FlushColdResponse

GetStreamAttrsRequest

GetStreamAttrsResponse

GroupAppendBatchResponse

GroupEngineMetrics

GroupLeaderHint

GroupReadStreamParts

GroupSnapshot

HeadStreamRequest

HeadStreamResponse

ImportGroupStateRequest

ImportGroupStateResponse

InMemoryGroupEngine

InMemoryGroupEngineFactory

InlineSnapshotStore

Bytes live inside the pointer. Equivalent to today’s in-memory snapshot.

PlanColdFlushRequest

PlanGroupColdFlushRequest

PublishSnapshotRequest

PublishSnapshotResponse

PurgeBucketReport

Cluster-local summary of a bucket purge across all Raft groups.

PurgeBucketResponse

RaftUncommittedAdmission

Per-group admission that rejects new writes when the raft layer has not yet committed enough previously-submitted bytes. Independently configurable from the cold-side admission; intended to catch “replication lag” scenarios where hot bytes have not yet grown because nothing is committing.

ReadSnapshotRequest

ReadSnapshotResponse

ReadStreamRequest

ReadStreamResponse

RuntimeConfig

RuntimeMailboxSnapshot

RuntimeMetrics

RuntimeMetricsSnapshot

S3SnapshotStore

Bytes live in an opendal-managed S3 bucket under {prefix}/group-{gid}/.

SetBucketQuotaRequest

Sets or clears one bucket’s data-plane quota record on a group. The caller replicates the same request to every group.

SetBucketQuotaResponse

ShardRuntime

SnapshotKey

Identifier the store uses to derive a key/path for a snapshot blob.

SnapshotPointer

Reference shipped through openraft SnapshotData. Tiny when the backend stores the actual bytes out of line.

SnapshotReferenceConfig

Node identities that may persist an external snapshot pointer for each group. S3 pruning is enabled only after every expected voter has published its current reference, which makes rolling upgrades fail closed.

StreamAppendCount

StreamAttrs

StreamIntegritySnapshot

StreamRecordRange

StreamSnapshot

TouchStreamAccessResponse

UpdateStreamAttrsRequest

UpdateStreamAttrsResponse

Enums

ColdGcTarget

ColdStoreEvent

ColdStoreOperation

ErrorStatus

GroupEngineError

GroupInfraError

Infra error variants with structured fields render their human message on demand (message) instead of storing a denormalized copy alongside the fields. Internal is the exception: it carries free-form text with no structured source, so it keeps an owned message.

GroupReadStreamBody

GroupWriteCommand

Replicated group-level write envelope around the canonical StreamCommand: either one per-stream command, or an atomic batch of them applied as a single raft entry. This enum (serde-encoded) is the raft log payload; there is no separate wire mirror.

GroupWriteResponse

RuntimeError

RuntimeThreading

SnapshotCompression

SnapshotLocation

Where a snapshot blob lives. Carried in SnapshotPointer over openraft.

SnapshotStoreError

StreamErrorCode

StreamErrorContext

Traits

GroupEngine

GroupEngineFactory

SnapshotStore

Functions

default_snapshot_store

Default backend used when none is wired: bytes ride inline in the pointer.

new_cold_chunk_path

new_external_payload_path

snapshot_store_from_config

Pick a snapshot store from a typed ursula_config::RaftSnapshotConfig. Returns None when the backend is “inline” (the default) so callers can fall back to default_snapshot_store without instantiating anything.

Type Aliases

ColdChunkRef

ColdStoreHandle

ExternalPayloadRef

GroupAckColdGcFuture

GroupAdvanceRetentionFuture

GroupAppendBatchFuture

GroupAppendFuture

GroupBootstrapStreamFuture

GroupBucketUsageFuture

GroupCloseStreamFuture

GroupColdHotBacklogFuture

GroupCompactColdFuture

GroupCreateStreamFuture

GroupDeleteSnapshotFuture

GroupDeleteStreamFuture

GroupEngineCreateFuture

GroupFlushColdFuture

GroupGetStreamAttrsFuture

GroupHeadStreamFuture

GroupImportGroupStateFuture

GroupInstallSnapshotFuture

GroupPlanColdFlushFuture

GroupPlanColdGcFuture

GroupPlanNextColdFlushBatchFuture

GroupPublishSnapshotFuture

GroupPurgeBucketFuture

GroupReadSnapshotFuture

GroupReadStreamFuture

GroupReadStreamPartsFuture

GroupRequireLiveReadOwnerFuture

GroupSetBucketQuotaFuture

GroupShutdownFuture

GroupSnapshotFuture

GroupTouchStreamAccessFuture

GroupUpdateStreamAttrsFuture

GroupWriteBatchFuture

GroupWriteFuture

ProducerRequest

SharedSnapshotStore

SnapshotBytesIterator

SnapshotStoreFuture