Struct PgStorageBackend 

pub struct PgStorageBackend<C>
where
    C: PgCacheConn,
{ /* private fields */ }

L2 durable cache tier: content-addressed key → value over Postgres, shared across pods, survives a roll.

Generic over the PgCacheConn seam so it is fully testable against a mock.

Implementations

impl<C> PgStorageBackend<C>

where C: PgCacheConn,

pub fn new(conn: C) -> PgStorageBackend<C>

Wrap a PgCacheConn.

pub fn conn(&self) -> &C

Borrow the underlying connection (for composition / diagnostics).

Trait Implementations

impl<C> NarRefIndex for PgStorageBackend<C>

where C: PgCacheConn + 'static,

The reverse index as one zero-value row per edge in sui_cache_nar_ref.

The key is the canonical NarRefKey, so the referrer lookup is a primary-key range scan under NarRefScan rather than a table sweep.

fn record<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, nar_path: &'life1 str, hash: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, PgStorageBackend<C>: 'async_trait,

Record “hash’s narinfo advertises nar_path”. Idempotent.

fn forget<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, nar_path: &'life1 str, hash: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, PgStorageBackend<C>: 'async_trait,

Forget that edge. Idempotent — forgetting an absent edge is Ok(()).

fn referrers<'life0, 'life1, 'async_trait>( &'life0 self, nar_path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Every store-path hash whose narinfo advertises nar_path, sorted and deduplicated.

impl<C> StorageBackend for PgStorageBackend<C>

where C: PgCacheConn + 'static,

fn delete_nar_record<'life0, 'life1, 'async_trait>( &'life0 self, nar_path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Remove a NAR by key, clearing both generations.

A key may exist as a legacy whole-value row (written before the streaming path) or as chunk rows, and a NAR that was re-pushed across the change can be both. Dropping only one leaves the other still readable, so a “deleted” NAR would keep serving.

fn nar_residency(&self) -> NarResidency

O(chunk). A NAR crosses the wire as NAR_CHUNK_BYTES rows in both directions; no statement ever binds or returns the whole value.

fn get_nar_stream<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Pin<Box<dyn Stream<Item = Result<Bytes, StoreError>> + Send>>>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Read a NAR back as bounded chunks, from either storage generation.

Chunked rows are checked first (via the marker); a key with no marker falls back to windowing a legacy whole-value row with substr. Both arms are O(chunk) — the fallback exists so the NARs already in the production database are servable without materializing them, not as a buffered escape hatch.

fn put_nar_stream<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 str, src: &'life2 dyn NarSource, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, PgStorageBackend<C>: 'async_trait,

Write a NAR as bounded chunk rows, publishing with a marker written last.

Order is the invariant, not a convention:

1. drop any prior chunks and the legacy whole row — a stale marker or a stale legacy row would otherwise shadow the new value;
2. write chunks 0..n, each a bounded bind;
3. write the marker.

A failure anywhere in (1)–(2) leaves no marker, so the key reads as a clean miss. There is no window in which a reader can observe a truncated NAR.

fn wipe_all<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, PgStorageBackend<C>: 'async_trait,

Complete L2 wipe: truncate the narinfo, legacy NAR, NAR-chunk and reverse-edge tables. Unlike the per-hash delete, this reclaims NAR rows wholesale. Returns the narinfo row count.

fn get_narinfo<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Retrieve narinfo text by store path hash.

fn put_narinfo_record<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, hash: &'life1 str, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, PgStorageBackend<C>: 'async_trait,

Store narinfo text keyed by store path hash — the record verb: one key, no index maintenance.

fn delete_narinfo_record<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Remove a narinfo record by store path hash. Idempotent; removing an absent narinfo is Ok(()).

fn nar_ref_index(&self) -> &dyn NarRefIndex

This backend’s narhash → store-hash reverse index.

fn get_nar<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, PgStorageBackend<C>: 'async_trait,

Retrieve a NAR blob by its relative path.

fn put_nar<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 str, data: &'life2 [u8], ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, PgStorageBackend<C>: 'async_trait,

Store a NAR blob at the given relative path.

fn list_narinfos<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<Vec<String>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, PgStorageBackend<C>: 'async_trait,

List all stored narinfo hashes.

fn put_narinfo<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, hash: &'life1 str, content: &'life2 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, Self: 'async_trait,

Store narinfo text and record the reverse edge it creates.

fn advertised_nar<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<String>, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

The NAR path this store path’s narinfo advertises — resolved, never guessed.

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, hash: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<(), StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, Self: 'async_trait,

Delete a store path’s narinfo, and its NAR only if nothing else advertises that NAR.

fn reindex_nar_refs<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<usize, StoreError>> + Send + 'async_trait>>

where 'life0: 'async_trait, Self: 'async_trait,

Rebuild every reverse edge from the narinfos this backend holds, and return the number of edges recorded.