Crate loonfs_objectstore 

The LoonFS object-store boundary.

LoonFS assumes only the narrow provider contract the format spec names — create-if-absent, compare-and-swap, read-after-write visibility, prefix listing — and this crate owns that boundary: the ObjectStore trait, provider adapters for S3, Cloudflare R2, Google Cloud Storage, Azure Blob Storage, and the local filesystem, the durable key layout in keys and layout, and the contract probe in probe that proves a configured store honours that contract — the same checks the conformance suite runs against real providers.

Re-exports

pub use object_store::ObjectStoreError as Error;

pub use object_store::ByteRange;

pub use object_store::ByteStream;

pub use object_store::MultipartCompletion;

pub use object_store::MultipartPart;

pub use object_store::ObjectBody;

pub use object_store::ObjectMetadata;

pub use object_store::ObjectStore;

pub use object_store::ObjectStoreError;

pub use object_store::PutMode;

pub use object_store::Result;

pub use object_store::SharedObjectStore;

pub use object_store::StoredObjectChecksum;

pub use probe::run_store_contract_probe;

pub use probe::StoreProbeCheck;

pub use probe::StoreProbeOutcome;

pub use probe::StoreProbeReport;

Modules

abs

Azure Blob Storage provider.

gcs

Google Cloud Storage provider.

keys

Key construction for every durable object family.

layout

The durable key grammar: object families, their path shapes, and parsing keys back into classified families.

local_fs_store

LocalFsStore: the local-filesystem ObjectStore provider.

metrics

A metrics-recording wrapper around any object store: per-operation samples classified by object family.

object_store

The ObjectStore contract every provider implements, plus its shared value and error types.

presign

Presigned-URL issuing for direct transfers: direct_put uploads and direct_get downloads.

probe

On-demand proof that a configured store honours the object-store contract LoonFS depends on.

s3_compatible

S3CompatibleStore: the S3-API store, constructed per provider.

timing

Local monotonic elapsed-time boundary for self-enforced deadlines and budgets.

Structs

ConfiguredObjectStore

One validated runtime provider, plus the transfer issuer it supports.

ProviderObjectStore

Adapts the upstream object_store provider surface to the narrower LoonFS contract.

ProviderObjectStoreConfig

Configures logical key scoping for a generic provider client.

SecretString

A secret string such as an access key, token, or signing secret.

Enums

ConfiguredObjectStoreKind

Identifies the concrete provider backing a ConfiguredObjectStore.

ImmutableWriteError

Failure to establish that an immutable key contains the requested bytes.

StoreConfig

Provider selection plus credentials, as written in config files.

StoreConfigError

Validation failure for a StoreConfig.

Constants

ACCESS_KEY_ID_ENV

Environment variable the S3-compatible providers read their access-key id from when the config file leaves it out.

PROVIDER_ATTEMPT_TIMEOUT

Bound for one control-plane HTTP attempt’s request phase, and the response-body idle bound for every request. An attempt that makes no progress for this long fails and counts against the operation deadline instead of consuming it invisibly.

PROVIDER_CONNECT_TIMEOUT

One HTTP attempt’s connect timeout.

PROVIDER_MULTIPART_PART_BYTES

Fixed size of every multipart part except the last. Cloudflare R2 requires all non-final parts to share one size, and every supported provider requires at least 5 MiB per non-final part; 8 MiB matches the part size mainstream storage clients default to, and keeps every part a cheap retry that fits comfortably inside one flat attempt bound.

PROVIDER_MULTIPART_PART_WINDOW

Concurrent in-flight parts per multipart upload.

PROVIDER_MULTIPART_THRESHOLD_BYTES

Payload size at and above which overwrite puts use the provider’s native multipart upload instead of one whole-object PUT, matching the multipart thresholds mainstream storage clients ship. The format spec allows this for large immutable file data and forbids relying on it for small mutable control objects: create-if-absent and compare-and-swap puts never take this path, because providers complete multipart uploads as unconditional overwrites and those modes exist to carry real provider preconditions.

PROVIDER_OPERATION_DEADLINE

Hard deadline for one logical object-store operation, consumed across every retry of that operation rather than restarting per attempt. Reads get it as the provider client’s retry timeout; verified immutable writes and deletes share it through TransportRetryPolicy. The deadline gates starting another attempt, and one outer attempt may itself contain the inner client’s full retry budget for status-code retries — so one operation’s total wall time is bounded by the deadline plus the inner retry budget plus one attempt bound (worst case roughly six minutes), still a hard bound. The GC grace window is derived above this bound (format spec, “Garbage collection”, rule 1); multipart uploads deliberately carry no whole-operation clock (their parts are individually bounded), which leaves the floor inequality untouched because everything it times — WAL segments inside the publish budget, the root compare-and-swap — is a small control object on the single-request path.

PROVIDER_STREAMED_PART_WINDOW

Buffered parts a streamed write holds at once.

PROVIDER_TRANSFER_ATTEMPT_TIMEOUT

Bound for one payload-bearing HTTP attempt’s request phase. A request body is opaque to progress observation while it uploads, so a flat generous bound stands in for stall detection: parts are at most PROVIDER_MULTIPART_PART_BYTES, and an 8 MiB body that cannot finish inside this bound is moving slower than roughly 70 KiB/s — treated as stalled and retried on a fresh connection.

SECRET_ACCESS_KEY_ENV

Environment variable the S3-compatible providers read their secret access key from when the config file leaves it out.

SESSION_TOKEN_ENV

Environment variable a temporary AWS credential’s session token comes from when the config file leaves it out.