ksp-store-lib

ksp-store-lib est la façade runtime Store commune de KSP.

Elle expose aux consumers une surface backend-neutral, réexporte les contrats RAW de ksp-store-api, sélectionne uniquement les backends compilés et masque leurs objets physiques. Le backend PostgreSQL officiel est activé par défaut via la feature postgres et reste implémenté dans ksp-store-postgres-lib.

Responsabilités

ksp-store-lib possède :

StoreSettings, avec un réseau logique unique, un backend sélectionné et un timeout de fermeture borné ;
les settings PostgreSQL publics KSP-owned : pool, TLS, bootstrap/migrations et URI sensible ;
la feature postgres par défaut et le comportement explicite backend_not_compiled lorsque PostgreSQL est sélectionné sans cette feature ;
Store::open, qui ne retourne une instance qu'après validation, ouverture physique du backend compilé et bootstrap/history réussis ;
Store::runtime_snapshot() pour les compteurs runtime sûrs sans I/O ;
Store::health().await pour la readiness portable et bornée ;
Store::close(self).await pour la fermeture explicite bornée ;
le mapping des erreurs backend vers des codes Store stables sans exposer les erreurs physiques ;
les six capabilities RawTransaction* dispatchées vers le backend compilé ;
une validation réseau backend-neutral avant dispatch pour toutes les opérations qui portent explicitement un réseau ;
les réexports crate-root de ksp-store-api nécessaires aux consumers ordinaires.

Une instance = un réseau

Une instance Store représente exactement :

1 Store = 1 RawNetworkId + 1 backend physique sélectionné

Le runtime Store n'est pas un multiplexeur multi-database ou multi-réseau. La sélection d'un target nommé appartient à Config. Le document std.store peut donc définir plusieurs targets indépendants, mais un appel à Store::open reçoit les settings d'un seul target.

Cette séparation permet d'utiliser des bases PostgreSQL distinctes par réseau tout en conservant le réseau dans l'identité logique des données RAW.

PostgreSQL

Avec la feature par défaut :

ksp-store-lib
    -> ksp-store-api
    -> ksp-logging-lib
    -> ksp-store-postgres-lib

ksp-store-lib ne réexporte aucun type tokio-postgres, Deadpool ou Rustls.

Les modes TLS publics sont volontairement limités à :

Disabled
VerifyFull

VerifyFull impose TLS avec vérification de la chaîne et de l'identité serveur. La policy typée Store prime sur les paramètres TLS présents dans l'URI.

Config et secrets

Store ne lit ni .env, ni variables KSP_* / KSPB_*, ni variables/fichiers implicites libpq (PG*, .pgpass, fichiers TLS PostgreSQL).

ksp-config-lib possède std.store, la résolution des secrets et la sélection du target. Il construit ensuite un StoreSettings backend-neutral. L'URI PostgreSQL reste nécessaire au runtime mais n'a aucun getter public dans ksp-store-lib et son Debug est redacted.

Surface RawTransaction

Store implémente les six capabilities transactionnelles acquises dans ksp-store-api :

RawTransactionRead
RawTransactionWrite
RawTransactionObservationRead
RawTransactionObservationWrite
RawTransactionRetentionRead
RawTransactionRetentionWrite

Le consumer manipule uniquement les modèles et outcomes backend-neutral. Les erreurs physiques PostgreSQL sont projetées vers des codes Store stables sans exposer le backend.

La façade fournit ainsi :

lecture d'une transaction canonique, de ses observations et de sa rétention ;
écriture atomique transaction + observation ;
ajout idempotent d'observations ;
pagination keyset déterministe par cursor opaque ;
application de transitions de rétention demandées par le caller ;
validation réseau avant dispatch lorsqu'un input porte explicitement son réseau.

Hors périmètre

Sont volontairement hors de cette surface :

persistence/query/rétention PostgreSQL de RawAccountState ;
batch-size, priorité, backlog ou policy de worker/job ;
transport d'acquisition, Program decoding et materialization ;
exposition publique de SQL, pool, client, row, statement ou transaction PostgreSQL.

Documentation

USAGE.md — guide pratique de construction, lifecycle et capabilities Store ;
../ksp-store-postgres-lib/README.md — responsabilité du backend PostgreSQL physique ;
../../config/std.store.json — targets Store committed ;
../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md — architecture durable Store ;
../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md — plan de fondation ;
../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md — validation de fondation ;
../../docs/plans/024-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION_PLAN.md — plan RawTransaction ;
../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md — validation RawTransaction.

5.3 KiB Raw Blame History