125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
<!-- file: crates/ksp-job-backfill-lib/README.md -->
|
|
<!-- version: 2 -->
|
|
|
|
# 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é, common RAW et Store backend-neutral sans posséder leurs politiques internes. Elle couvre l'admission, la découverte historique, l'hydratation `getTransaction`, l'adaptation vers `ksp-raw-transaction-lib`, 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-raw-transaction-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.
|