v0.3.2-pre.011

crates/ksp-store-lib/USAGE.md

@@ -0,0 +1,219 @@
+<!-- file: crates/ksp-store-lib/USAGE.md -->
+<!-- version: 1 -->
+
+# Utilisation de ksp-store-lib
+
+## 1. Dépendance et features
+
+Le consumer runtime normal dépend uniquement de la façade :
+
+```toml
+[dependencies]
+ksp-store-lib = { path = "../ksp-store-lib" }
+```
+
+La feature par défaut est :
+
+```text
+postgres
+```
+
+Pour construire un binaire sans backend physique :
+
+```toml
+ksp-store-lib = { path = "../ksp-store-lib", default-features = false }
+```
+
+Dans ce mode, le type PostgreSQL reste connu par la surface de settings mais `Store::open` retourne `ERROR_CODE_BACKEND_NOT_COMPILED` avant toute I/O si PostgreSQL est sélectionné.
+
+Un consumer ordinaire ne dépend pas directement de `ksp-store-postgres-lib`.
+
+## 2. Construire des settings PostgreSQL programmatiquement
+
+La construction directe est utile pour les tests, outils internes ou compositions qui n'utilisent pas `ksp-config-lib`.
+
+```rust
+fn programmatic_store_settings(connection_uri: std::string::String) -> ksp_store_lib::Result<ksp_store_lib::StoreSettings> {
+    let network = ksp_store_lib::RawNetworkId::new("devnet");
+    let network = match network {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+
+    let postgres = ksp_store_lib::PostgresStoreSettings::new(
+        connection_uri,
+        ksp_store_lib::PostgresPoolSettings::default(),
+        ksp_store_lib::PostgresTlsMode::VerifyFull,
+        ksp_store_lib::PostgresBootstrapSettings::default(),
+    );
+
+    let settings = ksp_store_lib::StoreSettings::with_default_shutdown(
+        network,
+        ksp_store_lib::StoreBackendSettings::Postgres(postgres),
+    );
+
+    let validation = settings.validate();
+    if let std::result::Result::Err(error) = validation {
+        return std::result::Result::Err(error);
+    }
+
+    return std::result::Result::Ok(settings);
+}
+```
+
+`PostgresStoreSettings` ne fournit volontairement aucun getter public de l'URI. Son `Debug` remplace cette valeur par `<redacted>`.
+
+## 3. Ouvrir et fermer un Store
+
+`Store::open` est async et ne retourne un succès qu'après que le backend compilé a prouvé sa fondation runtime.
+
+```rust
+async fn use_store(settings: ksp_store_lib::StoreSettings) -> ksp_store_lib::Result<()> {
+    let store = ksp_store_lib::Store::open(settings).await;
+    let store = match store {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+
+    let runtime = store.runtime_snapshot();
+    let _network = runtime.network();
+    let _capacity = runtime.pool_capacity();
+    let _size = runtime.pool_size();
+    let _available = runtime.pool_available();
+    let _waiting = runtime.pool_waiting();
+
+    let health = store.health().await;
+    match health.state() {
+        ksp_store_lib::StoreHealthState::Ready => {}
+        ksp_store_lib::StoreHealthState::NotReady => {
+            let _safe_error_code = health.last_error_code();
+        }
+        _ => {}
+    }
+
+    return store.close().await;
+}
+```
+
+`Store::close(self)` consomme l'instance afin qu'une fermeture explicite ne puisse pas être suivie d'une nouvelle opération via la même valeur.
+
+## 4. Construire les settings depuis Config
+
+Le chemin applicatif recommandé utilise `ksp-config-lib`, propriétaire du document `std.store`, de `.env` et des secrets.
+
+Après construction du `ConfigDocumentEngine` :
+
+```rust
+fn resolve_store_settings(
+    engine: &ksp_config_lib::ConfigDocumentEngine,
+    environment: &ksp_config_lib::ConfigEnvironment,
+    target: std::option::Option<&str>,
+) -> ksp_core_lib::Result<ksp_store_lib::StoreSettings> {
+    let resolved = engine.load_resolved_store_config(target, environment);
+    let resolved = match resolved {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+
+    return std::result::Result::Ok(resolved.into_settings());
+}
+```
+
+Targets committed :
+
+```text
+devnet   -> RawNetworkId("devnet")
+mainnet  -> RawNetworkId("mainnet-beta")
+testnet  -> RawNetworkId("testnet")
+```
+
+Chaque target peut utiliser une URI PostgreSQL distincte. `default_profile` sélectionne un seul target ; `Store` ne route pas automatiquement entre plusieurs targets.
+
+## 5. Settings disponibles
+
+### `PostgresPoolSettings`
+
+Valeurs par défaut :
+
+```text
+max_connections         8
+connect_timeout         10 s
+wait_timeout             5 s
+create_timeout          10 s
+recycle_timeout          5 s
+```
+
+Les getters sont :
+
+```text
+max_connections()
+connect_timeout()
+wait_timeout()
+create_timeout()
+recycle_timeout()
+```
+
+`validate()` vérifie les bornes sans I/O.
+
+### `PostgresBootstrapSettings`
+
+Valeurs par défaut :
+
+```text
+auto_migrate            true
+migration_timeout       30 s
+migration_lock_timeout  10 s
+```
+
+Getters :
+
+```text
+auto_migrate()
+migration_timeout()
+migration_lock_timeout()
+```
+
+### `StoreSettings`
+
+La surface expose :
+
+```text
+backend()
+backend_kind()
+network()
+shutdown_timeout()
+validate()
+```
+
+`StoreSettings::new` permet de choisir explicitement le timeout de shutdown. `StoreSettings::with_default_shutdown` utilise la borne commune par défaut de 5 secondes.
+
+## 6. Health et diagnostics
+
+`StoreRuntimeSnapshot` est synchrone et ne déclenche aucune I/O. Il expose uniquement :
+
+```text
+backend_kind
+network
+pool_capacity
+pool_size
+pool_available
+pool_waiting
+```
+
+`StoreHealthSnapshot` ajoute une probe async bornée :
+
+```text
+state = Ready | NotReady
+migration_version
+pending_migration_count
+last_error_code
+runtime snapshot
+```
+
+Aucun snapshot n'expose URI, host, user, database, SQL, handle backend ou texte d'erreur PostgreSQL.
+
+## 7. Limite fonctionnelle actuelle
+
+`ksp-store-lib` réexporte les modèles et traits RAW de `ksp-store-api`, mais le backend PostgreSQL de la fondation n'implémente encore aucune capability `RawTransaction*` ou `RawAccount*`.
+
+Les consumers ne doivent donc pas interpréter la disponibilité du runtime PostgreSQL comme une persistence métier déjà présente.