v0.2.1-pre.006
This commit is contained in:
263
deltas/0.2.1/pre.006.md
Normal file
263
deltas/0.2.1/pre.006.md
Normal file
@@ -0,0 +1,263 @@
|
||||
<!-- file: deltas/0.2.1/pre.006.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user