---
prev: false
next: false
---

# 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](/guide/sdk/) 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](https://specifications.freedesktop.org/basedir-spec/latest/):
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.

### Read-Only Blob Staging

Use `cache.provider().stage_blob(&digest, parent).await` to prepare a blob for
read-only, seekable access without loading the whole payload into memory.
The parent directory must already exist and is owned by the caller. The
returned `StagedBlob` owns its temporary storage; `into_reader()` transfers
that ownership to a `StagedBlobReader` implementing synchronous `Read` and
`Seek`. Neither type exposes a mutable file handle or storage path. Dropping
the lease or its reader removes temporary storage.

Raw immutable blobs can be pinned without copying on compatible filesystems.
All staged blobs are verified before a reader is returned, including pinned raw
files. Compressed blobs and filesystems without hardlink support use bounded
decoding. Corrupt local content is removed; a remote provider refetches it once
before returning a staging failure.
A successful lease remains readable if the cache subsequently removes the
original blob. Ordinary `get_blob_to_file` and `copy_blob_to_file` destinations
remain independent, mutable copies.

`stage_blob_guarded(&digest, parent, guard)` additionally retains a
`Send + 'static` owner through remote ingestion and local blocking decoding.
If staging is cancelled, active workers keep their owner until they finish;
a local decoder also retains and then removes its private temporary directory.
The completed lease does not retain the guard. A cancelled operation can drop
the guard on a blocking worker thread after the calling future has been dropped.
The existing cache selection, remote retrieval and publication defaults are
unchanged. These APIs do not execute actions or create runtime sessions.

### Owned Blob Producers

The lower-level provider also offers `put_produced(guard, producer)` for
synchronous serializers. The owned producer runs on a blocking worker and
writes sequential bytes through `std::io::Write`, avoiding an intermediate
serialized file. Both arguments must be `Send + 'static`. Use `()` as the
guard when no additional lifetime reservation is needed.

```rust
let digest = cache.provider().put_produced((), |writer| {
    writer.write_all(b"generated content")
}).await?;
```

The guard stays with the worker through encoding and durable local publication.
Dropping the future removes its scratch paths immediately; subsequent writes
fail, but a producer already doing other blocking work keeps its guard until
that work ends. Producers must bound their own buffers. No blob is published
unless the producer and final encoding succeed. Remote mirroring follows the
same size-bounded policy as `put_stream`; existing cache defaults are unchanged.

Integrations that already own capacity for two workers can opt into
`put_produced_pipelined(guard, producer)`. Its guard must cover both workers.
Digest calculation overlaps encoding through a one-chunk queue with chunks
capped at 512 KiB. The producer joins the digest worker on success, errors and
cancellation before releasing the guard. When extra capacity is unavailable,
use the serial `put_produced` method instead of waiting while holding a partial
reservation. Blob bytes, digest validation and durable publication are unchanged.

### 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. Inputs are hashed as they are added, without
retaining a separate copy of their contents. Builder memory stays
bounded independently of input size, and cloning a builder copies only its
hash state. The versioned encoding and resulting action keys are unchanged.

### 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. |
| `StagedBlob` | Owns temporary storage for read-only blob access. |
| `StagedBlobReader` | Reads and seeks within a staged blob while retaining its storage lease. |
| `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.

`Error::Cache` wraps a cache failure that can classify itself. Call
`is_not_found()` to tell confirmed absence apart from `is_unavailable()`, a
remote service that could not answer, and `is_corrupt()`, content that failed
its integrity check. `kind()` returns the full classification, which also
distinguishes refused credentials, malformed remote answers, configuration
problems, transfers larger than their budget, and local filesystem failures.
Only confirmed absence means the content is not cached; see
[Misses, Failures, And Integrity](/guide/sdk/#misses-failures-and-integrity).

### Matching On Cache Errors

The classification methods are the compatible way to react to a cache
failure. The cache error type gained a variant for classified remote
failures in this release, and that error type is not marked as
non-exhaustive, so code that matches every variant of it without a wildcard
arm stops compiling and needs a new arm. Failures that earlier releases
reported as a generic remote error, or as a miss, now arrive in that new
variant. Match on `kind()` or the `is_*` methods instead of on variants, and
always keep a wildcard arm when matching on the classification itself,
because new kinds can be added without a breaking release. Display text for
remote failures is unchanged.

```rust
match cache.get_action_result(action).await {
    Ok(Some(result)) => replay(result),
    Ok(None) => run_and_store().await?,
    Err(once::Error::Cache(error)) if error.is_unavailable() => run_without_cache().await?,
    Err(error) => return Err(error.into()),
}
```