127 lines
3.7 KiB
Markdown
127 lines
3.7 KiB
Markdown
<!-- file: kb-store/README.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# `kb-store`
|
||
|
||
`kb-store` regroupe les contrats de persistance neutres et l’adaptateur PostgreSQL de production de Khadhroony Bot3.
|
||
|
||
La crate remplace l’ancienne séparation physique entre contrats et PostgreSQL, sans mélanger leurs responsabilités. Tous les modules restent privés et l’API stable est réexportée depuis `src/lib.rs`.
|
||
|
||
## Architecture
|
||
|
||
```text
|
||
src/
|
||
├── lib.rs
|
||
├── constants.rs
|
||
├── contracts.rs
|
||
├── contracts/
|
||
│ ├── dto.rs
|
||
│ ├── dto/
|
||
│ ├── entity.rs
|
||
│ ├── entity/
|
||
│ ├── error.rs
|
||
│ ├── health.rs
|
||
│ ├── pagination.rs
|
||
│ └── repository.rs
|
||
├── postgres.rs
|
||
└── postgres/
|
||
├── migrations.rs
|
||
├── query.rs
|
||
├── query/
|
||
├── replay_candidates.rs
|
||
├── repository.rs
|
||
├── repository/
|
||
├── store.rs
|
||
└── test_serial.rs
|
||
```
|
||
|
||
`contracts` ne dépend d’aucun backend. `postgres` implémente ces contrats avec `sqlx`. `lib.rs` ne contient aucune logique métier.
|
||
|
||
## Direction des dépendances
|
||
|
||
```text
|
||
kb-core
|
||
↑
|
||
kb-lib ← kb-store
|
||
```
|
||
|
||
`MdCoreInstructionReplayInput` et sa version de contrat appartiennent à `kb-lib`, car ils sont partagés avec les décodeurs. `kb-store` les consomme et les réexporte. `kb-lib` ne dépend jamais de `kb-store`.
|
||
|
||
`kb-store` ne dépend pas de `kb-config`. L’application résout sa configuration, puis construit explicitement `PostgresStoreOptions`. Cette séparation évite de coupler la persistance à la forme évolutive des profils.
|
||
|
||
## Contrats publics
|
||
|
||
Les familles principales sont :
|
||
|
||
- transactions raw et observations d’acquisition ;
|
||
- graphe core Solana : transaction, comptes, instructions, inner instructions, logs et balances ;
|
||
- sélection et lifecycle de replay ;
|
||
- extraction core atomique ;
|
||
- décodage, couverture et matérialisation atomiques ;
|
||
- ledger de traitement versionné ;
|
||
- santé, migrations et pagination bornée.
|
||
|
||
Les traits publics sont :
|
||
|
||
- `StoreHealthStore` ;
|
||
- `RawTransactionStore` ;
|
||
- `CoreTransactionStore` ;
|
||
- `CoreExtractionStore` ;
|
||
- `DecodePipelineStore` ;
|
||
- `ProgramObservationStore` ;
|
||
- `DecodedEventStore` ;
|
||
- `MaterializedEventStore` ;
|
||
- `ProcessingLedgerStore`.
|
||
|
||
## PostgreSQL
|
||
|
||
`PostgresStore` fournit :
|
||
|
||
- connexion depuis `PostgresStoreOptions` validées ;
|
||
- création depuis un `sqlx::PgPool` existant ;
|
||
- initialisation idempotente des tables raw, core, decode, materialization et ledger ;
|
||
- diagnostics de backend, migrations et tables ;
|
||
- sélections bornées de candidats de replay ;
|
||
- implémentations des traits store-neutral.
|
||
|
||
Les transactions raw sont immuables. Les écritures core, decode et materialization conservent leur lineage et utilisent le ledger pour le skip version/hash, le force replay et l’idempotence.
|
||
|
||
Exemple :
|
||
|
||
```rust
|
||
let options = match kb_store::PostgresStoreOptions::new(
|
||
database_url,
|
||
8,
|
||
5_000,
|
||
true,
|
||
) {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
let store = match kb_store::PostgresStore::connect(options).await {
|
||
std::result::Result::Ok(value) => value,
|
||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||
};
|
||
return std::result::Result::Ok(store);
|
||
```
|
||
|
||
## Validation
|
||
|
||
```bash
|
||
cargo fmt --all
|
||
cargo check -p kb-store
|
||
cargo test -p kb-store
|
||
cargo clippy -p kb-store --all-targets
|
||
KB_POSTGRES_TEST_URL='postgres://solana:solana@localhost:5432/solana_test' \
|
||
cargo test -p kb-store -- --nocapture
|
||
```
|
||
|
||
La validation complète du jalon ajoute :
|
||
|
||
```bash
|
||
cargo check --workspace
|
||
cargo test --workspace
|
||
cargo clippy --workspace --all-targets
|
||
```
|
||
|