232 lines
13 KiB
Rust
232 lines
13 KiB
Rust
// file: crates/ksp-store-lib/src/lib.rs
|
|
// version: 10
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! Common backend-neutral Store runtime facade for KSP.
|
|
//!
|
|
//! The runtime facade owns backend selection, lifecycle, safe diagnostics and
|
|
//! backend-neutral capability dispatch. `0.3.3-pre.008` completed the six PostgreSQL
|
|
//! `RawTransaction` capabilities. `0.3.4-pre.008` adds the four `RawAccount*` capabilities
|
|
//! on both the physical backend and this common facade, completing the canonical RAW runtime inventory at
|
|
//! ten capabilities without exposing physical types. The `0.3.8` inspection
|
|
//! contracts are reexported here before backend/facade dispatch is opened.
|
|
//!
|
|
//! The default `postgres` feature compiles the official PostgreSQL backend as
|
|
//! an optional implementation dependency. No backend implementation type is
|
|
//! part of this crate's public surface.
|
|
|
|
mod constants;
|
|
mod error;
|
|
mod health;
|
|
mod settings;
|
|
mod store;
|
|
|
|
/// Error code reserved for operations attempted after a Store backend is closed.
|
|
pub use self::error::ERROR_CODE_BACKEND_CLOSED;
|
|
/// Error code used when a known Store backend is selected without its compiled feature.
|
|
pub use self::error::ERROR_CODE_BACKEND_NOT_COMPILED;
|
|
/// Error code used when a compiled Store backend cannot complete opening.
|
|
pub use self::error::ERROR_CODE_BACKEND_OPEN_FAILED;
|
|
/// Error code used when PostgreSQL physical configuration is malformed or unsupported.
|
|
pub use self::error::ERROR_CODE_POSTGRES_CONFIG_INVALID;
|
|
/// Error code used when PostgreSQL physical connection establishment fails.
|
|
pub use self::error::ERROR_CODE_POSTGRES_CONNECT_FAILED;
|
|
/// Error code used when PostgreSQL returns persisted RAW data incompatible with the Store contract.
|
|
pub use self::error::ERROR_CODE_POSTGRES_DATA_INVALID;
|
|
/// Error code used when a lightweight PostgreSQL health/readiness probe fails safely.
|
|
pub use self::error::ERROR_CODE_POSTGRES_HEALTH_FAILED;
|
|
/// Error code used when PostgreSQL migration/bootstrap execution fails safely.
|
|
pub use self::error::ERROR_CODE_POSTGRES_MIGRATION_FAILED;
|
|
/// Error code used when PostgreSQL migration history diverges from the embedded immutable KSP history.
|
|
pub use self::error::ERROR_CODE_POSTGRES_MIGRATION_MISMATCH;
|
|
/// Error code used when a requested RAW page size exceeds PostgreSQL's exact physical LIMIT boundary.
|
|
pub use self::error::ERROR_CODE_POSTGRES_PAGE_LIMIT_UNSUPPORTED;
|
|
/// Error code used when a bounded PostgreSQL pool operation reaches its deadline.
|
|
pub use self::error::ERROR_CODE_POSTGRES_POOL_TIMEOUT;
|
|
/// Error code used when a PostgreSQL RAW read statement fails safely.
|
|
pub use self::error::ERROR_CODE_POSTGRES_READ_FAILED;
|
|
/// Error code used when PostgreSQL cannot represent a requested RAW retention compaction state.
|
|
pub use self::error::ERROR_CODE_POSTGRES_RETENTION_COMPACTION_UNSUPPORTED;
|
|
/// Error code used when PostgreSQL schema history is newer than this Store runtime.
|
|
pub use self::error::ERROR_CODE_POSTGRES_SCHEMA_NEWER;
|
|
/// Error code used when PostgreSQL verified TLS setup or negotiation fails.
|
|
pub use self::error::ERROR_CODE_POSTGRES_TLS_FAILED;
|
|
/// Error code used when a PostgreSQL RAW write statement or transaction fails safely.
|
|
pub use self::error::ERROR_CODE_POSTGRES_WRITE_FAILED;
|
|
/// Error code used when a RAW write requires a canonical reference that is not durable.
|
|
pub use self::error::ERROR_CODE_RAW_REFERENCE_NOT_FOUND;
|
|
/// Error code used when Store settings violate backend-neutral bounds or invariants.
|
|
pub use self::error::ERROR_CODE_SETTINGS_INVALID;
|
|
/// Error code used when explicit Store shutdown exceeds its configured deadline.
|
|
pub use self::error::ERROR_CODE_SHUTDOWN_TIMEOUT;
|
|
/// Error code used when a network-scoped operation targets a network different from the Store binding.
|
|
pub use self::error::ERROR_CODE_WRONG_NETWORK;
|
|
/// Portable Store health/readiness projection containing only safe diagnostics.
|
|
pub use self::health::StoreHealthSnapshot;
|
|
/// Portable Store health state independent from physical backend types.
|
|
pub use self::health::StoreHealthState;
|
|
/// Safe synchronous Store runtime snapshot containing backend-neutral pool counters.
|
|
pub use self::health::StoreRuntimeSnapshot;
|
|
/// Bounded PostgreSQL bootstrap and migration settings owned by the Store facade.
|
|
pub use self::settings::PostgresBootstrapSettings;
|
|
/// Bounded PostgreSQL connection-pool settings owned by the Store facade.
|
|
pub use self::settings::PostgresPoolSettings;
|
|
/// PostgreSQL settings owned by the Store facade without exposing backend implementation types.
|
|
pub use self::settings::PostgresStoreSettings;
|
|
/// TLS policy accepted by the backend-neutral PostgreSQL settings surface.
|
|
pub use self::settings::PostgresTlsMode;
|
|
/// Backend identity understood independently from compiled Cargo features.
|
|
pub use self::settings::StoreBackendKind;
|
|
/// Backend-specific settings selected through the common Store facade.
|
|
pub use self::settings::StoreBackendSettings;
|
|
/// Complete backend-neutral settings consumed by the common Store runtime facade.
|
|
pub use self::settings::StoreSettings;
|
|
/// Opaque common Store runtime facade with consuming async shutdown.
|
|
pub use self::store::Store;
|
|
/// Error code used when a RAW write collides with divergent content for the same logical identity.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_CONFLICT;
|
|
/// Error code used when a RAW Store model violates one of its backend-agnostic invariants.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_MODEL_INVALID;
|
|
/// Error code used when a KSP-owned RAW persistence payload violates its format or admission contract.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_PAYLOAD_INVALID;
|
|
/// Error code used when acquisition provenance is malformed, unsafe or internally inconsistent.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_PROVENANCE_INVALID;
|
|
/// Error code used when one RAW query or cursor violates backend-agnostic query invariants.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_QUERY_INVALID;
|
|
/// Error code used when a RAW retention transition violates the logical lifecycle contract.
|
|
pub use ksp_store_api::ERROR_CODE_RAW_RETENTION_INVALID;
|
|
/// Common KSP error type used by Store-facing contracts.
|
|
pub use ksp_store_api::Error;
|
|
/// Stable structured code identifying a KSP error category and condition.
|
|
pub use ksp_store_api::ErrorCode;
|
|
/// Structured contextual field attached to a KSP error.
|
|
pub use ksp_store_api::ErrorContext;
|
|
/// Maximum complete RAW account-data length admitted by the Store API.
|
|
pub use ksp_store_api::MAX_RAW_ACCOUNT_DATA_BYTES;
|
|
/// Maximum UTF-8 byte length accepted for one safe logical RAW/provenance code.
|
|
pub use ksp_store_api::MAX_RAW_CODE_BYTES;
|
|
/// Maximum opaque query cursor length admitted by the Store API.
|
|
pub use ksp_store_api::MAX_RAW_PAGE_CURSOR_BYTES;
|
|
/// Maximum KSP-owned canonical RAW payload admitted by the Store API.
|
|
pub use ksp_store_api::MAX_RAW_PAYLOAD_BYTES;
|
|
/// Maximum source-wire payload size recorded as acquisition metadata.
|
|
pub use ksp_store_api::MAX_RAW_SOURCE_PAYLOAD_BYTES;
|
|
/// Maximum supported Unix millisecond timestamp.
|
|
pub use ksp_store_api::MAX_RAW_UNIX_MILLIS;
|
|
/// Canonical Solana account address primitive shared by persistent models.
|
|
pub use ksp_store_api::Pubkey;
|
|
/// Persistable acquisition observation linked to one complete canonical RAW account state.
|
|
pub use ksp_store_api::RawAccountObservation;
|
|
/// Read capability for persisted RAW account-state observations.
|
|
pub use ksp_store_api::RawAccountObservationRead;
|
|
/// Write capability for additional observations of already persisted RAW account states.
|
|
pub use ksp_store_api::RawAccountObservationWrite;
|
|
/// Canonical complete N1 RAW account state independent from acquisition transport.
|
|
pub use ksp_store_api::RawAccountState;
|
|
/// Backend-independent random-access inspection query for RAW account states.
|
|
pub use ksp_store_api::RawAccountStateInspectionQuery;
|
|
/// Read capability for data-free random-access RAW account-state inspection.
|
|
pub use ksp_store_api::RawAccountStateInspectionRead;
|
|
/// Backend-independent list query for complete canonical RAW account states.
|
|
pub use ksp_store_api::RawAccountStateQuery;
|
|
/// Read capability for complete canonical RAW account states.
|
|
pub use ksp_store_api::RawAccountStateRead;
|
|
/// Durable backend-independent identity of one canonical RAW account state.
|
|
pub use ksp_store_api::RawAccountStateReference;
|
|
/// Data-free summary of one canonical RAW account state for operator inspection.
|
|
pub use ksp_store_api::RawAccountStateSummary;
|
|
/// Write capability for complete canonical RAW account-state acquisitions.
|
|
pub use ksp_store_api::RawAccountStateWrite;
|
|
/// Origin category describing why one acquisition was performed.
|
|
pub use ksp_store_api::RawAcquisitionOrigin;
|
|
/// Safe source-independent acquisition provenance attached to one persisted observation.
|
|
pub use ksp_store_api::RawAcquisitionProvenance;
|
|
/// Combined outcome of one atomic canonical RAW entity plus observation acquisition.
|
|
pub use ksp_store_api::RawAcquisitionWriteOutcome;
|
|
/// Fixed-size digest identifying canonical or source bytes without retaining them.
|
|
pub use ksp_store_api::RawContentHash;
|
|
/// Outcome for one canonical RAW entity in an idempotent persistence operation.
|
|
pub use ksp_store_api::RawEntityWriteOutcome;
|
|
/// Bounded identifier of one KSP-owned source-independent RAW persistence format.
|
|
pub use ksp_store_api::RawFormatId;
|
|
/// One bounded random-access inspection page with exact logical counts.
|
|
pub use ksp_store_api::RawInspectionPage;
|
|
/// Random-access page request dedicated to bounded interactive RAW inspection.
|
|
pub use ksp_store_api::RawInspectionPageRequest;
|
|
/// Bounded logical network/cluster identifier used in backend-independent Store identities.
|
|
pub use ksp_store_api::RawNetworkId;
|
|
/// Stable deterministic idempotence key for one persisted acquisition observation.
|
|
pub use ksp_store_api::RawObservationKey;
|
|
/// Outcome for one deterministic acquisition observation write.
|
|
pub use ksp_store_api::RawObservationWriteOutcome;
|
|
/// One deterministic page of backend-independent Store results.
|
|
pub use ksp_store_api::RawPage;
|
|
/// Opaque backend-owned cursor returned by one deterministic Store query.
|
|
pub use ksp_store_api::RawPageCursor;
|
|
/// Caller-requested page size without an arbitrary KSP policy ceiling.
|
|
pub use ksp_store_api::RawPageLimit;
|
|
/// Opaque-cursor page request used by backend-independent list operations.
|
|
pub use ksp_store_api::RawPageRequest;
|
|
/// Bounded source-independent KSP RAW persistence payload.
|
|
pub use ksp_store_api::RawPayload;
|
|
/// Bounded logical code used by acquisition provenance fields.
|
|
pub use ksp_store_api::RawProvenanceCode;
|
|
/// Logical availability state of one canonical RAW payload.
|
|
pub use ksp_store_api::RawRetentionState;
|
|
/// Outcome of one atomic RAW retention transition.
|
|
pub use ksp_store_api::RawRetentionWriteOutcome;
|
|
/// Optional inclusive Solana slot bounds for one Store query.
|
|
pub use ksp_store_api::RawSlotRange;
|
|
/// Deterministic traversal direction for Store list queries.
|
|
pub use ksp_store_api::RawSortDirection;
|
|
/// Bounded UTC timestamp represented as whole milliseconds since Unix epoch.
|
|
pub use ksp_store_api::RawTimestamp;
|
|
/// Canonical source-independent N1 RAW transaction persisted by Store backends.
|
|
pub use ksp_store_api::RawTransaction;
|
|
/// Explicit write mode for canonical RAW transaction acquisitions.
|
|
pub use ksp_store_api::RawTransactionAcquisitionMode;
|
|
/// Backend-independent random-access inspection query for RAW transactions.
|
|
pub use ksp_store_api::RawTransactionInspectionQuery;
|
|
/// Read capability for payload-free random-access RAW transaction inspection.
|
|
pub use ksp_store_api::RawTransactionInspectionRead;
|
|
/// Persistable acquisition observation linked to one canonical RAW transaction.
|
|
pub use ksp_store_api::RawTransactionObservation;
|
|
/// Read capability for persisted RAW transaction observations.
|
|
pub use ksp_store_api::RawTransactionObservationRead;
|
|
/// Write capability for additional observations of already persisted RAW transactions.
|
|
pub use ksp_store_api::RawTransactionObservationWrite;
|
|
/// Backend-independent list query for canonical RAW transactions.
|
|
pub use ksp_store_api::RawTransactionQuery;
|
|
/// Read capability for canonical RAW transactions.
|
|
pub use ksp_store_api::RawTransactionRead;
|
|
/// Durable backend-independent identity of one canonical RAW transaction.
|
|
pub use ksp_store_api::RawTransactionReference;
|
|
/// Read capability for canonical RAW transaction retention metadata.
|
|
pub use ksp_store_api::RawTransactionRetentionRead;
|
|
/// Requested compare-and-transition operation for one RAW transaction retention state.
|
|
pub use ksp_store_api::RawTransactionRetentionTransition;
|
|
/// Write capability for policy-authorized RAW transaction retention transitions.
|
|
pub use ksp_store_api::RawTransactionRetentionWrite;
|
|
/// Canonical 64-byte Solana transaction signature used by Store identities.
|
|
pub use ksp_store_api::RawTransactionSignature;
|
|
/// Payload-free summary of one canonical RAW transaction for operator inspection.
|
|
pub use ksp_store_api::RawTransactionSummary;
|
|
/// Minimal durable identity retained after a canonical RAW transaction payload is purged.
|
|
pub use ksp_store_api::RawTransactionTombstone;
|
|
/// Write capability for canonical RAW transaction acquisitions.
|
|
pub use ksp_store_api::RawTransactionWrite;
|
|
/// Common KSP result alias using [`Error`].
|
|
pub use ksp_store_api::Result;
|
|
/// Boxed async operation returned by object-safe Store capability contracts.
|
|
pub use ksp_store_api::StoreApiFuture;
|
|
|
|
/// Crate-owned tracing target reserved for Store runtime behavior.
|
|
pub(crate) use self::constants::TRACING_TARGET;
|
|
|
|
// Keep the mandatory crate-owned tracing target part of the compiled scaffold
|
|
// without inventing runtime logging before the first behavioral log site.
|
|
const _: &str = crate::TRACING_TARGET;
|