# `VulnCheck.Cache`
[🔗](https://github.com/Voskan/vulncheck/blob/v1.0.1/lib/vulncheck/cache.ex#L1)

Atomic on-disk cache for advisory feeds and analyzed `.beam` modules, plus
air-gapped bundle export/import.

Layout (default root: `$XDG_CACHE_HOME/vulncheck` or `~/.cache/vulncheck`):

    feeds/osv_hex_all.zip.entry            OSV Hex archive and metadata
    feeds/cves/<CVE-ID>.json.entry         EEF CNA / MITRE records and metadata
    feeds/hex/packages/<name>.json.entry   Hex.pm package metadata
    beam-v4/<sha256>.etf                   cached module summaries

Every write goes to a unique temporary file that is then renamed into
place, so concurrent CI jobs sharing a cache never observe partial files.

# `fetch_status`

```elixir
@type fetch_status() :: :network | :cached | :revalidated | :stale
```

# `atomic_write`

```elixir
@spec atomic_write(Path.t(), iodata()) :: :ok | {:error, term()}
```

Atomically writes `data` to `path` (temporary file + rename).

# `beam_dir`

```elixir
@spec beam_dir(VulnCheck.Config.t()) :: String.t()
```

Directory holding cached `.beam` summaries.

# `dir`

```elixir
@spec dir(VulnCheck.Config.t() | keyword()) :: String.t()
```

Root cache directory for a configuration.

# `export_bundle`

```elixir
@spec export_bundle(VulnCheck.Config.t(), Path.t()) :: {:ok, map()} | {:error, term()}
```

Exports a verified snapshot of cached feeds.

# `feeds_dir`

```elixir
@spec feeds_dir(VulnCheck.Config.t()) :: String.t()
```

Directory holding feed data. Offline runs read the most recent valid
snapshot: the live cache or the snapshot selected by `feeds import`.

# `fetch`

```elixir
@spec fetch(String.t(), String.t(), VulnCheck.Config.t(), keyword()) ::
  {:ok, binary(), fetch_status()} | {:error, term()}
```

Returns the body of a cached resource. For resources that affect scan
results, use `fetch_validated/5` to validate and decode before publication.

# `fetch_validated`

```elixir
@spec fetch_validated(
  String.t(),
  String.t(),
  VulnCheck.Config.t(),
  keyword(),
  function()
) ::
  {:ok, term(), fetch_status(), map()} | {:error, term()}
```

Fetches and decodes a resource, publishing its body and metadata together
only after validation succeeds. Returns the decoded value, refresh
status (`:network | :cached | :revalidated | :stale`) and metadata. Options
include `:http_client`, `:http_opts`, `:offline`, `:ttl`, `:immutable`,
`:force`, `:allow_stale` and `:max_age`.

When `:force` is `true` and the refresh fails with a transient or 5xx error,
`allow_stale: true` (the default) falls back to the last verified copy with
status `:stale` and records `"refresh_error"` in metadata; pass
`allow_stale: false` to fail instead.

# `get_beam`

```elixir
@spec get_beam(VulnCheck.Config.t() | keyword(), String.t()) :: {:ok, term()} | :miss
```

Reads a cached module summary by `.beam` SHA-256. Corrupt entries, oversized
entries, schema mismatches or entries that would require creating atoms are
treated as misses.

# `import_bundle`

```elixir
@spec import_bundle(Path.t(), VulnCheck.Config.t()) :: {:ok, map()} | {:error, term()}
```

Validates a bundle and selects it for later offline scans.

# `list_feed_files`

```elixir
@spec list_feed_files(VulnCheck.Config.t()) :: [String.t()]
```

Lists cached feed resources (relative paths), excluding metadata and temporary files.

# `prune`

```elixir
@spec prune(VulnCheck.Config.t()) :: %{
  snapshots: non_neg_integer(),
  snapshot_bytes: non_neg_integer(),
  module_caches: non_neg_integer(),
  module_cache_bytes: non_neg_integer()
}
```

Removes imported feed snapshots beyond the most recently used ones (the
snapshot selected by `feeds import` is kept) and module caches written by
other cache schema versions.

# `put_beam`

```elixir
@spec put_beam(VulnCheck.Config.t() | keyword(), String.t(), term()) ::
  :ok | {:error, term()}
```

Stores a module summary under its `.beam` SHA-256.

# `read_feed`

```elixir
@spec read_feed(VulnCheck.Config.t(), String.t()) ::
  {:ok, binary()} | {:error, term()}
```

Reads a verified cached feed file without any network access.

# `read_meta`

```elixir
@spec read_meta(Path.t()) :: map()
```

Reads verified metadata stored with a cached file.

# `sha256`

```elixir
@spec sha256(iodata()) :: String.t()
```

SHA-256 hex digest of a binary.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
