144 lines
8.9 KiB
Rust
144 lines
8.9 KiB
Rust
// file: crates/ksp-store-postgres-lib/src/lib.rs
|
|
// version: 23
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! Official PostgreSQL backend implementation for KSP Store.
|
|
//!
|
|
//! The backend owns the physical `tokio-postgres` connection, bounded Deadpool
|
|
//! pool, explicit Rustls TLS policy, private KSP migration/bootstrap engine and
|
|
//! safe lightweight health/readiness probe. `0.3.3-pre.003-fix.001` splits
|
|
//! migrations into versioned physical resources and verifies the effective
|
|
//! PostgreSQL schema contract before readiness. `0.3.3-pre.004` adds exact
|
|
//! backend-private RAW transaction/observation/retention read mapping.
|
|
//! `0.3.3-pre.005` adds atomic canonical/observation writes, real idempotence
|
|
//! checks and safe conflict classification without exposing PostgreSQL rows or
|
|
//! SQL through the public bridge. `0.3.3-pre.006` adds deterministic keyset
|
|
//! pagination with a fixed opaque cursor bound to network, range and direction.
|
|
//! `0.3.3-pre.007` adds atomic `Full -> Archived -> Purged` retention transitions
|
|
//! with compare-and-transition outcomes and explicit rejection of `Compacted`.
|
|
//! `0.3.3-pre.008` implements all six `RawTransaction*` capabilities directly on
|
|
//! `PostgresBackend` while preserving the existing narrow backend bridge.
|
|
//! `0.3.4-pre.002` registers additive V002 and its two minimal RAW account
|
|
//! tables with canonical state/observation PKs and the observation-state FK.
|
|
//! `0.3.4-pre.003` completes V002 with exact physical bounds, one unfiltered
|
|
//! navigation index, external-schema compatibility and the bounded prerelease
|
|
//! checksum transition from the provisional `pre.002` schema. `0.3.4-pre.004`
|
|
//! adds backend-private RAW account state/observation read mapping and hostile-row
|
|
//! guards. `0.3.4-pre.005` adds atomic account state+observation acquisition writes
|
|
//! with exact idempotence/conflict classification. `0.3.4-pre.006` adds additional
|
|
//! account observations guarded by the existing state reference. `0.3.4-pre.007` adds
|
|
//! deterministic account keyset pagination with the fixed `KSPA` cursor. `0.3.4-pre.008`
|
|
//! implements the four `RawAccount*` capabilities directly on `PostgresBackend`, completing
|
|
//! the backend RAW capability inventory at ten without exposing physical PostgreSQL types.
|
|
//! `0.3.8-pre.004` adds payload-free random-access RawTransaction inspection;
|
|
//! `0.3.8-pre.005` adds the corresponding data-free RawAccountState inspection
|
|
//! with exact counts while preserving both keyset traversal families unchanged.
|
|
//!
|
|
//! This crate depends on `ksp-store-api` and never on `ksp-store-lib`. The
|
|
//! common facade consumes only this crate's narrow backend bridge and never
|
|
//! exposes PostgreSQL pool, client, row or statement types.
|
|
|
|
mod constants;
|
|
mod error;
|
|
mod health;
|
|
mod migration;
|
|
mod raw_account;
|
|
mod raw_transaction;
|
|
mod runtime;
|
|
mod schema;
|
|
|
|
/// Stable KSP error code for unsupported PostgreSQL retention compaction.
|
|
pub use self::error::ERROR_CODE_POSTGRES_RETENTION_COMPACTION_UNSUPPORTED;
|
|
/// Safe backend-local error returned to the common Store facade.
|
|
pub use self::error::PostgresBackendError;
|
|
/// Safe backend-local error classification used by the common Store facade.
|
|
pub use self::error::PostgresBackendErrorKind;
|
|
/// Opaque physical PostgreSQL backend owning its connection pool.
|
|
pub use self::runtime::PostgresBackend;
|
|
/// Safe PostgreSQL readiness projection returned through the backend bridge.
|
|
pub use self::runtime::PostgresBackendHealthSnapshot;
|
|
/// Safe PostgreSQL pool counter projection returned through the backend bridge.
|
|
pub use self::runtime::PostgresBackendRuntimeSnapshot;
|
|
/// Physical PostgreSQL settings bridge consumed only by the backend crate.
|
|
pub use self::runtime::PostgresBackendSettings;
|
|
/// TLS mode accepted by the physical PostgreSQL settings bridge.
|
|
pub use self::runtime::PostgresBackendTlsMode;
|
|
|
|
/// Crate-owned tracing target for PostgreSQL backend behavior.
|
|
pub(crate) use self::constants::TRACING_TARGET;
|
|
/// Private bounded health probe consumed by the physical backend runtime.
|
|
pub(crate) use self::health::probe_health;
|
|
/// Private migration/bootstrap runner consumed by the physical backend runtime.
|
|
pub(crate) use self::migration::bootstrap;
|
|
/// Current embedded migration version consumed by the private health probe.
|
|
pub(crate) use self::migration::current_migration_version;
|
|
/// Private RAW account cursor decoder consumed by the physical RAW account module.
|
|
pub(crate) use self::raw_account::cursor::decode_raw_account_cursor;
|
|
/// Private RAW account cursor encoder consumed by the physical RAW account module.
|
|
pub(crate) use self::raw_account::cursor::encode_raw_account_cursor;
|
|
/// Private physical account page-limit converter consumed by the physical RAW account module.
|
|
pub(crate) use self::raw_account::cursor::raw_account_physical_page_limit;
|
|
/// Private RAW account observation reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::get_raw_account_observation;
|
|
/// Private RAW account state reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::get_raw_account_state;
|
|
/// Private data-free RAW account-state inspection reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::inspect_raw_account_states;
|
|
/// Private RAW account-state list reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::list_raw_account_states;
|
|
/// Private atomic RAW account acquisition writer consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::persist_raw_account_acquisition;
|
|
/// Private additional RAW account observation writer consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_account::record_raw_account_observation;
|
|
/// Private RAW transaction cursor decoder consumed by the physical RAW module.
|
|
pub(crate) use self::raw_transaction::cursor::decode_raw_transaction_cursor;
|
|
/// Private RAW transaction cursor encoder consumed by the physical RAW module.
|
|
pub(crate) use self::raw_transaction::cursor::encode_raw_transaction_cursor;
|
|
/// Private physical page-limit converter consumed by the physical RAW module.
|
|
pub(crate) use self::raw_transaction::cursor::raw_transaction_physical_page_limit;
|
|
/// Private RAW transaction reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::get_raw_transaction;
|
|
/// Private RAW transaction observation reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::get_raw_transaction_observation;
|
|
/// Private RAW transaction retention-state reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::get_raw_transaction_retention_state;
|
|
/// Private RAW transaction tombstone reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::get_raw_transaction_tombstone;
|
|
/// Private payload-free RAW transaction inspection reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::inspect_raw_transactions;
|
|
/// Private RAW transaction list reader consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::list_raw_transactions;
|
|
/// Private atomic RAW transaction acquisition writer consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::persist_raw_transaction_acquisition;
|
|
/// Private additional RAW transaction observation writer consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::record_raw_transaction_observation;
|
|
/// Private RAW transaction retention transition writer consumed by the physical backend runtime.
|
|
pub(crate) use self::raw_transaction::transition_raw_transaction_retention;
|
|
/// Private Deadpool error mapper shared with the health probe.
|
|
pub(crate) use self::runtime::map_pool_error;
|
|
/// Private Deadpool status projector shared with the health probe.
|
|
pub(crate) use self::runtime::runtime_snapshot_from_status;
|
|
/// Private physical schema resource descriptor consumed by the migration engine.
|
|
pub(crate) use self::schema::SchemaResource;
|
|
/// Private physical schema resource compatibility state consumed by the migration engine.
|
|
pub(crate) use self::schema::SchemaResourceState;
|
|
/// Private V000 schema resource inventory consumed by the migration engine.
|
|
pub(crate) use self::schema::V000_RESOURCES;
|
|
/// Private V001 schema resource inventory consumed by the migration engine.
|
|
pub(crate) use self::schema::V001_RESOURCES;
|
|
/// Private V002 schema resource inventory consumed by the migration engine.
|
|
pub(crate) use self::schema::V002_RESOURCES;
|
|
/// Private physical schema resource inspector consumed by the migration engine.
|
|
pub(crate) use self::schema::inspect_resource;
|
|
/// Private managed-schema adoption probe consumed by the migration engine.
|
|
pub(crate) use self::schema::managed_schema_objects_exist;
|
|
/// Private V001 external-schema compatibility gate consumed by the migration engine.
|
|
pub(crate) use self::schema::verify_v001_external_compatibility;
|
|
/// Private V002 external-schema compatibility gate consumed by the migration engine.
|
|
pub(crate) use self::schema::verify_v002_external_compatibility;
|
|
|
|
const _: &str = crate::TRACING_TARGET;
|