109 lines
5.3 KiB
Markdown
109 lines
5.3 KiB
Markdown
<!-- file: crates/ksp-store-lib/README.md -->
|
|
<!-- version: 4 -->
|
|
|
|
# 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 :
|
|
|
|
```text
|
|
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 :
|
|
|
|
```text
|
|
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 à :
|
|
|
|
```text
|
|
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` :
|
|
|
|
```text
|
|
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`](USAGE.md) — guide pratique de construction, lifecycle et capabilities Store ;
|
|
- [`../ksp-store-postgres-lib/README.md`](../ksp-store-postgres-lib/README.md) — responsabilité du backend PostgreSQL physique ;
|
|
- [`../../config/std.store.json`](../../config/std.store.json) — targets Store committed ;
|
|
- [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — architecture durable Store ;
|
|
- [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — plan de fondation ;
|
|
- [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../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`](../../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`](../../docs/validation/020-V0_3_3_STORE_POSTGRES_RAW_TRANSACTION.md) — validation `RawTransaction`.
|