109 lines
3.1 KiB
Markdown
109 lines
3.1 KiB
Markdown
<!-- file: kb-core/USAGE.md -->
|
||
<!-- version: 1 -->
|
||
|
||
# Utilisation de kb-core
|
||
|
||
## Objectif
|
||
|
||
La crate expose les contrats minimaux communs utilisés par les autres crates du workspace.
|
||
|
||
## Résultat partagé
|
||
|
||
```rust
|
||
fn validate_name(name: &str) -> kb_core::Result<()> {
|
||
if name.trim().is_empty() {
|
||
return std::result::Result::Err(kb_core::Error::new(
|
||
"name_empty",
|
||
"name must not be empty",
|
||
));
|
||
}
|
||
|
||
return std::result::Result::Ok(());
|
||
}
|
||
```
|
||
|
||
## Erreur personnalisée stable
|
||
|
||
```rust
|
||
let error = kb_core::Error::new(
|
||
"profile_missing",
|
||
"the requested profile does not exist",
|
||
);
|
||
|
||
assert_eq!(error.code(), "profile_missing");
|
||
assert_eq!(
|
||
error.message(),
|
||
"the requested profile does not exist"
|
||
);
|
||
```
|
||
|
||
`Error::new` doit recevoir un code stable destiné aux logs, aux tests et aux adaptateurs UI.
|
||
|
||
## Familles d’erreur
|
||
|
||
```rust
|
||
let config_error = kb_core::Error::config("missing active profile");
|
||
let io_error = kb_core::Error::io("cannot read configuration file");
|
||
let db_error = kb_core::Error::db("database connection refused");
|
||
|
||
assert_eq!(config_error.code(), "config");
|
||
assert_eq!(io_error.code(), "io");
|
||
assert_eq!(db_error.code(), "db");
|
||
```
|
||
|
||
Les constructeurs publics disponibles couvrent notamment la configuration, les I/O, JSON, tracing, Tauri, HTTP, WebSocket, base de données, état invalide, absence de connexion et fonctionnalité non implémentée.
|
||
|
||
## Conversion depuis une erreur I/O
|
||
|
||
```rust
|
||
let read_result = std::fs::read_to_string("missing.file");
|
||
|
||
let core_result: kb_core::Result<std::string::String> =
|
||
match read_result {
|
||
std::result::Result::Ok(value) => {
|
||
std::result::Result::Ok(value)
|
||
},
|
||
std::result::Result::Err(error) => {
|
||
std::result::Result::Err(kb_core::Error::from(error))
|
||
},
|
||
};
|
||
```
|
||
|
||
## Identité d’un module
|
||
|
||
```rust
|
||
let name = kb_core::ModuleName(
|
||
"spl_token_decoder".to_string(),
|
||
);
|
||
let version = kb_core::ModuleVersion(
|
||
"0.4.6".to_string(),
|
||
);
|
||
let kind = kb_core::ModuleKind::Decoder;
|
||
|
||
assert_eq!(name.0, "spl_token_decoder");
|
||
assert_eq!(version.0, "0.4.6");
|
||
assert_eq!(kind, kb_core::ModuleKind::Decoder);
|
||
```
|
||
|
||
`ModuleKind` distingue actuellement les ingestors, extractors, observers, decoders, materializers, aggregators et validators.
|
||
|
||
## Erreurs et invariants
|
||
|
||
- le code d’une erreur doit rester stable ;
|
||
- le message peut être détaillé pour l’opérateur, mais ne doit pas contenir de secret ;
|
||
- `ModuleName` et `ModuleVersion` sont des identités, pas des mécanismes de résolution dynamique ;
|
||
- une nouvelle variante publique doit rester compatible avec les consommateurs du workspace.
|
||
|
||
## Tests de référence
|
||
|
||
- `custom_error_preserves_code_and_message` ;
|
||
- `family_error_formats_with_family_prefix`.
|
||
|
||
Ces tests illustrent le contrat stable entre code, message et représentation textuelle.
|
||
|
||
## Limites durables
|
||
|
||
- `kb-core` ne remplace pas les types métier spécialisés ;
|
||
- elle ne fournit pas de journalisation ni de sérialisation automatique des erreurs ;
|
||
- elle ne contient pas de logique de transport, stockage ou protocole.
|