v0.2.11-pre.003-fix.001
This commit is contained in:
220
deltas/0.2.11/pre.003-fix.001.md
Normal file
220
deltas/0.2.11/pre.003-fix.001.md
Normal file
@@ -0,0 +1,220 @@
|
||||
<!-- file: deltas/0.2.11/pre.003-fix.001.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# Delta `0.2.11-pre.003-fix.001` — conformité crate-root, staging HTTP et burst documenté
|
||||
|
||||
## 1. Base requise
|
||||
|
||||
Ce correctif s'applique exclusivement après :
|
||||
|
||||
```text
|
||||
v0.2.10
|
||||
+ 0.2.11-pre.001
|
||||
+ 0.2.11-pre.001-fix.001
|
||||
+ 0.2.11-pre.002
|
||||
+ 0.2.11-pre.002-fix.001
|
||||
+ 0.2.11-pre.002-fix.002
|
||||
+ 0.2.11-pre.002-fix.003
|
||||
+ 0.2.11-pre.003
|
||||
```
|
||||
|
||||
La version Cargo attendue à l'entrée est :
|
||||
|
||||
```text
|
||||
0.2.11-pre.3
|
||||
```
|
||||
|
||||
La version Cargo de sortie est :
|
||||
|
||||
```text
|
||||
0.2.11-pre.3.fix.1
|
||||
```
|
||||
|
||||
## 2. Motif du correctif
|
||||
|
||||
Le gate opérateur de `pre.003` a révélé plusieurs écarts avant poursuite vers `pre.004` :
|
||||
|
||||
```text
|
||||
RUST-FMT-104 : 6 violations dans src/error.rs
|
||||
cargo check : 6 warnings de réexports pub(crate) HTTP inutilisés
|
||||
cargo clippy --workspace --all-targets : mêmes warnings de réexports
|
||||
cargo test -p ksp-offchain-transport-lib : 20 PASS, 1 FAIL
|
||||
```
|
||||
|
||||
Le test en échec était :
|
||||
|
||||
```text
|
||||
http_admission::tests::documented_burst_is_consumed_atomically_before_refill
|
||||
```
|
||||
|
||||
La cause était une validation incorrecte refusant `burst > requests`. Cette contrainte contredit un cas déjà retenu dans le plan : Coinbase documente `10 req/s` avec `burst 15`.
|
||||
|
||||
Une relecture de `docs/rules/RULES_RUST.md` confirme également deux règles applicables :
|
||||
|
||||
```text
|
||||
RUST-IMPORT-009 / RUST-API-004
|
||||
un item pub/pub(crate) crate-wide est consommé via la façade crate::Item,
|
||||
y compris depuis son module de déclaration.
|
||||
|
||||
RUST-API-008
|
||||
un helper préparatoire sans consumer de production reste sous #[cfg(test)]
|
||||
jusqu'à sa première consommation réelle ; #[allow(dead_code)] n'est pas utilisé
|
||||
pour conserver artificiellement du code mort.
|
||||
```
|
||||
|
||||
## 3. Correction de façade crate-root
|
||||
|
||||
Les items HTTP partagés continuent d'être réexportés au crate-root dans le build de test, et leurs implémentations utilisent désormais leur chemin de façade :
|
||||
|
||||
```text
|
||||
impl crate::HttpAdmissionPolicy
|
||||
impl crate::HttpAdmissionController
|
||||
impl crate::HttpJsonDocument
|
||||
impl crate::HttpGetRequest
|
||||
impl crate::HttpRestClient
|
||||
impl crate::HttpClientSettings
|
||||
```
|
||||
|
||||
Les signatures et références crate-wide correspondantes utilisent également `crate::Item` lorsqu'elles traversent un module.
|
||||
|
||||
Les types strictement privés, tels que `HttpTokenBucketState`, restent locaux et ne sont pas réexportés.
|
||||
|
||||
## 4. Staging `RUST-API-008`
|
||||
|
||||
Aucun adapter de production ne consomme encore les primitives `http_*` en `pre.003`.
|
||||
|
||||
Les trois modules préparatoires sont donc compilés sous :
|
||||
|
||||
```text
|
||||
#[cfg(test)]
|
||||
```
|
||||
|
||||
jusqu'à `pre.004`, où les premiers adapters de production les consommeront réellement.
|
||||
|
||||
Les anciens :
|
||||
|
||||
```text
|
||||
#[allow(dead_code)]
|
||||
```
|
||||
|
||||
sont supprimés.
|
||||
|
||||
Le staging concerne :
|
||||
|
||||
```text
|
||||
http_admission
|
||||
http_client
|
||||
http_settings
|
||||
```
|
||||
|
||||
Les codes d'erreur HTTP publics restent disponibles dans le build normal ; aucune API HTTP générique n'est rendue publique aux consumers.
|
||||
|
||||
## 5. Correction du burst
|
||||
|
||||
La policy fixe conserve les invariants suivants :
|
||||
|
||||
```text
|
||||
requests > 0
|
||||
window > 0
|
||||
window <= borne défensive
|
||||
burst > 0 lorsqu'il est explicite
|
||||
burst absent -> capacité locale conservatrice de 1
|
||||
```
|
||||
|
||||
En revanche :
|
||||
|
||||
```text
|
||||
burst <= requests
|
||||
```
|
||||
|
||||
n'est plus un invariant.
|
||||
|
||||
Un burst documenté est une capacité instantanée distincte de la cadence moyenne et peut légitimement lui être supérieur.
|
||||
|
||||
Le canari déterministe couvre explicitement :
|
||||
|
||||
```text
|
||||
1 req/s
|
||||
burst 2
|
||||
2 admissions immédiates
|
||||
3e admission différée
|
||||
```
|
||||
|
||||
Cette propriété protège notamment la représentabilité future du cas Coinbase `10 req/s, burst 15`.
|
||||
|
||||
## 6. Ordre des constantes
|
||||
|
||||
Le bloc `const` de `src/error.rs` est réordonné alphabétiquement conformément à `RUST-FMT-005` / `RUST-FMT-104` sans modifier les valeurs des codes d'erreur.
|
||||
|
||||
Aucun code d'erreur n'est ajouté, supprimé ou renommé.
|
||||
|
||||
## 7. Test HTTP complémentaire
|
||||
|
||||
Un canari supplémentaire construit une requête HTTPS officielle-style sans effectuer de réseau, ajoute query pair et header sensible, puis vérifie que la représentation `Debug` ne contient ni host ni credential.
|
||||
|
||||
Ce canari consomme également le constructeur `HttpGetRequest::new_https` pendant le staging `cfg(test)`.
|
||||
|
||||
## 8. Fichiers modifiés
|
||||
|
||||
```text
|
||||
Cargo.toml
|
||||
crates/ksp-offchain-transport-lib/src/error.rs
|
||||
crates/ksp-offchain-transport-lib/src/http_admission.rs
|
||||
crates/ksp-offchain-transport-lib/src/http_client.rs
|
||||
crates/ksp-offchain-transport-lib/src/http_settings.rs
|
||||
crates/ksp-offchain-transport-lib/src/lib.rs
|
||||
crates/ksp-offchain-transport-lib/unit_tests/http_admission.rs
|
||||
crates/ksp-offchain-transport-lib/unit_tests/http_client.rs
|
||||
docs/plans/018-V0_2_11_OFFCHAIN_PRICE_TRANSPORT_PLAN.md
|
||||
docs/validation/014-V0_2_11_OFFCHAIN_PRICE_TRANSPORT.md
|
||||
```
|
||||
|
||||
## 9. Fichier ajouté
|
||||
|
||||
```text
|
||||
deltas/0.2.11/pre.003-fix.001.md
|
||||
```
|
||||
|
||||
## 10. Fichiers volontairement inchangés
|
||||
|
||||
```text
|
||||
crates/ksp-offchain-transport-lib/Cargo.toml
|
||||
crates/ksp-offchain-transport-lib/tests/**
|
||||
CHANGELOG.md
|
||||
ROADMAP.md
|
||||
README.md
|
||||
.env.example
|
||||
config/**
|
||||
crates/ksp-config-lib/**
|
||||
crates/ksp-onchain-transport-lib/**
|
||||
prompts/**
|
||||
```
|
||||
|
||||
Le manifeste de la crate hérite toujours de `workspace.package.version`; seul le `Cargo.toml` racine porte le bump technique.
|
||||
|
||||
## 11. Validations sandbox
|
||||
|
||||
Exécutées après le correctif :
|
||||
|
||||
```text
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
General Rust rule audit: clean
|
||||
Rust export completeness audit: 0 candidate(s)
|
||||
KSP workspace Rust rule audit: clean
|
||||
```
|
||||
|
||||
Le sandbox ne fournit pas Cargo ; les gates opérateur restent à rejouer sur l'état exact du correctif.
|
||||
|
||||
## 12. Gate opérateur demandé
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
python3 scripts/audit_rust_workspace_rules.py
|
||||
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.2.11
|
||||
cargo check --workspace
|
||||
cargo clippy --workspace --all-targets
|
||||
cargo test -p ksp-offchain-transport-lib
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
Le passage à `pre.004` est conditionné à un gate propre sans warning et au retour au vert du test de burst.
|
||||
Reference in New Issue
Block a user