aion_core/
describe.rs

1//! Describe-workflow response projection.
2//!
3//! The ops console's `POST /workflows/describe` read consumes exactly this shape:
4//! a workflow [`WorkflowSummary`] projection plus the run's event [`Event`]
5//! history as plain JSON. Defining it here lets the same type be exported to
6//! TypeScript (so the generated bindings match the wire by construction) and be
7//! produced directly by the HTTP handler at the transport boundary.
8
9use chrono::{DateTime, Utc};
10use serde::{Deserialize, Serialize};
11
12use crate::{ActivityId, Event, RunId, WorkflowSummary};
13
14/// Response to a describe-workflow request.
15///
16/// `history` is the run's events as plain serialized [`Event`] values (never a
17/// protobuf-derived envelope), so the ops console decodes each entry directly.
18/// When `include_history` is false the server returns an empty `history`.
19///
20/// `unserved` is computed independently of `include_history`: it is the answer
21/// to "can anything still advance this run", and an operator who asked for the
22/// summary alone still needs it.
23#[derive(Serialize, Deserialize, ts_rs::TS, Clone, Debug, PartialEq)]
24pub struct DescribeWorkflowResponse {
25    /// Workflow summary projected from authoritative history, when the workflow
26    /// exists.
27    pub summary: Option<WorkflowSummary>,
28    /// The run's event history as plain serialized events.
29    pub history: Vec<Event>,
30    /// Every activity this run's history records as dispatched and unterminated
31    /// that the fleet cannot currently serve.
32    ///
33    /// EMPTY is the healthy answer, and it is the only healthy answer: an
34    /// activity a live compatible worker could take is never listed here. A
35    /// non-empty list is the difference between "a worker is working on it" and
36    /// "it is parked with nobody to take it", which the projected
37    /// [`crate::WorkflowStatus`] alone cannot express — `Running` covers both.
38    pub unserved: Vec<UnservedActivity>,
39    /// Every generation boundary in this workflow's WHOLE history, ascending —
40    /// one entry per `WorkflowStarted`.
41    ///
42    /// This is the answer to "which run does the event at sequence `n` belong
43    /// to": the last boundary at or before `n`. It is stated by the server
44    /// because only the server holds the whole history, and a reader that
45    /// derives it from a window can only be right when the window happens to
46    /// contain the boundary.
47    ///
48    /// 🔴 THIS EXISTS BECAUSE DERIVING IT CLIENT-SIDE FAILS SILENTLY AND
49    /// TOTALLY. The ops console scanned its loaded window (500 events) for
50    /// `WorkflowStarted`; on any workflow longer than one window the boundary is
51    /// never in it, so every attempt row rendered "run unknown" — an accurate
52    /// admission of ignorance on every row, which trains an operator to ignore
53    /// the column. Computed from the same history the summary is projected
54    /// from, so it costs no additional read and cannot disagree with it.
55    pub generations: Vec<RunGeneration>,
56}
57
58/// One generation boundary: the sequence at which a `WorkflowStarted` opened
59/// `run_id`.
60///
61/// Only `WorkflowStarted` opens a generation. `WorkflowReopened` also carries a
62/// `run_id`, but it names the run it REOPENS rather than beginning a new one, so
63/// treating it as a boundary would state the same fact twice and would misread a
64/// reopen that arrives out of order.
65#[derive(Serialize, Deserialize, ts_rs::TS, Clone, Debug, PartialEq, Eq)]
66pub struct RunGeneration {
67    /// Workflow sequence of the `WorkflowStarted` that opened this run.
68    pub seq: u64,
69    /// The run that sequence opened.
70    pub run_id: RunId,
71}
72
73/// One in-flight activity whose recorded dispatch address is not being served.
74///
75/// The activity's identity, address, and dispatch instant come from the run's
76/// own recorded history; the verdict and the counts come from the live
77/// connected-worker fleet at read time. Both halves are named so an operator can
78/// see which is which.
79#[derive(Serialize, Deserialize, ts_rs::TS, Clone, Debug, PartialEq, Eq)]
80pub struct UnservedActivity {
81    /// Activity ordinal recorded in history.
82    pub activity_id: ActivityId,
83    /// Activity type the dispatch needs served.
84    pub activity_type: String,
85    /// Task queue the dispatch was recorded against.
86    pub task_queue: String,
87    /// Node affinity recorded on the dispatch, if any.
88    pub node: Option<String>,
89    /// One-based delivery attempt recorded on the `ActivityStarted`.
90    pub attempt: u32,
91    /// When the engine recorded the dispatch — NOT when a worker took it, which
92    /// is precisely the thing that never happened.
93    pub dispatched_at: DateTime<Utc>,
94    /// Canonical queue-service reason (`NO_QUEUE_DECLARATION`,
95    /// `NO_LIVE_POLLERS`, `POLLERS_INCOMPATIBLE`), in the same vocabulary the
96    /// dispatch refusals and the server logs use.
97    pub reason: String,
98    /// One sentence naming what an operator has to fix.
99    pub detail: String,
100    /// Workers connected for the `(namespace, task_queue)` pool, whatever they
101    /// serve.
102    pub workers_in_pool: u64,
103    /// Of those, workers advertising this activity type.
104    pub workers_serving_activity: u64,
105    /// Of those, workers that also satisfy the dispatch's node pin.
106    pub compatible_workers: u64,
107    /// Whether THIS server process is currently holding the dispatch in its
108    /// selection wait.
109    ///
110    /// False with a non-empty verdict is its own signal: history says the
111    /// activity is in flight, the fleet cannot serve it, and no selection in
112    /// this process is even waiting for it — the shape a run left behind by a
113    /// restart takes.
114    pub dispatch_parked: bool,
115}
aion_core/describe.rs

aion_core/
describe.rs
