Codex.Files.Registry (Codex SDK v0.3.0)

GenServer-backed manifest that tracks staged file attachments, deduplicates by checksum, and prunes expired entries on a schedule. This powers the public Codex.Files helpers.

Summary

Types

stage_opts()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

ensure_started()

Ensures the registry is running, starting it under the current process when necessary.

force_cleanup()

Triggers an immediate cleanup pass to remove expired attachments.

list()

Lists all staged attachments currently tracked in the manifest.

metrics()

Aggregates counts, sizes, and TTL information for staged attachments.

reset(staging_dir)

Clears the manifest and deletes staged files within the provided staging directory.

stage(opts)

Inserts or refreshes a staged attachment using the supplied options, returning the canonical Attachment struct stored in ETS.

Types

stage_opts()

@type stage_opts() :: %{
  checksum: String.t(),
  name: String.t(),
  persist: boolean(),
  ttl_ms: :infinity | pos_integer(),
  size: non_neg_integer(),
  source_path: Path.t(),
  destination_path: Path.t()
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

ensure_started()

@spec ensure_started() :: {:ok, pid()} | {:error, term()}

Ensures the registry is running, starting it under the current process when necessary.

force_cleanup()

@spec force_cleanup() :: :ok

Triggers an immediate cleanup pass to remove expired attachments.

list()

@spec list() :: [Codex.Files.Attachment.t()]

Lists all staged attachments currently tracked in the manifest.

metrics()

@spec metrics() :: map()

Aggregates counts, sizes, and TTL information for staged attachments.

reset(staging_dir)

@spec reset(Path.t()) :: :ok

Clears the manifest and deletes staged files within the provided staging directory.

stage(opts)

@spec stage(stage_opts()) :: {:ok, Codex.Files.Attachment.t()} | {:error, term()}

Inserts or refreshes a staged attachment using the supplied options, returning the canonical Attachment struct stored in ETS.