89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
<!-- file: kb-store/USAGE.md -->
|
||
<!-- version: 2 -->
|
||
|
||
# Utilisation de kb-store
|
||
|
||
## Connexion PostgreSQL
|
||
|
||
```rust
|
||
let options = match kb_store::PostgresStoreOptions::new(
|
||
database_url,
|
||
"public".to_string(),
|
||
10,
|
||
std::time::Duration::from_secs(10),
|
||
) {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
let store = match kb_store::PostgresStore::connect(options).await {
|
||
Ok(value) => value,
|
||
Err(error) => return Err(error),
|
||
};
|
||
if let Err(error) = store.initialize_store_schema().await {
|
||
return Err(error);
|
||
}
|
||
```
|
||
|
||
`PostgresStoreOptions::new` valide le DSN, le schéma, le nombre de connexions et le timeout. Utiliser `masked_dsn` ou `mask_postgres_dsn` dans les logs ; ne jamais journaliser le DSN brut.
|
||
|
||
## Diagnostics
|
||
|
||
```rust
|
||
let health = store.health_snapshot().await;
|
||
let migrations = store.migration_snapshot().await;
|
||
let backend = store.backend_diagnostics().await;
|
||
```
|
||
|
||
Les diagnostics de tables raw, Core et decode/materialization sont également disponibles par les méthodes `*_table_diagnostics`.
|
||
|
||
## Contrats de repositories
|
||
|
||
Les traits publics principaux sont :
|
||
|
||
- `StoreHealthStore` ;
|
||
- `RawTransactionStore` ;
|
||
- `CoreTransactionStore` ;
|
||
- `CoreExtractionStore` ;
|
||
- `DecodePipelineStore` ;
|
||
- `ProgramObservationStore` ;
|
||
- `DecodedEventStore` ;
|
||
- `MaterializedEventStore` ;
|
||
- `ProcessingLedgerStore`.
|
||
|
||
Ils permettent au pipeline de dépendre d’un contrat async plutôt que d’une requête SQL directe.
|
||
|
||
## Replay et requêtes bornées
|
||
|
||
```rust
|
||
let candidates = store.replay_transaction_candidates(filter).await;
|
||
let programs = store.replay_program_summaries(program_filter).await;
|
||
let entities = store.replay_entity_summaries(entity_filter).await;
|
||
```
|
||
|
||
Les filtres refusent les limites nulles ou supérieures aux bornes publiques. `PageRequest` impose également `DEFAULT_PAGE_SIZE` et `MAX_PAGE_SIZE`.
|
||
|
||
## Transactions atomiques
|
||
|
||
Les bundles `CoreExtractionBundle`, `DecodePersistenceBundle` et `MaterializationPersistenceBundle` regroupent les écritures qui doivent réussir ou être annulées ensemble. Les consommateurs ne doivent pas reproduire manuellement ces transactions avec des écritures isolées.
|
||
|
||
## Schéma et tables
|
||
|
||
Les constantes `RAW_STORE_TABLE_NAMES`, `CORE_STORE_TABLE_NAMES` et `DECODE_STORE_TABLE_NAMES` exposent les noms canoniques. Les fonctions `validate_*_table_names` et `is_valid_solana_table_name` servent aux audits et outils d’administration.
|
||
|
||
## Erreurs et invariants
|
||
|
||
Toutes les APIs utilisent `kb_core::Result`. Les DTO valident notamment les signatures, chemins, Program IDs, clés, montants, états de traitement et identités de ledger. Les erreurs de contrat peuvent être construites avec `storage_contract_error`.
|
||
|
||
## Tests instructifs
|
||
|
||
- les tests `*_rejects_*` documentent les invariants des DTO et filtres ;
|
||
- `decoded_events_and_ledger_roll_back_together` vérifie l’atomicité ;
|
||
- `optional_postgres_*_from_env` couvre les parcours réels lorsque l’environnement PostgreSQL est configuré ;
|
||
- les tests de schéma vérifient les noms, index, contraintes et migrations.
|
||
|
||
## Limites
|
||
|
||
- backend actif : PostgreSQL ;
|
||
- les tests réels sont optionnels sans DSN de test ;
|
||
- la crate ne prend aucune décision de décodage ou de matérialisation.
|