Struct NamespaceEngine 

pub struct NamespaceEngine<S> { /* private fields */ }

A namespace-scoped core API.

NamespaceEngine owns an object store handle plus, for a mutating engine, the writer identity used for mutations. It is the main entrypoint for direct reads, path writes, explicit commits, uploads, checkpoints, and retention work.

An engine built by NamespaceEngineBuilder::build_reader carries no writer identity: it serves reads, and every mutation refuses.

Implementations

impl<S: ObjectStore> NamespaceEngine<S>

pub fn builder(store: S) -> NamespaceEngineBuilder<S>

Starts an engine builder for the supplied object store.

The builder requires a namespace id, and a writer id unless it is finished with NamespaceEngineBuilder::build_reader.

pub fn namespace_id(&self) -> &NamespaceId

Returns the namespace this engine is bound to.

pub fn writer_id(&self) -> Option<&str>

Returns the writer id used for epoch acquisition and commit publication, or None for a read-only engine.

pub async fn bootstrap_namespace( &self, options: BootstrapOptions, ) -> Result<NamespaceSummary, BootstrapNamespaceError>

Creates the namespace if it does not already exist.

Use this before normal reads and writes for a new namespace.

pub async fn fork_namespace( &self, target: &NamespaceId, ) -> Result<NamespaceSummary, Error>

Creates a new namespace at the current head of this namespace.

The fork shares immutable file bytes but gets its own metadata history.

pub async fn delete_namespace( &self, options: DeleteNamespaceOptions, ) -> Result<DeleteNamespaceResponse, Error>

Deletes this namespace: a fenced, terminal head-state transition. Commits acknowledged before the swap stay committed; everything that observes the deleted head afterward fails with namespace_deleted.

pub async fn resolve_path( &self, path: impl AsRef<str>, context: &RuntimeReadContext, ) -> Result<AuthoritativePathEntry, Error>

Stats one path against the pinned runtime read context.

pub async fn list_path_page( &self, path: impl AsRef<str>, request: PageRequest<DirectoryPageCursor>, context: &RuntimeReadContext, ) -> Result<Page<AuthoritativePathEntry, DirectoryPageCursor>, Error>

Lists one directory page against the pinned runtime read context.

pub async fn read_file( &self, path: impl AsRef<str>, context: &RuntimeReadContext, max_content_bytes: Option<u64>, ) -> Result<AuthoritativeFileBytes, Error>

Reads file content against the pinned runtime read context.

pub async fn read_file_stream( &self, path: impl AsRef<str>, context: &RuntimeReadContext, chunk_bytes: NonZeroU64, start_offset: u64, ) -> Result<FileContentStream<S>, Error>

where S: Clone,

Opens a bounded streaming read of a file’s current content against the pinned runtime read context.

The path resolves exactly as it does for Self::read_file; what differs is everything after. The content arrives as chunk_bytes ranged reads with the verifying digest folded over them, so what the read costs in memory is one chunk rather than the file’s size, and the deployment’s buffered-read cap deliberately does not apply — that cap bounds what a caller materializes, and this caller materializes a chunk.

The pinned context resolves the path; it does not have to survive the read. The reference names one immutable object at a random id, so no commit landing mid-read can change the bytes under a reader.

start_offset skips bytes the caller already holds; the stream still verifies the whole object, so those bytes reach it through FileContentStream::fold_resumed_prefix before it fetches anything.

pub async fn direct_download_target( &self, path: impl AsRef<str>, revision_no: Option<RevisionNo>, context: &RuntimeReadContext, ) -> Result<DirectDownloadTarget, Error>

Resolves a path to the content object a direct read would fetch, against the pinned runtime read context.

This reads metadata only. It is the read-side counterpart of Self::begin_direct_put_upload_target: both hand a host the one object key it needs in order to sign a transfer, and neither moves a byte.

pub async fn list_file_revisions_page( &self, path: impl AsRef<str>, request: PageRequest<FileRevisionsPageCursor>, context: &RuntimeReadContext, ) -> Result<Page<FileRevision, FileRevisionsPageCursor>, Error>

Lists one revision page for a path against the pinned runtime read context.

pub async fn list_trash_page( &self, request: PageRequest<TrashPageCursor>, context: &RuntimeReadContext, ) -> Result<Page<TrashEntry, TrashPageCursor>, Error>

Lists one trash page against the pinned runtime read context.

pub async fn list_checkpoint_files_page( &self, checkpoint_id: &CheckpointId, request: PageRequest<CheckpointFilesPageCursor>, context: &RuntimeReadContext, ) -> Result<CheckpointFilesPage, Error>

Reads one page of the files visible in the state checkpoint_id pins, in ascending inode-id order.

The checkpoint’s pinned manifest is the only state enumerated: the context’s own basis and WAL tail are deliberately not read, so a commit landing while a consumer pages through changes nothing it sees. Everything after the pinned sequence is the change feed’s job. The context supplies the namespace’s immutable identity and proves the namespace is still live.

pub async fn resolve_current_files( &self, inode_ids: &[InodeId], context: &RuntimeReadContext, ) -> Result<Vec<CurrentFileState>, Error>

Answers, for each inode id, what it looks like in the namespace’s current state: whether it is visible, its current revision, and its current path.

One pinned read serves the whole batch, so every answer describes the same state, and answers come back in input order. Ids that name nothing are answered as not visible rather than refused — a consumer holding ids from an earlier enumeration routinely holds stale ones. At most MAX_RESOLVE_CURRENT_FILES ids per call; a larger batch is refused before anything is read.

pub async fn read_content_ref( &self, content_ref: &ContentRef, max_bytes: u64, context: &RuntimeReadContext, ) -> Result<Vec<u8>, Error>

Reads one immutable content object by reference.

max_bytes is the caller’s own budget for this read, checked against the reference’s declared size before any fetch; it is independent of any deployment-wide download limit, so a consumer sizes its own buffers. After the fetch the bytes are verified against the reference’s size and digest, and a mismatch fails the read — there is no partial answer and no second attempt against another key.

pub async fn list_file_revisions_for_inode_page( &self, inode_id: InodeId, request: PageRequest<FileRevisionsPageCursor>, context: &RuntimeReadContext, ) -> Result<Page<FileRevision, FileRevisionsPageCursor>, Error>

Lists one revision page for an inode against the pinned runtime read context.

pub async fn read_file_revision( &self, path: impl AsRef<str>, revision_no: RevisionNo, context: &RuntimeReadContext, max_content_bytes: Option<u64>, ) -> Result<AuthoritativeFileBytes, Error>

Reads one revision’s content by path against the pinned runtime read context.

pub async fn read_file_revision_for_inode( &self, inode_id: InodeId, revision_no: RevisionNo, context: &RuntimeReadContext, max_content_bytes: Option<u64>, ) -> Result<Vec<u8>, Error>

Reads one revision’s content against the pinned runtime read context.

pub async fn publish_namespace_commits_batch( &self, candidates: Vec<CommitCandidate>, ) -> Vec<Result<CommitResponse, Error>>

Publishes already-classified mutation candidates as one batch: one WAL segment, one head compare-and-swap, one result per candidate in order.

pub async fn list_changes_after( &self, after_seq: ChangeSeq, limit: EffectiveLimit, ) -> Result<ChangesResponse, Error>

Reads up to limit committed changes after after_seq.

pub async fn begin_upload( &self, request: BeginUploadRequest, ) -> Result<BeginUploadResponse, Error>

Starts a durable upload session with explicit transport options.

pub async fn begin_direct_put_upload_target( &self, claim: DirectPutContentClaim, ) -> Result<BeginDirectPutUploadTargetResponse, Error>

Mints a direct_put upload target: a fresh content identity, the reference that names it, and the internal object key to sign.

pub async fn begin_direct_multipart_upload_target( &self, options: DirectMultipartUploadOptions, ) -> Result<BeginDirectMultipartUploadTargetResponse, Error>

Mints a direct_multipart upload target: a fresh content identity, the provider upload that assembles it, and the part geometry the client cuts its payload to. What the payload turns out to be is claimed at completion.

pub async fn direct_multipart_part_targets( &self, upload_id: &UploadId, requested: &[UploadPartChecksumClaim], ) -> Result<MultipartPartTargets, Error>

Resolves one wave of parts for signing against the session that owns them. Nothing durable is written: parts are the client’s bookkeeping.

pub async fn upload_content( &self, upload_id: &UploadId, bytes: &[u8], ) -> Result<UploadContentResponse, Error>

Uploads whole-file content into an upload session.

pub async fn upload_streamed_content( &self, upload_id: &UploadId, body: ByteStream, ) -> Result<UploadContentResponse, Error>

Uploads content that arrives as a stream into an upload session, hashing it on the way through instead of holding it.

pub async fn complete_upload( &self, upload_id: &UploadId, request: &CompleteUploadRequest, ) -> Result<CompleteUploadResponse, Error>

Completes an upload session when the expected content ref matches.

pub async fn complete_upload_prepared( &self, upload_id: &UploadId, request: &CompleteUploadRequest, ) -> Result<CompletedUpload, Error>

Completes an upload session and returns proof for later publication.

Service-proxied completion performs no content-blob I/O. Direct-put completion performs one content-blob HEAD and no content-blob GET.

pub async fn complete_upload_prepared_with_catalog( &self, catalog: &VerifiedNamespaceCatalogEntry, upload_id: &UploadId, request: &CompleteUploadRequest, ) -> Result<CompletedUpload, Error>

Completes an upload with a namespace catalog binding already resolved by the runtime.

pub async fn stage_owned_bytes( &self, catalog: &VerifiedNamespaceCatalogEntry, bytes: &[u8], ) -> Result<PreparedContent, Error>

Stages bytes this process holds as content a session owns, ready to publish here.

This is the whole upload lifecycle for the caller that is also the uploader: a session opens, the bytes land under the identity it allocated, and the session completes — with no wire step between them and no receipt at the end, because the publication happens in this process and takes the reference directly. What it does not skip is the session record, which is what content garbage collection reads to decide an object’s fate; without one the bytes would be reachable by nothing and reclaimable by nothing.

Two small control writes on top of the content write, in that order.

pub async fn stage_owned_stream( &self, catalog: &VerifiedNamespaceCatalogEntry, body: ByteStream, ) -> Result<PreparedContent, Error>

Stages a streamed payload as content a session owns, hashing it on the way through instead of holding it.

The streaming twin of Self::stage_owned_bytes; ownership and cost are identical.

pub async fn abort_upload( &self, upload_id: &UploadId, ) -> Result<AbortUploadResponse, Error>

Aborts an upload session, then deletes the content object it owned.

Terminal and idempotent: repeating it succeeds, and it refuses a session that already completed, whose content may be published.

pub async fn read_upload_status( &self, upload_id: &UploadId, ) -> Result<(UploadStatusResponse, Option<CompletedUploadReceipt>), Error>

Reads one upload session, minting a fresh receipt when it is completed so a lost commit response never costs a retransfer.

pub async fn create_checkpoint( &self, name: String, ttl_ms: Option<u64>, ) -> Result<CreateCheckpointResponse, Error>

Creates or reuses a named checkpoint pinning the current namespace head for the calling user.

A checkpoint pins a manifest version for retention/provenance. If the current head has no manifest yet, this first publishes one for the current durable namespace state; it is not a request to compact metadata. ttl_ms computes the record’s expiry from the engine’s clock; absent means the pin holds until explicitly released.

pub async fn list_checkpoints(&self) -> Result<ListCheckpointsResponse, Error>

Lists every active checkpoint record on the namespace, oldest first.

A read: nothing here releases, expires, or reaps a record. A record whose expiry has passed but which no collection pass has released is still active and is still listed, with that expiry in the answer.

pub async fn release_checkpoint( &self, checkpoint_id: &CheckpointId, ) -> Result<ReleaseCheckpointResponse, Error>

Releases a user-owned checkpoint by id.

Idempotent: releasing an already-released or reaped record succeeds. The record is reaped by a later garbage-collection pass; its basis becomes collectable only on the pass after that.

pub async fn flush_wal(&self) -> Result<FlushWalResponse, Error>

Flushes the visible WAL tail and advances metadata/root.json to a manifest covering the current head.

This is the latest-state maintenance operation: it absorbs the visible WAL tail into a published manifest and advances the root, creating no checkpoint record. Superseded manifests become garbage-collection candidates once nothing pins them.

pub async fn reorganize_metadata( &self, ) -> Result<MetadataReorganizeReport, Error>

Runs at most one metadata reorganization unit: folds one family group’s L0 delta rows into new base segments and publishes a manifest swapping that group’s references. Checkpoints only append L0 runs, so calling this from maintenance is what keeps read fan-out bounded. Repeat until the report says NotNeeded; every call re-reads durable state, so interrupted reorganizations resume from the live manifest.

pub async fn advance_retention_floor( &self, ) -> Result<AdvanceRetentionResponse, Error>

Advances the retention floor when a verified checkpoint makes it safe.

Trait Implementations

impl<S: Debug> Debug for NamespaceEngine<S>

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

Formats the value using the given formatter.