Sasedev/khadhroony-bot3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.5.1-pre.005

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-10 01:36:42 +02:00
parent ec07ddbd80
commit b6a286a4df
54 changed files with 6236 additions and 5569 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md -->
<!-- version: 5 -->
<!-- version: 6 -->
# Politique de namespace Khadhroony Solana
@@ -65,8 +65,9 @@ La classification d'une valeur sensible doit survivre à la substitution. Une ch
La restructuration `0.5.1` doit séparer au minimum :
- la configuration généraliste dans son propre document et son propre schéma ;
- la configuration logging dans un document et un schéma indépendants, avec des profils logging sélectionnables indépendamment des profils réseau/applicatifs.
- la configuration généraliste dans `config/app.config.json`, avec son schéma sous `config/schemas/app.config.schema.json` ;
- la configuration logging dans `config/logging.config.json`, avec son schéma sous `config/schemas/logging.config.schema.json` et des profils logging sélectionnables indépendamment des profils réseau/applicatifs ;
- des exemples conformes mais non chargés par défaut sous `config/example.app.config.json` et `config/example.logging.config.json`.
D'autres documents spécialisés ne sont créés que si l'audit démontre une responsabilité, un cycle de vie ou une validation réellement indépendants.

102
docs/guides/CONFIGURATION.md
View File

@@ -1,85 +1,95 @@
<!-- file: docs/guides/CONFIGURATION.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Guide de configuration
## Objectif
Ce guide décrit le chargement et l’utilisation de la configuration bot3. La référence d’API détaillée reste `ks-config/USAGE.md`.
Ce guide décrit le chargement des documents de configuration après leur séparation. La référence d’API générale reste `ks-config/USAGE.md` et la configuration logging appartient à `ks-logging`.
## Fichiers actifs
- `config/example.config.json` : exemple utilisateur complet ;
- `config/schema.config.json` : contrat JSON formel ;
- `config/app.config.json` : configuration générale chargée par défaut ;
- `config/logging.config.json` : configuration logging chargée par défaut ;
- `config/example.app.config.json` et `config/example.logging.config.json` : exemples minimaux conformes ;
- `config/schemas/app.config.schema.json` : schéma général ;
- `config/schemas/logging.config.schema.json` : schéma logging ;
- `.env`, ou le fichier sélectionné par `KS_ENV_FILE` : valeurs d’environnement non versionnées ;
- `.env.example` : noms de variables attendues sans secrets.
- `.env.example` : noms de variables attendues sans secrets réels.
Le format actif est JSON. Le futur split de configuration prévu en `0.5.x` ne modifie pas le contrat actuel.
`KS_CONFIG_PATH` et `KS_LOGGING_CONFIG_PATH` permettent de remplacer indépendamment les deux chemins par défaut.
## Séquence de chargement
## Configuration générale
L’API recommandée est `read_config_json_file_with_environment`. Elle :
L’API recommandée reste `ks_config::read_config_json_file_with_environment`. Elle :
1. charge `.env`, ou le fichier explicitement sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
2. lit le JSON ;
3. résout les placeholders namespacés `${KS_*}` / `${KB_*}` et les fallbacks éventuels ;
4. valide le schéma JSON ;
5. désérialise les types de configuration et applique les invariants métier ;
6. laisse ensuite `active_profile` sélectionner le profil actif.
## Exemple opérateur
1. charge `.env`, ou le fichier sélectionné par `KS_ENV_FILE`, sans écraser les variables du processus ;
2. lit le JSON général ;
3. résout les placeholders `${KS_*}` / `${KB_*}` ;
4. valide `config/schemas/app.config.schema.json` ;
5. désérialise `AppConfig` et applique les invariants métier ;
6. laisse `active_profile` sélectionner le profil applicatif actif.
```rust
let config = match ks_config::read_config_json_file_with_environment(
std::path::Path::new("config/example.config.json"),
std::path::Path::new("config/app.config.json"),
std::path::Path::new("."),
) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let profile = match ks_config::active_profile(&config) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
println!("active profile={}", profile.name);
```
Le profil général ne contient plus de bloc `logging`.
## Configuration logging
`ks_logging::read_logging_json_file_with_environment` charge séparément le document logging et `ks_logging::active_logging_profile` sélectionne son profil actif.
```rust
let logging = match ks_logging::read_logging_json_file_with_environment(
std::path::Path::new("config/logging.config.json"),
std::path::Path::new("."),
) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let logging_profile = match ks_logging::active_logging_profile(&logging) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
```
Les deux `active_profile` sont indépendants. Il n’existe aucun fallback implicite du profil logging vers le nom du profil applicatif.
## Invariants
- aucun secret ne doit être ajouté à l’exemple versionné ;
- les placeholders non résolus doivent provoquer un diagnostic explicite ;
- le schéma embarqué et `config/schema.config.json` doivent rester identiques ;
- tant que `0.5.1-pre.006` n’a pas introduit les DTO publics sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle ;
- les noms de profils et rôles d’endpoints doivent rester cohérents avec leurs consommateurs.
## Quotas HTTP cumulés
Les limites HTTP sont déclarées par rôle, mais les quotas d’un endpoint public s’appliquent généralement à l’endpoint ou à l’adresse IP entière. Pour un endpoint unique, il faut donc considérer au minimum :
- la somme des `requests_per_second` de tous les rôles actifs ;
- la somme des bursts pouvant partir dans la même fenêtre ;
- la limite propre à une méthode RPC répétée ;
- les autres processus utilisant la même IP ou le même fournisseur.
Le profil public Devnet de l’exemple utilise `3 r/s` pour `http_queries` et `1 r/s` pour `http_transactions`. Un profil privé ou payant peut utiliser d’autres valeurs, mais elles doivent suivre le contrat réel du fournisseur.
- aucun secret réel ne doit être ajouté aux fichiers versionnés ;
- les placeholders non résolus doivent rester détectables ;
- chaque schéma embarqué doit rester identique au fichier sous `config/schemas/` ;
- les profils applicatifs et logging sont validés indépendamment ;
- `ks-config` ne possède plus de types logging ;
- tant que `0.5.1-pre.006` n’a pas introduit les DTO sûrs, la configuration runtime résolue reste strictement backend et ne doit pas être exposée telle quelle.
## Diagnostic
Pour isoler une erreur :
1. afficher la liste des fichiers d’environnement chargés ;
2. résoudre le JSON sans l’écrire dans les logs s’il contient des secrets ;
3. valider le schéma ;
4. valider le modèle typé ;
5. vérifier le profil actif ;
6. vérifier les rôles HTTP, WebSocket, stockage et logging.
1. vérifier le fichier d’environnement chargé ;
2. vérifier séparément les chemins app et logging ;
3. valider chaque document contre son schéma ;
4. vérifier son `active_profile` ;
5. vérifier ensuite les rôles HTTP/WebSocket, stockage ou routes logging concernés.
Ne jamais écrire dans les logs le JSON résolu complet s’il contient une valeur issue de `KS_SECRET_*` ou `KB_SECRET_*`.
## Références
- `ks-config/README.md` ;
- `ks-config/USAGE.md` ;
- `ks-config/TODO.md` ;
- `ks-config/README.md` et `ks-config/USAGE.md` ;
- `ks-logging/README.md` et `ks-logging/USAGE.md` ;
- `config/README.md` ;
- `docs/decisions/WINCODE_COMPATIBILITY_POLICY.md`.
- `docs/decisions/KHADHROONY_SOLANA_NAMESPACE_POLICY.md`.

53
docs/guides/LOGGING.md
View File

@@ -1,34 +1,43 @@
<!-- file: docs/guides/LOGGING.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Guide de logging et tracing
## Objectif
`ks-logging` initialise les routes de tracing définies par la configuration et conserve les guards nécessaires à leur durée de vie.
`ks-logging` possède désormais le contrat logging, son document de profils, son schéma JSON et l’initialisation runtime `tracing`.
## Flux de démarrage
1. charger et valider la configuration avec `ks-config` ;
2. construire `LoggingConfig` ;
1. charger `config/logging.config.json` avec `ks_logging::read_logging_json_file_with_environment` ;
2. sélectionner le profil avec `ks_logging::active_logging_profile` ;
3. appeler `ks_logging::init_logging` une seule fois ;
4. conserver `LoggingGuard` jusqu’à la fermeture du processus ;
5. émettre les événements avec des targets canoniques.
```rust
let guard = match ks_logging::init_logging(&config.logging) {
let document = match ks_logging::read_logging_json_file_with_environment(
std::path::Path::new("config/logging.config.json"),
std::path::Path::new("."),
) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let config = match ks_logging::active_logging_profile(&document) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
let guard = match ks_logging::init_logging(config) {
std::result::Result::Ok(value) => value,
std::result::Result::Err(error) => return std::result::Result::Err(error),
};
tracing::info!(
target: ks_logging::tracing_target(),
routes = guard.route_count(),
"logging initialized"
);
```
## Routes
Le profil logging est sélectionné indépendamment du profil général de `app.config.json`.
## Contrat JSON
Le schéma est `config/schemas/logging.config.schema.json`. Les exemples sont `config/logging.config.json` pour la configuration runtime de référence et `config/example.logging.config.json` pour un exemple minimal.
Une route définit notamment :
@@ -52,28 +61,28 @@ ks-onchain-transport.http
ks-lib-executor.spl.token-2022
ks-lib-materializer.compliance.audit
ks-lib-materializer.token.accounts
ks-lib-materializer.transaction.annotations
```
Pour un matérialisateur, la target de tracing est l’identité runtime `ks-lib-materializer.<domain>[.<subsystem>]`. Elle reste distincte du `processorName` persisté `materializer.<domain>[.<subsystem>]`, qui ne doit pas être utilisé comme target de logs.
Une nouvelle target doit être ajoutée selon `docs/OPERATION_NAMING_CONVENTION.md` et les règles Khadhroony.
Pour un matérialisateur, la target de tracing reste distincte du `processorName` persisté.
## Frontend desktop
Les fenêtres Tauri utilisent la permission tracing prévue par leurs capabilities. Les logs frontend sont adaptés vers le backend sans permettre au frontend de choisir arbitrairement une target sensible.
Le desktop charge les documents app et logging séparément. Il ne convertit plus un type `ks_config::LoggingConfig` vers `ks_logging::LoggingConfig` : le type runtime est possédé directement par `ks-logging`.
La surface publique de diagnostic/configuration reste volontairement inchangée jusqu’à `0.5.1-pre.006`, qui supprimera l’exposition des configurations résolues complètes.
## Diagnostic
- vérifier les routes actives via `route_names()` ;
- vérifier `KS_LOGGING_CONFIG_PATH` si le fichier par défaut n’est pas utilisé ;
- vérifier le profil logging actif indépendamment du profil app ;
- valider le document contre son schéma ;
- confirmer le niveau global et les filtres spécifiques ;
- vérifier le chemin et les permissions d’une route fichier ;
- vérifier que le guard n’est pas détruit prématurément ;
- vérifier les chemins et permissions des routes fichier ;
- ne pas réinitialiser le subscriber global pendant l’exécution.
## Références
- `ks-logging/README.md` ;
- `ks-logging/USAGE.md` ;
- `ks-config/USAGE.md` ;
- `docs/architecture/ARCHITECTURE.md`.
- `config/README.md` ;
- `docs/OPERATION_NAMING_CONVENTION.md`.

28
docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/V0_5_1_KHADHROONY_SOLANA_NAMESPACE_AND_CONFIG_PLAN.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Plan temporaire `0.5.1` — namespace Khadhroony Solana et configuration sûre
@@ -408,7 +408,7 @@ Les targets de tracing de crates génériques doivent également migrer vers `ks
L'audit distingue trois ensembles afin de ne pas transformer des exemples historiques en contrats runtime :
- **85 noms** actuellement utilisés/référencés par le code, les tests, `.env.example`, les fixtures ou `config/example.config.json` ;
- **85 noms** actuellement utilisés/référencés par le code, les tests, `.env.example`, les fixtures ou `config/app.config.json` ;
- **17 noms supplémentaires** présents uniquement dans le guide opérateur Devnet actif ;
- soit **102 noms historiques actifs à migrer ou consolider**, dont plusieurs convergent volontairement vers une même cible canonique.
@@ -561,10 +561,12 @@ Les anciennes fixtures `TOKEN_2022_*` et les alias opérateur déjà préfixés
L'audit `0.5.0` a confirmé une duplication importante : chaque profil généraliste transporte un bloc logging volumineux. La cible minimale devient :
```text
config/example.config.json
config/example.logging.json
config/schema.config.json
config/schema.logging.json
config/app.config.json
config/logging.config.json
config/example.app.config.json
config/example.logging.config.json
config/schemas/app.config.schema.json
config/schemas/logging.config.schema.json
```
Les profils applicatifs/réseau et les profils logging sont sélectionnables indépendamment. Un profil `devnet` n'impose donc pas un profil logging `debug`, et `mainnet` n'impose pas mécaniquement un profil logging `release`.
@@ -575,7 +577,7 @@ Le code duplique actuellement dans `ks-config` et `ks-logging` les concepts :
- `LogTargetConfig` ;
- `LogTargetFilterConfig`.
`kb-app-demo-desktop` contient en plus une conversion manuelle de `ks_config::LoggingConfig` vers `ks_logging::LoggingConfig`. `0.5.1` doit supprimer cette duplication en donnant au logging un contrat possédé par `ks-logging`, tout en laissant `ks-config` charger/valider/composer les documents sans réinventer les types runtime du logging.
La migration `pre.005` ferme cette dette : `ks-config` ne définit plus de type logging, `ks-logging` possède le document, le schéma et les types runtime, et le desktop charge les deux fichiers indépendamment. `ks-logging` réutilise uniquement les helpers génériques d’environnement de `ks-config`, sans créer de dépendance inverse.
Aucun troisième document spécialisé n'est créé dans `0.5.1` sans bénéfice de découplage démontré.
@@ -628,7 +630,7 @@ Avant chaque changement structurel correspondant, conserver ou ajouter des tests
- l'interdiction des variables de configuration possédées par le workspace hors namespace d'ownership `KS_*` ou `KB_*` ;
- la propagation de sensibilité depuis `KS_SECRET_*` vers les valeurs composées ;
- l'impossibilité pour une sentinelle secrète d'apparaître dans `Debug`, logs, erreurs, payloads Tauri, sérialisation publique ou diagnostic ;
- la validation indépendante de `schema.config.json` et `schema.logging.json` ;
- la validation indépendante de `config/schemas/app.config.schema.json` et `config/schemas/logging.config.schema.json` ;
- l'indépendance des profils généralistes et logging ;
- l'absence de duplication structurelle des types logging entre `ks-config` et `ks-logging` ;
- le maintien des contrats publics réellement nécessaires après remplacement des types de configuration exposés.
@@ -672,10 +674,12 @@ Les tests ne doivent pas figer comme comportement légitime la fuite actuelle de
### `0.5.1-pre.005` — split config/logging
- extraire `example.logging.json` et `schema.logging.json` ;
- rendre profils logging et généralistes indépendants ;
- supprimer les structures logging dupliquées et la conversion desktop manuelle ;
- maintenir schémas, exemples et documentation synchronisés.
- **implémenté** : `config/app.config.json` et `config/logging.config.json` deviennent les deux documents chargés par défaut ;
- **implémenté** : les schémas sont centralisés sous `config/schemas/app.config.schema.json` et `config/schemas/logging.config.schema.json` ;
- **implémenté** : `example.app.config.json` et `example.logging.config.json` fournissent des exemples minimaux conformes ;
- **implémenté** : les profils logging et généralistes possèdent chacun leur propre `active_profile` ;
- **implémenté** : `ks-logging` devient propriétaire unique du contrat logging et de sa validation ;
- **implémenté** : le desktop supprime la conversion `ks_config::LoggingConfig` -> `ks_logging::LoggingConfig`.
### `0.5.1-pre.006` — surfaces publiques sûres

5
docs/rules/RULES_SPECIFIC_KHADHROONY.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/RULES_SPECIFIC_KHADHROONY.md -->
<!-- version: 15 -->
<!-- version: 16 -->
# Règles spécifiques à `khadhroony-bot3`
@@ -238,6 +238,9 @@ Aucun renommage massif de modules n'est autorisé sans étape de contrôle dédi
## Règles de configuration
- La configuration applicative commune doit passer par `ks-config`.
- Les fichiers runtime chargés par défaut sont `config/app.config.json` pour la configuration générale et `config/logging.config.json` pour le logging ; leurs sélections de profils sont indépendantes.
- Les schémas JSON de configuration actifs sont conservés sous `config/schemas/`, notamment `app.config.schema.json` et `logging.config.schema.json`.
- Les exemples conformes sont conservés sous `config/` avec des noms distincts des fichiers runtime, notamment `example.app.config.json` et `example.logging.config.json`.
- Les fichiers JSON de configuration ne doivent pas contenir de commentaires.
- Les secrets ne doivent pas être écrits en clair dans le dépôt.
- Les valeurs sensibles doivent utiliser des variables d'environnement ou un stockage chiffré dédié.