Bsdkrun.Cache (bsdkrun_ex v0.5.0)

Cached guest directories.

Entries are keyed, so a rebuild can pick up where the last one left off:

case Bsdkrun.Cache.restore("web", key: key, restore_keys: ["deps-"]) do
  {:ok, %{restored: false}} ->
    Bsdkrun.Sandbox.exec("web", ["npm", "ci"])
    Bsdkrun.Cache.save("web", "/app/node_modules", key: key)

  {:ok, _hit} ->
    :ok
end

Where entries live — host disk or S3 — is host configuration, not an SDK concern: set BSDKRUN_CACHE_BACKEND / BSDKRUN_CACHE_S3_*, or write ~/.config/bsdkrun/cache.toml.

Summary

Types

entry()

A stored cache entry, as cache ls reports it.

result()

What a restore did. A miss is not an error — check :restored.

Functions

list()

Every stored cache entry, newest first.

remove(keys \\ [], opts \\ [])

Remove entries by key, or every one of them with all: true.

restore(id, opts)

Restore a stored tree.

save(id, path, opts)

Archive the guest directory at path under :key.

Types

entry()

@type entry() :: %{
  key: String.t(),
  path: String.t(),
  compression: String.t(),
  size: non_neg_integer(),
  created: non_neg_integer(),
  digest: String.t()
}

A stored cache entry, as cache ls reports it.

result()

@type result() :: %{
  restored: boolean(),
  requested_key: String.t(),
  key: String.t() | nil,
  path: String.t() | nil,
  size: non_neg_integer() | nil,
  compression: String.t() | nil,
  created: non_neg_integer() | nil
}

What a restore did. A miss is not an error — check :restored.

Functions

list()

@spec list() :: {:ok, [entry()]} | {:error, Bsdkrun.Error.t()}

Every stored cache entry, newest first.

remove(keys \\ [], opts \\ [])

@spec remove(
  [String.t()],
  keyword()
) :: :ok | {:error, Bsdkrun.Error.t()}

Remove entries by key, or every one of them with all: true.

restore(id, opts)

@spec restore(
  String.t(),
  keyword()
) :: {:ok, result()} | {:error, Bsdkrun.Error.t()}

Restore a stored tree.

Options: :key (required), :path (defaults to where it was saved from), :restore_keys — prefixes tried in order when the key misses.

save(id, path, opts)

@spec save(String.t(), String.t(), keyword()) ::
  {:ok, entry()} | {:error, Bsdkrun.Error.t()}

Archive the guest directory at path under :key.

Options: :key (required), :compression ("gzip" by default, or "zstd", "estargz", "none"), :force to replace an existing entry.