125 lines
4.4 KiB
Markdown
125 lines
4.4 KiB
Markdown
<!-- file: crates/ksp-store-postgres-lib/README.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# 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` ;
|
|
- le sentinel `V000__bootstrap.sql` et son checksum SHA-256 ;
|
|
- 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 embarque uniquement :
|
|
|
|
```text
|
|
migrations/V000__bootstrap.sql
|
|
```
|
|
|
|
Elle 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.
|
|
|
|
Aucune migration métier RAW n'appartient à cette fondation.
|
|
|
|
## 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.
|
|
|
|
## Hors périmètre actuel
|
|
|
|
La crate ne contient encore :
|
|
|
|
- aucune implémentation PostgreSQL des capabilities `RawTransaction*` ;
|
|
- aucune implémentation PostgreSQL des capabilities `RawAccount*` ;
|
|
- aucun repository métier RAW ;
|
|
- aucune table/index métier ;
|
|
- 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.
|