Skip to main content

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}