ksp-worker-api

ksp-worker-api fournit les contrats passifs et runtime-neutral communs aux services continus KSP. Elle décrit un Worker observable ; elle n'est ni un runtime de Worker ni une API métier d'acquisition.

La crate possède l'identité logique d'un Worker, son lifecycle continu, une classification minimale de health/activity, l'intention de stop coopératif et un contrat latest-value fixe pour l'observation. Elle ne possède aucun runtime concret, aucune politique de restart, aucun Job, aucun Transport, aucun Store et aucun contrat Solana.

Responsabilités

La façade crate-root expose :

WorkerId et WorkerKindCode, bornés et validés ;
WorkerState, WorkerHealth et WorkerActivity ;
WorkerLifecycle, propriétaire des transitions admises ;
WorkerStopToken, cloneable et idempotent ;
WorkerSnapshotSequence, strictement monotone et sans wrap silencieux ;
WorkerSnapshot, forme commune fixe sans payload métier ;
WorkerSnapshotSource, contrat object-safe de lecture courante et attente d'une valeur plus récente ;
les codes d'erreur Worker et les types Error/Result communs de Core.

Lifecycle

Le lifecycle admis reste explicitement borné :

Created  -> Starting | Stopped
Starting -> Running | Stopping | Faulted(ErrorCode)
Running  -> Stopping | Faulted(ErrorCode)
Stopping -> Stopped | Faulted(ErrorCode)
Stopped  -> terminal
Faulted  -> terminal

Stopped et Faulted sont terminaux et immuables. Une transition invalide retourne ERROR_CODE_WORKER_TRANSITION_INVALID sans modifier l'état source.

Observation latest-value

WorkerSnapshotSource n'impose ni callback, ni queue d'événements, ni runtime async particulier. Un listener lit d'abord current(), mémorise la WorkerSnapshotSequence, puis appelle wait_for_change() s'il doit attendre une valeur plus récente.

Les mises à jour intermédiaires peuvent être coalescées : le contrat porte sur la dernière valeur complète, pas sur la livraison de chaque événement. Le snapshot commun ne contient que l'identité, la séquence, le lifecycle, la health et l'activity.

Stop

WorkerStopToken représente uniquement une intention coopérative partagée. Il ne tue pas une tâche, ne ferme pas un socket et ne décide pas du résultat terminal. Le runtime concret observe cette intention puis pilote WorkerLifecycle selon sa politique de shutdown.

Contrôle runtime et restart

La crate ne possède aucune opération runtime générique start(), stop(), restart(), aucun scheduler, retry/backoff, process manager ou handle d'exécution. WorkerLifecycle expose uniquement les transitions d'état détenues par le producer concret ; WorkerStopToken exprime uniquement une intention coopérative.

Un lifecycle/source terminal n'est jamais réanimé ni rebinding vers une nouvelle exécution. Démarrage, arrêt effectif, drain, join, recréation et supervision appartiennent au Worker concret, au caller ou à une couche de contrôle supérieure.

Firewall

La dépendance normale est volontairement minimale :

ksp-worker-api
    -> ksp-core-lib

La crate ne dépend pas de ksp-job-api, Tokio, Futures, serde, Logging, Config, Interface, Transport, Store, Tauri ou d'un SDK provider.

Documentation

USAGE.md — utilisation durable des contrats Worker ;
../../docs/architecture/003-COMPONENT_CONTRACTS.md — contrats de composants ;
../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md — séparation Worker/Job et ownership d'acquisition.

3.7 KiB Raw Blame History