5.3 KiB
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 :
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 à :
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 :
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 à :
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 :
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 :
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é.