Struct StorageService 

pub struct StorageService { /* private fields */ }

Asynchronous storage service wrapping a single Backend.

StorageService is the main entry point for storing and retrieving objects. It delegates all storage operations to the backend supplied at construction, adding task spawning, panic isolation, and a concurrency limit on top.

The typical backend is TieredStorage, which provides size-based routing to high-volume and long-term backends along with redirect tombstone management. Any type implementing Backend can be used.

Lifecycle

After construction, call start to start the service’s background processes.

Run-to-Completion and Panic Isolation

Each operation runs to completion even if the caller is cancelled (e.g., on client disconnect). This ensures that multi-step operations in the backend are never left partially applied. Post-commit cleanup (e.g. deleting unreferenced long-term blobs) runs in background tasks so callers are not blocked. Call join during shutdown to wait for outstanding cleanup. Operations are also isolated from panics in backend code — a failure in one operation does not bring down other in-flight work. See Error::Panic.

Concurrency Limit

A semaphore caps the number of in-flight backend operations. The limit is configured via with_concurrency_limit; without an explicit value the default is DEFAULT_CONCURRENCY_LIMIT. Operations that exceed the limit are rejected immediately with Error::AtCapacity.

Implementations

impl StorageService

pub fn new(backend: Box<dyn Backend>) -> Self

Creates a new StorageService wrapping the given backend.

pub fn with_concurrency_limit(self, max: usize) -> Self

Sets the maximum number of concurrent backend operations.

Must be called before start. Operations beyond this limit are rejected with Error::AtCapacity.

pub fn tasks_available(&self) -> usize

Returns the number of backend task slots currently available.

pub fn tasks_running(&self) -> usize

Returns the number of backend tasks currently running.

pub fn tasks_limit(&self) -> usize

Returns the configured limit for concurrent backend tasks.

pub fn stream(&self) -> Result<StreamExecutor>

Prepares to stream multiple operations concurrently against this service.

Operations are executed concurrently up to a window derived from the service’s current capacity. The permits for that window are reserved upfront — if the service is at capacity, this returns Error::AtCapacity immediately before any operations are read.

pub fn start(&self)

Starts background processes for the storage service.

Currently spawns a task that emits the service.concurrency.in_use and service.concurrency.limit gauges once per second.

pub async fn insert_object( &self, context: ObjectContext, key: Option<String>, metadata: Metadata, stream: ClientStream, ) -> Result<InsertResponse>

Creates or overwrites an object.

The object is identified by the components of an ObjectId. The context is required, while the key can be assigned automatically if set to None.

Run-to-completion

Once called, the operation runs to completion even if the returned future is dropped (e.g., on client disconnect). This guarantees that partially written objects in the backend are never left in an inconsistent state.

pub async fn get_metadata(&self, id: ObjectId) -> Result<MetadataResponse>

Retrieves only the metadata for an object, without the payload.

pub async fn get_object(&self, id: ObjectId) -> Result<GetResponse>

Streams the contents of an object.

pub async fn delete_object(&self, id: ObjectId) -> Result<DeleteResponse>

Deletes an object, if it exists.

Run-to-completion

Once called, the operation runs to completion even if the returned future is dropped. This guarantees that multi-step delete sequences in the backend are never left partially applied.

pub async fn join(&self)

Waits for all outstanding background operations to complete.

Blocks until any pending background cleanup tasks finish, up to the backend’s configured timeout. Should be called during graceful shutdown after the HTTP server has stopped accepting new requests.

Trait Implementations

impl Clone for StorageService

fn clone(&self) -> StorageService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StorageService

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.