Skip to main content

Crate objsds

Crate objsds 

Source
Expand description

Blocking, single-object distributed data structures.

Each Map or Log is stored as one JSON object. Every public operation is synchronous and may block the calling thread on object-store I/O. Reads download and decode the complete structure. Mutations additionally encode and conditionally replace the complete structure, so their CPU, memory, and transfer costs are O(n) in the total structure size, not merely the item being accessed. Applications must bound structure growth accordingly.

A read operation observes one coherent object version (a snapshot), but a sequence of calls is not a transaction. Mutations use compare-and-swap. A concurrent writer can therefore produce Error::Conflict; this crate does not retry automatically because retry policy, backoff, and idempotency belong to the caller.

§Bounded conflict retries

A retry must re-run the complete operation so it reads a fresh snapshot. Keep attempts bounded and inspect the final conflict:

use objsds::{Error, Map, Version};
use objsds_store::ObjectStore;
use serde::{Serialize, de::DeserializeOwned};

fn insert_with_limit<S, V>(
    map: &Map<S, V>,
    key: &str,
    value: V,
    max_attempts: usize,
) -> Result<Version, Error<S::Error>>
where
    S: ObjectStore,
    V: Clone + Serialize + DeserializeOwned,
{
    assert!(max_attempts > 0);
    let mut last_conflict = None;
    for _ in 0..max_attempts {
        match map.insert(key, value.clone()) {
            Ok(version) => return Ok(version),
            Err(Error::Conflict(conflict)) => last_conflict = Some(conflict),
            Err(error) => return Err(error),
        }
        // Apply bounded backoff or jitter here if appropriate.
    }
    Err(Error::Conflict(
        last_conflict.expect("at least one attempt was made"),
    ))
}

observed: Some(version) means another object version was present when the failed condition was inspected; None means the object was absent then. Either observation can already be stale, so use it for diagnostics rather than as a new expected version.

Re-exports§

pub use objsds_store_s3 as s3;

Structs§

AlreadyExistsError
Creation found an object already present at the requested location.
ConflictError
A conditional replacement did not observe the expected object version.
Log
A single-object append-only JSON log.
LogBuilder
Builder for one append-only JSON Log.
LogId
Opaque, sortable identifier for a log record.
Map
A single-object UTF-8/JSON map.
MapBuilder
Builder for one UTF-8/JSON Map.
Objsds
Client sharing one object store and namespace.
ObjsdsBuilder
Builder for Objsds.
Record
One immutable Log record.
StoreError
The object store could not complete an operation.
Version
An opaque object version supplied by a store.

Enums§

BuildError
Invalid client or structure configuration.
CompatibilityError
Persisted metadata is incompatible with the requested structure.
DocumentError
A document could not be encoded or decoded.
Error
An objsds operation error.
InsertIfAbsent
Result of Map::insert_if_absent.