Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
665d7d2bb6f477e463fcbbace0d8fccfafdd791b
khadhroony-solana-project/deltas/0.2.1/pre.006.md
SinuS Von SifriduS f5d98c4e69 v0.2.1-pre.006
2026-08-17 21:03:51 +02:00

8.0 KiB
Raw Blame History

Delta v0.2.1-pre.006

Base

Base attendue :

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 :

0.2.1-pre.6

Objectif

Matérialiser la frontière de configuration standard de ksp-onchain-transport-lib sans inverser l'ownership :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

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 :

ksp-onchain-transport-lib = { path = "../ksp-onchain-transport-lib" }

Aucune nouvelle dépendance externe et aucune nouvelle feature externe.

Fichiers ajoutés

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

.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 :

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 :

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 View Git Blame Copy Permalink