v0.3.8-pre.013-fix.001
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -92,35 +92,161 @@ Le job :
|
||||
|
||||
Le caller desktop spécialisé actuel est `ksp-app-backfill-desk`. Il compose Config, le pool HTTP et Store, puis remet ces ressources au runtime Backfill. Il peut retenir le checkpoint terminal uniquement en mémoire Rust pour un Resume in-session ; cette rétention applicative ne transforme pas le checkpoint en garantie de reprise durable après redémarrage.
|
||||
|
||||
### Worker RAW live
|
||||
Cette verticale `0.3.6`/`0.3.7` est **la première stratégie de backfill**, pas la définition générale du backfill KSP. Son discovery `getSignaturesForAddress` + hydration `getTransaction` est HTTP parce que cette méthode a été choisie pour le premier vertical slice. Après stabilisation du worker live et de sa Desk, `0.3.12` doit réauditer `ksp-job-backfill-lib` et `ksp-app-backfill-desk` pour intégrer les autres stratégies historiques/catch-up pertinentes identifiées par l'audit RAW Transaction de `0.3.9`.
|
||||
|
||||
Le worker live futur :
|
||||
### Worker RAW Transaction live
|
||||
|
||||
Le premier worker concret de la couche RAW est retenu sous le nom :
|
||||
|
||||
```text
|
||||
subscriptions/fetch live
|
||||
|
|
||||
v
|
||||
ksp-onchain-transport-lib
|
||||
|
|
||||
v
|
||||
RAW ingestion
|
||||
|
|
||||
v
|
||||
D1 RAW
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
```
|
||||
|
||||
Il ne décode pas et ne matérialise pas.
|
||||
Sa responsabilité est l'acquisition **continue** de `RawTransaction` puis la persistance via `ksp-store-lib`. Il ne décode pas de Program, ne possède aucun SQL/backend physique et ne fait pas de la source réseau une partie de l'identité canonique de transaction.
|
||||
|
||||
Sa hot reconfiguration peut concerner selon le transport :
|
||||
Le modèle cible n'est pas :
|
||||
|
||||
- endpoints/providers ;
|
||||
- rôles ;
|
||||
- accounts/program IDs suivis ;
|
||||
- types de subscriptions ;
|
||||
- filtres ;
|
||||
- limites/concurrence.
|
||||
```text
|
||||
worker -> un transport unique
|
||||
```
|
||||
|
||||
La configuration desired/effective reste distinguée lorsqu'une reconfiguration est asynchrone.
|
||||
mais :
|
||||
|
||||
```text
|
||||
source(s) / stratégie(s) d'acquisition
|
||||
|
|
||||
+--> discovery de références
|
||||
| |
|
||||
| +--> hydration éventuelle
|
||||
|
|
||||
+--> transaction complète directe
|
||||
|
|
||||
v
|
||||
normalisation RawTransaction commune
|
||||
|
|
||||
+--> RawTransaction canonique
|
||||
+--> RawTransactionObservation par acquisition utile
|
||||
|
|
||||
v
|
||||
ksp-store-lib
|
||||
```
|
||||
|
||||
Une stratégie peut donc être :
|
||||
|
||||
- **alternative** : une source choisie à la place d'une autre ;
|
||||
- **complémentaire** : une source découvre une signature/slot et une autre hydrate la transaction complète ;
|
||||
- **redondante** : plusieurs providers/transports observent la même transaction et produisent des observations distinctes ;
|
||||
- **spécialisée** : une source live, une source de catch-up/gap repair et une source historique peuvent coexister avec des responsabilités différentes.
|
||||
|
||||
Le worker ne doit pas être réduit à un enum superficiel `Http | WebSocket | Grpc`. La configuration/runtime doit exprimer les **capacités et rôles d'acquisition réellement nécessaires** : discovery, hydration, direct full transaction, live, replay/catch-up, gap repair, filtre, finality/commitment, reprise et limites.
|
||||
|
||||
#### Audit obligatoire avant `0.3.10`
|
||||
|
||||
La fin de `0.3.9`, après fermeture fonctionnelle de `ksp-worker-api`, produit un audit exhaustif servant d'entrée architecturale à `0.3.10`. Cet audit ne doit pas déformer Worker API pour le premier consumer : un besoin découvert n'est remonté dans `ksp-worker-api` que s'il est réellement générique à des services continus non Solana.
|
||||
|
||||
L'audit doit au minimum comparer :
|
||||
|
||||
```text
|
||||
HTTP getSignaturesForAddress + getTransaction
|
||||
HTTP getBlocks/getBlock et autres stratégies slot/block pertinentes
|
||||
WS logsSubscribe + hydration HTTP éventuelle
|
||||
WS signatureSubscribe + hydration éventuelle
|
||||
WS blockSubscribe lorsqu'une source/provider l'offre réellement
|
||||
extensions transactionnelles provider-specific, dont Helius transactionSubscribe
|
||||
Yellowstone transactions
|
||||
Yellowstone transaction_status
|
||||
Yellowstone blocks
|
||||
Yellowstone block_meta
|
||||
replay/from_slot/catch-up lorsqu'une implémentation/provider le permet
|
||||
combinaisons multi-provider et multi-transport
|
||||
```
|
||||
|
||||
La liste n'est pas une promesse d'implémentation. Chaque voie est évaluée avant admission et peut être rejetée, réservée au backfill, réservée au live ou nécessiter une adaptation Transport/Config.
|
||||
|
||||
Pour chaque voie, l'audit couvre au minimum :
|
||||
|
||||
| Dimension | Question à trancher |
|
||||
|----------------------|-----------------------------------------------------------------------|
|
||||
| transport/protocole | HTTP, WS standard, extension provider, Yellowstone ou autre ? |
|
||||
| réseau | Mainnet, Devnet, Testnet réellement disponibles et utiles ? |
|
||||
| disponibilité | gratuite/payante/provider-dependent ; limites actuelles à réauditer ? |
|
||||
| temporalité | live, catch-up, historique, replay récent ? |
|
||||
| discovery | comment la transaction est-elle découverte ? |
|
||||
| transaction complète | reçue directement ou hydration nécessaire ? |
|
||||
| filtres | programmes/comptes/signatures/slots/status et bornes ? |
|
||||
| ordering/duplicates | quelles garanties existent et quelles duplications sont normales ? |
|
||||
| reconnect/replay | que se passe-t-il après coupure ? |
|
||||
| gap recovery | quelle autre stratégie répare les trous ? |
|
||||
| backpressure | quelles limites et comportements si le consumer ralentit ? |
|
||||
| commitment/finality | quels niveaux sont disponibles et comment les interpréter ? |
|
||||
| provenance | quelles métadonnées sûres alimentent `RawTransactionObservation` ? |
|
||||
| limites/quota | RPS, connexions, subscriptions, credits ou autres limites actuelles ? |
|
||||
| gap KSP Transport | surface déjà disponible ou adaptation nécessaire en `0.3.10` ? |
|
||||
| gap KSP Config | profil/secret/capability déjà disponible ou adaptation nécessaire ? |
|
||||
| usage | continuous ingest, gap repair, historical backfill ou combinaison ? |
|
||||
|
||||
#### Helius et Config
|
||||
|
||||
L'audit de `0.3.9` doit réexaminer les offres et documentations Helius **courantes au moment du travail**. Les tiers, quotas et capabilities provider ne sont pas figés par ce document.
|
||||
|
||||
Décisions déjà acquises :
|
||||
|
||||
```text
|
||||
KSP_SECRET_HELIUS_API_KEY existe déjà côté environnement KSP
|
||||
Helius HTTP et WS Mainnet/Devnet doivent être considérés comme futures sources candidates
|
||||
les profils/endpoints réellement nécessaires sont ajoutés seulement en 0.3.10
|
||||
aucune URL Helius nouvelle n'est ajoutée pendant 0.3.8
|
||||
Config reste l'unique propriétaire des secrets et de leur résolution
|
||||
les fonctionnalités standard et advanced/enhanced sont capability-gated, jamais supposées par le seul nom du provider
|
||||
```
|
||||
|
||||
L'archive kbot3 doit être relue uniquement comme **référence fonctionnelle** pour identifier les méthodes/sources déjà exploitées ou envisagées. Aucun code, DTO, client, URL hardcodée, modèle Config ou dépendance kbot3 n'est repris comme source d'implémentation.
|
||||
|
||||
#### `mainnet` et `mainnet-beta`
|
||||
|
||||
La terminologie réseau est un audit explicite avant toute modification. Les sources Solana actuelles utilisent de plus en plus `mainnet` alors que plusieurs surfaces/outils historiques conservent `mainnet-beta`.
|
||||
|
||||
KSP ne doit jamais créer deux identités persistées pour le même cluster par simple renommage. L'audit doit donc inventorier :
|
||||
|
||||
```text
|
||||
RawNetworkId et valeurs persistées Store
|
||||
Config profile ids / cluster labels
|
||||
Transport descriptors et provider metadata
|
||||
CLI/external aliases réellement acceptés
|
||||
compatibilité des checkpoints/fingerprints existants
|
||||
migration ou canonicalisation éventuellement nécessaire
|
||||
```
|
||||
|
||||
Aucun renommage de données persistées ou de profil n'est effectué en `0.3.8`. `0.3.10` ne l'implémente que si l'audit `0.3.9` établit une stratégie de compatibilité sûre.
|
||||
|
||||
#### Idempotence et multi-source
|
||||
|
||||
La convergence multi-source réutilise les invariants Store acquis :
|
||||
|
||||
```text
|
||||
identité canonique RawTransaction = réseau logique + signature
|
||||
source/provider/protocole != identité canonique
|
||||
acquisitions distinctes -> observations/provenances distinctes lorsque pertinentes
|
||||
même contenu canonique -> idempotence
|
||||
même identité avec contenu incompatible -> conflit explicite, jamais écrasement silencieux
|
||||
```
|
||||
|
||||
La déduplication ne doit donc pas supprimer la provenance utile sous prétexte que la transaction canonique existe déjà.
|
||||
|
||||
#### Rôle de `ksp-app-raw-transaction-ingest-desk`
|
||||
|
||||
La Desk prévue après le worker choisit et supervise les **source(s)/méthode(s)** offertes par la composition réellement disponible. Elle ne possède pas la logique de discovery, hydration, déduplication, replay ou persistance.
|
||||
|
||||
Elle doit pouvoir représenter selon les capacités finales de `0.3.10` :
|
||||
|
||||
```text
|
||||
une source unique
|
||||
plusieurs sources redondantes
|
||||
une combinaison discovery + hydration
|
||||
une stratégie live + gap repair
|
||||
```
|
||||
|
||||
Le détail des RAW persistés reste la responsabilité de Store Desk.
|
||||
|
||||
## CORE
|
||||
|
||||
@@ -222,7 +348,9 @@ Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, P
|
||||
|
||||
## Worker API
|
||||
|
||||
`ksp-worker-api` reste une lifecycle API générique pour services continus.
|
||||
`ksp-worker-api` reste une lifecycle API générique pour services continus. Elle est volontairement stabilisée avant l'audit détaillé du premier worker RAW afin de ne pas encoder Solana, Transport, Store ou une source d'acquisition particulière dans son contrat.
|
||||
|
||||
Le pattern latest-value de `ksp-job-api` peut être réutilisé conceptuellement lorsqu'il convient, mais Worker et Job conservent des sémantiques distinctes : un worker est un service continu qui peut rester actif indéfiniment, tandis qu'un job représente un traitement borné/terminable. Une dépendance `ksp-worker-api -> ksp-job-api` n'est pas supposée ; la réutilisation concrète doit être justifiée par un contrat réellement commun.
|
||||
|
||||
Concepts candidats :
|
||||
|
||||
@@ -353,13 +481,18 @@ ksp-job-backfill-lib
|
||||
### RAW worker
|
||||
|
||||
```text
|
||||
ksp-worker-raw-retriever
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
-> ksp-worker-api
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-interface-lib # seulement si un fait passif partagé aide la composition live
|
||||
-> ksp-store-lib # façade Store ; backend sélectionné par feature + Config
|
||||
-> ksp-config-lib
|
||||
-> ksp-interface-lib # seulement si un fait passif partagé aide réellement la composition live
|
||||
-> ksp-store-lib # façade Store ; aucun backend physique direct
|
||||
-> ksp-logging-lib
|
||||
|
||||
composition supérieure / future Desk
|
||||
-> ksp-config-lib
|
||||
-> ksp-worker-raw-transaction-ingest-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
Les événements Interface peuvent servir de signal provider-neutral à la composition live, mais ne constituent jamais le backlog durable. Après crash ou perte d'un événement, la reprise s'appuie sur Store et sur les primitives de replay/hydratation appropriées.
|
||||
@@ -392,9 +525,10 @@ selon les capacités réellement introduites.
|
||||
|
||||
## Questions laissées ouvertes
|
||||
|
||||
- nom final de la crate pipeline RAW si la réutilisation justifie une crate dédiée ;
|
||||
- nom final du worker RAW ;
|
||||
- nom final de la crate pipeline RAW si la réutilisation worker + backfill justifie réellement une crate dédiée ;
|
||||
- taxonomie exacte des stratégies/source capabilities de `ksp-worker-raw-transaction-ingest-lib`, à décider par l'audit de fin `0.3.9` ;
|
||||
- stratégie sûre de canonicalisation/aliasing `mainnet` / `mainnet-beta`, si un changement KSP est réellement nécessaire ;
|
||||
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
|
||||
- taille de batch et stratégie backpressure ;
|
||||
- taille de batch et stratégie backpressure des workers de processing ;
|
||||
- découpage des workers DECODE/SPECIALIZED par groupe lorsque les premiers groupes existent ;
|
||||
- mécanisme IPC des applications de contrôle futures.
|
||||
|
||||
Reference in New Issue
Block a user