140 lines
5.8 KiB
Markdown
140 lines
5.8 KiB
Markdown
<!-- file: crates/ksp-store-postgres-lib/README.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# ksp-store-postgres-lib
|
|
|
|
`ksp-store-postgres-lib` est le backend PostgreSQL physique officiel du Store KSP.
|
|
|
|
La crate implémente la fondation connexion/pool/TLS/migrations/health derrière `ksp-store-lib`. Elle dépend directement de `ksp-store-api` mais ne dépend jamais de la façade `ksp-store-lib`.
|
|
|
|
## Responsabilités
|
|
|
|
La crate possède seule pour PostgreSQL :
|
|
|
|
- le parsing et la normalisation de la configuration physique `tokio-postgres` ;
|
|
- le pool borné `deadpool-postgres` ;
|
|
- la policy TLS physique avec Rustls ;
|
|
- les roots système et le provider cryptographique AWS-LC ;
|
|
- le bootstrap/moteur de migrations privé KSP ;
|
|
- la table metadata `ksp_store_schema_migrations` ;
|
|
- la migration logique V000 relocalisée sous `migrations/v000_bootstrap/` et son checksum SHA-256 historique ;
|
|
- l'advisory transaction lock borné des migrations ;
|
|
- les snapshots runtime/health sûrs destinés au bridge de façade ;
|
|
- la fermeture explicite du pool et son fallback `Drop` best-effort ;
|
|
- la classification d'erreurs backend sans conserver le texte d'erreur PostgreSQL.
|
|
|
|
## Frontière d'utilisation
|
|
|
|
Les applications, jobs et workers KSP ne dépendent normalement pas de cette crate :
|
|
|
|
```text
|
|
consumer -> ksp-store-lib -> [feature postgres] ksp-store-postgres-lib
|
|
```
|
|
|
|
La surface publique de cette crate existe pour le bridge inter-crates et les tests d'intégration backend. Elle ne constitue pas une seconde façade Store.
|
|
|
|
`ksp-store-postgres-lib` ne réexporte pas `tokio-postgres`, Deadpool ou Rustls.
|
|
|
|
## Connexion et pool
|
|
|
|
`PostgresBackend::open` :
|
|
|
|
1. valide et normalise l'URI fournie explicitement ;
|
|
2. impose la policy TLS typée ;
|
|
3. construit un pool borné ;
|
|
4. prouve une connexion physique ;
|
|
5. vérifie/applique le bootstrap selon les settings ;
|
|
6. ne retourne qu'après succès de cette fondation.
|
|
|
|
Le backend ne lit aucun environnement, `.env`, `PG*`, `.pgpass` ou fichier TLS implicite libpq.
|
|
|
|
## TLS
|
|
|
|
Les modes sont exactement :
|
|
|
|
```text
|
|
Disabled
|
|
VerifyFull
|
|
```
|
|
|
|
`VerifyFull` exige :
|
|
|
|
- TLS ;
|
|
- roots système ;
|
|
- certificat valide ;
|
|
- vérification de l'identité serveur ;
|
|
- aucune dégradation automatique en plaintext.
|
|
|
|
Les configurations ne permettant pas de vérifier une identité serveur, comme `hostaddr` seul, sont rejetées.
|
|
|
|
## Migrations
|
|
|
|
La fondation historique V000 est embarquée sous :
|
|
|
|
```text
|
|
migrations/v000_bootstrap/tables/001_ksp_store_schema_migrations.sql
|
|
```
|
|
|
|
La vertical slice V001 est ensuite répartie sous `migrations/v001_raw_transaction/{tables,constraints,indexes}/` tout en restant une migration logique unique. V000 crée la metadata privée :
|
|
|
|
```text
|
|
ksp_store_schema_migrations
|
|
```
|
|
|
|
Le moteur vérifie version, nom et checksum SHA-256, sérialise les runners par advisory transaction lock et refuse une history divergente ou plus récente que le runtime.
|
|
|
|
V001 possède désormais le schéma physique `RawTransaction` et son contrat de compatibilité ; les opérations métier restent introduites par tranches afin de préserver des gates courts et vérifiables.
|
|
|
|
## Health et erreurs
|
|
|
|
`PostgresBackendRuntimeSnapshot` et `PostgresBackendHealthSnapshot` ne contiennent que des compteurs et états sûrs destinés à la façade.
|
|
|
|
`PostgresBackendError` ne conserve que :
|
|
|
|
```text
|
|
PostgresBackendErrorKind
|
|
phase statique
|
|
```
|
|
|
|
Le texte d'erreur PostgreSQL, l'URI, SQL et les valeurs bind ne traversent pas cette frontière.
|
|
|
|
## Support PostgreSQL
|
|
|
|
La politique de support de `0.3.2` fixe PostgreSQL 15 comme major minimal. Le test live de fondation refuse explicitement un serveur plus ancien ; le backend ne fixe aucun plafond arbitraire de major PostgreSQL. La compatibilité de migration reste basée sur le schéma KSP.
|
|
|
|
La preuve opérateur réelle et le major effectivement exercé sont conservés dans la matrice de validation, pas dans cette documentation durable.
|
|
|
|
## Lectures RAW `0.3.3-pre.004`
|
|
|
|
Le backend expose désormais quatre lectures étroites qui retournent uniquement des modèles `ksp-store-api` :
|
|
|
|
```text
|
|
get_raw_transaction
|
|
get_raw_transaction_observation
|
|
get_raw_transaction_retention_state
|
|
get_raw_transaction_tombstone
|
|
```
|
|
|
|
Le SQL et les rows restent privés au backend. Le mapping PostgreSQL est fallible et couvre notamment `NUMERIC(20,0) -> u64`, `BIGINT -> u32/u64`, timestamps bornés, bytes de taille fixe et codes de provenance. Une ligne stockée incompatible produit uniquement `PostgresBackendErrorKind::DataInvalid`; un échec de SELECT produit `ReadFailed`. Les lectures portant un `RawTransactionReference` rejettent un réseau différent avant toute acquisition de pool.
|
|
|
|
`Full` lit le payload chaud, `Archived` le reconstruit depuis la relation archive et `Purged` retourne `None`; le tombstone reste accessible séparément pour `Purged`.
|
|
|
|
## Hors périmètre actuel
|
|
|
|
La crate ne contient encore :
|
|
|
|
- aucune écriture PostgreSQL `RawTransaction*` ;
|
|
- aucune pagination/listing `RawTransaction` ;
|
|
- aucune implémentation complète des traits `RawTransaction*` de `ksp-store-api` tant que `list_raw_transactions` manque ;
|
|
- aucune implémentation PostgreSQL des capabilities `RawAccount*` ;
|
|
- aucune orchestration worker/job ;
|
|
- aucun transport d'acquisition ou decoder Program.
|
|
|
|
## Documentation
|
|
|
|
- [`USAGE.md`](USAGE.md) — bridge physique et lifecycle ;
|
|
- [`../ksp-store-lib/README.md`](../ksp-store-lib/README.md) — façade runtime destinée aux consumers ;
|
|
- [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — architecture Store ;
|
|
- [`../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md`](../../docs/plans/023-V0_3_2_STORE_POSTGRES_FOUNDATION_PLAN.md) — décisions pool/TLS/migrations ;
|
|
- [`../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md`](../../docs/validation/019-V0_3_2_STORE_POSTGRES_FOUNDATION.md) — preuves déterministes et PostgreSQL réel.
|