v0.2.1-pre.003
This commit is contained in:
196
deltas/0.2.1/pre.003.md
Normal file
196
deltas/0.2.1/pre.003.md
Normal file
@@ -0,0 +1,196 @@
|
||||
<!-- file: deltas/0.2.1/pre.003.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `v0.2.1-pre.003`
|
||||
|
||||
## Base
|
||||
|
||||
Base attendue : `v0.2.1-pre.002-fix.001`, validée localement avant ouverture de cette tranche.
|
||||
|
||||
Version Cargo cible :
|
||||
|
||||
```text
|
||||
0.2.1-pre.3
|
||||
```
|
||||
|
||||
## Objectif
|
||||
|
||||
Matérialiser la première couche de client/routing HTTP de `ksp-onchain-transport-lib` sans encore exécuter de méthode JSON-RPC :
|
||||
|
||||
- client endpoint logique autour de `reqwest::Client` ;
|
||||
- pool logique KSP ;
|
||||
- matching rôle/capability ;
|
||||
- priorité globale ;
|
||||
- round-robin équitable dans un même tier ;
|
||||
- fallback lorsque les candidats plus prioritaires ne sont pas sélectionnables ;
|
||||
- snapshots sûrs sans URL ;
|
||||
- préparation des états passifs nécessaires à la résilience de `pre.004`.
|
||||
|
||||
Cette tranche corrige également l'usage de `ROADMAP.md` afin de respecter son contrat existant : le ROADMAP décrit l'état synthétique et la planification majeure, pas l'historique des prereleases/fixes.
|
||||
|
||||
## Modifications
|
||||
|
||||
### Workspace
|
||||
|
||||
- `workspace.package.version` passe de `0.2.1-pre.2.fix.1` à `0.2.1-pre.3` ;
|
||||
- `reqwest` reste centralisé sous `[workspace.dependencies]`, avec `default-features = false` ;
|
||||
- activation explicite de la feature `rustls`, nécessaire à la construction réelle de clients HTTPS dans cette tranche ;
|
||||
- aucune feature `json` n'est ajoutée : les envelopes JSON-RPC restent possédées par KSP via `serde_json` ;
|
||||
- aucune dépendance Tokio directe n'est ajoutée à Transport dans cette tranche.
|
||||
|
||||
### `HttpEndpointClient`
|
||||
|
||||
Nouveau client endpoint logique :
|
||||
|
||||
- encapsule un `reqwest::Client` partageable ;
|
||||
- applique `connect_timeout`, `request_timeout` et `max_idle_connections_per_host` depuis les settings KSP ;
|
||||
- désactive les redirects automatiques ;
|
||||
- désactive les proxies système/environnement implicites ;
|
||||
- fixe un `User-Agent` KSP `ksp-onchain-transport-lib/<version>` ;
|
||||
- conserve l'URL hors de toute surface `Debug`/snapshot ;
|
||||
- expose uniquement identité, provider, cluster, état et capability matching sûrs.
|
||||
|
||||
### Snapshots et état passif
|
||||
|
||||
Nouveaux contrats publics :
|
||||
|
||||
```text
|
||||
HttpEndpointAvailability
|
||||
HttpEndpointRoleSnapshot
|
||||
HttpEndpointSnapshot
|
||||
HttpTransportPoolSnapshot
|
||||
```
|
||||
|
||||
Les snapshots ne contiennent jamais l'URL endpoint.
|
||||
|
||||
`HttpEndpointAvailability` réserve :
|
||||
|
||||
```text
|
||||
Disabled
|
||||
Available
|
||||
Degraded
|
||||
RateLimited
|
||||
```
|
||||
|
||||
`pre.003` ne produit activement que `Disabled` et `Available`. Les transitions `Degraded` / `RateLimited` appartiennent à `pre.004` avec cooldown, limiter et observations runtime.
|
||||
|
||||
### `HttpTransportPool`
|
||||
|
||||
Nouveaux contrats publics :
|
||||
|
||||
```text
|
||||
HttpTransportPool
|
||||
HttpEndpointSelection
|
||||
```
|
||||
|
||||
Algorithme concret de `pre.003` :
|
||||
|
||||
1. valider les settings Transport ;
|
||||
2. construire un client logique par endpoint ;
|
||||
3. exclure les endpoints disabled ;
|
||||
4. rechercher un rôle exact enabled ;
|
||||
5. exiger la capability exacte ou `*` ;
|
||||
6. choisir la plus faible priorité numérique ;
|
||||
7. appliquer un round-robin par couple rôle/request-kind dans ce meilleur tier ;
|
||||
8. utiliser un tier moins prioritaire lorsque les candidats plus prioritaires ne sont pas sélectionnables ;
|
||||
9. retourner `endpoint_selection_failed` si aucun candidat n'existe.
|
||||
|
||||
Le mutex synchrone du pool protège uniquement les curseurs de fairness et ne couvre aucune I/O ni aucun `await` réseau.
|
||||
|
||||
`select_for_method()` dérive le `request_kind` depuis le registre central et appelle `ensure_runtime_supported()` avant sélection ; une méthode historique `Removed` ne peut donc pas être routée comme méthode standard.
|
||||
|
||||
### ROADMAP
|
||||
|
||||
`ROADMAP.md` est ramené à son rôle défini par `FILE_CONTRACTS.md` :
|
||||
|
||||
- suppression des lignes servant de journal `0.2.1-pre.*` / `fix.*` ;
|
||||
- conservation d'un état synthétique de `0.2.0` ;
|
||||
- état synthétique courant de `0.2.1` ;
|
||||
- conservation des releases fonctionnelles `0.2.1+` et de leur planification majeure.
|
||||
|
||||
Aucune règle normative nouvelle n'est nécessaire : cette correction applique le contrat `ROADMAP.md` déjà documenté.
|
||||
|
||||
### Plan `008`
|
||||
|
||||
Le plan est synchronisé avec :
|
||||
|
||||
- la feature TLS réellement retenue ;
|
||||
- la politique client `reqwest` ;
|
||||
- le statut réalisé de `pre.003` ;
|
||||
- l'état exact après la tranche ;
|
||||
- le report explicite des limiteurs/concurrence/cooldown/retry effectifs à `pre.004`.
|
||||
|
||||
## Tests ajoutés
|
||||
|
||||
La crate Transport passe de 40 à **53 tests déclarés**.
|
||||
|
||||
Nouvelles preuves :
|
||||
|
||||
- snapshot client sans URL/secret ;
|
||||
- endpoint disabled visible mais non sélectionnable ;
|
||||
- matching rôle/wildcard capability ;
|
||||
- priorité globale ;
|
||||
- round-robin dans le meilleur tier ;
|
||||
- fallback depuis un endpoint plus prioritaire disabled ;
|
||||
- filtrage capability avant priorité ;
|
||||
- erreur structurée lorsque rien ne correspond ;
|
||||
- routing d'une méthode standard via son descriptor ;
|
||||
- snapshot pool sûr conservant les endpoints disabled ;
|
||||
- consommation du nouveau pool depuis l'API publique.
|
||||
|
||||
## Hors périmètre conservé
|
||||
|
||||
Restent à `pre.004` :
|
||||
|
||||
- token bucket RPS/burst ;
|
||||
- semaphore/max concurrent ;
|
||||
- cooldown après `429` ;
|
||||
- deadline effective de sélection/exécution ;
|
||||
- retry/backoff effectif ;
|
||||
- classification des erreurs `reqwest` pendant une requête ;
|
||||
- transitions runtime `Degraded` / `RateLimited`.
|
||||
|
||||
Restent à `pre.005+` :
|
||||
|
||||
- exécution JSON-RPC HTTP ;
|
||||
- méthodes canari typées ;
|
||||
- document Config standard et adapter ;
|
||||
- smoke tests réseau.
|
||||
|
||||
## Sources externes revérifiées
|
||||
|
||||
Pour `reqwest 0.13` :
|
||||
|
||||
- dépôt/documentation officielle `reqwest` : rustls est le backend TLS de référence actuel ;
|
||||
- changelog `reqwest` : en `0.13`, la feature historique `rustls-tls` a été renommée `rustls` ;
|
||||
- `ClientBuilder` officiel : `connect_timeout`, `timeout`, `pool_max_idle_per_host`, `redirect` et `no_proxy` sont disponibles sur le client async retenu.
|
||||
|
||||
## Validation
|
||||
|
||||
Non exécutée dans le sandbox de génération : `cargo` et `rustc` n'y sont pas installés.
|
||||
|
||||
À exécuter après application :
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-onchain-transport-lib
|
||||
cargo test --workspace
|
||||
cargo tree -p ksp-onchain-transport-lib
|
||||
cargo tree -p ksp-onchain-transport-lib -d
|
||||
cargo tree -p ksp-onchain-transport-lib -e features
|
||||
cargo tree -p ksp-onchain-transport-lib -e normal
|
||||
```
|
||||
|
||||
Les quatre `cargo tree` doivent être rejoués dans cette tranche car le feature-set de `reqwest` change avec l'activation de `rustls`.
|
||||
|
||||
## Suite
|
||||
|
||||
Tranche suivante prévue :
|
||||
|
||||
```text
|
||||
0.2.1-pre.004
|
||||
```
|
||||
|
||||
Périmètre : RPS/burst, concurrence, cooldown/429, timeout/deadline et retry/backoff borné, avec respect strict de `TransportRetryClass` et interdiction de resend après dispatch ambigu.
|
||||
Reference in New Issue
Block a user