journio_core/system_db.rs
1//! System database abstraction — ported from `journio/system_database.go` (5,916 LOC).
2//!
3//! Every persistence operation the engine needs is a method on this trait.
4//! Concrete impls live in `journio-postgres` (tokio-postgres + deadpool, with
5//! LISTEN/NOTIFY) and `journio-sqlite` (sqlx). Keeping the trait in core means the
6//! engine, recovery, queues, scheduler and FFI never import a backend crate.
7//!
8//! This is a **representative subset** of the full surface — expand as each
9//! phase of the port lands. Group methods by the Go file section they mirror.
10
11use async_trait::async_trait;
12use chrono::{DateTime, Utc};
13use std::time::Duration;
14
15use crate::dialect::Dialect;
16use crate::error::JournioResult;
17use crate::types::{
18 ListWorkflowsFilter, QueueConfig, ScheduleStatus, StepRecord, StreamEntry, VersionInfo,
19 WorkflowSchedule, WorkflowStatus, WorkflowStatusType,
20};
21use crate::value::Interchange;
22
23/// Inputs for `SystemDatabase::init_workflow` — ported from the
24/// `insertWorkflowStatusDBInput` / `WorkflowStatus` fields used in
25/// `system_database.go:936`.
26#[derive(Debug, Clone)]
27pub struct InitWorkflow {
28 pub workflow_id: String,
29 pub name: String,
30 pub status: WorkflowStatusType,
31 pub executor_id: String,
32 pub application_version: Option<String>,
33 pub application_id: Option<String>,
34 pub input: Option<Interchange>,
35 pub queue_name: Option<String>,
36 pub deduplication_id: Option<String>,
37 pub priority: i32,
38 pub queue_partition_key: Option<String>,
39 pub timeout: Option<Duration>,
40 pub deadline: Option<DateTime<Utc>>,
41 pub delay_until: Option<DateTime<Utc>>,
42 pub parent_workflow_id: Option<String>,
43 pub class_name: Option<String>,
44 pub config_name: Option<String>,
45 pub serialization: Option<String>,
46 pub authenticated_user: Option<String>,
47 pub assumed_role: Option<String>,
48 pub authenticated_roles: Option<Vec<String>>,
49 /// Bump `recovery_attempts` on conflict (recovery path).
50 pub increment_attempts: bool,
51 /// Mark MAX_RECOVERY_ATTEMPTS_EXCEEDED past this many attempts.
52 pub max_retries: i32,
53}
54
55impl InitWorkflow {
56 /// Convenience for a freshly-enqueued PENDING workflow.
57 pub fn new_pending(
58 workflow_id: impl Into<String>,
59 name: impl Into<String>,
60 executor_id: impl Into<String>,
61 ) -> Self {
62 Self {
63 workflow_id: workflow_id.into(),
64 name: name.into(),
65 status: WorkflowStatusType::Pending,
66 executor_id: executor_id.into(),
67 application_version: None,
68 application_id: None,
69 input: None,
70 queue_name: None,
71 deduplication_id: None,
72 priority: 0,
73 queue_partition_key: None,
74 timeout: None,
75 deadline: None,
76 delay_until: None,
77 parent_workflow_id: None,
78 class_name: None,
79 config_name: None,
80 serialization: None,
81 authenticated_user: None,
82 assumed_role: None,
83 authenticated_roles: None,
84 increment_attempts: false,
85 max_retries: 0,
86 }
87 }
88}
89
90/// Result of `init_workflow` — ported from `insertWorkflowResult`.
91/// The returned `status` reflects the row's *actual* status after the
92/// `ON CONFLICT` upsert (may differ from the input on recovery).
93#[derive(Debug, Clone)]
94pub struct InitWorkflowResult {
95 pub status: WorkflowStatusType,
96 pub attempts: i64,
97 pub name: String,
98 pub queue_name: Option<String>,
99 pub queue_partition_key: Option<String>,
100 pub timeout: Option<Duration>,
101 pub deadline: Option<DateTime<Utc>>,
102}
103
104/// A consumed notification — ported from `recvResult`
105/// (`system_database.go:3378`). Carries the decoded message plus the
106/// serialization name recorded on the notification row (the sender's format).
107#[derive(Debug, Clone)]
108pub struct Notification {
109 pub message: Interchange,
110 pub serialization: Option<String>,
111}
112
113#[derive(Debug, Clone, Default)]
114pub struct ForkWorkflow {
115 pub original_workflow_id: String,
116 pub forked_workflow_id: Option<String>,
117 pub start_step: i32,
118 pub application_version: Option<String>,
119 pub queue_name: Option<String>,
120 pub queue_partition_key: Option<String>,
121}
122
123/// The async persistence seam. All methods are transactional where the Go
124/// counterpart is; the Postgres impl uses `FOR UPDATE SKIP LOCKED` for dequeue.
125#[async_trait]
126pub trait SystemDatabase: Send + Sync {
127 /// Which dialect this backend speaks.
128 fn dialect(&self) -> &dyn Dialect;
129
130 // -- lifecycle ---------------------------------------------------------
131
132 /// Create schema + run any pending migrations (mirrors `runMigrations`).
133 async fn migrate(&self) -> JournioResult<()>;
134
135 /// Boot the background loops: notification listener (LISTEN/NOTIFY or
136 /// polling), queue pollers, etc. Mirrors `systemDB.launch`.
137 async fn launch(&self) -> JournioResult<()>;
138
139 /// Graceful shutdown of background loops.
140 async fn shutdown(&self) -> JournioResult<()>;
141
142 // -- workflow_status ---------------------------------------------------
143
144 /// Insert a workflow_status row (or upsert on ID conflict). Returns the
145 /// *actual* status after upsert — ported from `insertWorkflowStatus`
146 /// (`system_database.go:936`). Surfaces `QueueDeduplicated` on unique
147 /// constraint violation of `(queue_name, deduplication_id)` and
148 /// `ConflictingWorkflow` if name/queue mismatch an existing row.
149 async fn init_workflow(&self, init: InitWorkflow) -> JournioResult<InitWorkflowResult>;
150
151 /// Persist terminal result/error — ported from `recordWorkflowResult`.
152 async fn record_workflow_result(
153 &self,
154 workflow_id: &str,
155 status: WorkflowStatusType,
156 output: Option<&Interchange>,
157 error: Option<&str>,
158 ) -> JournioResult<()>;
159
160 /// Read full status — ported from `getWorkflowStatus`-style single-row
161 /// selects scattered through `system_database.go`.
162 async fn get_workflow_status(&self, workflow_id: &str)
163 -> JournioResult<Option<WorkflowStatus>>;
164
165 /// List workflows (filters optional) — ported from `listWorkflows`
166 /// (`system_database.go:1184`). The `limit`/offset filtering grows as the
167 /// port progresses; for now a simple cap.
168 async fn list_workflows(&self, limit: i64) -> JournioResult<Vec<WorkflowStatus>>;
169
170 /// List workflows with rich filtering and paging — ported from the
171 /// `listWorkflowsOptions` branch of `listWorkflows`
172 /// (`system_database.go:1184`). Backends translate the filter into their
173 /// native parameterization (Postgres `ANY($n)` arrays vs. SQLite
174 /// `QueryBuilder` separated lists).
175 async fn list_workflows_filtered(
176 &self,
177 filter: &ListWorkflowsFilter,
178 ) -> JournioResult<Vec<WorkflowStatus>>;
179
180 /// Cancel the provided workflows, leaving terminal rows untouched.
181 /// Returns the subset of IDs that already existed.
182 async fn cancel_workflows(&self, workflow_ids: &[String]) -> JournioResult<Vec<String>>;
183
184 /// Resume the provided workflows onto `queue_name`, or the internal queue
185 /// if `None`. Returns the subset of IDs that already existed.
186 async fn resume_workflows(
187 &self,
188 workflow_ids: &[String],
189 queue_name: Option<&str>,
190 ) -> JournioResult<Vec<String>>;
191
192 /// Recursively list all descendant workflows of `workflow_id`.
193 async fn get_workflow_children(&self, workflow_id: &str) -> JournioResult<Vec<WorkflowStatus>>;
194
195 /// Fork a workflow by cloning its durable state and enqueueing a new run.
196 async fn fork_workflow(&self, input: ForkWorkflow) -> JournioResult<String>;
197
198 /// Retrieve persisted queue configuration by name.
199 async fn get_queue(&self, queue_name: &str) -> JournioResult<Option<QueueConfig>>;
200
201 /// Create or replace persisted queue configuration.
202 async fn upsert_queue(&self, queue: &QueueConfig) -> JournioResult<()>;
203
204 // -- operation_outputs (step checkpointing) ----------------------------
205
206 /// Insert or read-back a completed step — ported from
207 /// `recordStepResult` / `checkStepExecution`.
208 async fn record_step_output(&self, step: &StepRecord) -> JournioResult<()>;
209
210 /// Fetch all recorded steps for replay — ported from the recovery path
211 /// in `workflow.go` + `system_database.go`.
212 async fn get_steps(&self, workflow_id: &str) -> JournioResult<Vec<StepRecord>>;
213
214 // -- queues ------------------------------------------------------------
215
216 /// Atomically dequeue the next runnable workflow for `queue_name`
217 /// (Postgres: `FOR UPDATE SKIP LOCKED`). Ported from `workflowQueue.loop`.
218 async fn dequeue_workflow(
219 &self,
220 queue_name: &str,
221 executor_id: &str,
222 ) -> JournioResult<Option<WorkflowStatus>>;
223
224 /// List queue names that currently have runnable or future queued work.
225 async fn list_runnable_queues(&self) -> JournioResult<Vec<String>>;
226
227 /// List all registered queues from the `queues` table — ported from
228 /// `listQueues` (`system_database.go:4434`). Used by the admin server's
229 /// queue-metadata endpoint.
230 async fn list_queues(&self) -> JournioResult<Vec<QueueConfig>>;
231
232 // -- inter-workflow communication --------------------------------------
233 //
234 // Go folds the wait/timeout loop into the DB layer (condition variables
235 // woken by a LISTEN/NOTIFY listener). The Rust port splits concerns: these
236 // methods are *non-blocking* primitives, and `WorkflowContext` owns the
237 // polling/timeout loop + checkpointing. LISTEN/NOTIFY can later collapse
238 // the poll interval without changing this trait.
239
240 /// `Send` a message — ported from `send` (`system_database.go:3346`).
241 /// Inserts a row into `notifications`. An empty `topic` is stored as the
242 /// null topic. Returns `NonExistentWorkflowError` when the destination
243 /// workflow does not exist (FK violation).
244 async fn send(
245 &self,
246 destination_id: &str,
247 topic: &str,
248 message: &Interchange,
249 ) -> JournioResult<()>;
250
251 /// Atomically consume the oldest unconsumed message on `topic` destined
252 /// for `workflow_id` — ported from the consume half of `recv`
253 /// (`system_database.go:3378`). Non-blocking: returns `None` when no
254 /// message is available. The polling/timeout loop lives in
255 /// [`crate::context::WorkflowContext::recv`].
256 async fn consume_notification(
257 &self,
258 workflow_id: &str,
259 topic: &str,
260 ) -> JournioResult<Option<Notification>>;
261
262 /// Optional LISTEN/NOTIFY-backed wait hint for `recv`. Backends without a
263 /// wakeup path can ignore it; the caller will re-poll after the timeout.
264 async fn wait_for_notification(
265 &self,
266 _workflow_id: &str,
267 _topic: &str,
268 timeout: Duration,
269 ) -> JournioResult<()> {
270 tokio::time::sleep(timeout).await;
271 Ok(())
272 }
273
274 /// `SetEvent` — ported from `setEvent` (`system_database.go:3573`).
275 /// Upserts `workflow_events` and appends `workflow_events_history`
276 /// (keyed by `function_id`, the calling step id).
277 async fn set_event(
278 &self,
279 workflow_id: &str,
280 key: &str,
281 value: &Interchange,
282 function_id: i32,
283 ) -> JournioResult<()>;
284
285 /// Read the current value of event `key` for `workflow_id` — ported from
286 /// the query half of `getEvent` (`system_database.go:3615`). Non-blocking:
287 /// returns `None` when the key is unset. The polling/timeout loop lives in
288 /// [`crate::context::WorkflowContext::get_event`].
289 async fn get_event_value(
290 &self,
291 workflow_id: &str,
292 key: &str,
293 ) -> JournioResult<Option<Interchange>>;
294
295 /// Optional LISTEN/NOTIFY-backed wait hint for `get_event`.
296 async fn wait_for_event(
297 &self,
298 _workflow_id: &str,
299 _key: &str,
300 timeout: Duration,
301 ) -> JournioResult<()> {
302 tokio::time::sleep(timeout).await;
303 Ok(())
304 }
305
306 // -- streams -----------------------------------------------------------
307
308 /// Append one serialized value to a durable stream within a workflow.
309 async fn write_stream(
310 &self,
311 workflow_id: &str,
312 key: &str,
313 value: &str,
314 function_id: i32,
315 serialization: Option<&str>,
316 ) -> JournioResult<()>;
317
318 /// Read stream entries from `from_offset`, ordered by offset. Returns the
319 /// drained entries plus whether the stream has been closed.
320 async fn read_stream(
321 &self,
322 workflow_id: &str,
323 key: &str,
324 from_offset: i64,
325 ) -> JournioResult<(Vec<StreamEntry>, bool)>;
326
327 /// Optional LISTEN/NOTIFY-backed wait hint for `read_stream`.
328 async fn wait_for_stream(
329 &self,
330 _workflow_id: &str,
331 _key: &str,
332 timeout: Duration,
333 ) -> JournioResult<()> {
334 tokio::time::sleep(timeout).await;
335 Ok(())
336 }
337
338 // -- recovery ----------------------------------------------------------
339
340 /// Workflows left PENDING for this executor at startup — ported from
341 /// `workflowRecovery` in `recovery.go` + `system_database.go`.
342 async fn get_workflows_for_recovery(
343 &self,
344 executor_id: &str,
345 ) -> JournioResult<Vec<WorkflowStatus>>;
346
347 // -- scheduler ---------------------------------------------------------
348
349 /// Create or replace a workflow schedule definition.
350 async fn upsert_schedule(&self, schedule: &WorkflowSchedule) -> JournioResult<()>;
351
352 /// Fetch a single schedule by name — ported from the
353 /// `ScheduleNamePrefixes` branch of `listSchedules`
354 /// (`system_database.go:4766`). Returns `None` if no schedule matches.
355 async fn get_schedule(&self, schedule_name: &str) -> JournioResult<Option<WorkflowSchedule>>;
356
357 /// List all persisted schedule definitions.
358 async fn list_schedules(&self) -> JournioResult<Vec<WorkflowSchedule>>;
359
360 /// Delete a schedule by name — ported from `deleteSchedule`
361 /// (`system_database.go:4928`).
362 async fn delete_schedule(&self, schedule_name: &str) -> JournioResult<()>;
363
364 /// Update only a schedule's status — ported from `updateSchedule`
365 /// (`system_database.go`). Used by pause/resume.
366 async fn update_schedule_status(
367 &self,
368 schedule_name: &str,
369 status: ScheduleStatus,
370 ) -> JournioResult<()>;
371
372 /// Update the last-fired timestamp after a successful trigger/backfill pass.
373 async fn update_schedule_last_fired_at(
374 &self,
375 schedule_name: &str,
376 fired_at: DateTime<Utc>,
377 ) -> JournioResult<()>;
378
379 // -- application versions ---------------------------------------------
380 //
381 // Ported from the `application_versions` helpers in
382 // `system_database.go:5174`. The "latest" version is simply the row with
383 // the greatest `version_timestamp`.
384
385 /// Register a new application version (no-op if the name already exists).
386 /// Ported from `createApplicationVersion`.
387 async fn create_application_version(&self, version_name: &str) -> JournioResult<()>;
388
389 /// Bump a version's timestamp, marking it as latest. Ported from
390 /// `updateApplicationVersionTimestamp`.
391 async fn update_application_version_timestamp(
392 &self,
393 version_name: &str,
394 timestamp_ms: i64,
395 ) -> JournioResult<()>;
396
397 /// All registered versions, newest first — ported from
398 /// `listApplicationVersions` (`system_database.go:5174`).
399 async fn list_application_versions(&self) -> JournioResult<Vec<VersionInfo>>;
400
401 /// The version with the greatest timestamp — ported from
402 /// `getLatestApplicationVersion`. Returns `None` when none are registered.
403 async fn get_latest_application_version(&self) -> JournioResult<Option<VersionInfo>>;
404
405 /// Set or update the delay on a DELAYED workflow — ported from
406 /// `setWorkflowDelay` (`system_database.go`). No-op for workflows not in
407 /// the DELAYED status.
408 async fn set_workflow_delay(
409 &self,
410 workflow_id: &str,
411 delay_until: DateTime<Utc>,
412 ) -> JournioResult<()>;
413
414 /// Permanently delete the given workflows and all their associated data
415 /// (operation outputs, events, event history, streams) — ported from
416 /// `deleteWorkflows` (`system_database.go`). When `delete_children` is
417 /// true, descendant workflows are deleted recursively first.
418 async fn delete_workflows(
419 &self,
420 workflow_ids: &[String],
421 delete_children: bool,
422 ) -> JournioResult<()>;
423
424 // -- GC ---------------------------------------------------------------
425
426 /// Delete completed workflows older than `before` — ported from
427 /// `permanentDeleteWorkflows`.
428 async fn delete_workflows_before(&self, before: DateTime<Utc>) -> JournioResult<u64>;
429}