142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
<!-- file: crates/ksp-job-api/USAGE.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Utilisation de ksp-job-api
|
|
|
|
Cette page décrit la façade publique durable de `ksp-job-api`. Les consumers utilisent uniquement les exports du crate-root.
|
|
|
|
## Construire une identité de job
|
|
|
|
```rust
|
|
fn job_identity() -> ksp_job_api::Result<(ksp_job_api::JobId, ksp_job_api::JobKindCode)> {
|
|
let id = match ksp_job_api::JobId::new("raw-backfill-mainnet-0001") {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
let kind = match ksp_job_api::JobKindCode::new("raw_transaction_backfill") {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
return std::result::Result::Ok((id, kind));
|
|
}
|
|
```
|
|
|
|
`JobId` identifie un job logique et ses reprises contrôlées. `JobKindCode` identifie une famille de jobs. Les deux sont bornés et utilisent un alphabet sûr ; leur `Debug` n'est pas une surface destinée à transporter un payload métier.
|
|
|
|
## Piloter un lifecycle passif
|
|
|
|
```rust
|
|
fn lifecycle(id: ksp_job_api::JobId, kind: ksp_job_api::JobKindCode) -> ksp_job_api::Result<ksp_job_api::JobLifecycle> {
|
|
let mut lifecycle = ksp_job_api::JobLifecycle::new(id, kind);
|
|
if let std::result::Result::Err(error) = lifecycle.start() {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
if let std::result::Result::Err(error) = lifecycle.complete(ksp_job_api::JobCompletion::Complete) {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
return std::result::Result::Ok(lifecycle);
|
|
}
|
|
```
|
|
|
|
Le producer ne doit pas forcer un état directement. Il utilise les opérations de `JobLifecycle`, qui refusent les transitions hors matrice.
|
|
|
|
Pour une annulation observée pendant l'exécution :
|
|
|
|
```rust
|
|
if let std::result::Result::Err(error) = lifecycle.mark_cancelling() {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
if let std::result::Result::Err(error) = lifecycle.mark_cancelled() {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
```
|
|
|
|
## Partager une intention d'annulation
|
|
|
|
```rust
|
|
let token = ksp_job_api::JobCancellationToken::new();
|
|
let listener = token.clone();
|
|
|
|
assert!(!listener.is_cancellation_requested());
|
|
assert!(token.request_cancellation());
|
|
assert!(listener.is_cancellation_requested());
|
|
assert!(!token.request_cancellation());
|
|
```
|
|
|
|
Le premier appel qui change l'état retourne `true`. Les demandes suivantes sont idempotentes et retournent `false`.
|
|
|
|
Le token ne doit pas être interprété comme une primitive de kill : le runtime concret décide où l'annulation peut interrompre l'admission ou une attente et quelles opérations déjà engagées doivent être drainées.
|
|
|
|
## Publier une valeur latest-value
|
|
|
|
Un producer concret peut construire une notification complète :
|
|
|
|
```rust
|
|
#[derive(Clone)]
|
|
struct Snapshot {
|
|
completed: usize,
|
|
}
|
|
|
|
let id = ksp_job_api::JobId::new("job-0001")?;
|
|
let kind = ksp_job_api::JobKindCode::new("example")?;
|
|
let sequence = ksp_job_api::JobNotificationSequence::initial();
|
|
let notification = ksp_job_api::JobNotification::new(
|
|
id,
|
|
kind,
|
|
sequence,
|
|
ksp_job_api::JobState::Running,
|
|
Snapshot { completed: 0 },
|
|
);
|
|
|
|
assert_eq!(notification.sequence().value(), 0);
|
|
assert_eq!(notification.state(), ksp_job_api::JobState::Running);
|
|
```
|
|
|
|
Le `Debug` de `JobNotification<S>` masque volontairement le snapshot. Le type concret `S` doit lui-même rester sûr à exposer lorsque le consumer accède explicitement à `snapshot()`.
|
|
|
|
## Implémenter une source de snapshots
|
|
|
|
Une implémentation concrète possède son runtime et expose seulement le contrat `JobSnapshotSource` :
|
|
|
|
```rust
|
|
async fn observe<S>(source: &S)
|
|
where
|
|
S: ksp_job_api::JobSnapshotSource,
|
|
{
|
|
let current = source.current();
|
|
let observed = current.sequence();
|
|
let newer = source.wait_for_change(observed).await;
|
|
assert!(newer.sequence().is_after(observed));
|
|
}
|
|
```
|
|
|
|
`wait_for_change` retourne la dernière valeur complète connue après coalescence éventuelle. Un consumer ne doit donc pas supposer qu'il recevra chaque mise à jour intermédiaire.
|
|
|
|
## Faire avancer une séquence
|
|
|
|
```rust
|
|
let first = ksp_job_api::JobNotificationSequence::initial();
|
|
let second = match first.next() {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
assert!(second.is_after(first));
|
|
```
|
|
|
|
L'épuisement de `u64` est une erreur explicite ; la séquence ne wrappe jamais silencieusement.
|
|
|
|
## Frontières à respecter
|
|
|
|
Ne pas ajouter à `ksp-job-api` :
|
|
|
|
```text
|
|
Tokio/Futures runtime concret
|
|
Transport ou Store
|
|
Config/Logging
|
|
DTO métier d'un job précis
|
|
scheduler, worker ou control plane
|
|
persistence de checkpoint
|
|
```
|
|
|
|
Ces responsabilités appartiennent aux crates concrètes et à la composition supérieure.
|