Sidereon.GNSS.ExactCache (Sidereon v1.0.0)

Atomic exact-product cache transactions.

The cache binds the complete distributor-independent product identity, the resolved distribution source, and digests and lengths for validated product, distributor archive, and provenance bytes. Native publication uses a bounded cross-process lock and one atomic reader-visible commit marker.

Transport and product-format validation remain caller responsibilities. A cache hit returns authenticated bytes; callers must still parse the product and interpret the authenticated provenance before use.

Summary

Types

entry()

single_flight_error()

single_flight_open()

single_flight_option()

Functions

abandon(owner)

Abandons a single-flight acquisition without publishing.

cleanup_abandoned(cache)

Removes unreferenced transaction artifacts while the writer lock is held.

committed_files(cache)

Reads a complete digest-verified entry through a lock-owning handle.

committed_files(path, identity, source)

Reads a complete digest-verified entry without taking the writer lock.

control_directory()

Returns the shared cache protocol's control-directory name.

heartbeat(owner)

Requests an immediate liveness heartbeat from a single-flight owner.

open_single_flight(path, identity, source, opts \\ [])

Opens an exact cache with bounded single-flight acquisition.

publish(cache, content, archive, provenance)

Publishes validated bytes as one immutable transaction.

with_lock(path, identity, source, timeout_ms \\ 30000, operation)

Runs an operation while holding the bounded cross-process writer lock.

Types

entry()

@type entry() :: %{
  product: String.t(),
  archive: String.t(),
  provenance: String.t(),
  entry_id: String.t(),
  product_bytes: binary(),
  archive_bytes: binary(),
  provenance_bytes: binary()
}

single_flight_error()

@type single_flight_error() ::
  :single_flight_timeout
  | :single_flight_ownership_lost
  | {:invalid_option, atom()}
  | {:cache_read_failed, term()}
  | {:cache_write_failed, term()}

single_flight_open()

@type single_flight_open() ::
  {:hit, entry()} | {:owner, Sidereon.GNSS.ExactCache.Owner.t()}

single_flight_option()

@type single_flight_option() ::
  {:poll_interval_ms, pos_integer()}
  | {:heartbeat_interval_ms, pos_integer()}
  | {:liveness_timeout_ms, pos_integer()}
  | {:wait_timeout_ms, pos_integer()}

Functions

abandon(owner)

@spec abandon(Sidereon.GNSS.ExactCache.Owner.t()) :: :ok | {:error, term()}

Abandons a single-flight acquisition without publishing.

cleanup_abandoned(cache)

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

Removes unreferenced transaction artifacts while the writer lock is held.

committed_files(cache)

@spec committed_files(term()) :: {:ok, entry()} | :miss | {:error, term()}

Reads a complete digest-verified entry through a lock-owning handle.

committed_files(path, identity, source)

@spec committed_files(
  String.t(),
  Sidereon.GNSS.Distribution.ProductIdentity.t(),
  atom()
) ::
  {:ok, entry()} | :miss | {:error, term()}

Reads a complete digest-verified entry without taking the writer lock.

control_directory()

@spec control_directory() :: String.t()

Returns the shared cache protocol's control-directory name.

heartbeat(owner)

@spec heartbeat(Sidereon.GNSS.ExactCache.Owner.t()) ::
  :ok | {:error, single_flight_error()}

Requests an immediate liveness heartbeat from a single-flight owner.

open_single_flight(path, identity, source, opts \\ [])

@spec open_single_flight(
  String.t(),
  Sidereon.GNSS.Distribution.ProductIdentity.t(),
  atom(),
  [
    single_flight_option()
  ]
) :: single_flight_open() | {:error, single_flight_error()}

Opens an exact cache with bounded single-flight acquisition.

A {:hit, entry} result contains a complete digest-verified transaction and the caller must not fetch. A {:owner, owner} result grants this caller the exclusive right to fetch, validate, and publish through publish/4.

Timing options are positive integer milliseconds. Defaults are 50 ms for :poll_interval_ms, 5 seconds for :heartbeat_interval_ms, 30 seconds for :liveness_timeout_ms, and 30 minutes for :wait_timeout_ms. The heartbeat interval must be shorter than the liveness timeout.

publish(cache, content, archive, provenance)

@spec publish(
  term() | Sidereon.GNSS.ExactCache.Owner.t(),
  binary(),
  binary(),
  binary()
) ::
  {:ok, entry()} | {:error, term()}

Publishes validated bytes as one immutable transaction.

with_lock(path, identity, source, timeout_ms \\ 30000, operation)

@spec with_lock(
  String.t(),
  Sidereon.GNSS.Distribution.ProductIdentity.t(),
  atom(),
  non_neg_integer(),
  (term() -> result)
) :: result
when result: term()

Runs an operation while holding the bounded cross-process writer lock.