v0.3.6-pre.012
This commit is contained in:
123
crates/ksp-job-backfill-lib/README.md
Normal file
123
crates/ksp-job-backfill-lib/README.md
Normal file
@@ -0,0 +1,123 @@
|
||||
<!-- file: crates/ksp-job-backfill-lib/README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# ksp-job-backfill-lib
|
||||
|
||||
`ksp-job-backfill-lib` implémente le premier job historique concret de KSP : un backfill borné de transactions Solana vers la couche RAW durable.
|
||||
|
||||
La crate compose les contrats Job, Transport observé et Store backend-neutral sans posséder leurs politiques internes. Elle couvre l'admission, la découverte historique, l'hydratation `getTransaction`, la conversion RAW v1, la persistance atomique, la concurrence bornée, la frontier contiguë, le checkpoint caller-owned, l'annulation coopérative et les snapshots latest-value.
|
||||
|
||||
## Identité
|
||||
|
||||
L'identité logique d'une transaction reste :
|
||||
|
||||
```text
|
||||
(RawNetworkId, RawTransactionSignature)
|
||||
```
|
||||
|
||||
Le rôle HTTP, le provider, l'endpoint et le protocole ne font pas partie de cette identité. Ils décrivent la sélection et/ou la provenance d'acquisition.
|
||||
|
||||
Le fingerprint d'un scope est déterministe sur sa sémantique de découverte et son réseau ; il n'intègre pas `JobId`, provider, endpoint, protocole ou rôle Transport.
|
||||
|
||||
## Scopes
|
||||
|
||||
Quatre scopes sont exposés :
|
||||
|
||||
```text
|
||||
LatestAddress
|
||||
BeforeAddress
|
||||
AfterAddress
|
||||
ExplicitSignatures
|
||||
```
|
||||
|
||||
La requête borne explicitement page size, nombre de pages, nombre de candidats et concurrence d'hydratation. Les signatures explicites sont dédupliquées de façon stable à la première occurrence.
|
||||
|
||||
## Hydratation et RAW v1
|
||||
|
||||
L'hydratation passe uniquement par la voie observée de `ksp-onchain-transport-lib`.
|
||||
|
||||
Un résultat disponible produit en mémoire :
|
||||
|
||||
- un `RawTransaction` canonique ;
|
||||
- une `RawTransactionObservation` liée à la même référence logique ;
|
||||
- une provenance contenant le provider et l'endpoint réellement gagnants ;
|
||||
- un payload JSON canonique `ksp.solana.raw_transaction`, version `1` ;
|
||||
- un digest SHA-256 des bytes canoniques.
|
||||
|
||||
Un `getTransaction = null` devient `BackfillHydrationOutcome::Missing` et ne fabrique ni payload ni provenance.
|
||||
|
||||
## Persistance
|
||||
|
||||
La persistance utilise exclusivement `ksp-store-lib` avec `default-features = false` côté dépendance de crate :
|
||||
|
||||
```text
|
||||
ksp-job-backfill-lib
|
||||
-> ksp-store-lib
|
||||
-X-> backend imposé par le job
|
||||
```
|
||||
|
||||
Le chemin d'écriture est l'acquisition atomique `RawTransaction + RawTransactionObservation` en mode normal. La crate distingue insertion, déjà présent, tombstone purgé, observation nouvelle/existante, missing et conflit. Un conflit de contenu n'est jamais converti en succès idempotent.
|
||||
|
||||
## Concurrence et checkpoint
|
||||
|
||||
L'exécution maintient au plus `hydration_concurrency` candidats actifs. Les terminaisons hors ordre sont réconciliées par index stable ; le checkpoint n'avance que sur un préfixe **contigu** d'outcomes durablement sûrs.
|
||||
|
||||
`BackfillCheckpoint` est opaque et caller-owned. Il lie :
|
||||
|
||||
```text
|
||||
JobId
|
||||
scope fingerprint
|
||||
completed contiguous prefix
|
||||
private Before resume cursor
|
||||
```
|
||||
|
||||
La crate ne persiste pas elle-même ce checkpoint. Une reprise crash-safe durable nécessite donc que le caller choisisse explicitement où conserver le checkpoint retourné.
|
||||
|
||||
## Runtime et annulation
|
||||
|
||||
`BackfillJobRuntime` est un coordinator single-run. `BackfillJobHandle` peut être cloné pour :
|
||||
|
||||
- demander une annulation coopérative ;
|
||||
- lire l'état de cette demande ;
|
||||
- obtenir une source latest-value indépendante.
|
||||
|
||||
L'annulation arrête l'admission de nouveau travail et peut interrompre certaines attentes pré-Store. Une persistance Store déjà soumise est toujours drainée avant publication terminale.
|
||||
|
||||
Les snapshots exposent uniquement des compteurs, phases, boundary, checkpoint et code d'échec sûrs ; ils ne contiennent ni payload RAW, ni URL/credential Transport.
|
||||
|
||||
## Dépendances
|
||||
|
||||
Les dépendances normales sont :
|
||||
|
||||
```text
|
||||
ksp-core-lib
|
||||
ksp-job-api
|
||||
ksp-logging-lib
|
||||
ksp-onchain-transport-lib
|
||||
ksp-store-lib (default-features = false)
|
||||
futures-util
|
||||
serde_json
|
||||
sha2
|
||||
tokio (macros + sync, détail runtime privé)
|
||||
```
|
||||
|
||||
La crate ne dépend pas de Config, `ksp-store-api` directement, `ksp-store-postgres-lib` ni d'un SDK provider.
|
||||
|
||||
## Hors périmètre
|
||||
|
||||
La crate ne possède pas :
|
||||
|
||||
- application desktop ou CLI ;
|
||||
- Worker API / worker live ;
|
||||
- retry, pacing ou sélection d'endpoint Transport ;
|
||||
- backend Store concret ;
|
||||
- decoding Program ou matérialisation CORE/DECODE/SPECIALIZED ;
|
||||
- table dédiée de checkpoint ;
|
||||
- control plane Job générique.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [`USAGE.md`](USAGE.md) — construction des scopes/requêtes, runtime, snapshots et reprise ;
|
||||
- [`../ksp-job-api/README.md`](../ksp-job-api/README.md) — contrats Job runtime-neutral ;
|
||||
- [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) — architecture durable acquisition/jobs ;
|
||||
- [`../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md`](../../docs/architecture/008-DATA_MATERIALIZATION_AND_STORE.md) — frontière RAW/Store.
|
||||
Reference in New Issue
Block a user