v0.3.11-pre.012
This commit is contained in:
158
crates/ksp-worker-raw-transaction-ingest-lib/README.md
Normal file
158
crates/ksp-worker-raw-transaction-ingest-lib/README.md
Normal file
@@ -0,0 +1,158 @@
|
||||
<!-- file: crates/ksp-worker-raw-transaction-ingest-lib/README.md -->
|
||||
<!-- version: 1 -->
|
||||
|
||||
# ksp-worker-raw-transaction-ingest-lib
|
||||
|
||||
`ksp-worker-raw-transaction-ingest-lib` est le premier Worker concret de KSP pour l'alimentation continue de la couche RAW Transaction.
|
||||
|
||||
La crate fournit la fondation runtime **source-neutral** du Worker : identité et settings bornés, lifecycle Start/Stop, admission privée bornée, canonicalisation via `ksp-raw-transaction-lib`, persistance backend-neutral via `ksp-store-lib`, supervision des tâches, shutdown borné et snapshots latest-value projetables sur `ksp-worker-api`.
|
||||
|
||||
La fondation ne contient volontairement encore **aucune source réseau productive**. Elle ne dépend pas de `ksp-onchain-transport-lib` et n'expose pas d'API publique permettant au caller d'injecter directement des transactions dans la queue interne. Les adapters live/catch-up sont des responsabilités ultérieures du même Worker, pas de son API de fondation.
|
||||
|
||||
## Identité et réseau
|
||||
|
||||
Une exécution est liée à :
|
||||
|
||||
```text
|
||||
RawNetworkId
|
||||
WorkerId
|
||||
Worker kind = raw_transaction_ingest
|
||||
```
|
||||
|
||||
Le réseau logique doit être identique à celui du `Store` remis au démarrage. La transaction canonique conserve l'identité durable définie par la couche RAW commune ; le Worker n'ajoute ni provider, ni endpoint, ni protocole à cette identité.
|
||||
|
||||
## Runtime
|
||||
|
||||
Le point d'entrée public est :
|
||||
|
||||
```text
|
||||
RawTransactionIngestWorker::start(settings, Arc<Store>)
|
||||
-> RawTransactionIngestHandle
|
||||
```
|
||||
|
||||
Le démarrage est synchrone mais nécessite qu'un runtime Tokio courant appartienne déjà au caller. Le Worker ne crée pas de runtime global et n'expose aucun `JoinHandle` public.
|
||||
|
||||
`RawTransactionIngestHandle` permet de :
|
||||
|
||||
- demander un stop coopératif et idempotent ;
|
||||
- obtenir une source de snapshots concrets latest-value ;
|
||||
- utiliser cette même source via `WorkerSnapshotSource` ;
|
||||
- attendre le terminal après drain/abort+join des tâches possédées.
|
||||
|
||||
La destruction du dernier handle de contrôle ferme aussi la voie de contrôle privée ; le runtime termine alors selon les mêmes règles de shutdown.
|
||||
|
||||
## Admission et Common RAW
|
||||
|
||||
La queue centrale est un `tokio::sync::mpsc` privé borné par `admission_queue_capacity`. Les sources internes doivent subir la backpressure du channel ; aucune queue non bornée ni silent drop n'est autorisé.
|
||||
|
||||
Chaque ingress admis est :
|
||||
|
||||
1. vérifié contre le réseau attendu ;
|
||||
2. canonicalisé exclusivement par `ksp-raw-transaction-lib` ;
|
||||
3. associé à une observation key déterministe sous le domaine `ksp.raw_transaction_ingest.observation.v1` ;
|
||||
4. assemblé en acquisition RAW commune ;
|
||||
5. remis à la persistence Store.
|
||||
|
||||
La crate ne possède pas un second format RAW et ne duplique pas le canonicaliseur commun.
|
||||
|
||||
## Persistence Store
|
||||
|
||||
La persistance passe uniquement par `ksp-store-lib` avec `default-features = false` dans la crate Worker. Aucun backend physique n'est imposé ou importé directement.
|
||||
|
||||
L'écriture utilise le mode normal d'acquisition atomique `RawTransaction + RawTransactionObservation`. Les outcomes distingués sont notamment :
|
||||
|
||||
```text
|
||||
entity inserted
|
||||
entity already present
|
||||
entity skipped purged
|
||||
observation inserted
|
||||
observation already present
|
||||
observation not recorded for purged entity
|
||||
content conflict
|
||||
store failure
|
||||
```
|
||||
|
||||
`persistence_concurrency` borne le nombre d'écritures Store simultanées. Un conflit de contenu est terminal et n'est jamais converti en succès idempotent.
|
||||
|
||||
## Shutdown et faults
|
||||
|
||||
Le shutdown possède une deadline bornée par `shutdown_drain_timeout`.
|
||||
|
||||
Avant publication terminale, le supervisor :
|
||||
|
||||
- arrête les nouvelles admissions ;
|
||||
- signale le stop aux sources privées ;
|
||||
- draine le travail déjà admis tant que la deadline le permet ;
|
||||
- récolte les persistences et sources possédées ;
|
||||
- en cas de timeout, abort les tâches restantes puis les rejoint avant le terminal.
|
||||
|
||||
Les codes d'erreur publics du Worker sont :
|
||||
|
||||
```text
|
||||
worker_raw_transaction_ingest.settings_invalid
|
||||
worker_raw_transaction_ingest.runtime_invalid
|
||||
worker_raw_transaction_ingest.store_failed
|
||||
worker_raw_transaction_ingest.content_conflict
|
||||
worker_raw_transaction_ingest.counter_exhausted
|
||||
worker_raw_transaction_ingest.source_failed
|
||||
worker_raw_transaction_ingest.drain_timeout
|
||||
```
|
||||
|
||||
Les diagnostics ne recopient pas de payload RAW, URL, credential, signature hostile ou texte backend/provider arbitraire.
|
||||
|
||||
## Snapshots
|
||||
|
||||
`RawTransactionIngestSnapshotSource` est latest-value. Les listeners peuvent rater des états intermédiaires mais obtiennent toujours une valeur complète et monotone par `WorkerSnapshotSequence`.
|
||||
|
||||
Le snapshot concret expose notamment :
|
||||
|
||||
```text
|
||||
lifecycle / health / activity
|
||||
admission_queue_capacity / admission_queue_depth
|
||||
persistence_concurrency / in_flight_persistence
|
||||
admitted_total / canonicalized_total / persisted_total
|
||||
entity_inserted_total / entity_already_present_total / entity_skipped_purged_total
|
||||
observation_inserted_total / observation_already_present_total
|
||||
content_conflict_total / store_failure_total / source_failure_total
|
||||
backpressure_wait_total
|
||||
```
|
||||
|
||||
Les compteurs ne wrapent jamais silencieusement.
|
||||
|
||||
## Dépendances
|
||||
|
||||
Les dépendances normales sont exactement :
|
||||
|
||||
```text
|
||||
ksp-core-lib
|
||||
ksp-logging-lib
|
||||
ksp-raw-transaction-lib
|
||||
ksp-store-lib (default-features = false)
|
||||
ksp-worker-api
|
||||
sha2
|
||||
tokio (macros, rt, sync, time)
|
||||
```
|
||||
|
||||
La crate ne dépend pas de Config, Job, `ksp-store-api` directement, backend Store concret, Transport, Tauri ou SDK provider.
|
||||
|
||||
## Hors périmètre de la fondation source-neutral
|
||||
|
||||
Cette surface ne possède pas encore :
|
||||
|
||||
- adapter HTTP/WS/Yellowstone productif ;
|
||||
- sélection Config de sources/endpoints/credentials ;
|
||||
- discovery/hydration/replay de continuité live ;
|
||||
- hot reconfiguration de listeners/sources ;
|
||||
- application Desk ou process autonome ;
|
||||
- campagne historique/backfill ;
|
||||
- décodage STRUCTURAL/DECODED/DOMAIN.
|
||||
|
||||
Ces extensions doivent conserver la séparation avec `ksp-job-backfill-lib` et réutiliser les mêmes contrats RAW/Store.
|
||||
|
||||
## Documentation
|
||||
|
||||
- [`USAGE.md`](USAGE.md) — utilisation de la façade publique actuelle ;
|
||||
- [`../ksp-worker-api/README.md`](../ksp-worker-api/README.md) — contrats Worker génériques ;
|
||||
- [`../ksp-raw-transaction-lib/README.md`](../ksp-raw-transaction-lib/README.md) — canonicalisation RAW commune ;
|
||||
- [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) — séparation Worker/Job ;
|
||||
- [`../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md`](../../docs/architecture/011-RAW_TRANSACTION_ACQUISITION.md) — architecture d'acquisition RawTransaction.
|
||||
Reference in New Issue
Block a user