v0.1.3-pre.015-fix.001
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: crates/ksp-config-lib/USAGE.md -->
|
||||
<!-- version: 1 -->
|
||||
<!-- version: 2 -->
|
||||
|
||||
# Utilisation de ksp-config-lib
|
||||
|
||||
@@ -182,3 +182,106 @@ Toute nouvelle variable runtime concrète `KSP_*` / `KSPB_*` introduite dans le
|
||||
Une application Tauri doit appeler les APIs ci-dessus via ses commandes/DTO applicatifs. Elle ne lit ni JSON ni `.env` directement et ne résout jamais elle-même les placeholders.
|
||||
|
||||
Les valeurs `Secret` ne doivent pas être incluses par défaut dans les DTO publics. Une action UI explicitement autorisée peut appeler une méthode `reveal_*` et transporter le résultat par un DTO spécifique, sans log ni diagnostic contenant la valeur réelle.
|
||||
|
||||
## 10. Index de la surface publique
|
||||
|
||||
Ce guide reste volontairement indépendant des numéros de release. Les contrats publics sont regroupés ci-dessous par usage ; les constantes de noms/erreurs accompagnent les mêmes familles et ne constituent pas des workflows séparés.
|
||||
|
||||
| Famille publique | Contrats principaux | Exemple |
|
||||
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------|
|
||||
| Bootstrap | `ConfigBootstrapOptions`, `ARG_CFG_PATH`, `ARG_SCHEMA_PATH`, `DEFAULT_CFG_PATH`, `DEFAULT_SCHEMA_PATH` | §1 |
|
||||
| Registre logique | `ConfigFileRegistry`, `ConfigFileId`, `ConfigFileDescriptor`, `ConfigFileKind`, `ARG_FILE_MAP`, constantes `FILE_ID_*` / `DEFAULT_*_FILENAME` | §1–2 |
|
||||
| Documents | `ConfigDocumentEngine`, `ConfigJsonDocument` | §2 |
|
||||
| Profils | `ResolvedConfigProfile`, `ConfigProfileSelectionSource`, `ConfigValueOrigin` | §5 |
|
||||
| Composites | `ResolvedConfigComposite`, `ResolvedCompositeComponent` | §5 |
|
||||
| Environnement | `ConfigEnvironment`, `ConfigEnvironmentSource`, `ConfigEnvironmentValue`, `DEFAULT_DOTENV_PATH`, `DEFAULT_DOTENV_EXAMPLE_PATH` | §3, §7–8 |
|
||||
| Sensibilité/provenance | `ConfigSensitivity`, `ConfigValueProvenance`, `ResolvedConfigText`, `ResolvedConfigJson`, `REDACTED_CONFIG_VALUE` | §3 |
|
||||
| Logging effectif | `ResolvedLoggingConfig` | §4 |
|
||||
| Management | `ConfigManagement`, `ConfigManagedSource`, `ConfigDocumentChangeReport`, `ConfigEnvironmentReport`, `ConfigEnvironmentChangeReport` | §6–7 |
|
||||
| Source Logging typée | `LoggingConfigDocument`, `LoggingProfileConfig`, `LoggingConsoleConfig`, `LoggingFileConfig`, `LoggingOutputFilterConfig`, `LoggingTargetFilterConfig` | §6 et exemple ci-dessous |
|
||||
| Erreurs Config | constantes `ERROR_CODE_*` réexportées par la crate | exemple ci-dessous |
|
||||
|
||||
### 10.1 Modifier une configuration Logging typée
|
||||
|
||||
Les getters permettent d'inspecter la source ; les setters et vues `*_mut()` permettent de construire un candidat avant validation/persistence :
|
||||
|
||||
```rust
|
||||
let mut document = match management.load_logging_document() {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
document.set_logs_directory("${KSP_LOGS_DIRECTORY:-logs}");
|
||||
|
||||
if let std::option::Option::Some(profile) = document.profiles_mut().first_mut() {
|
||||
profile.set_default_filter("debug");
|
||||
profile.console_mut().set_enabled(true);
|
||||
profile.console_mut().filter_mut().set_level("info");
|
||||
profile.console_mut().filter_mut().domains_mut().push("config".to_owned());
|
||||
}
|
||||
|
||||
let saved = match management.save_logging_document(&document) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
if saved.source_changed() && saved.reload_required() {
|
||||
// The application decides when/how to reload the affected runtime consumer.
|
||||
}
|
||||
```
|
||||
|
||||
La construction depuis zéro utilise les constructeurs publics `LoggingConfigDocument::new`, `LoggingProfileConfig::new`, `LoggingConsoleConfig::new`, `LoggingFileConfig::new`, `LoggingOutputFilterConfig::new` et `LoggingTargetFilterConfig::new`. Les mêmes contraintes schema/sémantiques sont appliquées au moment de `save_logging_document()`.
|
||||
|
||||
### 10.2 Inspecter un source enregistré sans contourner Config
|
||||
|
||||
```rust
|
||||
let source = match management.read_source(&file_id) {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
let logical_id = source.file_id();
|
||||
let managed_path = source.path();
|
||||
let raw_content = source.content();
|
||||
```
|
||||
|
||||
Cette API est notamment destinée à une UI de réparation lorsque le document n'est plus validable. Elle n'autorise pas la lecture d'un chemin arbitraire.
|
||||
|
||||
### 10.3 Exploiter les rapports `.env`
|
||||
|
||||
```rust
|
||||
let reports = match management.environment_report() {
|
||||
std::result::Result::Ok(value) => value,
|
||||
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
||||
};
|
||||
|
||||
for report in reports {
|
||||
let name = report.variable_name();
|
||||
let sensitivity = report.sensitivity();
|
||||
let desired = report.desired_safe_value();
|
||||
let effective = report.effective_safe_value();
|
||||
let source = report.effective_source();
|
||||
let shadowed = report.shadowed_by_process_environment();
|
||||
let _ = (name, sensitivity, desired, effective, source, shadowed);
|
||||
}
|
||||
```
|
||||
|
||||
Après une mutation, `ConfigEnvironmentChangeReport` expose `source_changed()`, `effective_changed()`, `shadowed_by_process_environment()` et `reload_required()`.
|
||||
|
||||
### 10.4 Distinguer un code d'erreur Config
|
||||
|
||||
Les codes publics permettent à une UI/service de brancher sa logique sans parser le texte du message :
|
||||
|
||||
```rust
|
||||
let loaded = engine.load_validated_document(&file_id);
|
||||
|
||||
if let std::result::Result::Err(error) = loaded {
|
||||
if error.code() == ksp_config_lib::ERROR_CODE_SCHEMA_VALIDATION_FAILED {
|
||||
// Present a schema-specific diagnostic path to the caller.
|
||||
}
|
||||
return std::result::Result::Err(error);
|
||||
}
|
||||
```
|
||||
|
||||
Le message/context d'erreur reste destiné au diagnostic ; l'identité machine-readable passe par `ErrorCode`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user