taskvisor 0.7.0

In-process Tokio task supervisor with retries, reliable outcomes, and per-key queue/replace/reject admission
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

//! # Runtime events
//!
//! Events describe what Taskvisor is doing.
//! Use them for logs, metrics, dashboards, alerts, and tests.
//!
//! | Type                                        | Role                                       |
//! |---------------------------------------------|--------------------------------------------|
//! | [`EventKind`]                               | Event classification                       |
//! | [`Event`]                                   | Event payload and metadata                 |
//! | [`BackoffSource`]                           | Why a `BackoffScheduled` event was emitted |
//! | [`RejectionKind`]                           | Machine-readable submission rejection      |
//! | [`TaskOutcomeKind`](crate::TaskOutcomeKind) | Machine-readable final outcome             |
//!
//! ## Events and final outcomes are different
//!
//! Event delivery is best-effort.
//! There are two bounded steps: the shared event bus and each subscriber's own queue.
//! A slow consumer may miss events at either step.
//!
//! ```text
//! runtime action
//!      ├── best-effort ──► event bus ──► subscriber queue ──► Subscribe
//!      └── reliable terminal result ────────────────────────► TaskWaiter
//! ```
//!
//! Use events for observation.
//! Do not use them as the only proof that work finished.
//! If you need one final result, use an `*_and_watch` method and await the returned [`TaskWaiter`](crate::TaskWaiter).
//!
//! ## Common task flow
//!
//! ```text
//! Add:
//!   TaskAddRequested ──► TaskAdded ──► AttemptStarting
//!                   └──► TaskAddFailed
//!
//! Attempt:
//!   AttemptStarting ──► AttemptSucceeded
//!              ├──► AttemptCanceled ──► TaskFinished(Canceled)
//!              ├──► AttemptFailed
//!              └──► AttemptTimedOut
//!
//! Successful attempt:
//!   AttemptSucceeded ──► TaskFinished(Completed)
//!              ├──► BackoffScheduled(Success) ──► AttemptStarting
//!              └──► AttemptStarting (Always without an interval)
//!
//! Retryable failure or configured timeout:
//!   AttemptFailed | AttemptTimedOut ──► BackoffScheduled(Failure) ──► AttemptStarting
//!                                  └──► TaskFinished(Failed)
//!
//! Fatal failure:
//!   AttemptFailed ──► TaskFinished(Fatal)
//!
//! Registry cleanup:
//!   [optional TaskRemoveRequested] ──► TaskFinished ──► TaskRemoved
//!
//! Queued controller removal (feature `controller`):
//!   TaskRemoveRequested ──► ControllerRejected(RemovedFromQueue)
//!
//! Shutdown:
//!   ShutdownRequested ──► AllStoppedWithinGrace | GraceExceeded
//! ```
//!
//! [`TaskRemoved`](EventKind::TaskRemoved) confirms registry cleanup.
//! It is sent after the managed task runner has been joined or cleaned up.
//!
//! ## Read the Stream Safely
//!
//! - [`AttemptFailed`](EventKind::AttemptFailed) describes one attempt.
//!   The task may retry. [`TaskFinished`](EventKind::TaskFinished) means that a registered task has reached its final [`TaskOutcomeKind`](crate::TaskOutcomeKind).
//!   Cancellation while waiting for a permit or backoff can produce `TaskFinished(Canceled)` without an `AttemptCanceled` event.
//! - [`Event::seq`] is process-local construction order.
//!   It can help sort events and detect gaps, but it is not a causal clock.
//! - Use [`EventKind::as_label`] for a stable telemetry label.
//!   Treat free-form [`Event::reason`] text as diagnostic, never as schema.
//!   Use [`TaskOutcomeKind`](crate::TaskOutcomeKind) and [`RejectionKind`] for machine decisions.
//! - Use [`RejectionKind`] for machine-readable handling of `TaskAddFailed` and `ControllerRejected`.
//!   Rejected work never enters the registry, so it has no `TaskFinished` or `TaskRemoved` event.
//!
//! ## Subscribers
//!
//! Implement [`Subscribe`](crate::Subscribe) to consume events.
//! With the `tracing` feature, `TracingBridge` sends them to `tracing`.
//! With the `logging` feature, `LogWriter` prints simple development logs.

mod event;
pub use event::{BackoffSource, Event, EventKind, RejectionKind};

mod bus;
pub(crate) use bus::Bus;