5.9 KiB
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 :
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 :
0.2.11-pre.3
La version Cargo de sortie est :
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 :
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 :
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 :
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 :
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 :
#[cfg(test)]
jusqu'à pre.004, où les premiers adapters de production les consommeront réellement.
Les anciens :
#[allow(dead_code)]
sont supprimés.
Le staging concerne :
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 :
requests > 0
window > 0
window <= borne défensive
burst > 0 lorsqu'il est explicite
burst absent -> capacité locale conservatrice de 1
En revanche :
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 :
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
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é
deltas/0.2.11/pre.003-fix.001.md
10. Fichiers volontairement inchangés
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 :
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é
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.