Skip to main content

journio_core/
context.rs

1//! Runtime contexts & handles — ported from `journio/journio.go` (`JOURNIOContext`,
2//! `journioContext`) and `journio/workflow.go` (`workflowState`, `WorkflowHandle`).
3//!
4//! The Go `JOURNIOContext` is an interface with ~30 methods; here it splits into:
5//!   - [`JournioContext`]     — the long-lived runtime (registry, db, loops)
6//!   - [`WorkflowContext`] — per-workflow execution state (id, step counter)
7//!
8//! The MVP execution path is implemented here. Later-phase primitives remain
9//! as `todo!()` until their corresponding storage/runtime layers land.
10
11use std::str::FromStr;
12use std::sync::atomic::{AtomicI32, Ordering};
13use std::sync::{Arc, Weak};
14use std::time::{Duration, Instant};
15
16use chrono::{DateTime, Utc};
17use cron::Schedule;
18use serde::{Deserialize, Serialize};
19use tokio::sync::RwLock;
20use tokio::time::sleep;
21use tokio_util::sync::CancellationToken;
22use uuid::Uuid;
23
24use crate::config::Config;
25use crate::error::{JournioError, JournioErrorCode, JournioResult};
26use crate::system_db::{ForkWorkflow, InitWorkflow, SystemDatabase};
27use crate::types::{
28    ListWorkflowsFilter, QueueConfig, ScheduleStatus, ScheduledWorkflowInput, StepRecord,
29    WorkflowSchedule, WorkflowStatus, WorkflowStatusType,
30};
31use crate::value::Interchange;
32use crate::workflow::{Registry, Step, Workflow};
33
34/// Poll interval for the context-layer wait loops (`recv` / `get_event` /
35/// `get_result`). Go wakes these via LISTEN/NOTIFY; the Rust port polls until
36/// the notification listener lands (Phase 4). Matches the `get_result` cadence.
37const POLL_INTERVAL: Duration = Duration::from_millis(25);
38const LISTENER_WAIT_CAP: Duration = Duration::from_secs(1);
39const PATCH_PREFIX: &str = "journio.patch-";
40pub(crate) const INTERNAL_QUEUE_NAME: &str = "_journio_internal_queue";
41const STREAM_CLOSED_SENTINEL: &str = "__JOURNIO_STREAM_CLOSED__";
42const DEBOUNCER_TOPIC: &str = "_journio_debouncer_topic";
43const INTERNAL_DEBOUNCER_WORKFLOW_NAME: &str = "__journio_internal_debouncer_workflow";
44
45/// Queue enqueue parameters — a compact Phase 2 subset of Go's
46/// `WorkflowOption` / `EnqueueOption` surface.
47#[derive(Debug, Clone, Default)]
48pub struct EnqueueOptions {
49    pub workflow_id: Option<String>,
50    pub application_version: Option<String>,
51    pub deduplication_id: Option<String>,
52    pub priority: i32,
53    pub queue_partition_key: Option<String>,
54    pub timeout: Option<Duration>,
55    pub delay_until: Option<DateTime<Utc>>,
56}
57
58#[derive(Debug, Clone, Default)]
59pub struct ScheduleOptions {
60    pub workflow_class_name: Option<String>,
61    pub automatic_backfill: bool,
62    pub cron_timezone: Option<String>,
63    pub queue_name: Option<String>,
64    pub status: Option<ScheduleStatus>,
65    pub last_fired_at: Option<DateTime<Utc>>,
66}
67
68#[derive(Debug, Clone, Copy, Default)]
69pub struct ReadStreamOptions {
70    pub snapshot: bool,
71    pub from_offset: i64,
72}
73
74#[derive(Debug, Clone, Default)]
75pub struct DebounceOptions {
76    pub workflow_id: Option<String>,
77    pub debounce_timeout: Option<Duration>,
78    pub queue_name: Option<String>,
79    pub application_version: Option<String>,
80    pub deduplication_id: Option<String>,
81    pub priority: i32,
82    pub queue_partition_key: Option<String>,
83    pub workflow_timeout: Option<Duration>,
84}
85
86#[derive(Debug, Clone, Default)]
87pub struct QueueOptions {
88    pub concurrency: Option<i32>,
89    pub worker_concurrency: Option<i32>,
90    pub rate_limit_max: Option<i32>,
91    pub rate_limit_period: Option<Duration>,
92    pub priority_enabled: bool,
93    pub partition_queue: bool,
94    pub polling_interval: Option<Duration>,
95}
96
97#[derive(Debug, Clone, Default)]
98pub struct ForkWorkflowOptions {
99    pub workflow_id: Option<String>,
100    pub start_step: u32,
101    pub application_version: Option<String>,
102    pub queue_name: Option<String>,
103    pub queue_partition_key: Option<String>,
104}
105
106#[derive(Debug, Clone, Serialize, Deserialize)]
107struct DebouncerWorkflowInput {
108    initial_input: Interchange,
109    target_workflow_name: String,
110    target_workflow_id: String,
111    delay_ms: u64,
112    timeout_ms: Option<u64>,
113    queue_name: Option<String>,
114    application_version: Option<String>,
115    deduplication_id: Option<String>,
116    priority: i32,
117    queue_partition_key: Option<String>,
118    workflow_timeout_ms: Option<u64>,
119}
120
121#[derive(Debug, Clone, Serialize, Deserialize)]
122struct DebounceMessage {
123    input: Interchange,
124    delay_ms: u64,
125    id: String,
126}
127
128/// Per-workflow execution state — ported from `workflowState` (`workflow.go`).
129/// Cheap to clone (all `Arc`).
130#[derive(Clone)]
131pub struct WorkflowContext {
132    pub(crate) inner: Arc<WorkflowCtxInner>,
133}
134
135#[allow(dead_code)]
136pub(crate) struct WorkflowCtxInner {
137    workflow_id: String,
138    step_counter: AtomicI32,
139    step_execution_depth: AtomicI32,
140    /// Weak back-reference to the runtime — avoids reference cycles.
141    journio: Weak<JournioContext>,
142    /// Durable cancellation (Go's ctx.Done() for the workflow).
143    cancel: CancellationToken,
144    authenticated_user: RwLock<Option<String>>,
145    assumed_role: RwLock<Option<String>>,
146}
147
148impl WorkflowContext {
149    pub fn workflow_id(&self) -> &str {
150        &self.inner.workflow_id
151    }
152
153    pub fn current_step_id(&self) -> i32 {
154        self.inner.step_counter.load(Ordering::SeqCst)
155    }
156
157    pub fn application_version(&self) -> JournioResult<String> {
158        Ok(self.journio()?.application_version())
159    }
160
161    pub fn executor_id(&self) -> JournioResult<String> {
162        Ok(self.journio()?.executor_id())
163    }
164
165    /// Allocate the next step id — ported from `workflowState.nextStepID`.
166    pub fn next_step_id(&self) -> i32 {
167        self.inner.step_counter.fetch_add(1, Ordering::SeqCst) + 1
168    }
169
170    pub fn cancellation(&self) -> CancellationToken {
171        self.inner.cancel.clone()
172    }
173
174    /// `RunAsStep` — ported from `RunAsStep` (`workflow.go:1937`).
175    pub async fn run_as_step(&self, step: Arc<dyn Step>) -> JournioResult<Interchange> {
176        let step_id = self.next_step_id();
177        let journio = self.journio()?;
178
179        if let Some(recorded) = self.recorded_step(step_id).await? {
180            validate_recorded_step(
181                self.workflow_id(),
182                step_id,
183                step.name(),
184                &recorded.function_name,
185            )?;
186            if let Some(message) = recorded.error {
187                return Err(recorded_step_error(
188                    self.workflow_id(),
189                    step_id,
190                    step.name(),
191                    message,
192                ));
193            }
194            return decode_interchange(
195                &journio,
196                self.workflow_id(),
197                step_id,
198                step.name(),
199                recorded.output,
200            );
201        }
202
203        let _step_scope = self.enter_step_execution();
204        match step.run(self).await {
205            Ok(output) => {
206                journio
207                    .system_db
208                    .record_step_output(&StepRecord {
209                        workflow_uuid: self.workflow_id().to_string(),
210                        function_id: step_id,
211                        function_name: step.name().to_string(),
212                        output: Some(encode_interchange(&journio, &output)?),
213                        error: None,
214                        child_workflow_id: None,
215                    })
216                    .await?;
217                Ok(output)
218            }
219            Err(err) => {
220                journio
221                    .system_db
222                    .record_step_output(&StepRecord {
223                        workflow_uuid: self.workflow_id().to_string(),
224                        function_id: step_id,
225                        function_name: step.name().to_string(),
226                        output: None,
227                        error: Some(err.message.clone()),
228                        child_workflow_id: None,
229                    })
230                    .await?;
231                Err(err)
232            }
233        }
234    }
235
236    /// `RunWorkflow` (inside a workflow, for child workflows) — `workflow.go:1028`.
237    pub async fn run_workflow(
238        &self,
239        name: &str,
240        input: Interchange,
241    ) -> JournioResult<WorkflowHandle> {
242        let function_id = self.next_step_id();
243        let function_name = format!("child::{name}");
244        let journio = self.journio()?;
245
246        if let Some(recorded) = self.recorded_step(function_id).await? {
247            validate_recorded_step(
248                self.workflow_id(),
249                function_id,
250                &function_name,
251                &recorded.function_name,
252            )?;
253            if let Some(message) = recorded.error {
254                return Err(recorded_step_error(
255                    self.workflow_id(),
256                    function_id,
257                    &function_name,
258                    message,
259                ));
260            }
261            if let Some(child_workflow_id) = recorded.child_workflow_id {
262                return Ok(WorkflowHandle {
263                    workflow_id: child_workflow_id,
264                    journio: Arc::downgrade(&journio),
265                });
266            }
267            return Err(JournioError::new(
268                JournioErrorCode::WorkflowExecutionError,
269                format!(
270                    "recorded child workflow step {} in workflow {} is missing child_workflow_id",
271                    function_id,
272                    self.workflow_id()
273                ),
274            ));
275        }
276
277        journio
278            .start_workflow(
279                name,
280                input,
281                WorkflowLaunch::Immediate,
282                None,
283                None,
284                Some(self.workflow_id().to_string()),
285                Some(ChildCheckpoint {
286                    parent_workflow_id: self.workflow_id().to_string(),
287                    function_id,
288                    function_name,
289                }),
290            )
291            .await
292    }
293
294    /// `Sleep` — durable sleep that survives recovery. Ported from
295    /// `sysDB.sleep` (`system_database.go:2964`). Records the wake-up deadline
296    /// as a checkpointed step (`journio.sleep`); on replay, decodes the recorded
297    /// deadline and sleeps only the remaining duration.
298    pub async fn sleep(&self, duration: Duration) -> JournioResult<Duration> {
299        const STEP_NAME: &str = "journio.sleep";
300        let step_id = self.next_step_id();
301        let journio = self.journio()?;
302
303        if let Some(recorded) = self.recorded_step(step_id).await? {
304            validate_recorded_step(
305                self.workflow_id(),
306                step_id,
307                STEP_NAME,
308                &recorded.function_name,
309            )?;
310            if let Some(message) = recorded.error {
311                return Err(recorded_step_error(
312                    self.workflow_id(),
313                    step_id,
314                    STEP_NAME,
315                    message,
316                ));
317            }
318            let decoded = decode_interchange(
319                &journio,
320                self.workflow_id(),
321                step_id,
322                STEP_NAME,
323                recorded.output,
324            )?;
325            let deadline = parse_deadline(&decoded)?;
326            let remaining = remaining_until(deadline);
327            tokio::time::sleep(remaining).await;
328            return Ok(remaining);
329        }
330
331        let deadline = Utc::now()
332            + chrono::Duration::from_std(duration)
333                .unwrap_or_else(|_| chrono::Duration::milliseconds(i64::MAX / 1_000_000));
334        let encoded =
335            encode_interchange(&journio, &serde_json::Value::String(deadline.to_rfc3339()))?;
336        journio
337            .system_db
338            .record_step_output(&StepRecord {
339                workflow_uuid: self.workflow_id().to_string(),
340                function_id: step_id,
341                function_name: STEP_NAME.to_string(),
342                output: Some(encoded),
343                error: None,
344                child_workflow_id: None,
345            })
346            .await?;
347
348        let remaining = remaining_until(deadline);
349        tokio::time::sleep(remaining).await;
350        Ok(remaining)
351    }
352
353    /// `Recv` — ported from `Recv` (`workflow.go:2477`). Polls for a message
354    /// on `topic` up to `timeout`. The first message found is recorded as a
355    /// checkpointed step (`journio.recv`) so replay returns the same value;
356    /// timeouts are recorded as errors for the same reason.
357    pub async fn recv(&self, topic: &str, timeout: Duration) -> JournioResult<Interchange> {
358        const STEP_NAME: &str = "journio.recv";
359        let step_id = self.next_step_id();
360        let journio = self.journio()?;
361
362        if let Some(recorded) = self.recorded_step(step_id).await? {
363            validate_recorded_step(
364                self.workflow_id(),
365                step_id,
366                STEP_NAME,
367                &recorded.function_name,
368            )?;
369            if let Some(message) = recorded.error {
370                return Err(recorded_step_error(
371                    self.workflow_id(),
372                    step_id,
373                    STEP_NAME,
374                    message,
375                ));
376            }
377            return decode_interchange(
378                &journio,
379                self.workflow_id(),
380                step_id,
381                STEP_NAME,
382                recorded.output,
383            );
384        }
385
386        let deadline = Instant::now() + timeout;
387        loop {
388            if let Some(notification) = journio
389                .system_db
390                .consume_notification(self.workflow_id(), topic)
391                .await?
392            {
393                let encoded = encode_interchange(&journio, &notification.message)?;
394                journio
395                    .system_db
396                    .record_step_output(&StepRecord {
397                        workflow_uuid: self.workflow_id().to_string(),
398                        function_id: step_id,
399                        function_name: STEP_NAME.to_string(),
400                        output: Some(encoded),
401                        error: None,
402                        child_workflow_id: None,
403                    })
404                    .await?;
405                return Ok(notification.message);
406            }
407            if Instant::now() >= deadline {
408                let err = ctx_step_error(
409                    JournioErrorCode::TimeoutError,
410                    self.workflow_id(),
411                    step_id,
412                    STEP_NAME,
413                    format!("no message received on topic {topic:?} within {timeout:?}"),
414                );
415                journio
416                    .system_db
417                    .record_step_output(&StepRecord {
418                        workflow_uuid: self.workflow_id().to_string(),
419                        function_id: step_id,
420                        function_name: STEP_NAME.to_string(),
421                        output: None,
422                        error: Some(err.message.clone()),
423                        child_workflow_id: None,
424                    })
425                    .await?;
426                return Err(err);
427            }
428            let remaining = deadline.saturating_duration_since(Instant::now());
429            journio
430                .system_db
431                .wait_for_notification(self.workflow_id(), topic, remaining.min(LISTENER_WAIT_CAP))
432                .await?;
433        }
434    }
435
436    /// `Send` (from within a workflow) — ported from `Send` (`workflow.go:2402`).
437    /// Runs as a checkpointed step (`journio.send`) so the side effect happens
438    /// exactly once across replays.
439    pub async fn send(&self, dest: &str, msg: Interchange, topic: &str) -> JournioResult<()> {
440        const STEP_NAME: &str = "journio.send";
441        let step_id = self.next_step_id();
442        let journio = self.journio()?;
443
444        if let Some(recorded) = self.recorded_step(step_id).await? {
445            validate_recorded_step(
446                self.workflow_id(),
447                step_id,
448                STEP_NAME,
449                &recorded.function_name,
450            )?;
451            if let Some(message) = recorded.error {
452                return Err(recorded_step_error(
453                    self.workflow_id(),
454                    step_id,
455                    STEP_NAME,
456                    message,
457                ));
458            }
459            return Ok(());
460        }
461
462        journio.system_db.send(dest, topic, &msg).await?;
463        journio
464            .system_db
465            .record_step_output(&StepRecord {
466                workflow_uuid: self.workflow_id().to_string(),
467                function_id: step_id,
468                function_name: STEP_NAME.to_string(),
469                output: None,
470                error: None,
471                child_workflow_id: None,
472            })
473            .await?;
474        Ok(())
475    }
476
477    /// `SetEvent` — ported from `SetEvent` (`workflow.go:2576`). Runs as a
478    /// checkpointed step (`journio.setEvent`).
479    pub async fn set_event(&self, key: &str, value: Interchange) -> JournioResult<()> {
480        const STEP_NAME: &str = "journio.setEvent";
481        let step_id = self.next_step_id();
482        let journio = self.journio()?;
483
484        if let Some(recorded) = self.recorded_step(step_id).await? {
485            validate_recorded_step(
486                self.workflow_id(),
487                step_id,
488                STEP_NAME,
489                &recorded.function_name,
490            )?;
491            if let Some(message) = recorded.error {
492                return Err(recorded_step_error(
493                    self.workflow_id(),
494                    step_id,
495                    STEP_NAME,
496                    message,
497                ));
498            }
499            return Ok(());
500        }
501
502        journio
503            .system_db
504            .set_event(self.workflow_id(), key, &value, step_id)
505            .await?;
506        journio
507            .system_db
508            .record_step_output(&StepRecord {
509                workflow_uuid: self.workflow_id().to_string(),
510                function_id: step_id,
511                function_name: STEP_NAME.to_string(),
512                output: None,
513                error: None,
514                child_workflow_id: None,
515            })
516            .await?;
517        Ok(())
518    }
519
520    /// `GetEvent` — ported from `GetEvent` (`workflow.go:2634`). Polls for the
521    /// value of `key` on `target` workflow up to `timeout`. The first value
522    /// found is recorded as a checkpointed step (`journio.getEvent`); timeouts are
523    /// recorded as errors.
524    pub async fn get_event(
525        &self,
526        target: &str,
527        key: &str,
528        timeout: Duration,
529    ) -> JournioResult<Interchange> {
530        const STEP_NAME: &str = "journio.getEvent";
531        let step_id = self.next_step_id();
532        let journio = self.journio()?;
533
534        if let Some(recorded) = self.recorded_step(step_id).await? {
535            validate_recorded_step(
536                self.workflow_id(),
537                step_id,
538                STEP_NAME,
539                &recorded.function_name,
540            )?;
541            if let Some(message) = recorded.error {
542                return Err(recorded_step_error(
543                    self.workflow_id(),
544                    step_id,
545                    STEP_NAME,
546                    message,
547                ));
548            }
549            return decode_interchange(
550                &journio,
551                self.workflow_id(),
552                step_id,
553                STEP_NAME,
554                recorded.output,
555            );
556        }
557
558        let deadline = Instant::now() + timeout;
559        loop {
560            if let Some(value) = journio.system_db.get_event_value(target, key).await? {
561                let encoded = encode_interchange(&journio, &value)?;
562                journio
563                    .system_db
564                    .record_step_output(&StepRecord {
565                        workflow_uuid: self.workflow_id().to_string(),
566                        function_id: step_id,
567                        function_name: STEP_NAME.to_string(),
568                        output: Some(encoded),
569                        error: None,
570                        child_workflow_id: None,
571                    })
572                    .await?;
573                return Ok(value);
574            }
575            if Instant::now() >= deadline {
576                let err = ctx_step_error(
577                    JournioErrorCode::TimeoutError,
578                    self.workflow_id(),
579                    step_id,
580                    STEP_NAME,
581                    format!("event {key:?} not set for workflow {target:?} within {timeout:?}"),
582                );
583                journio
584                    .system_db
585                    .record_step_output(&StepRecord {
586                        workflow_uuid: self.workflow_id().to_string(),
587                        function_id: step_id,
588                        function_name: STEP_NAME.to_string(),
589                        output: None,
590                        error: Some(err.message.clone()),
591                        child_workflow_id: None,
592                    })
593                    .await?;
594                return Err(err);
595            }
596            let remaining = deadline.saturating_duration_since(Instant::now());
597            journio
598                .system_db
599                .wait_for_event(target, key, remaining.min(LISTENER_WAIT_CAP))
600                .await?;
601        }
602    }
603
604    /// `WriteStream` — append a durable stream value exactly once.
605    pub async fn write_stream(&self, key: &str, value: Interchange) -> JournioResult<()> {
606        const STEP_NAME: &str = "journio.writeStream";
607        let step_id = self.next_step_id();
608        let journio = self.journio()?;
609
610        if let Some(recorded) = self.recorded_step(step_id).await? {
611            validate_recorded_step(
612                self.workflow_id(),
613                step_id,
614                STEP_NAME,
615                &recorded.function_name,
616            )?;
617            if let Some(message) = recorded.error {
618                return Err(recorded_step_error(
619                    self.workflow_id(),
620                    step_id,
621                    STEP_NAME,
622                    message,
623                ));
624            }
625            return Ok(());
626        }
627
628        let encoded = encode_interchange(&journio, &value)?;
629        journio
630            .system_db
631            .write_stream(
632                self.workflow_id(),
633                key,
634                &encoded,
635                step_id,
636                Some(journio.config.serializer.name()),
637            )
638            .await?;
639        journio
640            .system_db
641            .record_step_output(&StepRecord {
642                workflow_uuid: self.workflow_id().to_string(),
643                function_id: step_id,
644                function_name: STEP_NAME.to_string(),
645                output: None,
646                error: None,
647                child_workflow_id: None,
648            })
649            .await?;
650        Ok(())
651    }
652
653    /// `CloseStream` — closes a durable stream by writing the sentinel row.
654    pub async fn close_stream(&self, key: &str) -> JournioResult<()> {
655        const STEP_NAME: &str = "journio.closeStream";
656        let step_id = self.next_step_id();
657        let journio = self.journio()?;
658
659        if let Some(recorded) = self.recorded_step(step_id).await? {
660            validate_recorded_step(
661                self.workflow_id(),
662                step_id,
663                STEP_NAME,
664                &recorded.function_name,
665            )?;
666            if let Some(message) = recorded.error {
667                return Err(recorded_step_error(
668                    self.workflow_id(),
669                    step_id,
670                    STEP_NAME,
671                    message,
672                ));
673            }
674            return Ok(());
675        }
676
677        journio
678            .system_db
679            .write_stream(
680                self.workflow_id(),
681                key,
682                STREAM_CLOSED_SENTINEL,
683                step_id,
684                None,
685            )
686            .await?;
687        journio
688            .system_db
689            .record_step_output(&StepRecord {
690                workflow_uuid: self.workflow_id().to_string(),
691                function_id: step_id,
692                function_name: STEP_NAME.to_string(),
693                output: None,
694                error: None,
695                child_workflow_id: None,
696            })
697            .await?;
698        Ok(())
699    }
700
701    /// Debounce workflow execution by `key`, coalescing repeated invocations
702    /// into a single target workflow run that receives the latest input.
703    pub async fn debounce_workflow(
704        &self,
705        workflow_name: &str,
706        key: &str,
707        delay: Duration,
708        input: Interchange,
709        mut options: DebounceOptions,
710    ) -> JournioResult<WorkflowHandle> {
711        let target_workflow_id = match options.workflow_id.take() {
712            Some(value) => value,
713            None => durable_uuid_step(self, "journio.debounce.assignWorkflowID").await?,
714        };
715        let message_id = durable_uuid_step(self, "journio.debounce.assignMessageID").await?;
716        let journio = self.journio()?;
717        journio
718            .debounce_workflow_inner(
719                workflow_name,
720                key,
721                delay,
722                input,
723                options,
724                target_workflow_id,
725                message_id,
726            )
727            .await
728    }
729
730    /// `Patch` / `DeprecatePatch` — ported from `workflow.go` patching system.
731    pub async fn patch(&self, patch_name: &str) -> JournioResult<bool> {
732        let journio = self.journio()?;
733        validate_patching_enabled(&journio)?;
734        validate_patch_name(patch_name)?;
735        validate_not_within_step(self)?;
736
737        let step_id = self.peek_next_step_id();
738        let prefixed_patch_name = format!("{PATCH_PREFIX}{patch_name}");
739
740        match self.recorded_step(step_id).await? {
741            Some(recorded) if recorded.function_name == prefixed_patch_name => {
742                self.next_step_id();
743                Ok(true)
744            }
745            Some(_) => Ok(false),
746            None => {
747                journio
748                    .system_db
749                    .record_step_output(&StepRecord {
750                        workflow_uuid: self.workflow_id().to_string(),
751                        function_id: step_id,
752                        function_name: prefixed_patch_name,
753                        output: None,
754                        error: None,
755                        child_workflow_id: None,
756                    })
757                    .await?;
758                self.next_step_id();
759                Ok(true)
760            }
761        }
762    }
763
764    /// `DeprecatePatch` — ported from `workflow.go` patching system.
765    pub async fn deprecate_patch(&self, patch_name: &str) -> JournioResult<()> {
766        let journio = self.journio()?;
767        validate_patching_enabled(&journio)?;
768        validate_patch_name(patch_name)?;
769        validate_not_within_step(self)?;
770
771        let step_id = self.peek_next_step_id();
772        let prefixed_patch_name = format!("{PATCH_PREFIX}{patch_name}");
773
774        if self
775            .recorded_step(step_id)
776            .await?
777            .is_some_and(|recorded| recorded.function_name == prefixed_patch_name)
778        {
779            self.next_step_id();
780        }
781
782        Ok(())
783    }
784
785    fn journio(&self) -> JournioResult<Arc<JournioContext>> {
786        self.inner.journio.upgrade().ok_or_else(|| {
787            JournioError::new(
788                JournioErrorCode::InitializationError,
789                "Journio runtime is no longer available",
790            )
791        })
792    }
793
794    async fn recorded_step(&self, step_id: i32) -> JournioResult<Option<StepRecord>> {
795        let journio = self.journio()?;
796        let steps = journio.system_db.get_steps(self.workflow_id()).await?;
797        Ok(steps.into_iter().find(|step| step.function_id == step_id))
798    }
799
800    fn peek_next_step_id(&self) -> i32 {
801        self.inner.step_counter.load(Ordering::SeqCst) + 1
802    }
803
804    fn is_within_step(&self) -> bool {
805        self.inner.step_execution_depth.load(Ordering::SeqCst) > 0
806    }
807
808    fn enter_step_execution(&self) -> StepExecutionScope<'_> {
809        self.inner
810            .step_execution_depth
811            .fetch_add(1, Ordering::SeqCst);
812        StepExecutionScope { ctx: self }
813    }
814}
815
816struct StepExecutionScope<'a> {
817    ctx: &'a WorkflowContext,
818}
819
820impl Drop for StepExecutionScope<'_> {
821    fn drop(&mut self) {
822        self.ctx
823            .inner
824            .step_execution_depth
825            .fetch_sub(1, Ordering::SeqCst);
826    }
827}
828
829/// Handle returned by `RunWorkflow` — ported from `WorkflowHandle[R]`
830/// (`workflow.go`). Erased (no type param) because inputs/outputs are
831/// `Interchange`; typed users downcast via serde.
832#[derive(Clone)]
833pub struct WorkflowHandle {
834    pub workflow_id: String,
835    pub(crate) journio: Weak<JournioContext>,
836}
837
838impl WorkflowHandle {
839    pub fn workflow_id(&self) -> &str {
840        &self.workflow_id
841    }
842
843    /// `GetResult` — ported from `baseWorkflowHandle.GetResult`.
844    pub async fn get_result(&self, timeout: Option<Duration>) -> JournioResult<Interchange> {
845        let deadline = timeout.and_then(|value| Instant::now().checked_add(value));
846
847        loop {
848            let status = match self.get_status().await {
849                Ok(status) => status,
850                Err(err) if err.code == JournioErrorCode::NonExistentWorkflowError => {
851                    if let Some(deadline) = deadline {
852                        if Instant::now() >= deadline {
853                            return Err(workflow_terminal_error(
854                                JournioErrorCode::TimeoutError,
855                                &self.workflow_id,
856                                format!("timed out waiting for workflow {}", self.workflow_id),
857                            ));
858                        }
859                    }
860                    sleep(Duration::from_millis(25)).await;
861                    continue;
862                }
863                Err(err) => return Err(err),
864            };
865            match status.status {
866                WorkflowStatusType::Success => {
867                    return Ok(status.output.unwrap_or(Interchange::Null));
868                }
869                WorkflowStatusType::Error => {
870                    return Err(workflow_terminal_error(
871                        JournioErrorCode::WorkflowExecutionError,
872                        &self.workflow_id,
873                        status.error.unwrap_or_else(|| {
874                            format!("workflow {} completed with ERROR", self.workflow_id)
875                        }),
876                    ));
877                }
878                WorkflowStatusType::Cancelled => {
879                    return Err(workflow_terminal_error(
880                        JournioErrorCode::WorkflowCancelled,
881                        &self.workflow_id,
882                        status.error.unwrap_or_else(|| {
883                            format!("workflow {} was cancelled", self.workflow_id)
884                        }),
885                    ));
886                }
887                WorkflowStatusType::MaxRecoveryAttemptsExceeded => {
888                    return Err(workflow_terminal_error(
889                        JournioErrorCode::DeadLetterQueueError,
890                        &self.workflow_id,
891                        status.error.unwrap_or_else(|| {
892                            format!(
893                                "workflow {} exceeded the maximum number of recovery attempts",
894                                self.workflow_id
895                            )
896                        }),
897                    ));
898                }
899                WorkflowStatusType::Pending
900                | WorkflowStatusType::Enqueued
901                | WorkflowStatusType::Delayed => {
902                    if let Some(deadline) = deadline {
903                        if Instant::now() >= deadline {
904                            return Err(workflow_terminal_error(
905                                JournioErrorCode::TimeoutError,
906                                &self.workflow_id,
907                                format!("timed out waiting for workflow {}", self.workflow_id),
908                            ));
909                        }
910                    }
911                    sleep(Duration::from_millis(25)).await;
912                }
913            }
914        }
915    }
916
917    /// `GetStatus` — ported from `GetStatus`.
918    pub async fn get_status(&self) -> JournioResult<WorkflowStatus> {
919        let journio = self.journio()?;
920        journio
921            .system_db
922            .get_workflow_status(&self.workflow_id)
923            .await?
924            .ok_or_else(|| crate::error::constructors::non_existent_workflow(&self.workflow_id))
925    }
926
927    pub async fn cancel(&self) -> JournioResult<bool> {
928        let journio = self.journio()?;
929        journio.cancel_workflow(&self.workflow_id).await
930    }
931
932    pub async fn resume(&self, queue_name: Option<&str>) -> JournioResult<bool> {
933        let journio = self.journio()?;
934        journio.resume_workflow(&self.workflow_id, queue_name).await
935    }
936
937    pub async fn fork(&self, options: ForkWorkflowOptions) -> JournioResult<WorkflowHandle> {
938        let journio = self.journio()?;
939        journio.fork_workflow(&self.workflow_id, options).await
940    }
941
942    fn journio(&self) -> JournioResult<Arc<JournioContext>> {
943        self.journio.upgrade().ok_or_else(|| {
944            JournioError::new(
945                JournioErrorCode::InitializationError,
946                "Journio runtime is no longer available",
947            )
948        })
949    }
950}
951
952/// The long-lived Journio runtime — ported from `journioContext` (`journio/journio.go:221`).
953///
954/// Construct with [`JournioContext::new`] (which calls `process_config`), then
955/// [`JournioContext::launch`] to start background loops and run recovery.
956pub struct JournioContext {
957    pub config: Config,
958    pub registry: Registry,
959    pub(crate) system_db: Arc<dyn SystemDatabase>,
960    pub(crate) cancel: CancellationToken,
961    pub(crate) started: std::sync::atomic::AtomicBool,
962}
963
964impl JournioContext {
965    /// Construct + validate config + resolve backend. Ported from
966    /// `NewJOURNIOContext`.
967    pub async fn new(mut config: Config) -> JournioResult<Arc<Self>> {
968        crate::config::process_config(&mut config)?;
969        let system_db = resolve_backend(&config)?;
970        let ctx = Arc::new(Self {
971            config,
972            registry: Registry::new(),
973            system_db,
974            cancel: CancellationToken::new(),
975            started: false.into(),
976        });
977        ctx.register_workflow(Arc::new(InternalDebouncerWorkflow))?;
978        Ok(ctx)
979    }
980
981    /// Register a workflow before launch — ported from `RegisterWorkflow`.
982    pub fn register_workflow(&self, wf: Arc<dyn Workflow>) -> JournioResult<()> {
983        self.registry.register(wf)
984    }
985
986    pub fn application_version(&self) -> String {
987        self.config.application_version.clone().unwrap_or_default()
988    }
989
990    pub fn executor_id(&self) -> String {
991        self.config.executor_id.clone().unwrap_or_default()
992    }
993
994    /// Start runtime: migrate, launch DB loops, recover local executor's
995    /// workflows. Ported from `Launch`.
996    pub async fn launch(self: &Arc<Self>) -> JournioResult<()> {
997        self.system_db.migrate().await?;
998        self.system_db.launch().await?;
999        self.recover().await?;
1000        self.started.store(true, Ordering::SeqCst);
1001        self.spawn_background_loops();
1002        Ok(())
1003    }
1004
1005    /// Graceful shutdown — ported from `Shutdown`.
1006    pub async fn shutdown(&self, _timeout: Duration) -> JournioResult<()> {
1007        self.cancel.cancel();
1008        self.system_db.shutdown().await
1009    }
1010
1011    /// Signal the runtime to stop accepting new work (scheduler/queue loops
1012    /// observe the cancellation token and exit). Does **not** close the DB
1013    /// pool — that's `shutdown`. Ported from Go's `/deactivate` handler.
1014    pub fn deactivate(&self) {
1015        self.cancel.cancel();
1016    }
1017
1018    /// Enqueue a workflow from outside a workflow context. Ported from
1019    /// `RunWorkflow` at the top level (`workflow.go:1028`).
1020    pub async fn run_workflow(
1021        self: &Arc<Self>,
1022        name: &str,
1023        input: Interchange,
1024    ) -> JournioResult<WorkflowHandle> {
1025        self.start_workflow(
1026            name,
1027            input,
1028            WorkflowLaunch::Immediate,
1029            None,
1030            None,
1031            None,
1032            None,
1033        )
1034        .await
1035    }
1036
1037    pub async fn start_workflow_background(
1038        self: &Arc<Self>,
1039        name: &str,
1040        input: Interchange,
1041        options: EnqueueOptions,
1042    ) -> JournioResult<WorkflowHandle> {
1043        self.start_workflow(
1044            name,
1045            input,
1046            WorkflowLaunch::Background,
1047            None,
1048            Some(options),
1049            None,
1050            None,
1051        )
1052        .await
1053    }
1054
1055    /// Enqueue a workflow for deferred execution on `queue_name`.
1056    pub async fn enqueue_workflow(
1057        self: &Arc<Self>,
1058        queue_name: &str,
1059        name: &str,
1060        input: Interchange,
1061        options: EnqueueOptions,
1062    ) -> JournioResult<WorkflowHandle> {
1063        if queue_name.is_empty() {
1064            return Err(JournioError::new(
1065                JournioErrorCode::InitializationError,
1066                "queue_name cannot be empty",
1067            ));
1068        }
1069        let launch = if options.delay_until.is_some() {
1070            WorkflowLaunch::Delayed
1071        } else {
1072            WorkflowLaunch::Enqueued
1073        };
1074        self.start_workflow(
1075            name,
1076            input,
1077            launch,
1078            Some(queue_name.to_string()),
1079            Some(options),
1080            None,
1081            None,
1082        )
1083        .await
1084    }
1085
1086    /// Register or replace a persisted cron schedule.
1087    pub async fn register_schedule(
1088        self: &Arc<Self>,
1089        schedule_name: &str,
1090        workflow_name: &str,
1091        cron_spec: &str,
1092        context: Interchange,
1093        options: ScheduleOptions,
1094    ) -> JournioResult<()> {
1095        if self.registry.get(workflow_name).is_none() {
1096            return Err(JournioError::new(
1097                JournioErrorCode::InitializationError,
1098                format!("workflow {workflow_name} is not registered"),
1099            ));
1100        }
1101        validate_schedule_spec(cron_spec)?;
1102
1103        let schedule = WorkflowSchedule {
1104            schedule_id: Uuid::new_v4().to_string(),
1105            schedule_name: schedule_name.to_string(),
1106            workflow_name: workflow_name.to_string(),
1107            workflow_class_name: options.workflow_class_name,
1108            schedule: cron_spec.to_string(),
1109            status: options.status.unwrap_or(ScheduleStatus::Active),
1110            context,
1111            last_fired_at: options.last_fired_at.or_else(|| Some(Utc::now())),
1112            automatic_backfill: options.automatic_backfill,
1113            cron_timezone: options.cron_timezone,
1114            queue_name: options.queue_name,
1115        };
1116        self.system_db.upsert_schedule(&schedule).await
1117    }
1118
1119    pub async fn register_queue(
1120        self: &Arc<Self>,
1121        queue_name: &str,
1122        options: QueueOptions,
1123    ) -> JournioResult<QueueConfig> {
1124        validate_queue_options(queue_name, &options)?;
1125        let queue = QueueConfig {
1126            queue_id: Uuid::new_v4().to_string(),
1127            name: queue_name.to_string(),
1128            concurrency: options.concurrency,
1129            worker_concurrency: options.worker_concurrency,
1130            rate_limit_max: options.rate_limit_max,
1131            rate_limit_period_sec: options.rate_limit_period.map(|d| d.as_secs_f64()),
1132            priority_enabled: options.priority_enabled,
1133            partition_queue: options.partition_queue,
1134            polling_interval_sec: options
1135                .polling_interval
1136                .unwrap_or(Duration::from_secs(1))
1137                .as_secs_f64(),
1138        };
1139        self.system_db.upsert_queue(&queue).await?;
1140        self.system_db.get_queue(queue_name).await?.ok_or_else(|| {
1141            JournioError::new(
1142                JournioErrorCode::InitializationError,
1143                format!("queue {queue_name} missing after registration"),
1144            )
1145        })
1146    }
1147
1148    pub async fn cancel_workflow(&self, workflow_id: &str) -> JournioResult<bool> {
1149        Ok(self
1150            .system_db
1151            .cancel_workflows(&[workflow_id.to_string()])
1152            .await?
1153            .iter()
1154            .any(|candidate| candidate == workflow_id))
1155    }
1156
1157    pub async fn cancel_workflows(&self, workflow_ids: &[String]) -> JournioResult<Vec<String>> {
1158        self.system_db.cancel_workflows(workflow_ids).await
1159    }
1160
1161    pub async fn resume_workflow(
1162        &self,
1163        workflow_id: &str,
1164        queue_name: Option<&str>,
1165    ) -> JournioResult<bool> {
1166        Ok(self
1167            .system_db
1168            .resume_workflows(&[workflow_id.to_string()], queue_name)
1169            .await?
1170            .iter()
1171            .any(|candidate| candidate == workflow_id))
1172    }
1173
1174    pub async fn resume_workflows(
1175        &self,
1176        workflow_ids: &[String],
1177        queue_name: Option<&str>,
1178    ) -> JournioResult<Vec<String>> {
1179        self.system_db
1180            .resume_workflows(workflow_ids, queue_name)
1181            .await
1182    }
1183
1184    pub async fn get_workflow_children(
1185        &self,
1186        workflow_id: &str,
1187    ) -> JournioResult<Vec<WorkflowStatus>> {
1188        self.system_db.get_workflow_children(workflow_id).await
1189    }
1190
1191    pub async fn fork_workflow(
1192        self: &Arc<Self>,
1193        original_workflow_id: &str,
1194        options: ForkWorkflowOptions,
1195    ) -> JournioResult<WorkflowHandle> {
1196        if original_workflow_id.is_empty() {
1197            return Err(JournioError::new(
1198                JournioErrorCode::InitializationError,
1199                "original workflow ID cannot be empty",
1200            ));
1201        }
1202        if options.queue_partition_key.is_some() && options.queue_name.is_none() {
1203            return Err(JournioError::new(
1204                JournioErrorCode::InitializationError,
1205                "queue partition key requires a queue name",
1206            ));
1207        }
1208        let start_step = i32::try_from(options.start_step).map_err(|_| {
1209            JournioError::new(
1210                JournioErrorCode::InitializationError,
1211                format!("start step too large: {}", options.start_step),
1212            )
1213        })?;
1214        let workflow_id = self
1215            .system_db
1216            .fork_workflow(ForkWorkflow {
1217                original_workflow_id: original_workflow_id.to_string(),
1218                forked_workflow_id: options.workflow_id,
1219                start_step,
1220                application_version: options.application_version,
1221                queue_name: options.queue_name,
1222                queue_partition_key: options.queue_partition_key,
1223            })
1224            .await?;
1225        Ok(self.workflow_handle(workflow_id))
1226    }
1227
1228    /// `Send` from outside a workflow — ported from the non-workflow branch of
1229    /// `Send` (`workflow.go:2402`). Inserts the notification directly (no
1230    /// checkpoint; the caller is not durably executing).
1231    pub async fn send(
1232        self: &Arc<Self>,
1233        destination_id: &str,
1234        message: Interchange,
1235        topic: &str,
1236    ) -> JournioResult<()> {
1237        self.system_db.send(destination_id, topic, &message).await
1238    }
1239
1240    /// `GetEvent` from outside a workflow — ported from the optional-state
1241    /// branch of `GetEvent` (`workflow.go:2634`). Polls for the value without
1242    /// checkpointing (the caller is not durably executing). Returns
1243    /// `Interchange::Null` on timeout.
1244    pub async fn get_event(
1245        self: &Arc<Self>,
1246        target_workflow_id: &str,
1247        key: &str,
1248        timeout: Duration,
1249    ) -> JournioResult<Interchange> {
1250        let deadline = Instant::now() + timeout;
1251        loop {
1252            if let Some(value) = self
1253                .system_db
1254                .get_event_value(target_workflow_id, key)
1255                .await?
1256            {
1257                return Ok(value);
1258            }
1259            if Instant::now() >= deadline {
1260                return Ok(Interchange::Null);
1261            }
1262            sleep(POLL_INTERVAL).await;
1263        }
1264    }
1265
1266    /// Debounce workflow execution by `key`, coalescing repeated invocations
1267    /// into a single target workflow run that receives the latest input.
1268    pub async fn debounce_workflow(
1269        self: &Arc<Self>,
1270        workflow_name: &str,
1271        key: &str,
1272        delay: Duration,
1273        input: Interchange,
1274        mut options: DebounceOptions,
1275    ) -> JournioResult<WorkflowHandle> {
1276        let target_workflow_id = options
1277            .workflow_id
1278            .take()
1279            .unwrap_or_else(|| Uuid::new_v4().to_string());
1280        let message_id = Uuid::new_v4().to_string();
1281        self.debounce_workflow_inner(
1282            workflow_name,
1283            key,
1284            delay,
1285            input,
1286            options,
1287            target_workflow_id,
1288            message_id,
1289        )
1290        .await
1291    }
1292
1293    /// Read a durable stream until it is closed, the workflow becomes
1294    /// inactive, or snapshot mode drains the current contents.
1295    pub async fn read_stream(
1296        self: &Arc<Self>,
1297        workflow_id: &str,
1298        key: &str,
1299        options: ReadStreamOptions,
1300    ) -> JournioResult<(Vec<Interchange>, bool)> {
1301        let mut offset = options.from_offset;
1302        let mut values = Vec::new();
1303
1304        loop {
1305            let (entries, closed) = self.system_db.read_stream(workflow_id, key, offset).await?;
1306            for entry in entries {
1307                offset = entry.offset + 1;
1308                values.push(decode_stream_entry(self, workflow_id, key, &entry)?);
1309            }
1310
1311            if closed {
1312                return Ok((values, true));
1313            }
1314            if options.snapshot {
1315                return Ok((values, false));
1316            }
1317
1318            let Some(status) = self.system_db.get_workflow_status(workflow_id).await? else {
1319                return Err(crate::error::constructors::non_existent_workflow(
1320                    workflow_id,
1321                ));
1322            };
1323            if !stream_workflow_is_active(status.status) {
1324                return Ok((values, true));
1325            }
1326
1327            self.system_db
1328                .wait_for_stream(workflow_id, key, LISTENER_WAIT_CAP)
1329                .await?;
1330        }
1331    }
1332
1333    /// Dequeue and execute one queued workflow from `queue_name`.
1334    pub async fn run_queue_once(
1335        self: &Arc<Self>,
1336        queue_name: &str,
1337    ) -> JournioResult<Option<WorkflowHandle>> {
1338        let executor_id = self.config.executor_id.clone().unwrap_or_default();
1339        let Some(status) = self
1340            .system_db
1341            .dequeue_workflow(queue_name, &executor_id)
1342            .await?
1343        else {
1344            return Ok(None);
1345        };
1346
1347        let handle = self.workflow_handle(status.id.clone());
1348        let input = status.input.unwrap_or(Interchange::Null);
1349        self.execute_workflow(&status.id, &status.name, input)
1350            .await?;
1351        Ok(Some(handle))
1352    }
1353
1354    pub async fn run_all_queues_once(self: &Arc<Self>) -> JournioResult<usize> {
1355        let mut queue_names = self.system_db.list_runnable_queues().await?;
1356        if let Some(allowed) = &self.config.listen_queues {
1357            queue_names.retain(|queue_name| allowed.iter().any(|allowed| allowed == queue_name));
1358        }
1359        let mut processed = 0usize;
1360        for queue_name in queue_names {
1361            while self.run_queue_once(&queue_name).await?.is_some() {
1362                processed += 1;
1363            }
1364        }
1365        Ok(processed)
1366    }
1367
1368    /// Recover PENDING workflows owned by this executor — ported from
1369    /// `workflowRecovery` in `recovery.go`.
1370    async fn recover(self: &Arc<Self>) -> JournioResult<()> {
1371        let pending = self
1372            .system_db
1373            .get_workflows_for_recovery(&self.config.executor_id.clone().unwrap_or_default())
1374            .await?;
1375        tracing::info!(count = pending.len(), "recovered workflows");
1376        for workflow in pending {
1377            let Some(input) = workflow.input.clone() else {
1378                tracing::warn!(workflow_id = %workflow.id, "skipping recovery for workflow without input");
1379                continue;
1380            };
1381            self.execute_workflow(&workflow.id, &workflow.name, input)
1382                .await?;
1383        }
1384        Ok(())
1385    }
1386
1387    /// Expose the steps recorded for a workflow (admin/debug).
1388    pub async fn get_workflow_steps(&self, workflow_id: &str) -> JournioResult<Vec<StepRecord>> {
1389        self.system_db.get_steps(workflow_id).await
1390    }
1391
1392    /// List workflows with rich filtering — delegates to the system DB.
1393    /// Public accessor for the admin server.
1394    pub async fn list_workflows_filtered(
1395        &self,
1396        filter: &ListWorkflowsFilter,
1397    ) -> JournioResult<Vec<WorkflowStatus>> {
1398        self.system_db.list_workflows_filtered(filter).await
1399    }
1400
1401    /// Recover PENDING workflows for the given executors — ported from
1402    /// `recoverPendingWorkflows` (`recovery.go`). The admin server exposes
1403    /// this via `POST /journio-workflow-recovery`. Returns the IDs of workflows
1404    /// that were re-executed.
1405    pub async fn recover_workflows(
1406        self: &Arc<Self>,
1407        executor_ids: &[String],
1408    ) -> JournioResult<Vec<String>> {
1409        let mut recovered = Vec::new();
1410        for executor_id in executor_ids {
1411            let pending = self
1412                .system_db
1413                .get_workflows_for_recovery(executor_id)
1414                .await?;
1415            for workflow in pending {
1416                let Some(input) = workflow.input.clone() else {
1417                    tracing::warn!(
1418                        workflow_id = %workflow.id,
1419                        "skipping recovery for workflow without input"
1420                    );
1421                    continue;
1422                };
1423                self.execute_workflow(&workflow.id, &workflow.name, input)
1424                    .await?;
1425                recovered.push(workflow.id);
1426            }
1427        }
1428        Ok(recovered)
1429    }
1430
1431    /// Cancel all PENDING/ENQUEUED/DELAYED workflows created before `cutoff` —
1432    /// ported from `cancelAllBefore` (`system_database.go`). The admin server
1433    /// exposes this via `POST /journio-global-timeout`.
1434    pub async fn cancel_all_before(&self, cutoff: DateTime<Utc>) -> JournioResult<()> {
1435        let workflows = self
1436            .system_db
1437            .list_workflows_filtered(&ListWorkflowsFilter {
1438                end_time: Some(cutoff),
1439                statuses: vec![
1440                    WorkflowStatusType::Pending,
1441                    WorkflowStatusType::Enqueued,
1442                    WorkflowStatusType::Delayed,
1443                ],
1444                limit: Some(0),
1445                ..Default::default()
1446            })
1447            .await?;
1448        let ids: Vec<String> = workflows.into_iter().map(|wf| wf.id).collect();
1449        if !ids.is_empty() {
1450            self.system_db.cancel_workflows(&ids).await?;
1451        }
1452        Ok(())
1453    }
1454
1455    /// List all registered queue configurations — ported from
1456    /// `queueRunner.listQueues`. The admin server exposes this via
1457    /// `GET /journio-workflow-queues-metadata`.
1458    pub async fn list_queue_metadata(&self) -> JournioResult<Vec<QueueConfig>> {
1459        self.system_db.list_queues().await
1460    }
1461
1462    /// Construct a handle for an already-known workflow id.
1463    pub fn workflow_handle(self: &Arc<Self>, workflow_id: impl Into<String>) -> WorkflowHandle {
1464        WorkflowHandle {
1465            workflow_id: workflow_id.into(),
1466            journio: Arc::downgrade(self),
1467        }
1468    }
1469
1470    pub fn now(&self) -> DateTime<Utc> {
1471        Utc::now()
1472    }
1473
1474    /// Borrow the system database — exposed for the admin server and advanced
1475    /// callers that need direct persistence access.
1476    pub fn system_db(&self) -> &Arc<dyn SystemDatabase> {
1477        &self.system_db
1478    }
1479
1480    // Internal dispatch helper; the argument list mirrors the Go API.
1481    #[allow(clippy::too_many_arguments)]
1482    async fn debounce_workflow_inner(
1483        self: &Arc<Self>,
1484        workflow_name: &str,
1485        key: &str,
1486        delay: Duration,
1487        input: Interchange,
1488        options: DebounceOptions,
1489        target_workflow_id: String,
1490        message_id: String,
1491    ) -> JournioResult<WorkflowHandle> {
1492        if self.registry.get(workflow_name).is_none() {
1493            return Err(JournioError::new(
1494                JournioErrorCode::InitializationError,
1495                format!("workflow {workflow_name} is not registered"),
1496            ));
1497        }
1498
1499        let debouncer_key = debounce_deduplication_key(workflow_name, key);
1500        let debouncer_input = DebouncerWorkflowInput {
1501            initial_input: input.clone(),
1502            target_workflow_name: workflow_name.to_string(),
1503            target_workflow_id: target_workflow_id.clone(),
1504            delay_ms: duration_to_millis_u64(delay)?,
1505            timeout_ms: options
1506                .debounce_timeout
1507                .map(duration_to_millis_u64)
1508                .transpose()?,
1509            queue_name: options.queue_name,
1510            application_version: options.application_version,
1511            deduplication_id: options.deduplication_id,
1512            priority: options.priority,
1513            queue_partition_key: options.queue_partition_key,
1514            workflow_timeout_ms: options
1515                .workflow_timeout
1516                .map(duration_to_millis_u64)
1517                .transpose()?,
1518        };
1519
1520        loop {
1521            let result = self
1522                .enqueue_workflow(
1523                    INTERNAL_QUEUE_NAME,
1524                    INTERNAL_DEBOUNCER_WORKFLOW_NAME,
1525                    serde_json::to_value(&debouncer_input).map_err(|err| {
1526                        JournioError::new(
1527                            JournioErrorCode::InitializationError,
1528                            format!("failed to serialize debouncer input: {err}"),
1529                        )
1530                    })?,
1531                    EnqueueOptions {
1532                        deduplication_id: Some(debouncer_key.clone()),
1533                        ..Default::default()
1534                    },
1535                )
1536                .await;
1537
1538            match result {
1539                Ok(_) => {
1540                    return Ok(self.workflow_handle(target_workflow_id.clone()));
1541                }
1542                Err(err) if err.code == JournioErrorCode::QueueDeduplicated => {
1543                    let Some(existing) = self
1544                        .find_existing_debouncer_workflow(&debouncer_key)
1545                        .await?
1546                    else {
1547                        continue;
1548                    };
1549
1550                    self.send(
1551                        &existing.id,
1552                        serde_json::to_value(DebounceMessage {
1553                            input: input.clone(),
1554                            delay_ms: duration_to_millis_u64(delay)?,
1555                            id: message_id.clone(),
1556                        })
1557                        .map_err(|ser_err| {
1558                            JournioError::new(
1559                                JournioErrorCode::InitializationError,
1560                                format!("failed to serialize debounce message: {ser_err}"),
1561                            )
1562                        })?,
1563                        DEBOUNCER_TOPIC,
1564                    )
1565                    .await?;
1566
1567                    let ack = self
1568                        .get_event(&existing.id, &message_id, Duration::from_secs(2))
1569                        .await?;
1570                    if ack.is_null() {
1571                        continue;
1572                    }
1573
1574                    let existing_input = parse_debouncer_input(&existing)?;
1575                    return Ok(self.workflow_handle(existing_input.target_workflow_id));
1576                }
1577                Err(err) => return Err(err),
1578            }
1579        }
1580    }
1581
1582    // Internal dispatch helper; the argument list mirrors the Go API.
1583    #[allow(clippy::too_many_arguments)]
1584    async fn start_workflow(
1585        self: &Arc<Self>,
1586        name: &str,
1587        input: Interchange,
1588        launch: WorkflowLaunch,
1589        queue_name: Option<String>,
1590        enqueue: Option<EnqueueOptions>,
1591        parent_workflow_id: Option<String>,
1592        child_checkpoint: Option<ChildCheckpoint>,
1593    ) -> JournioResult<WorkflowHandle> {
1594        // Only an immediately-executed workflow needs to be registered locally —
1595        // an enqueued/delayed workflow is picked up by some executor process
1596        // (which owns the registration). Mirrors Go's `Client.Enqueue`, which
1597        // inserts the row directly without consulting the registry.
1598        if matches!(
1599            launch,
1600            WorkflowLaunch::Immediate | WorkflowLaunch::Background
1601        ) && self.registry.get(name).is_none()
1602        {
1603            return Err(JournioError::new(
1604                JournioErrorCode::InitializationError,
1605                format!("workflow {name} is not registered"),
1606            ));
1607        }
1608        validate_enqueue_options(&queue_name, &enqueue)?;
1609
1610        if let Some(queue_name) = queue_name.as_deref() {
1611            if let Some(queue) = self.system_db.get_queue(queue_name).await? {
1612                validate_queue_assignment(name, queue_name, &queue, enqueue.as_ref())?;
1613            }
1614        }
1615
1616        let workflow_id = enqueue
1617            .as_ref()
1618            .and_then(|opts| opts.workflow_id.clone())
1619            .unwrap_or_else(|| Uuid::new_v4().to_string());
1620        let mut init = InitWorkflow::new_pending(
1621            workflow_id.clone(),
1622            name.to_string(),
1623            self.config.executor_id.clone().unwrap_or_default(),
1624        );
1625        init.status = match launch {
1626            WorkflowLaunch::Immediate | WorkflowLaunch::Background => WorkflowStatusType::Pending,
1627            WorkflowLaunch::Enqueued => WorkflowStatusType::Enqueued,
1628            WorkflowLaunch::Delayed => WorkflowStatusType::Delayed,
1629        };
1630        init.input = Some(input.clone());
1631        init.parent_workflow_id = parent_workflow_id;
1632        init.application_version = enqueue
1633            .as_ref()
1634            .and_then(|opts| opts.application_version.clone())
1635            .or_else(|| self.config.application_version.clone());
1636        init.application_id = Some(self.config.app_name.clone());
1637        init.serialization = Some(self.config.serializer.name().to_string());
1638        init.queue_name = queue_name;
1639        if let Some(opts) = enqueue {
1640            init.deduplication_id = opts.deduplication_id;
1641            init.priority = opts.priority;
1642            init.queue_partition_key = opts.queue_partition_key;
1643            init.timeout = opts.timeout;
1644            init.delay_until = opts.delay_until;
1645        }
1646
1647        self.system_db.init_workflow(init).await?;
1648
1649        if let Some(checkpoint) = child_checkpoint {
1650            self.system_db
1651                .record_step_output(&StepRecord {
1652                    workflow_uuid: checkpoint.parent_workflow_id,
1653                    function_id: checkpoint.function_id,
1654                    function_name: checkpoint.function_name,
1655                    output: None,
1656                    error: None,
1657                    child_workflow_id: Some(workflow_id.clone()),
1658                })
1659                .await?;
1660        }
1661
1662        if matches!(launch, WorkflowLaunch::Immediate) {
1663            self.execute_workflow(&workflow_id, name, input).await?;
1664        } else if matches!(launch, WorkflowLaunch::Background) {
1665            let ctx = self.clone();
1666            let workflow_id = workflow_id.clone();
1667            let name = name.to_string();
1668            tokio::spawn(async move {
1669                if let Err(err) = ctx.execute_workflow(&workflow_id, &name, input).await {
1670                    tracing::error!(workflow_id = %workflow_id, error = %err, "background workflow failed");
1671                }
1672            });
1673        }
1674
1675        Ok(WorkflowHandle {
1676            workflow_id,
1677            journio: Arc::downgrade(self),
1678        })
1679    }
1680
1681    async fn execute_workflow(
1682        self: &Arc<Self>,
1683        workflow_id: &str,
1684        name: &str,
1685        input: Interchange,
1686    ) -> JournioResult<Interchange> {
1687        let workflow = self.registry.get(name).ok_or_else(|| {
1688            JournioError::new(
1689                JournioErrorCode::InitializationError,
1690                format!("workflow {name} is not registered"),
1691            )
1692        })?;
1693
1694        let ctx = WorkflowContext {
1695            inner: Arc::new(WorkflowCtxInner {
1696                workflow_id: workflow_id.to_string(),
1697                step_counter: AtomicI32::new(0),
1698                step_execution_depth: AtomicI32::new(0),
1699                journio: Arc::downgrade(self),
1700                cancel: self.cancel.child_token(),
1701                authenticated_user: RwLock::new(None),
1702                assumed_role: RwLock::new(None),
1703            }),
1704        };
1705
1706        match workflow.run(&ctx, input).await {
1707            Ok(output) => {
1708                self.system_db
1709                    .record_workflow_result(
1710                        workflow_id,
1711                        WorkflowStatusType::Success,
1712                        Some(&output),
1713                        None,
1714                    )
1715                    .await?;
1716                Ok(output)
1717            }
1718            Err(err) => {
1719                let terminal_status = if err.code == JournioErrorCode::WorkflowCancelled {
1720                    WorkflowStatusType::Cancelled
1721                } else {
1722                    WorkflowStatusType::Error
1723                };
1724                self.system_db
1725                    .record_workflow_result(workflow_id, terminal_status, None, Some(&err.message))
1726                    .await?;
1727                Err(err)
1728            }
1729        }
1730    }
1731
1732    async fn find_existing_debouncer_workflow(
1733        &self,
1734        deduplication_id: &str,
1735    ) -> JournioResult<Option<WorkflowStatus>> {
1736        let workflows = self.system_db.list_workflows(10_000).await?;
1737        Ok(workflows.into_iter().find(|workflow| {
1738            workflow.name == INTERNAL_DEBOUNCER_WORKFLOW_NAME
1739                && workflow.queue_name.as_deref() == Some(INTERNAL_QUEUE_NAME)
1740                && workflow.deduplication_id.as_deref() == Some(deduplication_id)
1741                && matches!(
1742                    workflow.status,
1743                    WorkflowStatusType::Pending
1744                        | WorkflowStatusType::Enqueued
1745                        | WorkflowStatusType::Delayed
1746                )
1747        }))
1748    }
1749
1750    fn spawn_background_loops(self: &Arc<Self>) {
1751        let queue_ctx = self.clone();
1752        tokio::spawn(async move {
1753            queue_ctx.run_queue_worker_loop().await;
1754        });
1755
1756        let scheduler_ctx = self.clone();
1757        tokio::spawn(async move {
1758            scheduler_ctx.run_scheduler_loop().await;
1759        });
1760    }
1761
1762    async fn run_queue_worker_loop(self: Arc<Self>) {
1763        loop {
1764            if self.cancel.is_cancelled() {
1765                return;
1766            }
1767
1768            match self.run_all_queues_once().await {
1769                Ok(processed) if processed > 0 => continue,
1770                Ok(_) => sleep(POLL_INTERVAL).await,
1771                Err(err) => {
1772                    tracing::warn!(error = %err, "queue worker loop iteration failed");
1773                    sleep(POLL_INTERVAL).await;
1774                }
1775            }
1776        }
1777    }
1778
1779    async fn run_scheduler_loop(self: Arc<Self>) {
1780        loop {
1781            if self.cancel.is_cancelled() {
1782                return;
1783            }
1784
1785            if let Err(err) = self.run_scheduler_once().await {
1786                tracing::warn!(error = %err, "scheduler loop iteration failed");
1787            }
1788
1789            tokio::select! {
1790                _ = self.cancel.cancelled() => return,
1791                _ = sleep(self.config.scheduler_polling_interval) => {}
1792            }
1793        }
1794    }
1795
1796    async fn run_scheduler_once(self: &Arc<Self>) -> JournioResult<()> {
1797        let schedules = self.system_db.list_schedules().await?;
1798        let now = Utc::now();
1799
1800        for schedule in schedules {
1801            if schedule.status != ScheduleStatus::Active {
1802                continue;
1803            }
1804
1805            let spec = parse_schedule(&schedule.schedule)?;
1806            let Some(last_fired_at) = schedule.last_fired_at else {
1807                self.system_db
1808                    .update_schedule_last_fired_at(&schedule.schedule_name, now)
1809                    .await?;
1810                continue;
1811            };
1812
1813            let due_times =
1814                due_schedule_times(&spec, last_fired_at, now, schedule.automatic_backfill);
1815            if due_times.is_empty() {
1816                continue;
1817            }
1818
1819            let queue_name = schedule
1820                .queue_name
1821                .clone()
1822                .unwrap_or_else(|| INTERNAL_QUEUE_NAME.to_string());
1823
1824            for scheduled_time in &due_times {
1825                let workflow_id = format!(
1826                    "sched-{}-{}",
1827                    schedule.schedule_name,
1828                    scheduled_time.to_rfc3339()
1829                );
1830                if self
1831                    .system_db
1832                    .get_workflow_status(&workflow_id)
1833                    .await?
1834                    .is_some()
1835                {
1836                    continue;
1837                }
1838
1839                let input = serde_json::to_value(ScheduledWorkflowInput {
1840                    scheduled_time: *scheduled_time,
1841                    context: schedule.context.clone(),
1842                })
1843                .map_err(|err| {
1844                    JournioError::new(
1845                        JournioErrorCode::InitializationError,
1846                        format!(
1847                            "failed to serialize scheduled workflow input for {}: {err}",
1848                            schedule.schedule_name
1849                        ),
1850                    )
1851                })?;
1852
1853                self.enqueue_workflow(
1854                    &queue_name,
1855                    &schedule.workflow_name,
1856                    input,
1857                    EnqueueOptions {
1858                        workflow_id: Some(workflow_id),
1859                        ..Default::default()
1860                    },
1861                )
1862                .await?;
1863            }
1864
1865            if let Some(last) = due_times.last().copied() {
1866                self.system_db
1867                    .update_schedule_last_fired_at(&schedule.schedule_name, last)
1868                    .await?;
1869            }
1870        }
1871
1872        Ok(())
1873    }
1874}
1875
1876struct ChildCheckpoint {
1877    parent_workflow_id: String,
1878    function_id: i32,
1879    function_name: String,
1880}
1881
1882#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1883enum WorkflowLaunch {
1884    Immediate,
1885    Background,
1886    Enqueued,
1887    Delayed,
1888}
1889
1890fn validate_schedule_spec(spec: &str) -> JournioResult<()> {
1891    parse_schedule(spec).map(|_| ())
1892}
1893
1894fn parse_schedule(spec: &str) -> JournioResult<Schedule> {
1895    Schedule::from_str(spec).map_err(|err| {
1896        JournioError::new(
1897            JournioErrorCode::InitializationError,
1898            format!("invalid cron schedule {spec:?}: {err}"),
1899        )
1900    })
1901}
1902
1903pub(crate) fn parse_cron_schedule(spec: &str) -> JournioResult<Schedule> {
1904    parse_schedule(spec)
1905}
1906
1907fn due_schedule_times(
1908    schedule: &Schedule,
1909    last_fired_at: DateTime<Utc>,
1910    now: DateTime<Utc>,
1911    automatic_backfill: bool,
1912) -> Vec<DateTime<Utc>> {
1913    let mut upcoming = schedule.after(&last_fired_at);
1914    let mut due = Vec::new();
1915
1916    while let Some(next) = upcoming.next() {
1917        if next > now {
1918            break;
1919        }
1920        due.push(next);
1921        if !automatic_backfill {
1922            due.truncate(1);
1923            for candidate in upcoming.by_ref() {
1924                if candidate > now {
1925                    break;
1926                }
1927                due[0] = candidate;
1928            }
1929            break;
1930        }
1931    }
1932
1933    due
1934}
1935
1936fn resolve_backend(config: &Config) -> JournioResult<Arc<dyn SystemDatabase>> {
1937    if let Some(db) = config.system_db.clone() {
1938        return Ok(db);
1939    }
1940    Err(JournioError::new(
1941        JournioErrorCode::InitializationError,
1942        "no system_db provided: the journio-postgres / journio-sqlite crate must construct the backend \
1943         and inject it via Config.system_db (core is driver-free)",
1944    ))
1945}
1946
1947fn encode_interchange(journio: &JournioContext, value: &Interchange) -> JournioResult<String> {
1948    journio.config.serializer.serialize(value)
1949}
1950
1951fn decode_interchange(
1952    journio: &JournioContext,
1953    workflow_id: &str,
1954    step_id: i32,
1955    step_name: &str,
1956    encoded: Option<String>,
1957) -> JournioResult<Interchange> {
1958    match encoded {
1959        Some(encoded) => journio
1960            .config
1961            .serializer
1962            .deserialize(&encoded)
1963            .map_err(|mut err| {
1964                err.workflow_id = Some(workflow_id.to_string());
1965                err.step_id = Some(step_id);
1966                err.step_name = Some(step_name.to_string());
1967                err
1968            }),
1969        None => Ok(Interchange::Null),
1970    }
1971}
1972
1973fn decode_stream_entry(
1974    journio: &JournioContext,
1975    workflow_id: &str,
1976    key: &str,
1977    entry: &crate::types::StreamEntry,
1978) -> JournioResult<Interchange> {
1979    journio.config
1980        .serializer
1981        .deserialize(&entry.value)
1982        .map_err(|err| {
1983            JournioError::new(
1984                JournioErrorCode::WorkflowUnexpectedTypeError,
1985                format!(
1986                    "failed to decode stream entry for workflow {workflow_id}, key {key} with serialization {:?}: {err}",
1987                    entry.serialization.as_deref().unwrap_or(journio.config.serializer.name())
1988                ),
1989            )
1990        })
1991}
1992
1993fn stream_workflow_is_active(status: WorkflowStatusType) -> bool {
1994    matches!(
1995        status,
1996        WorkflowStatusType::Pending | WorkflowStatusType::Enqueued
1997    )
1998}
1999
2000fn duration_to_millis_u64(value: Duration) -> JournioResult<u64> {
2001    u64::try_from(value.as_millis()).map_err(|_| {
2002        JournioError::new(
2003            JournioErrorCode::InitializationError,
2004            "duration is too large to convert to milliseconds",
2005        )
2006    })
2007}
2008
2009fn millis_to_duration(value: u64) -> Duration {
2010    Duration::from_millis(value)
2011}
2012
2013fn debounce_deduplication_key(workflow_name: &str, key: &str) -> String {
2014    format!("debounce::{workflow_name}::{key}")
2015}
2016
2017fn validate_queue_options(queue_name: &str, options: &QueueOptions) -> JournioResult<()> {
2018    if queue_name.is_empty() {
2019        return Err(JournioError::new(
2020            JournioErrorCode::InitializationError,
2021            "queue_name cannot be empty",
2022        ));
2023    }
2024    if let (Some(worker), Some(global)) = (options.worker_concurrency, options.concurrency) {
2025        if worker > global {
2026            return Err(JournioError::new(
2027                JournioErrorCode::InitializationError,
2028                format!(
2029                    "queue {queue_name}: concurrency must be greater than or equal to worker_concurrency"
2030                ),
2031            ));
2032        }
2033    }
2034    if let Some(limit) = options.rate_limit_max {
2035        if limit <= 0 {
2036            return Err(JournioError::new(
2037                JournioErrorCode::InitializationError,
2038                format!("queue {queue_name}: rate limiter limit must be positive"),
2039            ));
2040        }
2041    }
2042    if let Some(period) = options.rate_limit_period {
2043        if period.is_zero() {
2044            return Err(JournioError::new(
2045                JournioErrorCode::InitializationError,
2046                format!("queue {queue_name}: rate limiter period must be positive"),
2047            ));
2048        }
2049    }
2050    if let Some(interval) = options.polling_interval {
2051        if interval.is_zero() {
2052            return Err(JournioError::new(
2053                JournioErrorCode::InitializationError,
2054                format!("queue {queue_name}: polling interval must be positive"),
2055            ));
2056        }
2057    }
2058    Ok(())
2059}
2060
2061fn validate_enqueue_options(
2062    queue_name: &Option<String>,
2063    enqueue: &Option<EnqueueOptions>,
2064) -> JournioResult<()> {
2065    if let Some(enqueue) = enqueue.as_ref() {
2066        if enqueue.queue_partition_key.is_some() && queue_name.is_none() {
2067            return Err(JournioError::new(
2068                JournioErrorCode::WorkflowExecutionError,
2069                "queue partition key requires a queue name",
2070            ));
2071        }
2072        if enqueue.queue_partition_key.is_some() && enqueue.deduplication_id.is_some() {
2073            return Err(JournioError::new(
2074                JournioErrorCode::WorkflowExecutionError,
2075                "queue partition key cannot be combined with deduplication_id",
2076            ));
2077        }
2078    }
2079    Ok(())
2080}
2081
2082fn validate_queue_assignment(
2083    workflow_name: &str,
2084    queue_name: &str,
2085    queue: &QueueConfig,
2086    enqueue: Option<&EnqueueOptions>,
2087) -> JournioResult<()> {
2088    let partition_key = enqueue.and_then(|value| value.queue_partition_key.as_deref());
2089    if queue.partition_queue && partition_key.is_none() {
2090        return Err(JournioError::new(
2091            JournioErrorCode::WorkflowExecutionError,
2092            format!(
2093                "queue {queue_name} has partitions enabled, but no partition key was provided for workflow {workflow_name}"
2094            ),
2095        ));
2096    }
2097    if !queue.partition_queue && partition_key.is_some() {
2098        return Err(JournioError::new(
2099            JournioErrorCode::WorkflowExecutionError,
2100            format!(
2101                "queue {queue_name} is not a partitioned queue, but a partition key was provided for workflow {workflow_name}"
2102            ),
2103        ));
2104    }
2105    Ok(())
2106}
2107
2108fn parse_debouncer_input(workflow: &WorkflowStatus) -> JournioResult<DebouncerWorkflowInput> {
2109    let input = workflow.input.clone().ok_or_else(|| {
2110        JournioError::new(
2111            JournioErrorCode::InitializationError,
2112            format!("debouncer workflow {} is missing input", workflow.id),
2113        )
2114    })?;
2115    serde_json::from_value(input).map_err(|err| {
2116        JournioError::new(
2117            JournioErrorCode::InitializationError,
2118            format!("failed to decode debouncer workflow input: {err}"),
2119        )
2120    })
2121}
2122
2123async fn durable_uuid_step(ctx: &WorkflowContext, name: &'static str) -> JournioResult<String> {
2124    let step = Arc::new(crate::workflow::StepFunc::new(name, |_ctx| {
2125        Box::pin(async move { Ok(Uuid::new_v4().to_string()) })
2126    }));
2127    let value = ctx.run_as_step(step).await?;
2128    serde_json::from_value(value).map_err(|err| {
2129        JournioError::new(
2130            JournioErrorCode::WorkflowUnexpectedTypeError,
2131            format!("failed to decode durable UUID step output: {err}"),
2132        )
2133    })
2134}
2135
2136async fn durable_now_step(
2137    ctx: &WorkflowContext,
2138    name: &'static str,
2139) -> JournioResult<DateTime<Utc>> {
2140    let step = Arc::new(crate::workflow::StepFunc::new(name, |_ctx| {
2141        Box::pin(async move { Ok(Utc::now().to_rfc3339()) })
2142    }));
2143    let value = ctx.run_as_step(step).await?;
2144    let encoded: String = serde_json::from_value(value).map_err(|err| {
2145        JournioError::new(
2146            JournioErrorCode::WorkflowUnexpectedTypeError,
2147            format!("failed to decode durable timestamp step output: {err}"),
2148        )
2149    })?;
2150    DateTime::parse_from_rfc3339(&encoded)
2151        .map(|value| value.with_timezone(&Utc))
2152        .map_err(|err| {
2153            JournioError::new(
2154                JournioErrorCode::WorkflowUnexpectedTypeError,
2155                format!("failed to parse durable timestamp {encoded}: {err}"),
2156            )
2157        })
2158}
2159
2160struct InternalDebouncerWorkflow;
2161
2162#[async_trait::async_trait]
2163impl Workflow for InternalDebouncerWorkflow {
2164    fn name(&self) -> &str {
2165        INTERNAL_DEBOUNCER_WORKFLOW_NAME
2166    }
2167
2168    async fn run(&self, ctx: &WorkflowContext, input: Interchange) -> JournioResult<Interchange> {
2169        let input: DebouncerWorkflowInput = serde_json::from_value(input).map_err(|err| {
2170            JournioError::new(
2171                JournioErrorCode::WorkflowUnexpectedTypeError,
2172                format!("failed to decode internal debouncer input: {err}"),
2173            )
2174        })?;
2175
2176        let start_time = durable_now_step(ctx, "journio.debounce.startTime").await?;
2177        let max_start_time = input.timeout_ms.map(|timeout_ms| {
2178            start_time
2179                + chrono::Duration::from_std(millis_to_duration(timeout_ms))
2180                    .unwrap_or_else(|_| chrono::Duration::milliseconds(i64::MAX))
2181        });
2182
2183        let mut current_input = input.initial_input.clone();
2184        let mut target_start_time = start_time
2185            + chrono::Duration::from_std(millis_to_duration(input.delay_ms))
2186                .unwrap_or_else(|_| chrono::Duration::milliseconds(i64::MAX));
2187        if let Some(max_start_time) = max_start_time {
2188            if target_start_time > max_start_time {
2189                target_start_time = max_start_time;
2190            }
2191        }
2192
2193        loop {
2194            let now = durable_now_step(ctx, "journio.debounce.loopTime").await?;
2195            let remaining = target_start_time
2196                .signed_duration_since(now)
2197                .to_std()
2198                .unwrap_or(Duration::ZERO);
2199            if remaining.is_zero() {
2200                break;
2201            }
2202
2203            match ctx.recv(DEBOUNCER_TOPIC, remaining).await {
2204                Ok(message) => {
2205                    let message: DebounceMessage =
2206                        serde_json::from_value(message).map_err(|err| {
2207                            JournioError::new(
2208                                JournioErrorCode::WorkflowUnexpectedTypeError,
2209                                format!("failed to decode debounce message: {err}"),
2210                            )
2211                        })?;
2212                    current_input = message.input;
2213                    let mut next_target_start = now
2214                        + chrono::Duration::from_std(millis_to_duration(message.delay_ms))
2215                            .unwrap_or_else(|_| chrono::Duration::milliseconds(i64::MAX));
2216                    if let Some(max_start_time) = max_start_time {
2217                        if next_target_start > max_start_time {
2218                            next_target_start = max_start_time;
2219                        }
2220                    }
2221                    target_start_time = next_target_start;
2222                    if !message.id.is_empty() {
2223                        ctx.set_event(&message.id, serde_json::json!(true)).await?;
2224                    }
2225                }
2226                Err(err) if err.code == JournioErrorCode::TimeoutError => break,
2227                Err(err) => return Err(err),
2228            }
2229        }
2230
2231        let journio = ctx.journio()?;
2232        let mut launch = EnqueueOptions {
2233            workflow_id: Some(input.target_workflow_id.clone()),
2234            application_version: input.application_version.clone(),
2235            deduplication_id: input.deduplication_id.clone(),
2236            priority: input.priority,
2237            queue_partition_key: input.queue_partition_key.clone(),
2238            timeout: input.workflow_timeout_ms.map(millis_to_duration),
2239            ..Default::default()
2240        };
2241
2242        if let Some(queue_name) = input.queue_name.as_deref() {
2243            journio
2244                .enqueue_workflow(
2245                    queue_name,
2246                    &input.target_workflow_name,
2247                    current_input,
2248                    launch,
2249                )
2250                .await?;
2251        } else {
2252            launch.deduplication_id = None;
2253            journio
2254                .start_workflow(
2255                    &input.target_workflow_name,
2256                    current_input,
2257                    WorkflowLaunch::Immediate,
2258                    None,
2259                    Some(launch),
2260                    None,
2261                    None,
2262                )
2263                .await?;
2264        }
2265
2266        Ok(Interchange::Null)
2267    }
2268}
2269
2270fn validate_recorded_step(
2271    workflow_id: &str,
2272    step_id: i32,
2273    expected_name: &str,
2274    recorded_name: &str,
2275) -> JournioResult<()> {
2276    if expected_name != recorded_name {
2277        return Err(crate::error::constructors::unexpected_step(
2278            workflow_id,
2279            step_id,
2280            expected_name,
2281            recorded_name,
2282        ));
2283    }
2284    Ok(())
2285}
2286
2287fn validate_patching_enabled(journio: &JournioContext) -> JournioResult<()> {
2288    if journio.config.enable_patching {
2289        return Ok(());
2290    }
2291    Err(JournioError::new(
2292        JournioErrorCode::PatchingNotEnabled,
2293        "Patching system is not enabled. Set enable_patching to true in the Journio context configuration to use patch and deprecate_patch",
2294    ))
2295}
2296
2297fn validate_patch_name(patch_name: &str) -> JournioResult<()> {
2298    if patch_name.is_empty() {
2299        return Err(JournioError::new(
2300            JournioErrorCode::StepExecutionError,
2301            "patch name cannot be empty",
2302        ));
2303    }
2304    Ok(())
2305}
2306
2307fn validate_not_within_step(ctx: &WorkflowContext) -> JournioResult<()> {
2308    if !ctx.is_within_step() {
2309        return Ok(());
2310    }
2311
2312    Err(ctx_step_error(
2313        JournioErrorCode::StepExecutionError,
2314        ctx.workflow_id(),
2315        ctx.peek_next_step_id(),
2316        "patching",
2317        "cannot call patching APIs within a step".to_string(),
2318    ))
2319}
2320
2321fn recorded_step_error(
2322    workflow_id: &str,
2323    step_id: i32,
2324    step_name: &str,
2325    message: String,
2326) -> JournioError {
2327    ctx_step_error(
2328        JournioErrorCode::StepExecutionError,
2329        workflow_id,
2330        step_id,
2331        step_name,
2332        message,
2333    )
2334}
2335
2336/// Build a `JournioError` anchored at a workflow step — mirrors Go's
2337/// `newStepExecutionError` / `newTimeoutError` constructors (the only
2338/// difference is the `code`).
2339fn ctx_step_error(
2340    code: JournioErrorCode,
2341    workflow_id: &str,
2342    step_id: i32,
2343    step_name: &str,
2344    message: String,
2345) -> JournioError {
2346    let mut err = JournioError::new(code, message);
2347    err.workflow_id = Some(workflow_id.to_string());
2348    err.step_id = Some(step_id);
2349    err.step_name = Some(step_name.to_string());
2350    err
2351}
2352
2353/// Parse an RFC3339 deadline recorded by `sleep`.
2354fn parse_deadline(value: &Interchange) -> JournioResult<DateTime<Utc>> {
2355    value
2356        .as_str()
2357        .and_then(|s| DateTime::parse_from_rfc3339(s).ok())
2358        .map(|dt| dt.with_timezone(&Utc))
2359        .ok_or_else(|| {
2360            JournioError::new(
2361                JournioErrorCode::StepExecutionError,
2362                "recorded sleep deadline was not a valid RFC3339 timestamp",
2363            )
2364        })
2365}
2366
2367/// Duration from now until `deadline`, clamped at zero.
2368fn remaining_until(deadline: DateTime<Utc>) -> Duration {
2369    let now = Utc::now();
2370    if deadline <= now {
2371        return Duration::ZERO;
2372    }
2373    (deadline - now).to_std().unwrap_or(Duration::ZERO)
2374}
2375
2376fn workflow_terminal_error(
2377    code: JournioErrorCode,
2378    workflow_id: &str,
2379    message: String,
2380) -> JournioError {
2381    let mut err = JournioError::new(code, message);
2382    err.workflow_id = Some(workflow_id.to_string());
2383    err
2384}
2385
2386#[cfg(test)]
2387mod tests {
2388    use super::*;
2389
2390    use std::collections::HashMap;
2391    use std::sync::Mutex;
2392    use std::sync::atomic::{AtomicUsize, Ordering as AtomicOrdering};
2393
2394    use async_trait::async_trait;
2395
2396    use crate::dialect::{Dialect, DialectName};
2397    use crate::system_db::Notification;
2398    use crate::types::{ListWorkflowsFilter, VersionInfo};
2399    use crate::workflow::{StepFunc, WorkflowFn};
2400
2401    /// A stored notification row in the fake DB.
2402    #[derive(Clone)]
2403    struct FakeNotification {
2404        destination_id: String,
2405        topic: String,
2406        message: Interchange,
2407        consumed: bool,
2408    }
2409
2410    #[derive(Clone)]
2411    struct FakeStreamEntry {
2412        workflow_id: String,
2413        key: String,
2414        value: String,
2415        offset: i64,
2416        serialization: Option<String>,
2417    }
2418
2419    #[derive(Default)]
2420    struct FakeState {
2421        workflows: HashMap<String, WorkflowStatus>,
2422        steps: HashMap<String, Vec<StepRecord>>,
2423        notifications: Vec<FakeNotification>,
2424        /// (workflow_uuid, key) → value.
2425        events: HashMap<(String, String), Interchange>,
2426        streams: Vec<FakeStreamEntry>,
2427        queues: HashMap<String, QueueConfig>,
2428        schedules: HashMap<String, WorkflowSchedule>,
2429        application_versions: Vec<VersionInfo>,
2430    }
2431
2432    #[derive(Default)]
2433    struct FakeSystemDatabase {
2434        state: Mutex<FakeState>,
2435    }
2436
2437    /// Matches `_JOURNIO_NULL_TOPIC` / `NULL_TOPIC` in the real backends.
2438    const FAKE_NULL_TOPIC: &str = "__null__topic__";
2439
2440    fn normalize_topic(topic: &str) -> &str {
2441        if topic.is_empty() {
2442            FAKE_NULL_TOPIC
2443        } else {
2444            topic
2445        }
2446    }
2447
2448    #[derive(Clone, Copy)]
2449    struct TestDialect;
2450
2451    impl Dialect for TestDialect {
2452        fn name(&self) -> DialectName {
2453            DialectName::Postgres
2454        }
2455
2456        fn schema_prefix(&self, _schema: &str) -> String {
2457            String::new()
2458        }
2459
2460        fn rewrite_query(&self, query: &str) -> String {
2461            query.to_string()
2462        }
2463
2464        fn lock_skip_locked(&self) -> &str {
2465            "FOR UPDATE SKIP LOCKED"
2466        }
2467
2468        fn lock_nowait(&self) -> &str {
2469            "FOR UPDATE NOWAIT"
2470        }
2471
2472        fn supports_listen_notify(&self) -> bool {
2473            false
2474        }
2475
2476        fn supports_array_parameters(&self) -> bool {
2477            false
2478        }
2479
2480        fn supports_data_modifying_cte(&self) -> bool {
2481            false
2482        }
2483    }
2484
2485    #[async_trait]
2486    impl SystemDatabase for FakeSystemDatabase {
2487        fn dialect(&self) -> &dyn Dialect {
2488            static DIALECT: TestDialect = TestDialect;
2489            &DIALECT
2490        }
2491
2492        async fn migrate(&self) -> JournioResult<()> {
2493            Ok(())
2494        }
2495
2496        async fn launch(&self) -> JournioResult<()> {
2497            Ok(())
2498        }
2499
2500        async fn shutdown(&self) -> JournioResult<()> {
2501            Ok(())
2502        }
2503
2504        async fn init_workflow(
2505            &self,
2506            init: InitWorkflow,
2507        ) -> JournioResult<crate::system_db::InitWorkflowResult> {
2508            let mut state = self.state.lock().expect("fake db lock");
2509            let status = workflow_status_from_init(&init);
2510            state.workflows.insert(init.workflow_id.clone(), status);
2511            Ok(crate::system_db::InitWorkflowResult {
2512                status: init.status,
2513                attempts: 1,
2514                name: init.name,
2515                queue_name: init.queue_name,
2516                queue_partition_key: init.queue_partition_key,
2517                timeout: init.timeout,
2518                deadline: init.deadline,
2519            })
2520        }
2521
2522        async fn record_workflow_result(
2523            &self,
2524            workflow_id: &str,
2525            status: WorkflowStatusType,
2526            output: Option<&Interchange>,
2527            error: Option<&str>,
2528        ) -> JournioResult<()> {
2529            let mut state = self.state.lock().expect("fake db lock");
2530            let existing = state
2531                .workflows
2532                .get_mut(workflow_id)
2533                .expect("workflow exists");
2534            existing.status = status;
2535            existing.output = output.cloned();
2536            existing.error = error.map(ToString::to_string);
2537            existing.updated_at = Utc::now();
2538            existing.completed_at = Some(Utc::now());
2539            Ok(())
2540        }
2541
2542        async fn get_workflow_status(
2543            &self,
2544            workflow_id: &str,
2545        ) -> JournioResult<Option<WorkflowStatus>> {
2546            let state = self.state.lock().expect("fake db lock");
2547            Ok(state.workflows.get(workflow_id).cloned())
2548        }
2549
2550        async fn list_workflows(&self, limit: i64) -> JournioResult<Vec<WorkflowStatus>> {
2551            let state = self.state.lock().expect("fake db lock");
2552            Ok(state
2553                .workflows
2554                .values()
2555                .take(limit as usize)
2556                .cloned()
2557                .collect())
2558        }
2559
2560        async fn list_workflows_filtered(
2561            &self,
2562            filter: &ListWorkflowsFilter,
2563        ) -> JournioResult<Vec<WorkflowStatus>> {
2564            let state = self.state.lock().expect("fake db lock");
2565            let mut rows: Vec<WorkflowStatus> = state
2566                .workflows
2567                .values()
2568                .filter(|wf| matches_filter(wf, filter))
2569                .cloned()
2570                .collect();
2571            rows.sort_by(|left, right| {
2572                if filter.sort_desc {
2573                    right.created_at.cmp(&left.created_at)
2574                } else {
2575                    left.created_at.cmp(&right.created_at)
2576                }
2577            });
2578            if let Some(offset) = filter.offset {
2579                let offset = offset as usize;
2580                if offset >= rows.len() {
2581                    rows.clear();
2582                } else {
2583                    rows.drain(..offset);
2584                }
2585            }
2586            if let Some(limit) = filter.limit {
2587                rows.truncate(limit as usize);
2588            }
2589            Ok(rows)
2590        }
2591
2592        async fn set_workflow_delay(
2593            &self,
2594            workflow_id: &str,
2595            delay_until: DateTime<Utc>,
2596        ) -> JournioResult<()> {
2597            let mut state = self.state.lock().expect("fake db lock");
2598            if let Some(workflow) = state.workflows.get_mut(workflow_id) {
2599                if workflow.status == WorkflowStatusType::Delayed {
2600                    workflow.delay_until = Some(delay_until);
2601                }
2602            }
2603            Ok(())
2604        }
2605
2606        async fn delete_workflows(
2607            &self,
2608            workflow_ids: &[String],
2609            delete_children: bool,
2610        ) -> JournioResult<()> {
2611            let mut state = self.state.lock().expect("fake db lock");
2612            let ids: std::collections::HashSet<&String> = workflow_ids.iter().collect();
2613            let to_delete = if delete_children {
2614                let mut pending: Vec<String> = ids.iter().copied().cloned().collect();
2615                let mut all: std::collections::HashSet<String> = pending.iter().cloned().collect();
2616                while let Some(parent) = pending.pop() {
2617                    for wf in state.workflows.values() {
2618                        if wf.parent_workflow_id.as_deref() == Some(parent.as_str())
2619                            && all.insert(wf.id.clone())
2620                        {
2621                            pending.push(wf.id.clone());
2622                        }
2623                    }
2624                }
2625                all
2626            } else {
2627                ids.into_iter().cloned().collect()
2628            };
2629            for id in &to_delete {
2630                state.workflows.remove(id);
2631                state.steps.remove(id);
2632                state.events.retain(|(workflow_id, _), _| workflow_id != id);
2633            }
2634            Ok(())
2635        }
2636
2637        async fn cancel_workflows(&self, workflow_ids: &[String]) -> JournioResult<Vec<String>> {
2638            let mut state = self.state.lock().expect("fake db lock");
2639            let now = Utc::now();
2640            let mut found = Vec::new();
2641            for workflow_id in workflow_ids {
2642                let Some(workflow) = state.workflows.get_mut(workflow_id) else {
2643                    continue;
2644                };
2645                found.push(workflow_id.clone());
2646                if matches!(
2647                    workflow.status,
2648                    WorkflowStatusType::Success
2649                        | WorkflowStatusType::Error
2650                        | WorkflowStatusType::Cancelled
2651                ) {
2652                    continue;
2653                }
2654                workflow.status = WorkflowStatusType::Cancelled;
2655                workflow.updated_at = now;
2656                workflow.completed_at = Some(now);
2657                workflow.started_at = None;
2658                workflow.queue_name = None;
2659                workflow.deduplication_id = None;
2660            }
2661            Ok(found)
2662        }
2663
2664        async fn resume_workflows(
2665            &self,
2666            workflow_ids: &[String],
2667            queue_name: Option<&str>,
2668        ) -> JournioResult<Vec<String>> {
2669            let mut state = self.state.lock().expect("fake db lock");
2670            let now = Utc::now();
2671            let queue_name = queue_name.unwrap_or(INTERNAL_QUEUE_NAME).to_string();
2672            let mut found = Vec::new();
2673            for workflow_id in workflow_ids {
2674                let Some(workflow) = state.workflows.get_mut(workflow_id) else {
2675                    continue;
2676                };
2677                found.push(workflow_id.clone());
2678                if matches!(
2679                    workflow.status,
2680                    WorkflowStatusType::Success | WorkflowStatusType::Error
2681                ) {
2682                    continue;
2683                }
2684                workflow.status = WorkflowStatusType::Enqueued;
2685                workflow.queue_name = Some(queue_name.clone());
2686                workflow.attempts = 0;
2687                workflow.deadline = None;
2688                workflow.deduplication_id = None;
2689                workflow.started_at = None;
2690                workflow.updated_at = now;
2691                workflow.completed_at = None;
2692            }
2693            Ok(found)
2694        }
2695
2696        async fn get_workflow_children(
2697            &self,
2698            workflow_id: &str,
2699        ) -> JournioResult<Vec<WorkflowStatus>> {
2700            let state = self.state.lock().expect("fake db lock");
2701            let mut queue = vec![workflow_id.to_string()];
2702            let mut children = Vec::new();
2703
2704            while let Some(parent_id) = queue.pop() {
2705                for workflow in state.workflows.values() {
2706                    if workflow.parent_workflow_id.as_deref() == Some(parent_id.as_str()) {
2707                        children.push(workflow.clone());
2708                        queue.push(workflow.id.clone());
2709                    }
2710                }
2711            }
2712
2713            Ok(children)
2714        }
2715
2716        async fn fork_workflow(&self, input: ForkWorkflow) -> JournioResult<String> {
2717            let mut state = self.state.lock().expect("fake db lock");
2718            let original = state
2719                .workflows
2720                .get(&input.original_workflow_id)
2721                .cloned()
2722                .ok_or_else(|| {
2723                    crate::error::constructors::non_existent_workflow(&input.original_workflow_id)
2724                })?;
2725            let forked_workflow_id = input
2726                .forked_workflow_id
2727                .unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
2728            let now = Utc::now();
2729
2730            let mut forked = original.clone();
2731            forked.id = forked_workflow_id.clone();
2732            forked.status = WorkflowStatusType::Enqueued;
2733            forked.output = None;
2734            forked.error = None;
2735            forked.created_at = now;
2736            forked.updated_at = now;
2737            forked.completed_at = None;
2738            forked.started_at = None;
2739            forked.attempts = 0;
2740            forked.queue_name = Some(
2741                input
2742                    .queue_name
2743                    .unwrap_or_else(|| INTERNAL_QUEUE_NAME.to_string()),
2744            );
2745            forked.queue_partition_key = input.queue_partition_key;
2746            forked.application_version = input
2747                .application_version
2748                .unwrap_or_else(|| original.application_version.clone());
2749            forked.forked_from = Some(input.original_workflow_id.clone());
2750            forked.was_forked_from = false;
2751
2752            state.workflows.insert(forked_workflow_id.clone(), forked);
2753            if let Some(existing) = state.workflows.get_mut(&input.original_workflow_id) {
2754                existing.was_forked_from = true;
2755            }
2756
2757            if input.start_step > 0 {
2758                if let Some(steps) = state.steps.get(&input.original_workflow_id).cloned() {
2759                    let copied: Vec<StepRecord> = steps
2760                        .into_iter()
2761                        .filter(|step| step.function_id < input.start_step)
2762                        .map(|mut step| {
2763                            step.workflow_uuid = forked_workflow_id.clone();
2764                            step
2765                        })
2766                        .collect();
2767                    if !copied.is_empty() {
2768                        state.steps.insert(forked_workflow_id.clone(), copied);
2769                    }
2770                }
2771
2772                let latest_events: Vec<_> = state
2773                    .events
2774                    .iter()
2775                    .filter(|((workflow_id, _), _)| workflow_id == &input.original_workflow_id)
2776                    .map(|((_, key), value)| (key.clone(), value.clone()))
2777                    .collect();
2778                for (key, value) in latest_events {
2779                    state
2780                        .events
2781                        .insert((forked_workflow_id.clone(), key), value);
2782                }
2783
2784                let copied_streams: Vec<_> = state
2785                    .streams
2786                    .iter()
2787                    .filter(|entry| {
2788                        entry.workflow_id == input.original_workflow_id
2789                            && entry.offset < i64::from(input.start_step)
2790                    })
2791                    .cloned()
2792                    .collect();
2793                for mut entry in copied_streams {
2794                    entry.workflow_id = forked_workflow_id.clone();
2795                    state.streams.push(entry);
2796                }
2797            }
2798
2799            Ok(forked_workflow_id)
2800        }
2801
2802        async fn get_queue(&self, queue_name: &str) -> JournioResult<Option<QueueConfig>> {
2803            let state = self.state.lock().expect("fake db lock");
2804            Ok(state.queues.get(queue_name).cloned())
2805        }
2806
2807        async fn upsert_queue(&self, queue: &QueueConfig) -> JournioResult<()> {
2808            let mut state = self.state.lock().expect("fake db lock");
2809            state.queues.insert(queue.name.clone(), queue.clone());
2810            Ok(())
2811        }
2812
2813        async fn record_step_output(&self, step: &StepRecord) -> JournioResult<()> {
2814            let mut state = self.state.lock().expect("fake db lock");
2815            let steps = state.steps.entry(step.workflow_uuid.clone()).or_default();
2816            if let Some(existing) = steps
2817                .iter_mut()
2818                .find(|existing| existing.function_id == step.function_id)
2819            {
2820                *existing = step.clone();
2821            } else {
2822                steps.push(step.clone());
2823                steps.sort_by_key(|entry| entry.function_id);
2824            }
2825            Ok(())
2826        }
2827
2828        async fn get_steps(&self, workflow_id: &str) -> JournioResult<Vec<StepRecord>> {
2829            let state = self.state.lock().expect("fake db lock");
2830            Ok(state.steps.get(workflow_id).cloned().unwrap_or_default())
2831        }
2832
2833        async fn dequeue_workflow(
2834            &self,
2835            queue_name: &str,
2836            executor_id: &str,
2837        ) -> JournioResult<Option<WorkflowStatus>> {
2838            let mut state = self.state.lock().expect("fake db lock");
2839            let now = Utc::now();
2840            let candidate_id = state
2841                .workflows
2842                .values()
2843                .filter(|workflow| {
2844                    workflow.queue_name.as_deref() == Some(queue_name)
2845                        && matches!(
2846                            workflow.status,
2847                            WorkflowStatusType::Enqueued | WorkflowStatusType::Delayed
2848                        )
2849                        && match workflow.status {
2850                            WorkflowStatusType::Delayed => workflow
2851                                .delay_until
2852                                .is_none_or(|delay_until| delay_until <= now),
2853                            _ => true,
2854                        }
2855                })
2856                .min_by(|left, right| {
2857                    left.priority
2858                        .cmp(&right.priority)
2859                        .then_with(|| left.created_at.cmp(&right.created_at))
2860                })
2861                .map(|workflow| workflow.id.clone());
2862
2863            let Some(candidate_id) = candidate_id else {
2864                return Ok(None);
2865            };
2866
2867            let workflow = state
2868                .workflows
2869                .get_mut(&candidate_id)
2870                .expect("candidate workflow exists");
2871            workflow.status = WorkflowStatusType::Pending;
2872            workflow.executor_id = executor_id.to_string();
2873            workflow.started_at = Some(now);
2874            workflow.updated_at = now;
2875            if workflow.deadline.is_none() {
2876                if let Some(timeout) = workflow.timeout {
2877                    workflow.deadline = chrono::Duration::from_std(timeout)
2878                        .ok()
2879                        .map(|duration| now + duration);
2880                }
2881            }
2882
2883            Ok(Some(workflow.clone()))
2884        }
2885
2886        async fn list_runnable_queues(&self) -> JournioResult<Vec<String>> {
2887            let state = self.state.lock().expect("fake db lock");
2888            let mut names: Vec<String> = state
2889                .workflows
2890                .values()
2891                .filter_map(|workflow| {
2892                    if matches!(
2893                        workflow.status,
2894                        WorkflowStatusType::Enqueued | WorkflowStatusType::Delayed
2895                    ) {
2896                        workflow.queue_name.clone()
2897                    } else {
2898                        None
2899                    }
2900                })
2901                .collect();
2902            names.sort();
2903            names.dedup();
2904            Ok(names)
2905        }
2906
2907        async fn list_queues(&self) -> JournioResult<Vec<QueueConfig>> {
2908            let state = self.state.lock().expect("fake db lock");
2909            let mut queues: Vec<QueueConfig> = state.queues.values().cloned().collect();
2910            queues.sort_by(|left, right| left.name.cmp(&right.name));
2911            Ok(queues)
2912        }
2913
2914        async fn send(
2915            &self,
2916            destination_id: &str,
2917            topic: &str,
2918            message: &Interchange,
2919        ) -> JournioResult<()> {
2920            let mut state = self.state.lock().expect("fake db lock");
2921            // Mirror the FK: a Send to an unknown destination is an error.
2922            if !state.workflows.contains_key(destination_id) {
2923                return Err(JournioError::new(
2924                    JournioErrorCode::NonExistentWorkflowError,
2925                    format!("destination workflow {destination_id} does not exist"),
2926                ));
2927            }
2928            state.notifications.push(FakeNotification {
2929                destination_id: destination_id.to_string(),
2930                topic: normalize_topic(topic).to_string(),
2931                message: message.clone(),
2932                consumed: false,
2933            });
2934            Ok(())
2935        }
2936
2937        async fn consume_notification(
2938            &self,
2939            workflow_id: &str,
2940            topic: &str,
2941        ) -> JournioResult<Option<Notification>> {
2942            let mut state = self.state.lock().expect("fake db lock");
2943            let topic = normalize_topic(topic);
2944            let candidate = state
2945                .notifications
2946                .iter_mut()
2947                .find(|n| !n.consumed && n.destination_id == workflow_id && n.topic == topic);
2948            if let Some(n) = candidate {
2949                n.consumed = true;
2950                Ok(Some(Notification {
2951                    message: n.message.clone(),
2952                    serialization: Some("JOURNIO_JSON".to_string()),
2953                }))
2954            } else {
2955                Ok(None)
2956            }
2957        }
2958
2959        async fn set_event(
2960            &self,
2961            workflow_id: &str,
2962            key: &str,
2963            value: &Interchange,
2964            _function_id: i32,
2965        ) -> JournioResult<()> {
2966            let mut state = self.state.lock().expect("fake db lock");
2967            state
2968                .events
2969                .insert((workflow_id.to_string(), key.to_string()), value.clone());
2970            Ok(())
2971        }
2972
2973        async fn get_event_value(
2974            &self,
2975            workflow_id: &str,
2976            key: &str,
2977        ) -> JournioResult<Option<Interchange>> {
2978            let state = self.state.lock().expect("fake db lock");
2979            Ok(state
2980                .events
2981                .get(&(workflow_id.to_string(), key.to_string()))
2982                .cloned())
2983        }
2984
2985        async fn write_stream(
2986            &self,
2987            workflow_id: &str,
2988            key: &str,
2989            value: &str,
2990            _function_id: i32,
2991            serialization: Option<&str>,
2992        ) -> JournioResult<()> {
2993            let mut state = self.state.lock().expect("fake db lock");
2994            if state.streams.iter().any(|entry| {
2995                entry.workflow_id == workflow_id
2996                    && entry.key == key
2997                    && entry.value == STREAM_CLOSED_SENTINEL
2998            }) {
2999                return Err(JournioError::new(
3000                    JournioErrorCode::WorkflowExecutionError,
3001                    format!("stream {key:?} is already closed"),
3002                ));
3003            }
3004
3005            let offset = state
3006                .streams
3007                .iter()
3008                .filter(|entry| entry.workflow_id == workflow_id && entry.key == key)
3009                .map(|entry| entry.offset)
3010                .max()
3011                .unwrap_or(-1)
3012                + 1;
3013            state.streams.push(FakeStreamEntry {
3014                workflow_id: workflow_id.to_string(),
3015                key: key.to_string(),
3016                value: value.to_string(),
3017                offset,
3018                serialization: serialization.map(ToString::to_string),
3019            });
3020            Ok(())
3021        }
3022
3023        async fn read_stream(
3024            &self,
3025            workflow_id: &str,
3026            key: &str,
3027            from_offset: i64,
3028        ) -> JournioResult<(Vec<crate::types::StreamEntry>, bool)> {
3029            let state = self.state.lock().expect("fake db lock");
3030            let mut entries = Vec::new();
3031            let mut closed = false;
3032
3033            for entry in state.streams.iter().filter(|entry| {
3034                entry.workflow_id == workflow_id && entry.key == key && entry.offset >= from_offset
3035            }) {
3036                if entry.value == STREAM_CLOSED_SENTINEL {
3037                    closed = true;
3038                    break;
3039                }
3040                entries.push(crate::types::StreamEntry {
3041                    value: entry.value.clone(),
3042                    offset: entry.offset,
3043                    serialization: entry.serialization.clone(),
3044                });
3045            }
3046
3047            Ok((entries, closed))
3048        }
3049
3050        async fn get_workflows_for_recovery(
3051            &self,
3052            executor_id: &str,
3053        ) -> JournioResult<Vec<WorkflowStatus>> {
3054            let state = self.state.lock().expect("fake db lock");
3055            Ok(state
3056                .workflows
3057                .values()
3058                .filter(|workflow| {
3059                    workflow.executor_id == executor_id
3060                        && matches!(
3061                            workflow.status,
3062                            WorkflowStatusType::Pending
3063                                | WorkflowStatusType::Enqueued
3064                                | WorkflowStatusType::Delayed
3065                        )
3066                })
3067                .cloned()
3068                .collect())
3069        }
3070
3071        async fn delete_workflows_before(&self, _before: DateTime<Utc>) -> JournioResult<u64> {
3072            Ok(0)
3073        }
3074
3075        async fn upsert_schedule(&self, schedule: &WorkflowSchedule) -> JournioResult<()> {
3076            let mut state = self.state.lock().expect("fake db lock");
3077            state
3078                .schedules
3079                .insert(schedule.schedule_name.clone(), schedule.clone());
3080            Ok(())
3081        }
3082
3083        async fn get_schedule(
3084            &self,
3085            schedule_name: &str,
3086        ) -> JournioResult<Option<WorkflowSchedule>> {
3087            let state = self.state.lock().expect("fake db lock");
3088            Ok(state.schedules.get(schedule_name).cloned())
3089        }
3090
3091        async fn list_schedules(&self) -> JournioResult<Vec<WorkflowSchedule>> {
3092            let state = self.state.lock().expect("fake db lock");
3093            let mut schedules: Vec<_> = state.schedules.values().cloned().collect();
3094            schedules.sort_by(|left, right| left.schedule_name.cmp(&right.schedule_name));
3095            Ok(schedules)
3096        }
3097
3098        async fn delete_schedule(&self, schedule_name: &str) -> JournioResult<()> {
3099            let mut state = self.state.lock().expect("fake db lock");
3100            state.schedules.remove(schedule_name);
3101            Ok(())
3102        }
3103
3104        async fn update_schedule_status(
3105            &self,
3106            schedule_name: &str,
3107            status: ScheduleStatus,
3108        ) -> JournioResult<()> {
3109            let mut state = self.state.lock().expect("fake db lock");
3110            if let Some(schedule) = state.schedules.get_mut(schedule_name) {
3111                schedule.status = status;
3112            }
3113            Ok(())
3114        }
3115
3116        async fn update_schedule_last_fired_at(
3117            &self,
3118            schedule_name: &str,
3119            fired_at: DateTime<Utc>,
3120        ) -> JournioResult<()> {
3121            let mut state = self.state.lock().expect("fake db lock");
3122            if let Some(schedule) = state.schedules.get_mut(schedule_name) {
3123                schedule.last_fired_at = Some(fired_at);
3124            }
3125            Ok(())
3126        }
3127
3128        async fn create_application_version(&self, version_name: &str) -> JournioResult<()> {
3129            let mut state = self.state.lock().expect("fake db lock");
3130            if state
3131                .application_versions
3132                .iter()
3133                .any(|version| version.version_name == version_name)
3134            {
3135                return Ok(());
3136            }
3137            let now_ms = Utc::now().timestamp_millis();
3138            state.application_versions.push(VersionInfo {
3139                version_id: uuid::Uuid::new_v4().to_string(),
3140                version_name: version_name.to_string(),
3141                version_timestamp: now_ms,
3142                created_at: now_ms,
3143            });
3144            Ok(())
3145        }
3146
3147        async fn update_application_version_timestamp(
3148            &self,
3149            version_name: &str,
3150            timestamp_ms: i64,
3151        ) -> JournioResult<()> {
3152            let mut state = self.state.lock().expect("fake db lock");
3153            if let Some(version) = state
3154                .application_versions
3155                .iter_mut()
3156                .find(|version| version.version_name == version_name)
3157            {
3158                version.version_timestamp = timestamp_ms;
3159            }
3160            Ok(())
3161        }
3162
3163        async fn list_application_versions(&self) -> JournioResult<Vec<VersionInfo>> {
3164            let state = self.state.lock().expect("fake db lock");
3165            let mut versions = state.application_versions.clone();
3166            versions.sort_by_key(|v| std::cmp::Reverse(v.version_timestamp));
3167            Ok(versions)
3168        }
3169
3170        async fn get_latest_application_version(&self) -> JournioResult<Option<VersionInfo>> {
3171            let state = self.state.lock().expect("fake db lock");
3172            Ok(state
3173                .application_versions
3174                .iter()
3175                .max_by_key(|version| version.version_timestamp)
3176                .cloned())
3177        }
3178    }
3179
3180    /// Mirrors the WHERE-clause logic the real backends build from
3181    /// [`ListWorkflowsFilter`].
3182    fn matches_filter(wf: &WorkflowStatus, filter: &ListWorkflowsFilter) -> bool {
3183        if !filter.workflow_ids.is_empty() && !filter.workflow_ids.contains(&wf.id) {
3184            return false;
3185        }
3186        if !filter.workflow_id_prefixes.is_empty()
3187            && !filter
3188                .workflow_id_prefixes
3189                .iter()
3190                .any(|prefix| wf.id.starts_with(prefix))
3191        {
3192            return false;
3193        }
3194        if !filter.statuses.is_empty() && !filter.statuses.contains(&wf.status) {
3195            return false;
3196        }
3197        if !filter.names.is_empty() && !filter.names.contains(&wf.name) {
3198            return false;
3199        }
3200        if !filter.application_versions.is_empty()
3201            && !filter
3202                .application_versions
3203                .contains(&wf.application_version)
3204        {
3205            return false;
3206        }
3207        if !filter.queue_names.is_empty()
3208            && !wf
3209                .queue_name
3210                .as_deref()
3211                .is_some_and(|name| filter.queue_names.iter().any(|q| q == name))
3212        {
3213            return false;
3214        }
3215        if filter.queues_only && wf.queue_name.is_none() {
3216            return false;
3217        }
3218        if !filter.authenticated_users.is_empty()
3219            && !wf
3220                .authenticated_user
3221                .as_deref()
3222                .is_some_and(|user| filter.authenticated_users.iter().any(|u| u == user))
3223        {
3224            return false;
3225        }
3226        if !filter.executor_ids.is_empty() && !filter.executor_ids.contains(&wf.executor_id) {
3227            return false;
3228        }
3229        if !filter.forked_from.is_empty()
3230            && !wf
3231                .forked_from
3232                .as_deref()
3233                .is_some_and(|from| filter.forked_from.iter().any(|f| f == from))
3234        {
3235            return false;
3236        }
3237        if !filter.parent_workflow_ids.is_empty()
3238            && !wf
3239                .parent_workflow_id
3240                .as_deref()
3241                .is_some_and(|parent| filter.parent_workflow_ids.iter().any(|p| p == parent))
3242        {
3243            return false;
3244        }
3245        if !filter.deduplication_ids.is_empty()
3246            && !wf
3247                .deduplication_id
3248                .as_deref()
3249                .is_some_and(|id| filter.deduplication_ids.iter().any(|d| d == id))
3250        {
3251            return false;
3252        }
3253        if let Some(start) = filter.start_time {
3254            if wf.created_at < start {
3255                return false;
3256            }
3257        }
3258        if let Some(end) = filter.end_time {
3259            if wf.created_at > end {
3260                return false;
3261            }
3262        }
3263        if let Some(after) = filter.completed_after {
3264            if !wf.completed_at.is_some_and(|completed| completed >= after) {
3265                return false;
3266            }
3267        }
3268        if let Some(before) = filter.completed_before {
3269            if !wf.completed_at.is_some_and(|completed| completed <= before) {
3270                return false;
3271            }
3272        }
3273        true
3274    }
3275
3276    fn workflow_status_from_init(init: &InitWorkflow) -> WorkflowStatus {
3277        WorkflowStatus {
3278            id: init.workflow_id.clone(),
3279            status: init.status,
3280            name: init.name.clone(),
3281            authenticated_user: init.authenticated_user.clone(),
3282            assumed_role: init.assumed_role.clone(),
3283            authenticated_roles: init.authenticated_roles.clone(),
3284            output: None,
3285            error: None,
3286            executor_id: init.executor_id.clone(),
3287            created_at: Utc::now(),
3288            updated_at: Utc::now(),
3289            application_version: init.application_version.clone().unwrap_or_default(),
3290            application_id: init.application_id.clone(),
3291            attempts: 1,
3292            queue_name: init.queue_name.clone(),
3293            timeout: init.timeout,
3294            deadline: init.deadline,
3295            started_at: None,
3296            deduplication_id: init.deduplication_id.clone(),
3297            input: init.input.clone(),
3298            priority: init.priority,
3299            queue_partition_key: init.queue_partition_key.clone(),
3300            forked_from: None,
3301            was_forked_from: false,
3302            parent_workflow_id: init.parent_workflow_id.clone(),
3303            completed_at: None,
3304            class_name: init.class_name.clone(),
3305            config_name: init.config_name.clone(),
3306            serialization: init.serialization.clone(),
3307            delay_until: init.delay_until,
3308        }
3309    }
3310
3311    async fn test_context() -> (Arc<JournioContext>, Arc<FakeSystemDatabase>) {
3312        let fake = Arc::new(FakeSystemDatabase::default());
3313        let config = Config {
3314            app_name: "test-app".to_string(),
3315            system_db: Some(fake.clone()),
3316            executor_id: Some("local".to_string()),
3317            ..Default::default()
3318        };
3319        let ctx = JournioContext::new(config).await.expect("context");
3320        (ctx, fake)
3321    }
3322
3323    #[tokio::test]
3324    async fn run_workflow_executes_step_once_and_persists_output() {
3325        let (ctx, fake) = test_context().await;
3326        let counter = Arc::new(AtomicUsize::new(0));
3327
3328        let step_counter = counter.clone();
3329        let step = Arc::new(StepFunc::new("step", move |_ctx| {
3330            let step_counter = step_counter.clone();
3331            Box::pin(async move {
3332                step_counter.fetch_add(1, AtomicOrdering::SeqCst);
3333                Ok(21_i64)
3334            })
3335        }));
3336
3337        let workflow_step = step.clone();
3338        let workflow = Arc::new(WorkflowFn::new("workflow", move |ctx, input: i64| {
3339            let workflow_step = workflow_step.clone();
3340            Box::pin(async move {
3341                let value = ctx.run_as_step(workflow_step).await?;
3342                let step_output: i64 = serde_json::from_value(value).expect("step output");
3343                Ok(step_output + input)
3344            })
3345        }));
3346
3347        ctx.register_workflow(workflow).expect("register workflow");
3348        let handle = ctx
3349            .run_workflow("workflow", serde_json::json!(21))
3350            .await
3351            .expect("run workflow");
3352        let result = handle
3353            .get_result(Some(Duration::from_secs(1)))
3354            .await
3355            .expect("result");
3356
3357        assert_eq!(
3358            serde_json::from_value::<i64>(result).expect("workflow output"),
3359            42
3360        );
3361        assert_eq!(counter.load(AtomicOrdering::SeqCst), 1);
3362
3363        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3364        assert_eq!(steps.len(), 1);
3365        assert_eq!(steps[0].function_name, "step");
3366    }
3367
3368    #[tokio::test]
3369    async fn workflow_handle_times_out_for_pending_workflow() {
3370        let (ctx, fake) = test_context().await;
3371        fake.init_workflow(InitWorkflow::new_pending(
3372            "pending",
3373            "pending-workflow",
3374            "local",
3375        ))
3376        .await
3377        .expect("insert pending workflow");
3378
3379        let handle = WorkflowHandle {
3380            workflow_id: "pending".to_string(),
3381            journio: Arc::downgrade(&ctx),
3382        };
3383
3384        let err = handle
3385            .get_result(Some(Duration::from_millis(50)))
3386            .await
3387            .expect_err("timeout expected");
3388        assert_eq!(err.code, JournioErrorCode::TimeoutError);
3389    }
3390
3391    #[tokio::test]
3392    async fn recovery_replays_pending_workflow_without_reexecuting_completed_step() {
3393        let (ctx, fake) = test_context().await;
3394        let step_one_counter = Arc::new(AtomicUsize::new(0));
3395        let step_two_counter = Arc::new(AtomicUsize::new(0));
3396
3397        let workflow_id = "recover-me".to_string();
3398        let mut init = InitWorkflow::new_pending(workflow_id.clone(), "recovery-workflow", "local");
3399        init.input = Some(serde_json::json!(2));
3400        fake.init_workflow(init).await.expect("seed workflow");
3401        fake.record_step_output(&StepRecord {
3402            workflow_uuid: workflow_id.clone(),
3403            function_id: 1,
3404            function_name: "step-one".to_string(),
3405            output: Some(serde_json::json!(40).to_string()),
3406            error: None,
3407            child_workflow_id: None,
3408        })
3409        .await
3410        .expect("seed checkpoint");
3411
3412        let step_one = Arc::new(StepFunc::new("step-one", {
3413            let step_one_counter = step_one_counter.clone();
3414            move |_ctx| {
3415                let step_one_counter = step_one_counter.clone();
3416                Box::pin(async move {
3417                    step_one_counter.fetch_add(1, AtomicOrdering::SeqCst);
3418                    Ok(40_i64)
3419                })
3420            }
3421        }));
3422
3423        let step_two = Arc::new(StepFunc::new("step-two", {
3424            let step_two_counter = step_two_counter.clone();
3425            move |_ctx| {
3426                let step_two_counter = step_two_counter.clone();
3427                Box::pin(async move {
3428                    step_two_counter.fetch_add(1, AtomicOrdering::SeqCst);
3429                    Ok(2_i64)
3430                })
3431            }
3432        }));
3433
3434        let workflow = Arc::new(WorkflowFn::new(
3435            "recovery-workflow",
3436            move |ctx, input: i64| {
3437                let step_one = step_one.clone();
3438                let step_two = step_two.clone();
3439                Box::pin(async move {
3440                    let first = serde_json::from_value::<i64>(ctx.run_as_step(step_one).await?)
3441                        .expect("first");
3442                    let second = serde_json::from_value::<i64>(ctx.run_as_step(step_two).await?)
3443                        .expect("second");
3444                    Ok(first + second + input)
3445                })
3446            },
3447        ));
3448
3449        ctx.register_workflow(workflow).expect("register workflow");
3450        ctx.launch().await.expect("launch and recover");
3451
3452        let status = fake
3453            .get_workflow_status(&workflow_id)
3454            .await
3455            .expect("workflow status")
3456            .expect("status row");
3457        assert_eq!(status.status, WorkflowStatusType::Success);
3458        assert_eq!(status.output.expect("output"), serde_json::json!(44));
3459        assert_eq!(step_one_counter.load(AtomicOrdering::SeqCst), 0);
3460        assert_eq!(step_two_counter.load(AtomicOrdering::SeqCst), 1);
3461    }
3462
3463    // ------------------------------------------------------------------
3464    // Send / Recv
3465    // ------------------------------------------------------------------
3466
3467    #[tokio::test]
3468    async fn send_and_recv_within_workflow_round_trips_message() {
3469        let (ctx, fake) = test_context().await;
3470        let workflow = Arc::new(WorkflowFn::new("self-recv", |ctx, _input: ()| {
3471            Box::pin(async move {
3472                // Send to self, then receive. Both are checkpointed steps.
3473                ctx.send(ctx.workflow_id(), serde_json::json!("hello"), "greetings")
3474                    .await?;
3475                ctx.recv("greetings", Duration::from_secs(1)).await
3476            })
3477        }));
3478        ctx.register_workflow(workflow).expect("register workflow");
3479
3480        let handle = ctx
3481            .run_workflow("self-recv", serde_json::json!(null))
3482            .await
3483            .expect("run workflow");
3484        let result = handle
3485            .get_result(Some(Duration::from_secs(2)))
3486            .await
3487            .expect("result");
3488
3489        assert_eq!(result, serde_json::json!("hello"));
3490
3491        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3492        let names: Vec<&str> = steps.iter().map(|s| s.function_name.as_str()).collect();
3493        assert_eq!(names, vec!["journio.send", "journio.recv"]);
3494        // The recv step carries the consumed message.
3495        let recv_step = steps
3496            .iter()
3497            .find(|s| s.function_name == "journio.recv")
3498            .expect("recv step");
3499        assert_eq!(recv_step.output.as_deref(), Some("\"hello\""));
3500    }
3501
3502    #[tokio::test]
3503    async fn recv_times_out_and_records_error_for_replay() {
3504        let (ctx, fake) = test_context().await;
3505        let workflow = Arc::new(WorkflowFn::new("waiter", |ctx, _input: ()| {
3506            Box::pin(async move {
3507                match ctx.recv("empty", Duration::from_millis(60)).await {
3508                    Ok(value) => Ok(value),
3509                    // Normalise to a value so the workflow still completes SUCCESS.
3510                    Err(err) if err.code == JournioErrorCode::TimeoutError => {
3511                        Ok(serde_json::json!("timed out"))
3512                    }
3513                    Err(err) => Err(err),
3514                }
3515            })
3516        }));
3517        ctx.register_workflow(workflow).expect("register workflow");
3518
3519        let handle = ctx
3520            .run_workflow("waiter", serde_json::json!(null))
3521            .await
3522            .expect("run workflow");
3523        let result = handle
3524            .get_result(Some(Duration::from_secs(2)))
3525            .await
3526            .expect("result");
3527        assert_eq!(result, serde_json::json!("timed out"));
3528
3529        // The timeout must be checkpointed so replay returns the same outcome.
3530        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3531        let recv_step = steps
3532            .iter()
3533            .find(|s| s.function_name == "journio.recv")
3534            .expect("recv step");
3535        assert!(recv_step.error.as_deref().unwrap().contains("no message"));
3536    }
3537
3538    #[tokio::test]
3539    async fn cross_workflow_send_via_top_level_send_delivers_message() {
3540        let (ctx, _fake) = test_context().await;
3541
3542        // The receiver runs in the background (it blocks on Recv). It publishes
3543        // its workflow id through a shared slot so the sender can target it.
3544        let id_slot: Arc<Mutex<Option<String>>> = Arc::new(Mutex::new(None));
3545
3546        let receiver_workflow = {
3547            let id_slot = id_slot.clone();
3548            Arc::new(WorkflowFn::new("receiver", move |ctx, _input: ()| {
3549                let id_slot = id_slot.clone();
3550                Box::pin(async move {
3551                    *id_slot.lock().expect("slot") = Some(ctx.workflow_id().to_string());
3552                    ctx.recv("topic", Duration::from_secs(2)).await
3553                })
3554            }))
3555        };
3556        ctx.register_workflow(receiver_workflow)
3557            .expect("register receiver");
3558
3559        let runner_ctx = ctx.clone();
3560        let receiver_task = tokio::spawn(async move {
3561            runner_ctx
3562                .run_workflow("receiver", serde_json::json!(null))
3563                .await
3564        });
3565
3566        // Wait for the receiver to publish its id, then send (top-level, no checkpoint).
3567        let receiver_id = loop {
3568            if let Some(id) = id_slot.lock().expect("slot").clone() {
3569                break id;
3570            }
3571            tokio::time::sleep(Duration::from_millis(5)).await;
3572        };
3573        ctx.send(&receiver_id, serde_json::json!("payload"), "topic")
3574            .await
3575            .expect("top-level send");
3576
3577        let handle = receiver_task
3578            .await
3579            .expect("receiver task")
3580            .expect("run receiver");
3581        let result = handle
3582            .get_result(Some(Duration::from_secs(2)))
3583            .await
3584            .expect("result");
3585        assert_eq!(result, serde_json::json!("payload"));
3586    }
3587
3588    // ------------------------------------------------------------------
3589    // SetEvent / GetEvent
3590    // ------------------------------------------------------------------
3591
3592    #[tokio::test]
3593    async fn set_and_get_event_within_workflow_round_trips_value() {
3594        let (ctx, _fake) = test_context().await;
3595        let workflow = Arc::new(WorkflowFn::new("eventer", |ctx, _input: ()| {
3596            Box::pin(async move {
3597                ctx.set_event("status", serde_json::json!("done")).await?;
3598                ctx.get_event(ctx.workflow_id(), "status", Duration::from_secs(1))
3599                    .await
3600            })
3601        }));
3602        ctx.register_workflow(workflow).expect("register workflow");
3603
3604        let handle = ctx
3605            .run_workflow("eventer", serde_json::json!(null))
3606            .await
3607            .expect("run workflow");
3608        let result = handle
3609            .get_result(Some(Duration::from_secs(2)))
3610            .await
3611            .expect("result");
3612        assert_eq!(result, serde_json::json!("done"));
3613    }
3614
3615    #[tokio::test]
3616    async fn get_event_times_out_and_records_error_for_replay() {
3617        let (ctx, fake) = test_context().await;
3618        let workflow = Arc::new(WorkflowFn::new("poller", |ctx, _input: ()| {
3619            Box::pin(async move {
3620                match ctx
3621                    .get_event(ctx.workflow_id(), "never", Duration::from_millis(60))
3622                    .await
3623                {
3624                    Ok(value) => Ok(value),
3625                    Err(err) if err.code == JournioErrorCode::TimeoutError => {
3626                        Ok(serde_json::json!("timed out"))
3627                    }
3628                    Err(err) => Err(err),
3629                }
3630            })
3631        }));
3632        ctx.register_workflow(workflow).expect("register workflow");
3633
3634        let handle = ctx
3635            .run_workflow("poller", serde_json::json!(null))
3636            .await
3637            .expect("run workflow");
3638        let result = handle
3639            .get_result(Some(Duration::from_secs(2)))
3640            .await
3641            .expect("result");
3642        assert_eq!(result, serde_json::json!("timed out"));
3643
3644        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3645        let get_step = steps
3646            .iter()
3647            .find(|s| s.function_name == "journio.getEvent")
3648            .expect("getEvent step");
3649        assert!(get_step.error.as_deref().unwrap().contains("not set"));
3650    }
3651
3652    // ------------------------------------------------------------------
3653    // Sleep
3654    // ------------------------------------------------------------------
3655
3656    #[tokio::test]
3657    async fn sleep_records_deadline_and_completes() {
3658        let (ctx, fake) = test_context().await;
3659        let workflow = Arc::new(WorkflowFn::new("sleeper", |ctx, _input: ()| {
3660            Box::pin(async move {
3661                ctx.sleep(Duration::from_millis(30)).await?;
3662                Ok(serde_json::json!("woke"))
3663            })
3664        }));
3665        ctx.register_workflow(workflow).expect("register workflow");
3666
3667        let handle = ctx
3668            .run_workflow("sleeper", serde_json::json!(null))
3669            .await
3670            .expect("run workflow");
3671        let result = handle
3672            .get_result(Some(Duration::from_secs(2)))
3673            .await
3674            .expect("result");
3675        assert_eq!(result, serde_json::json!("woke"));
3676
3677        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3678        let sleep_step = steps
3679            .iter()
3680            .find(|s| s.function_name == "journio.sleep")
3681            .expect("sleep step recorded");
3682        assert!(
3683            sleep_step.output.is_some(),
3684            "sleep deadline was checkpointed"
3685        );
3686    }
3687
3688    #[tokio::test]
3689    async fn sleep_replay_does_not_block_when_deadline_has_passed() {
3690        let (ctx, fake) = test_context().await;
3691        let workflow_id = "sleep-replay".to_string();
3692        let mut init = InitWorkflow::new_pending(workflow_id.clone(), "sleeper", "local");
3693        init.input = Some(serde_json::json!(null));
3694        fake.init_workflow(init).await.expect("seed workflow");
3695
3696        // Seed a sleep checkpoint with a deadline already in the past.
3697        let past = (Utc::now() - chrono::Duration::seconds(5)).to_rfc3339();
3698        fake.record_step_output(&StepRecord {
3699            workflow_uuid: workflow_id.clone(),
3700            function_id: 1,
3701            function_name: "journio.sleep".to_string(),
3702            output: Some(serde_json::to_string(&serde_json::Value::String(past)).expect("encode")),
3703            error: None,
3704            child_workflow_id: None,
3705        })
3706        .await
3707        .expect("seed sleep checkpoint");
3708
3709        let workflow = Arc::new(WorkflowFn::new("sleeper", |ctx, _input: ()| {
3710            Box::pin(async move {
3711                // 10s sleep — but the recorded deadline is in the past, so replay is instant.
3712                ctx.sleep(Duration::from_secs(10)).await?;
3713                Ok(serde_json::json!("done"))
3714            })
3715        }));
3716        ctx.register_workflow(workflow).expect("register workflow");
3717
3718        // launch() runs recovery; if sleep re-blocked this would hang until the test timeout.
3719        let launched = tokio::time::timeout(Duration::from_secs(2), ctx.launch()).await;
3720        launched.expect("launch did not hang").expect("launch ok");
3721
3722        let status = fake
3723            .get_workflow_status(&workflow_id)
3724            .await
3725            .expect("status")
3726            .expect("status row");
3727        assert_eq!(status.status, WorkflowStatusType::Success);
3728        assert_eq!(status.output.expect("output"), serde_json::json!("done"));
3729    }
3730
3731    // ------------------------------------------------------------------
3732    // Patch / DeprecatePatch
3733    // ------------------------------------------------------------------
3734
3735    #[tokio::test]
3736    async fn patch_records_marker_and_selects_new_code_path() {
3737        let fake = Arc::new(FakeSystemDatabase::default());
3738        let config = Config {
3739            app_name: "test-app".to_string(),
3740            system_db: Some(fake.clone()),
3741            executor_id: Some("local".to_string()),
3742            enable_patching: true,
3743            ..Default::default()
3744        };
3745        let ctx = JournioContext::new(config).await.expect("context");
3746
3747        let workflow = Arc::new(WorkflowFn::new("patcher", |ctx, input: i64| {
3748            Box::pin(async move {
3749                let output = if ctx.patch("my-patch").await? {
3750                    input + 2
3751                } else {
3752                    input + 1
3753                };
3754                Ok(output)
3755            })
3756        }));
3757        ctx.register_workflow(workflow).expect("register workflow");
3758
3759        let handle = ctx
3760            .run_workflow("patcher", serde_json::json!(1))
3761            .await
3762            .expect("run workflow");
3763        let result = handle
3764            .get_result(Some(Duration::from_secs(1)))
3765            .await
3766            .expect("result");
3767
3768        assert_eq!(serde_json::from_value::<i64>(result).expect("result"), 3);
3769        let steps = fake.get_steps(handle.workflow_id()).await.expect("steps");
3770        assert_eq!(steps.len(), 1);
3771        assert_eq!(steps[0].function_name, "journio.patch-my-patch");
3772    }
3773
3774    #[tokio::test]
3775    async fn patch_replay_preserves_old_code_path_for_existing_workflow() {
3776        let fake = Arc::new(FakeSystemDatabase::default());
3777        let config = Config {
3778            app_name: "test-app".to_string(),
3779            system_db: Some(fake.clone()),
3780            executor_id: Some("local".to_string()),
3781            enable_patching: true,
3782            ..Default::default()
3783        };
3784        let ctx = JournioContext::new(config).await.expect("context");
3785
3786        let workflow_id = "pre-patch".to_string();
3787        let mut init = InitWorkflow::new_pending(workflow_id.clone(), "patcher", "local");
3788        init.input = Some(serde_json::json!(1));
3789        fake.init_workflow(init).await.expect("seed workflow");
3790        fake.record_step_output(&StepRecord {
3791            workflow_uuid: workflow_id.clone(),
3792            function_id: 1,
3793            function_name: "legacy-step".to_string(),
3794            output: Some(serde_json::json!(2).to_string()),
3795            error: None,
3796            child_workflow_id: None,
3797        })
3798        .await
3799        .expect("seed legacy step");
3800
3801        let legacy_step = Arc::new(StepFunc::new("legacy-step", |_ctx| {
3802            Box::pin(async move { Ok(2_i64) })
3803        }));
3804        let patched_step = Arc::new(StepFunc::new("patched-step", |_ctx| {
3805            Box::pin(async move { Ok(3_i64) })
3806        }));
3807
3808        let workflow = Arc::new(WorkflowFn::new("patcher", move |ctx, _input: i64| {
3809            let legacy_step = legacy_step.clone();
3810            let patched_step = patched_step.clone();
3811            Box::pin(async move {
3812                let chosen = if ctx.patch("my-patch").await? {
3813                    ctx.run_as_step(patched_step).await?
3814                } else {
3815                    ctx.run_as_step(legacy_step).await?
3816                };
3817                Ok(chosen)
3818            })
3819        }));
3820        ctx.register_workflow(workflow).expect("register workflow");
3821
3822        ctx.launch().await.expect("launch and recover");
3823
3824        let status = fake
3825            .get_workflow_status(&workflow_id)
3826            .await
3827            .expect("status")
3828            .expect("status row");
3829        assert_eq!(status.status, WorkflowStatusType::Success);
3830        assert_eq!(status.output.expect("output"), serde_json::json!(2));
3831
3832        let steps = fake.get_steps(&workflow_id).await.expect("steps");
3833        assert_eq!(steps.len(), 1);
3834        assert_eq!(steps[0].function_name, "legacy-step");
3835    }
3836
3837    #[tokio::test]
3838    async fn deprecate_patch_consumes_existing_marker_without_nondeterminism() {
3839        let fake = Arc::new(FakeSystemDatabase::default());
3840        let config = Config {
3841            app_name: "test-app".to_string(),
3842            system_db: Some(fake.clone()),
3843            executor_id: Some("local".to_string()),
3844            enable_patching: true,
3845            ..Default::default()
3846        };
3847        let ctx = JournioContext::new(config).await.expect("context");
3848
3849        let workflow_id = "deprecated-patch".to_string();
3850        let mut init = InitWorkflow::new_pending(workflow_id.clone(), "patcher", "local");
3851        init.input = Some(serde_json::json!(1));
3852        fake.init_workflow(init).await.expect("seed workflow");
3853        fake.record_step_output(&StepRecord {
3854            workflow_uuid: workflow_id.clone(),
3855            function_id: 1,
3856            function_name: "journio.patch-my-patch".to_string(),
3857            output: None,
3858            error: None,
3859            child_workflow_id: None,
3860        })
3861        .await
3862        .expect("seed patch marker");
3863        fake.record_step_output(&StepRecord {
3864            workflow_uuid: workflow_id.clone(),
3865            function_id: 2,
3866            function_name: "patched-step".to_string(),
3867            output: Some(serde_json::json!(3).to_string()),
3868            error: None,
3869            child_workflow_id: None,
3870        })
3871        .await
3872        .expect("seed patched step");
3873
3874        let patched_step = Arc::new(StepFunc::new("patched-step", |_ctx| {
3875            Box::pin(async move { Ok(3_i64) })
3876        }));
3877
3878        let workflow = Arc::new(WorkflowFn::new("patcher", move |ctx, _input: i64| {
3879            let patched_step = patched_step.clone();
3880            Box::pin(async move {
3881                ctx.deprecate_patch("my-patch").await?;
3882                ctx.run_as_step(patched_step).await
3883            })
3884        }));
3885        ctx.register_workflow(workflow).expect("register workflow");
3886
3887        ctx.launch().await.expect("launch and recover");
3888
3889        let status = fake
3890            .get_workflow_status(&workflow_id)
3891            .await
3892            .expect("status")
3893            .expect("status row");
3894        assert_eq!(status.status, WorkflowStatusType::Success);
3895        assert_eq!(status.output.expect("output"), serde_json::json!(3));
3896
3897        let steps = fake.get_steps(&workflow_id).await.expect("steps");
3898        assert_eq!(steps.len(), 2);
3899        assert_eq!(steps[0].function_name, "journio.patch-my-patch");
3900        assert_eq!(steps[1].function_name, "patched-step");
3901    }
3902
3903    #[tokio::test]
3904    async fn patch_returns_error_when_patching_is_disabled() {
3905        let (ctx, _fake) = test_context().await;
3906        let workflow = Arc::new(WorkflowFn::new("patch-disabled", |ctx, _input: ()| {
3907            Box::pin(async move { ctx.patch("my-patch").await })
3908        }));
3909        ctx.register_workflow(workflow).expect("register workflow");
3910
3911        let err = match ctx
3912            .run_workflow("patch-disabled", serde_json::json!(null))
3913            .await
3914        {
3915            Ok(_) => panic!("patching should fail"),
3916            Err(err) => err,
3917        };
3918        assert_eq!(err.code, JournioErrorCode::PatchingNotEnabled);
3919        assert!(err.message.contains("Patching system is not enabled"));
3920    }
3921
3922    #[tokio::test]
3923    async fn enqueue_workflow_and_run_queue_once_executes_workflow() {
3924        let (ctx, fake) = test_context().await;
3925        let workflow = Arc::new(WorkflowFn::new("queued-workflow", |_ctx, input: i64| {
3926            Box::pin(async move { Ok(input + 1) })
3927        }));
3928        ctx.register_workflow(workflow).expect("register workflow");
3929
3930        let handle = ctx
3931            .enqueue_workflow(
3932                "jobs",
3933                "queued-workflow",
3934                serde_json::json!(41),
3935                EnqueueOptions::default(),
3936            )
3937            .await
3938            .expect("enqueue workflow");
3939
3940        let queued_status = fake
3941            .get_workflow_status(handle.workflow_id())
3942            .await
3943            .expect("queued status")
3944            .expect("queued row");
3945        assert_eq!(queued_status.status, WorkflowStatusType::Enqueued);
3946
3947        let ran = ctx.run_queue_once("jobs").await.expect("run queue");
3948        assert!(ran.is_some(), "queue worker should find one workflow");
3949
3950        let result = handle
3951            .get_result(Some(Duration::from_secs(1)))
3952            .await
3953            .expect("result");
3954        assert_eq!(result, serde_json::json!(42));
3955    }
3956
3957    #[tokio::test]
3958    async fn run_queue_once_skips_not_yet_due_delayed_workflow() {
3959        let (ctx, fake) = test_context().await;
3960        let workflow = Arc::new(WorkflowFn::new("delayed-workflow", |_ctx, input: i64| {
3961            Box::pin(async move { Ok(input + 1) })
3962        }));
3963        ctx.register_workflow(workflow).expect("register workflow");
3964
3965        let handle = ctx
3966            .enqueue_workflow(
3967                "jobs",
3968                "delayed-workflow",
3969                serde_json::json!(1),
3970                EnqueueOptions {
3971                    delay_until: Some(Utc::now() + chrono::Duration::minutes(1)),
3972                    ..Default::default()
3973                },
3974            )
3975            .await
3976            .expect("enqueue delayed workflow");
3977
3978        let ran = ctx.run_queue_once("jobs").await.expect("run queue");
3979        assert!(
3980            ran.is_none(),
3981            "delayed workflow should not run before due time"
3982        );
3983
3984        let status = fake
3985            .get_workflow_status(handle.workflow_id())
3986            .await
3987            .expect("status")
3988            .expect("row");
3989        assert_eq!(status.status, WorkflowStatusType::Delayed);
3990    }
3991}