264 lines
8.0 KiB
Markdown
264 lines
8.0 KiB
Markdown
<!-- 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`.
|