128 lines
5.3 KiB
Markdown
128 lines
5.3 KiB
Markdown
<!-- file: docs/architecture/003-COMPONENT_CONTRACTS.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# Contrats initiaux des composants KSP
|
|
|
|
## Convention API / implémentation
|
|
|
|
Lorsqu'un domaine doit exposer des contrats publics pouvant être implémentés indépendamment, KSP sépare :
|
|
|
|
```text
|
|
ksp-<domain>-api
|
|
ksp-<domain>-lib
|
|
```
|
|
|
|
La crate `ksp-<domain>-api` est techniquement une bibliothèque Rust mais ne porte volontairement pas le suffixe `-lib`. Elle expose principalement des traits, types, enums et contrats publics ; elle peut être consommée par plusieurs implémentations et n'est pas, à elle seule, une implémentation fonctionnelle destinée aux exécutables.
|
|
|
|
La crate `ksp-<domain>-lib` contient l'implémentation officielle KSP correspondante lorsqu'une telle implémentation existe.
|
|
|
|
Cette séparation n'est pas automatique pour tous les domaines. Elle est utilisée lorsqu'une vraie frontière d'extension ou de backend justifie une API indépendante.
|
|
|
|
Premiers couples retenus :
|
|
|
|
- `ksp-program-api` + `ksp-program-lib` ;
|
|
- `ksp-materializer-api` + `ksp-materializer-lib` ;
|
|
- `ksp-store-api` + `ksp-store-lib`.
|
|
|
|
Un unique `ksp-api-lib` monolithique est rejeté.
|
|
|
|
## `ksp-program-api` / `ksp-program-lib`
|
|
|
|
`ksp-program-api` possède les contrats publics communs de décodage/exécution. Une crate séparée doit pouvoir implémenter et tester ces contrats sans dépendre de `ksp-program-lib`.
|
|
|
|
`ksp-program-lib` contient les implémentations officielles intégrées des Program IDs supportés.
|
|
|
|
Le decoder vise toute surface techniquement décodable dont la définition est connue. Le statut `deprecated` concerne l'exécution, pas le décodage. Lorsqu'une définition wire a été réellement écrasée/remplacée sous la même identité et que l'ancienne définition n'est plus distinguable de manière fiable, le decoder utilise la définition la plus récente applicable.
|
|
|
|
L'executor expose les opérations techniquement exécutables connues ; une opération obsolète mais encore identifiable/exécutable peut rester implémentée et être marquée `deprecated`. La politique de sécurité appartient à une couche supérieure.
|
|
|
|
## `ksp-materializer-api` / `ksp-materializer-lib`
|
|
|
|
`ksp-materializer-api` possède les contrats publics/extensibles de matérialisation. Une crate externe doit pouvoir implémenter un materializer contre cette API sans dépendre de `ksp-materializer-lib`.
|
|
|
|
`ksp-materializer-lib` contient les materializers officiels intégrés KSP.
|
|
|
|
## `ksp-store-api` / `ksp-store-lib`
|
|
|
|
`ksp-store-api` possède les contrats backend-agnostic de persistance et d'accès aux données KSP.
|
|
|
|
`ksp-store-lib` contient PostgreSQL comme implémentation officielle de référence : configuration/connexion, migrations, repositories, queries et mécanismes backend nécessaires.
|
|
|
|
Les applications, workers, jobs et materializers consomment les contrats KSP et ne contournent pas le store pour accéder directement au backend.
|
|
|
|
## Notifications de données
|
|
|
|
Une notification de donnée décrit la donnée disponible, pas son producteur.
|
|
|
|
Le même type de donnée doit utiliser le même contrat de notification qu'elle provienne :
|
|
|
|
- de W1 ;
|
|
- d'un job de backfill ;
|
|
- d'un import ;
|
|
- d'une autre source future.
|
|
|
|
`ksp-store-api` est le propriétaire candidat des références/événements canoniques indiquant qu'une donnée persistée est disponible, par exemple conceptuellement `RawDataRef` / `RawDataAvailable`.
|
|
|
|
Le contrat de notification reste distinct du mécanisme de transport concret : channel in-process, PostgreSQL LISTEN/NOTIFY, IPC, broker ou autre mécanisme futur.
|
|
|
|
## Workers
|
|
|
|
Les workers sont des services continus/live. Leurs contrats communs appartiennent à :
|
|
|
|
```text
|
|
ksp-worker-api
|
|
```
|
|
|
|
Cette API ne contient aucun contrat de job.
|
|
|
|
Une future implémentation commune de gouvernance/contrôle des workers peut vivre dans :
|
|
|
|
```text
|
|
ksp-worker-control-lib
|
|
```
|
|
|
|
W1 reste un worker d'acquisition raw live/quasi-live : configuration, transport, persistance raw, reconfiguration à chaud et notification de disponibilité. Il ne décode pas, ne matérialise pas et ne réalise aucun replay/backfill historique.
|
|
|
|
## Jobs
|
|
|
|
Les jobs sont des travaux déclenchés à la demande, suivables et terminables. Leurs contrats communs appartiennent à :
|
|
|
|
```text
|
|
ksp-job-api
|
|
```
|
|
|
|
Cette API ne contient aucun contrat de worker.
|
|
|
|
Les implémentations concrètes utilisent le préfixe `ksp-job-`.
|
|
|
|
Premier candidat retenu :
|
|
|
|
```text
|
|
ksp-job-backfill
|
|
```
|
|
|
|
D'autres jobs pourront être introduits pour metadata, quotes ou autres travaux ponctuels lorsqu'un besoin réel existe.
|
|
|
|
Le contrôle/gouvernance commun des jobs reste séparé du contrôle des workers, même si certaines opérations semblent similaires.
|
|
|
|
## Pipelines
|
|
|
|
KSP ne prévoit pas de `ksp-pipeline-lib` monolithique. Lorsqu'un pipeline réutilisable devient nécessaire, il est introduit séparément avec un périmètre concret et borné.
|
|
|
|
## Demos et scénarios
|
|
|
|
Il n'existe pas de crate monolithique `ksp-scenarios-lib`.
|
|
|
|
Les scénarios sont organisés en crates spécialisées par domaine cohérent, par exemple :
|
|
|
|
```text
|
|
ksp-scenario-memo-lib
|
|
ksp-scenario-token-lib
|
|
ksp-scenario-ata-lib
|
|
ksp-scenario-token-2022-lib
|
|
ksp-scenario-metadata-lib
|
|
ksp-scenario-spm-lib
|
|
```
|
|
|
|
Les metadata d'assets/tokens peuvent regrouper Metaplex Token Metadata et Token-2022 Metadata. Solana Program Metadata reste séparé.
|