# Delta `v0.2.1-pre.006` ## Base Base attendue : ```text v0.2.1-pre.005-fix.001 ``` Cette base a été validée localement par le user avec `cargo fmt --all`, `cargo check --workspace`, `cargo clippy --workspace --all-targets`, les tests Transport, Config, Core et `cargo test --workspace`. Les canaries workspace de dépendances et de targets Logging sont également propres. Version Cargo cible : ```text 0.2.1-pre.6 ``` ## Objectif Matérialiser la frontière de configuration standard de `ksp-onchain-transport-lib` sans inverser l'ownership : ```text Config document / environment -> ksp-config-lib adapter -> HttpTransportSettings ``` Transport ne lit toujours ni Config, ni `.env`, ni `KSP_*` / `KSPB_*`. ## Nouveau document standard Transport Nouvelles ressources gérées : ```text cfg.std.transport -> config/std.transport.json schema.std.transport -> config/schemas/std.transport.schema.json ``` Le document standard possède : - `format_version = 1` ; - `retry` au niveau global ; - `default_profile` autonome ; - `profiles[]` contenant les endpoints propres au profil ; - endpoints avec identité/provider/cluster/URL/timeouts/idle-pool ; - rôles avec capabilities/request kinds, priorité et limites RPS/burst/concurrence/cooldown. Le profil par défaut committé est `devnet_public`. Le document fournit également `mainnet_public`. Les URLs publiques utilisent : ```text KSP_PUBLIC_SOLANA_DEVNET_HTTP_URL KSP_PUBLIC_SOLANA_MAINNET_HTTP_URL ``` avec fallback vers les endpoints publics Solana correspondants. ## Schema `config/schemas/std.transport.schema.json` : - Draft 2020-12 ; - `additionalProperties = false` aux frontières structurées ; - `format_version` fixé à `1` ; - invariants numériques positifs pour timeouts/limites ; - `request_kinds` non vide et wildcard `*` exclusif ; - profils et endpoints non vides ; - descriptors non vides sans whitespace de bord. Le schema protège la forme source ; la validation finale des invariants runtime reste possédée par `HttpTransportSettings::validate()`. ## Exemple provider-neutral `config/examples/std.transport.example.json` démontre un profil `mainnet_mixed` avec : - endpoint public de fallback ; - endpoint privé prioritaire ; - URL privée provenant de `KSP_SECRET_SOLANA_HTTP_URL`. Aucun credential réel n'est committé. `.env.example` inventorie les deux URLs publiques et documente l'URL privée optionnelle sous forme commentée. ## Registry Config Nouveaux contrats : ```text FILE_ID_STD_TRANSPORT FILE_ID_SCHEMA_STD_TRANSPORT DEFAULT_STD_TRANSPORT_FILENAME DEFAULT_STD_TRANSPORT_SCHEMA_FILENAME ``` `ConfigFileRegistry::defaults()` contient désormais cinq descriptors ordonnés : ```text cfg.std.logging cfg.std.transport schema.composite schema.std.logging schema.std.transport ``` Le document Transport référence explicitement son schema. ## Adapter Config -> Transport Nouvelle surface publique : ```text ResolvedTransportConfig ConfigDocumentEngine::load_resolved_transport_config(...) ``` L'adapter : 1. charge et valide `cfg.std.transport` ; 2. sélectionne le `default_profile` ou le profil explicite ; 3. résout les placeholders via `ConfigEnvironment` ; 4. préserve valeur réelle, valeur sûre, sensibilité et provenance JSON Pointer ; 5. décode le contrat effectif Config ; 6. convertit les scalaires `*_ms` en `std::time::Duration` ; 7. construit les newtypes/roles/limits/endpoints Transport ; 8. parse les URLs via `HttpEndpointUrl` ; 9. construit `HttpTransportSettings` ; 10. délègue la validation structurelle finale à Transport. La dépendance est donc : ```text ksp-config-lib -> ksp-onchain-transport-lib ``` Le firewall inverse reste inchangé : Transport ne dépend pas de Config. ## Secrets, safe view et provenance Contrairement au document Logging, le document Transport peut légitimement consommer une valeur `Secret` pour une URL endpoint complète. `ResolvedTransportConfig` : - expose `effective()` pour conserver le réel/safe/provenance ; - expose `settings()` / `into_settings()` au runtime légitime ; - n'imprime dans `Debug` que la projection `ResolvedConfigJson` sûre ; - ne copie pas l'URL réelle dans le contexte d'une erreur d'adaptation. Un échec Transport est projeté vers `ERROR_CODE_EFFECTIVE_CONFIG_INVALID` avec uniquement le domaine/code Transport et les identités non sensibles utiles. ## Tests Nouveau module unitaire `unit_tests/transport.rs` : - mapping complet des scalaires Config vers le runtime Transport ; - validation des profils committés `devnet_public` / `mainnet_public` ; - provenance top-level `Global` pour `retry` et `Profile` pour `endpoints` ; - URL `KSP_SECRET_*` disponible au runtime mais redacted dans la safe view et `Debug` ; - precedence process > `.env` ; - provenance JSON Pointer de l'URL endpoint ; - URL secrète invalide -> `ERROR_CODE_EFFECTIVE_CONFIG_INVALID` sans fuite du canary. Le registry gagne un test dédié au document/schema Transport et la surface publique Config gagne un canary de disponibilité de l'adapter. La surface Config déclare désormais : ```text 95 tests unitaires 18 tests d'intégration 113 tests au total ``` ## Ownership et documentation `DEP-TRANSPORT-005` précise maintenant explicitement que `ksp-config-lib` peut dépendre des crates Transport pour posséder les adapters Config -> runtime settings, jamais l'inverse. Le README/USAGE/TODO de Config est synchronisé avec `std.transport`. Le ROADMAP reçoit uniquement la mise à jour synthétique normale de l'état `0.2.1`; il ne journalise pas les détails du delta. ## Dépendances Nouvelle dépendance interne de `ksp-config-lib` : ```toml ksp-onchain-transport-lib = { path = "../ksp-onchain-transport-lib" } ``` Aucune nouvelle dépendance externe et aucune nouvelle feature externe. ## Fichiers ajoutés ```text config/examples/std.transport.example.json config/schemas/std.transport.schema.json config/std.transport.json crates/ksp-config-lib/src/transport.rs crates/ksp-config-lib/unit_tests/fixtures/std.transport.json crates/ksp-config-lib/unit_tests/transport.rs deltas/0.2.1/pre.006.md ``` ## Fichiers modifiés ```text .env.example Cargo.toml ROADMAP.md crates/ksp-config-lib/Cargo.toml crates/ksp-config-lib/README.md crates/ksp-config-lib/TODO.md crates/ksp-config-lib/USAGE.md crates/ksp-config-lib/src/lib.rs crates/ksp-config-lib/src/registry.rs crates/ksp-config-lib/tests/ownership.rs crates/ksp-config-lib/tests/public_api.rs crates/ksp-config-lib/unit_tests/registry.rs docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md docs/rules/RULES_DEPENDENCIES.md ``` ## Validation de génération Effectuée dans le sandbox : - parsing TOML des manifests modifiés ; - parsing JSON des nouvelles ressources ; - validation Draft 2020-12 des deux documents Transport et de la fixture contre le nouveau schema via l'implémentation Python `jsonschema` disponible ; - contrôle des lignes Rust/TOML modifiées <= 160 colonnes ; - contrôle des EOF et headers ; - scan statique des interdits KSP sur le nouveau code de production ; - contrôle de l'inventaire des variables `KSP_*` dans `.env.example` ; - contrôle différentiel des fichiers livrés. Non exécutée dans le sandbox : validation Cargo/Rust, les binaires `cargo`, `rustc` et `rustfmt` n'étant pas disponibles. Après application : ```bash cargo fmt --all cargo check --workspace cargo clippy --workspace --all-targets cargo test -p ksp-config-lib cargo test -p ksp-onchain-transport-lib cargo test -p ksp-core-lib cargo test --workspace cargo tree -p ksp-config-lib cargo tree -p ksp-config-lib -d cargo tree -p ksp-config-lib -e features cargo tree -p ksp-config-lib -e normal ``` Le `cargo tree` Config est requis cette fois : la dépendance interne Config -> Transport modifie réellement le graphe de la crate Config, même sans nouvelle dépendance externe. ## Suite Tranche suivante prévue : ```text 0.2.1-pre.007 ``` Périmètre : completeness/canaries finales, smoke réseau opt-in, audit `cargo tree`, README/USAGE Transport, documentation de clôture, prompt `0.2.2` et préparation de `rel.001`.