Crate mbx_cache_core

Expand description

Protocol and storage primitives for mbx build caches.

This crate contains the types shared by cache clients, the task-scoped cache agent, and remote cache implementations. Protocol records are serialized with canonical_json before hashing; changing their shape is therefore a wire-format change, not merely an implementation detail.

Most consumers start with CacheDigest and the local stores LocalCas and LocalActionCache. Remote clients use RemoteCacheClient, while mbx’s compiler shim communicates with a CacheAgent using AgentRequest and AgentResponse.

use mbx_cache_core::{CacheDigest, canonical_json};
use serde::Serialize;

#[derive(Serialize)]
struct Key<'a> {
    compiler: &'a str,
    source: CacheDigest,
}

let source = CacheDigest::blake3(b"fn main() {}\n");
let bytes = canonical_json(&Key { compiler: "rustc", source })?;
let action = CacheDigest::blake3(&bytes);
assert_eq!(action.algorithm, "blake3");

Re-exports§

pub use action_slot::ActionSlot;

Modules§

action_slot: Coordination for replacing and removing action records.

Structs§

ActionDiagnostic: A privacy-preserving decomposition of an action key.
ActionPrediction: Adapter-owned data needed to reconstruct an action from a prior task run.
ActionPromiseCompletion: Immutable completion of an invocation-wide compilation promise.
ActionPromiseJoin: Request to join or claim one invocation-wide compilation promise.
AgentRemoteCache: Remote action-cache access owned by one task session.
AgentStats: Aggregate cache activity for one task session.
BlobPackReceipt: What a server did with the blobs in an uploaded pack.
BlobUpload: A digest paired with the data to upload under that digest.
BlockingAgentClient: A synchronous client over an already-connected local agent stream.
CacheAgent: Shared state for an agent hosted by the process that owns a build session.
CacheDigest: Algorithm-tagged digest and exact byte length of a cache object.
CacheDirectory: A canonical directory object stored in the CAS.
CacheDirectoryNode: A child directory entry in a canonical cache directory.
CacheFileNode: A file entry in a canonical cache directory.
CacheSymlinkNode: A symbolic-link entry in a canonical cache directory.
Capabilities: Cache service capabilities negotiated before optional protocol features.
CapabilityFeatures: Optional server protocol features.
CapabilityLimits: Server-advertised request and object limits.
CapabilityProtocol: Version advertised by a cache service.
CcMetadata: C and C++ action metadata stored alongside compiled objects.
CompilerStats: Count and cumulative wall time for one compiler-invocation outcome.
FileIdentity: The on-disk identity a recorded file digest describes.
FileObjectIdentity: The kernel identity of one file object on one mounted filesystem.
FileSnapshot: A pre-operation snapshot that can prove whether a file’s contents changed.
InstanceRoleCredentials: A source of credentials for the EC2 instance role attached to this machine.
LocalActionCache: A local index from action digests to their referenced cache objects.
LocalCas: A validated, content-addressed store on the local filesystem.
NoFileDigestCache: A FileDigestCache that remembers nothing and finds nothing.
PathAliases: Directories whose aliases a caller has already resolved.
PathMapping: Mapping from a host-specific absolute root to a stable key placeholder.
PinnedFile: A file as a probe found it: absent, or present with a length and modification time. Length alone would miss a rewrite that kept the size.
PinnedState: What a present pinned file looked like: enough to notice it being written, replaced, or made executable, without reading it.
RecordedFileDigest: A file digest recorded against the identity it was read under.
RemoteActionManifest: Task action-manifest bytes returned with their concurrency token.
RemoteActionResult: A canonical action-result record referencing objects in the CAS.
RemoteBlobPack: A verified set of remote CAS objects downloaded through blob-pack streams.
RemoteCacheClient: A client for a remote mbx cache.
RemoteCacheConfig: Connection, authentication, and retry settings for RemoteCacheClient.
RestoreStats: Local output restoration work performed by one action-cache adapter hit.
RustcMetadata: Rust-specific action metadata stored alongside compiled outputs.
S3Credentials: Long-lived or session credentials for an S3-compatible service.
S3RemoteCacheConfig: Connection, addressing, and credential settings for an S3 remote cache.
TaskActionManifest: Predictions associated with one stable task identity.
TemporaryCredentials: Temporary credentials and the instant they stop working.
ValidatedFileDigest: A file digest tied to the file object and pathname observed while reading.
WrapperSpan: A trace interval inside one wrapper process.
WrapperTiming: One wrapper invocation, independent of its cache hit/miss accounting.

Enums§

ActionPromiseState: State returned when a client joins an invocation-wide promise.
ActionStoreOutcome: The result of publishing an action with first-writer semantics.
AgentEvent: One accounted cache decision, as it happens.
AgentRequest: A request accepted by the task-scoped cache agent.
AgentResponse: A response returned by the task-scoped cache agent.
BlobSource: Backing data for a blob upload.
DigestAlgorithm: Hash algorithms supported by protocol version one.
FileDigestResolution: The outcome of resolving one file under a digest scope.
FileDigestScope: What a recorded file digest may stand in for.
ManifestPutOutcome: Result of a conditional task-manifest write.
PathNormalizationError: Why a path could not be represented with the configured mappings.
RemoteCacheMode: Operations permitted against a configured remote cache.
S3ConditionalWrites: Whether conditional writes are required, refused, or tried and given up on.

Constants§

ACTION_CONFLICT_MESSAGE: Why LocalActionCache::store refuses to replace an intact result.
ACTION_PROMISE_MEDIA_TYPE: Media type for ephemeral, invocation-keyed compilation promises.
ACTION_RESULT_BATCH_MEDIA_TYPE: Media type for a JSON batch of ActionResult records.
ACTION_RESULT_MEDIA_TYPE: Media type for canonical ActionResult JSON records.
AGENT_PROTOCOL_VERSION: Wire protocol version used between an in-process cache agent and its shims.
BLOB_MEDIA_TYPE: Media type for opaque content-addressed blobs.
BLOB_PACK_BLOBS_HEADER: Header declaring the number of blobs in a blob pack.
BLOB_PACK_BYTES_HEADER: Header declaring the total payload bytes in a blob pack.
BLOB_PACK_HEADER_BYTES: Bytes before each blob pack payload: algorithm, hash, and length.
BLOB_PACK_MAGIC: Magic prefix identifying a version-one blob pack.
BLOB_PACK_MEDIA_TYPE: Media type for framed batches of content-addressed blobs.
BLOB_PACK_RECEIPT_MEDIA_TYPE: Media type for the receipt describing an accepted blob-pack upload.
CLIENT_METADATA_MEDIA_TYPE: Media type for adapter-specific action metadata blobs.
DIGEST_LIST_MEDIA_TYPE: Media type for a JSON list of digests.
DIRECTORY_MEDIA_TYPE: Media type for canonical Directory JSON records.
MAX_ACTION_PREDICTION_PAYLOAD: Maximum serialized adapter payload in one action prediction.
MAX_ACTION_PROMISE_CLAIM_BYTES: Maximum opaque lease-token length accepted for an action promise.
NAMESPACE_HEADER: Header carrying the caller’s isolated cache namespace.
PROTOCOL_HEADER: Header carrying the negotiated cache protocol version.
PROTOCOL_VERSION: Major version of the HTTP cache protocol.
TASK_ACTION_MANIFEST_MEDIA_TYPE: Media type for task-to-action prediction manifests.

Traits§

AgentEventObserver: A sink for AgentEvents observed during one session.
FileDigestCache: Recorded digests a session may consult instead of rehashing a file.

Functions§

canonical_json: Serialize a protocol object using the JSON Canonicalization Scheme.
digest_file: Read and hash a file once, applying the checks required by scope in that same pass.
digest_file_validated: Read and hash a regular file only when the open handle remains stable and the pathname still names that same file after the read.
is_task_identity: Whether task is a well-formed task action identity.
merge_task_action_predictions: Append ordered task prediction updates and keep the manifest bounded.
normalize_mapped_path: Map an absolute path to its cache-key placeholder form.
normalize_resolved_mapped_path: Normalize a path against mapping roots already resolved by resolve_path_mappings.
normalize_resolved_mapped_path_with: normalize_resolved_mapped_path, resolving directory aliases through aliases rather than from scratch.
resolve_path_mappings: Resolve filesystem aliases in mapping roots once for repeated lookups.
task_manifest_actions: The action digests a task’s prediction manifest recorded.

Crate mbx_cache_core

Crate mbx_cache_core Copy item path

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate mbx_cache_core