147 lines
6.2 KiB
Markdown
147 lines
6.2 KiB
Markdown
<!-- file: deltas/0.3.6/pre.004.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta `0.3.6-pre.004` — provenance Transport observée pour `getTransaction`
|
|
|
|
## Base requise
|
|
|
|
```text
|
|
0.3.6-pre.003-fix.001 appliquée
|
|
workspace.package.version = 0.3.6-pre.3.fix.1
|
|
```
|
|
|
|
Le gate opérateur fourni pour cette base confirme :
|
|
|
|
```text
|
|
cargo fmt --all PASS
|
|
python3 scripts/audit_rust_workspace_rules.py PASS / clean
|
|
python3 scripts/audit_markdown_tables.py ... PASS / clean (264 tables / 145 fichiers)
|
|
cargo check --workspace PASS
|
|
cargo clippy --workspace --all-targets PASS
|
|
cargo test -p ksp-job-api PASS / 13 unitaires + 14 canaries
|
|
cargo tree -p ksp-job-api --edges normal Core-only confirmé
|
|
cargo tree -p ksp-job-api -e features aucune feature Job API
|
|
```
|
|
|
|
## Objectif
|
|
|
|
Matérialiser exclusivement la tranche `pre.004` du plan 027 : permettre au futur backfill de connaître le provider et l'endpoint HTTP qui ont réellement produit le succès de `getTransaction`, y compris après retry/reroutage, sans dupliquer le client RPC ni déplacer la politique Transport vers Job.
|
|
|
|
## Conception
|
|
|
|
La nouvelle enveloppe générique `HttpObservedValue<T>` contient uniquement :
|
|
|
|
- la valeur typée `T` ;
|
|
- le nom configuré et validé de l'endpoint victorieux ;
|
|
- le descripteur provider de cet endpoint.
|
|
|
|
Elle ne contient jamais :
|
|
|
|
- URL d'endpoint ;
|
|
- headers HTTP ;
|
|
- body HTTP brut ;
|
|
- credentials ou autre détail de connexion.
|
|
|
|
Son `Debug` conserve l'identité sûre de routage mais remplace systématiquement la valeur typée par `<available>` afin qu'un diagnostic générique ne rende pas accidentellement un payload transactionnel volumineux.
|
|
|
|
Le moteur HTTP commun n'est pas dupliqué. `execute_standard_rpc_with` possède toujours l'unique boucle de support, request-id, admission, deadline, retry, cooldown, HTTP, parsing JSON-RPC et accounting. Une projection de succès interne décide seulement de la forme de retour :
|
|
|
|
- `execute_standard_rpc` retourne la valeur historique sans allouer de provenance ;
|
|
- la voie interne observée capture endpoint/provider uniquement après le succès final ;
|
|
- `get_transaction_observed` réutilise cette voie et retourne `HttpObservedValue<Option<SolanaConfirmedTransaction>>`.
|
|
|
|
Les validations de paramètres `getTransaction` sont factorisées dans un helper commun. `get_transaction` et `get_transaction_observed` rejettent donc exactement les mêmes entrées et utilisent le même décodage typé. L'API historique reste source-compatible.
|
|
|
|
## Tests ajoutés
|
|
|
|
Deux tests unitaires Transport :
|
|
|
|
- `typed_get_transaction_observed_reports_actual_winner_after_retry_reroute` : deux endpoints de même priorité, premier résultat HTTP `429`, retry sur le second ; la valeur observée doit rapporter `winner-endpoint` / `winner-provider`, pas le candidat initial ;
|
|
- `typed_get_transaction_observed_preserves_null_and_redacts_typed_value_debug` : `result: null` reste `None`, endpoint/provider restent disponibles et le `Debug` ne rend pas la valeur typée.
|
|
|
|
Une canarie publique :
|
|
|
|
- `public_v0_3_6_pre_004_observed_get_transaction_surface_is_available_from_crate_root` : méthode et enveloppe observée sont consommables depuis le crate-root.
|
|
|
|
Aucun fixture wire nouveau n'est nécessaire : les fixtures `get_transaction.base64.json` et `get_transaction.null.json` existantes sont réutilisées.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
```text
|
|
deltas/0.3.6/pre.004.md
|
|
```
|
|
|
|
## Fichiers modifiés
|
|
|
|
```text
|
|
Cargo.toml
|
|
crates/ksp-onchain-transport-lib/src/http_executor.rs
|
|
crates/ksp-onchain-transport-lib/src/lib.rs
|
|
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
|
|
crates/ksp-onchain-transport-lib/tests/public_api.rs
|
|
crates/ksp-onchain-transport-lib/unit_tests/rpc_transactions.rs
|
|
docs/plans/027-V0_3_6_JOB_API_BACKFILL_PLAN.md
|
|
docs/validation/023-V0_3_6_JOB_API_BACKFILL.md
|
|
```
|
|
|
|
Mécanique Cargo :
|
|
|
|
```text
|
|
header version: 398 -> 399
|
|
workspace.package.version: 0.3.6-pre.3.fix.1 -> 0.3.6-pre.4
|
|
workspace members: inchangés
|
|
workspace dependencies: inchangées
|
|
```
|
|
|
|
## Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## Frontières conservées
|
|
|
|
- aucune crate Job ou Store n'entre dans Transport ;
|
|
- aucune dépendance ou feature n'est ajoutée ;
|
|
- aucune sélection d'endpoint, pause ou boucle de retry n'est ajoutée dans Job ;
|
|
- aucune nouvelle lecture Config/env n'est introduite ;
|
|
- aucun code, DTO, client, retry loop ou provenance kbot3 n'est copié ; la matrice fonctionnelle `pre.001` reste seulement une référence de besoin ;
|
|
- le legacy `get_transaction_legacy` reste inchangé et non observé ; le backfill v0.3.6 utilisera le formulaire moderne objet ;
|
|
- README/USAGE restent fermés jusqu'à la tranche de réconciliation documentaire prévue par le plan.
|
|
|
|
## Validations exécutées dans l'environnement d'assemblage
|
|
|
|
```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
|
|
|
|
python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts crates deltas/0.3.6
|
|
-> Markdown table audit: clean
|
|
|
|
python3 -m unittest scripts/tests/test_audit_markdown_tables.py
|
|
-> 5 tests / OK
|
|
```
|
|
|
|
Le premier passage de l'auditeur Rust a détecté deux rustdocs manquantes sur les helpers `pub(crate)` de `HttpObservedValue`; elles ont été ajoutées avant assemblage et le second passage est intégralement propre.
|
|
|
|
L'environnement d'assemblage ne fournit ni `cargo`, ni `rustfmt`, ni `rustc`. Aucune compilation ou suite Rust de `pre.004` n'est donc annoncée comme exécutée localement.
|
|
|
|
## 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.3.6
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-onchain-transport-lib
|
|
cargo tree -p ksp-onchain-transport-lib --edges normal
|
|
cargo tree -p ksp-onchain-transport-lib -e features
|
|
```
|
|
|
|
Le gate doit notamment confirmer le retry/reroutage déterministe du nouveau test observé et l'absence de nouvelle dépendance/feature Transport.
|
|
|
|
## Questions ouvertes
|
|
|
|
Aucune question ne bloque `pre.005` après un gate opérateur vert de `pre.004`.
|