Rust Software Development Kit

The Rust library is the once crate. It exposes cache primitives for embedding Once in Rust applications and tools. Script execution belongs to the command line and is not part of this library. See the language-library overview to compare the available bindings.

rust

#[tokio::main]
async fn main() -> once::Result<()> {
    let cache = once::Cache::new();
    let digest = cache.put_blob(b"hello").await?;
    let bytes = cache.get_blob(digest).await?;

    assert_eq!(bytes, b"hello");
    Ok(())
}

Installation#

Add the crate to your Cargo.toml:

toml

[dependencies]
once = { git = "https://github.com/tuist/once" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The crate is released from this repository for source integration. It is not currently published to the crates.io registry.

Cache#

once::Cache is the high-level cache client. It is cheap to clone and can be reused across blob and action-result operations.

Constructors#

Choose a constructor based on who owns provider selection. The workspace constructor uses the same effective configuration as the command line.

Application programming interface	Use
`Cache::new()`	Opens the default local cache using the operating-system convention.
`Cache::local(root)`	Opens an isolated local cache at a caller-owned root.
`Cache::from_workspace(root)`	Resolves the same effective provider as the command line for this workspace.
`Cache::with_provider(cache)`	Wraps an existing `CacheProvider`.

The default follows the X Desktop Group base-directory convention: its cache root is $XDG_CACHE_HOME/once/cas when XDG_CACHE_HOME is set, and $HOME/.cache/once/cas otherwise.

Introspection#

Use these methods when your integration needs to inspect how the cache was configured, for example to display diagnostics or pass the lower-level provider into code that already works with content-addressed storage primitives.

Application programming interface	Use
`provider()`	Returns the underlying `CacheProvider`.
`root()`	Returns the local root directory used by the provider.

Blobs#

Blobs are content-addressed byte payloads. Store bytes once, then refer to them by digest from action results, manifests, or other integration state.

Application programming interface	Use
`put_blob(bytes)`	Stores bytes and returns their content digest.
`put_stream(reader)`	Stores an asynchronous reader with bounded memory use.
`put_file(path)`	Stores a file without loading it completely into memory.
`get_blob(digest)`	Reads bytes for a digest.
`get_blob_to_file(digest, path)`	Writes a blob to a file and returns its byte count.
`has_blob(digest)`	Returns whether a blob exists.

Prefer the file and stream methods for logs, archives, compiler outputs, and other payloads whose size is not tightly bounded.

Action Keys#

ActionKeyBuilder gives cached automation a versioned, unambiguous identity. Start with a namespace owned by the integration, then add labeled values and content digests in deterministic order.

rust

let source = cache.put_file("inputs/source").await?;
let mut key = once::ActionKeyBuilder::new("example.compile");
key.push_bytes("tool", "compiler")
    .push_bytes("configuration", "release")
    .push_digest("source", source);
let action = key.finish();

Changing the namespace, a label, an input value, a digest, or input order produces a different action key.

Action Results#

Action results let embedders associate an action digest with an exit code, stdout digest, stderr digest, and output digests.

rust

use std::collections::BTreeMap;

#[tokio::main]
async fn main() -> once::Result<()> {
    let cache = once::Cache::new();
    let stdout = cache.put_blob(b"compiled").await?;
    let mut key = once::ActionKeyBuilder::new("example.compile");
    key.push_bytes("tool", "example");
    let action = key.finish();
    let result = once::ActionResult {
        exit_code: 0,
        stdout: Some(stdout),
        stderr: None,
        outputs: BTreeMap::new(),
    };

    cache.put_action_result(action, &result).await?;
    let cached = cache.get_action_result(action).await?;

    assert_eq!(cached, Some(result));
    Ok(())
}

The action-result methods store and retrieve metadata for a completed action. They do not run commands. The caller is responsible for executing work, including every relevant input in the action key, and deciding which blob digests belong in the cached result.

Application programming interface	Use
`put_action_result(action, result)`	Stores a cached result for an action digest.
`get_action_result(action)`	Returns a cached result when one exists.
`forget_action(action)`	Removes one cached action result. Referenced blobs are left intact.
`stats()`	Returns local cache statistics.

Types#

These are the public supporting types exposed by the crate root. They are re-exported so embedders can model cache state without importing lower level Once modules.

Type	Use
`Digest`	Identifies blobs and action cache entries.
`ActionResult`	Stores an action exit code, stdout digest, stderr digest, and output digests.
`Stats`	Reports local cache size and entry counts.
`CacheProvider`	Provides lower-level cache access for integrations that already own a provider.
`TuistCacheConfig`	Configures a manually constructed Tuist cache provider.
`ActionKeyBuilder`	Builds a versioned action digest from ordered, labeled inputs.
`Result<T>`	Library result alias.
`Error`	Reports invalid digest strings and cache provider errors.

Use digest_from_hex(hex) when a digest crosses a string boundary, such as structured data, configuration, or another process. It validates lowercase BLAKE3 hexadecimal strings and returns Error::InvalidDigest for invalid input.