68 lines
3.3 KiB
Markdown
68 lines
3.3 KiB
Markdown
<!-- file: crates/ksp-worker-api/README.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# ksp-worker-api
|
|
|
|
`ksp-worker-api` fournit les contrats passifs et runtime-neutral communs aux services continus KSP.
|
|
|
|
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é :
|
|
|
|
```text
|
|
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.
|
|
|
|
## Restart et contrôle
|
|
|
|
La crate ne possède aucun `restart()`, scheduler, retry/backoff, process manager ou handle runtime générique. Un lifecycle/source terminal n'est jamais réanimé ni rebinding vers une nouvelle exécution. La recréation et la supervision appartiennent au caller ou à une couche de contrôle supérieure.
|
|
|
|
## Firewall
|
|
|
|
La dépendance normale est volontairement minimale :
|
|
|
|
```text
|
|
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`](USAGE.md) — utilisation durable des contrats Worker ;
|
|
- [`../../docs/architecture/003-COMPONENT_CONTRACTS.md`](../../docs/architecture/003-COMPONENT_CONTRACTS.md) — contrats de composants ;
|
|
- [`../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md`](../../docs/architecture/009-ACQUISITION_WORKERS_AND_JOBS.md) — séparation Worker/Job et ownership d'acquisition.
|