Skip to content

PostgreSQL backup tool with Point-In-Time-Recovery and restore verification

4.8 KB
Raw Blame

Local Cache Specification

Purpose

Defines the transient key-value behavior that cache consumers can rely on when Databasus runs as one application process.

Requirements

Requirement: Cache state is process-local and volatile

The cache SHALL keep entries inside the running application process. A new process SHALL start with an empty cache and SHALL NOT require a remote cache service.

Scenario: Application restarts

  • WHEN the application process stops and starts again
  • THEN entries created by the previous process are absent

Scenario: Application starts without a cache service

  • WHEN an operator starts Databasus without a remote cache endpoint
  • THEN cache-backed features remain available

Requirement: Namespaced entries expire and can be invalidated

Each cache entry SHALL belong to a caller-selected namespace and SHALL have a positive lifetime. A read before expiration SHALL return the stored value. A read at or after expiration SHALL report a miss and make the expired entry eligible for reclamation. Callers SHALL be able to delete one entry or clear all entries owned by the process.

Scenario: Entry is read before expiration

  • WHEN a caller reads a stored entry before its lifetime ends
  • THEN the cache returns the stored value

Scenario: Entry reaches its expiration time

  • WHEN a caller reads an entry at or after its expiration time
  • THEN the cache reports a miss

Scenario: Namespaces use the same key

  • WHEN two callers store different values under the same key in different namespaces
  • THEN each caller reads the value from its own namespace

Scenario: Entry is invalidated

  • WHEN a caller invalidates a stored entry
  • THEN subsequent reads report a miss

Requirement: Conditional storage operations are atomic

The cache SHALL provide atomic read-and-delete and create-if-absent operations. Expired entries SHALL be treated as absent by both operations.

Scenario: Concurrent callers consume one value

  • WHEN multiple callers concurrently read and delete the same live entry
  • THEN exactly one caller receives the value
  • AND every other caller receives a miss

Scenario: Concurrent callers reserve one key

  • WHEN multiple callers concurrently create the same absent key
  • THEN exactly one caller stores its value
  • AND every other caller is told that a live entry already exists

Scenario: Caller reserves an expired key

  • WHEN a caller conditionally creates a key whose previous entry has expired
  • THEN the new value is stored

Requirement: Cache memory is bounded without evicting live entries

The cache SHALL enforce its configured payload budget. Before rejecting a write, it SHALL reclaim expired entries. It SHALL NOT evict an unexpired entry to admit another value.

Scenario: Expired entries occupy the available budget

  • WHEN a write needs space held by expired entries
  • THEN the cache reclaims those entries and admits the write

Scenario: Live entries occupy the available budget

  • WHEN a write would exceed the budget after expired entries are reclaimed
  • THEN the write fails
  • AND every unexpired entry remains available

Scenario: One value exceeds the budget

  • WHEN a caller tries to store a value larger than the entire cache budget
  • THEN the write fails without changing existing entries

Requirement: Concurrent cache access preserves the contract

Cache operations SHALL remain safe when called concurrently. A failed or canceled operation SHALL NOT leave a partially written value.

Scenario: Reads and writes overlap

  • WHEN callers read, write, invalidate, reserve and consume entries concurrently
  • THEN every completed operation has the same result as one valid serial ordering
  • AND no caller observes a partial value

Requirement: Security-sensitive cache failures stop protected operations

Restore-token issuance and consumption and stream-lock acquisition SHALL fail closed when their required cache operation fails. A cache failure SHALL NOT be interpreted as an absent token or an available stream lock.

Scenario: Restore-token issuance cannot store the token

  • WHEN the cache rejects or fails the write required to issue a restore token
  • THEN token issuance returns an error without returning a usable token

Scenario: Restore-token consumption cannot read and delete the token

  • WHEN the cache cannot atomically read and delete a submitted restore token
  • THEN token consumption returns an error
  • AND the restore operation does not start

Scenario: Stream-lock acquisition cannot reserve the lock

  • WHEN the cache cannot atomically reserve the required stream lock
  • THEN lock acquisition returns an error
  • AND the download or restore stream does not start