v0.3.9-pre.008
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/000-README.md -->
|
||||
<!-- version: 11 -->
|
||||
<!-- version: 12 -->
|
||||
|
||||
# Architecture KSP
|
||||
|
||||
@@ -25,8 +25,8 @@ Ils ne remplacent ni `ROADMAP.md`, ni les plans de version, ni les deltas.
|
||||
6. [`006-WIRE_AND_PROGRAM.md`](006-WIRE_AND_PROGRAM.md) — propriété des contrats wire, politique de dépendances codecs/interfaces, API Program ouverte, preparation d'exécution et extensibilité externe ;
|
||||
7. [`007-EXECUTION_AND_POLICY.md`](007-EXECUTION_AND_POLICY.md) — policy multi-checkpoints, orchestration transactionnelle, wallet/transport, retry, approval externe et résultat d'exécution ;
|
||||
8. [`008-DATA_MATERIALIZATION_AND_STORE.md`](008-DATA_MATERIALIZATION_AND_STORE.md) — niveaux durables D1–D4, Materialization, Store PostgreSQL de référence, provenance, idempotence, replay et notifications de données persistées ;
|
||||
9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — pipelines spécialisés, workers live, jobs de backfill/replay, backlog, claim/lease, reprise, concurrence et mécanisme de notification de référence ;
|
||||
9. [`009-ACQUISITION_WORKERS_AND_JOBS.md`](009-ACQUISITION_WORKERS_AND_JOBS.md) — séparation durable pipelines/workers/jobs, Worker API générique, producteurs RAW indépendants, reprise, concurrence et frontières de composition ;
|
||||
10. [`010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md`](010-APPS_SERVICES_SCENARIOS_AND_CONTROL.md) — apps spécialisées, workers autonomes et need-driven, control plane, scenarios réutilisables, demos desktop et frontières IPC/orchestration.
|
||||
11. [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md) — taxonomie durable d'acquisition `RawTransaction`, audits datés des voies Solana/providers, convergence Store et handoff Worker/Backfill.
|
||||
11. [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md) — synthèse Store-centrique des sources/capabilities `RawTransaction`, matrices providers/réseaux/preuves et handoffs indépendants Worker live / Backfill historique.
|
||||
|
||||
`004-COMPONENT_INVENTORY.md` et `005-DEPENDENCY_GRAPH.md` sont maintenus ensemble : une évolution du graphe qui change le propriétaire d'une responsabilité doit corriger l'inventaire au lieu de laisser deux descriptions contradictoires.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<!-- file: docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md -->
|
||||
<!-- version: 13 -->
|
||||
<!-- version: 14 -->
|
||||
|
||||
# Acquisition, workers, jobs et pipelines spécialisés
|
||||
|
||||
@@ -55,9 +55,7 @@ persistence D1 RAW
|
||||
notification after commit
|
||||
```
|
||||
|
||||
Une crate spécialisée `ksp-pipeline-raw-ingestion-lib` peut être introduite lorsque la réutilisation worker + job le justifie réellement.
|
||||
|
||||
Elle ne choisit pas le provider réseau et ne pilote pas le range historique.
|
||||
La canonicalisation `RawTransaction` réutilisable entre producteurs est désormais attribuée à une lower-layer source-neutral dédiée, `ksp-raw-transaction-lib`, à matérialiser avec le Worker RAW. Elle possède uniquement la normalisation/canonicalisation commune et la construction des modèles RAW/provenance ; elle ne possède ni lifecycle Worker/Job, ni provider, ni routing réseau, ni campagne historique.
|
||||
|
||||
### `ksp-job-backfill-lib`
|
||||
|
||||
@@ -136,15 +134,15 @@ 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.
|
||||
- **spécialisée** : une source live, une voie d'hydration et une voie de continuité/gap repair du run 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`
|
||||
#### Résultat de l'audit `0.3.9`
|
||||
|
||||
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 exhaustif est synthétisé dans [`011-RAW_TRANSACTION_ACQUISITION.md`](011-RAW_TRANSACTION_ACQUISITION.md). Il confirme qu'un besoin d'acquisition Solana/provider ne remonte pas dans `ksp-worker-api` : le contrat générique reste fermé et le futur Worker concret porte ses propres capabilities de sources.
|
||||
|
||||
L'audit doit au minimum comparer :
|
||||
Les familles admises par la synthèse couvrent notamment :
|
||||
|
||||
```text
|
||||
HTTP getSignaturesForAddress + getTransaction
|
||||
@@ -161,7 +159,7 @@ 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.
|
||||
La présence d'une voie dans l'architecture signifie qu'elle doit pouvoir être représentée lorsque son usage est pertinent ; son implémentation, son accessibilité commerciale et sa preuve live restent des dimensions séparées. Une même famille protocolaire peut servir au Worker, au Job ou aux deux selon l'intention, sans créer de relation entre ces producteurs.
|
||||
|
||||
Pour chaque voie, l'audit couvre au minimum :
|
||||
|
||||
@@ -343,26 +341,24 @@ Un satellite protocolaire reste avec son groupe : Meteora vaults avec Meteora, P
|
||||
|
||||
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 :
|
||||
Contrats communs actuels :
|
||||
|
||||
```text
|
||||
WorkerId
|
||||
WorkerDescriptor
|
||||
WorkerKindCode
|
||||
WorkerState
|
||||
WorkerHealth
|
||||
WorkerCapabilities
|
||||
WorkerActivity
|
||||
WorkerLifecycle
|
||||
WorkerStopToken
|
||||
WorkerSnapshotSequence
|
||||
WorkerSnapshot
|
||||
WorkerSnapshotSource
|
||||
```
|
||||
|
||||
Opérations minimales candidates :
|
||||
Le snapshot commun est fixe et ne porte aucun payload métier. `WorkerSnapshotSource` suit une sémantique latest-value object-safe. `WorkerStopToken` exprime une intention coopérative partagée.
|
||||
|
||||
```text
|
||||
start
|
||||
stop
|
||||
status
|
||||
health
|
||||
```
|
||||
|
||||
Une capability comme `reconfigure` n'est pas imposée à tous les workers.
|
||||
La crate n'expose aucune opération runtime universelle `start`, `stop`, `restart` ou `reconfigure`. Le Worker concret possède son runtime et traduit ses opérations de contrôle en transitions `WorkerLifecycle` et snapshots communs.
|
||||
|
||||
## Job API
|
||||
|
||||
@@ -458,6 +454,8 @@ Les événements utiles comprennent notamment :
|
||||
|
||||
### RAW backfill
|
||||
|
||||
État actuel avant extraction de la normalisation commune :
|
||||
|
||||
```text
|
||||
ksp-job-backfill-lib
|
||||
-> ksp-job-api
|
||||
@@ -466,15 +464,26 @@ ksp-job-backfill-lib
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-store-lib # façade Store ; default-features=false côté Job
|
||||
-> futures-util/tokio # runtime privé de Backfill
|
||||
-> serde_json/sha2 # RAW v1 canonique + digest
|
||||
-> serde_json/sha2 # RAW v1 canonique + digest actuellement locaux
|
||||
```
|
||||
|
||||
Cible après matérialisation de la lower-layer commune :
|
||||
|
||||
```text
|
||||
ksp-job-backfill-lib
|
||||
-> ksp-raw-transaction-lib
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
Le Job conserve seul ses scopes, campagnes, checkpoints et lifecycle.
|
||||
|
||||
### RAW worker
|
||||
|
||||
```text
|
||||
ksp-worker-raw-transaction-ingest-lib
|
||||
-> ksp-worker-api
|
||||
-> ksp-onchain-transport-lib
|
||||
-> ksp-raw-transaction-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
|
||||
@@ -486,6 +495,8 @@ composition supérieure / future Desk
|
||||
-> ksp-store-lib
|
||||
```
|
||||
|
||||
Le Worker conserve seul son runtime continu, ses sources actives, sa continuité et son lifecycle. Il n'appelle ni ne pilote le Job Backfill.
|
||||
|
||||
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.
|
||||
|
||||
### CORE replay/worker
|
||||
@@ -516,8 +527,6 @@ selon les capacités réellement introduites.
|
||||
|
||||
## Questions laissées ouvertes
|
||||
|
||||
- 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` ;
|
||||
- politique d'alias externe `mainnet-beta` à matérialiser uniquement aux frontières qui en ont réellement besoin, sans créer une seconde identité Store ;
|
||||
- modèle de claim/lease PostgreSQL pour les futurs processors continus ;
|
||||
- taille de batch et stratégie backpressure des workers de processing ;
|
||||
|
||||
Reference in New Issue
Block a user