dex_sdk/
flow_config.rs

1// Copyright (c) 2026 Super Durable, Inc.
2//
3// Licensed under the Sustainable Use License 1.0.
4// You may not use this file except in compliance with the License.
5// See the LICENSE file in the repository root.
6//
7// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
8
9use crate::StepDurability;
10
11#[derive(Clone, Debug, Default)]
12/// Overrides runtime behavior for one Flow.
13///
14/// StartFlow and SubFlow always select pull Workers, even when no override is supplied.
15/// [`crate::Client::update_flow_config`] leaves the Worker target unset, preserving the active Flow
16/// target. Other omitted fields use server defaults for StartFlow, inherit the parent configuration
17/// for SubFlow, and retain the active Flow setting for updates.
18/// Pass a value to [`crate::StartFlowOptions::config_override`] for one execution or to
19/// [`crate::Client::update_flow_config`] for an active Flow.
20pub struct FlowConfig {
21    pub(crate) active_step_search_mode: Option<ActiveStepSearchMode>,
22    pub(crate) attribute_store_names: Option<Vec<String>>,
23    pub(crate) continue_as_new_threshold: Option<u32>,
24    pub(crate) continue_as_new_page_size_bytes: Option<u32>,
25    pub(crate) step_durability: Option<StepDurability>,
26    pub(crate) history_window_events: Option<u32>,
27}
28
29impl FlowConfig {
30    /// Creates a config with no overrides.
31    pub fn new() -> Self {
32        Self::default()
33    }
34
35    /// Controls which active Step types Dex places in the search index.
36    pub fn active_step_search_mode(mut self, value: ActiveStepSearchMode) -> Self {
37        self.active_step_search_mode = Some(value);
38        self
39    }
40
41    /// Selects server-configured Attribute Stores for opted-in Attribute writes.
42    ///
43    /// Omitting this builder preserves the existing Flow setting. Passing an empty vector retains
44    /// protocol presence and disables later synchronization. Each enabled Attribute write is
45    /// projected to every selected store; an external store failure does not roll back the Flow
46    /// Attribute write.
47    #[must_use]
48    pub fn attribute_store_names(mut self, values: Vec<String>) -> Self {
49        self.attribute_store_names = Some(values);
50        self
51    }
52
53    /// Sets the event-count threshold that triggers Continue-As-New.
54    pub fn continue_as_new_threshold(mut self, value: u32) -> Self {
55        self.continue_as_new_threshold = Some(value);
56        self
57    }
58
59    /// Sets the maximum history page size, in bytes, carried into Continue-As-New.
60    pub fn continue_as_new_page_size_bytes(mut self, value: u32) -> Self {
61        self.continue_as_new_page_size_bytes = Some(value);
62        self
63    }
64
65    /// Sets the default persistence durability for Step handler writes.
66    pub fn step_durability(mut self, value: StepDurability) -> Self {
67        self.step_durability = Some(value);
68        self
69    }
70
71    /// Sets how many of the newest history events the run keeps, approximately.
72    ///
73    /// The run uses the kept events for history reads and Time Travel. Without this builder, the
74    /// run uses the server's `history.windowEvents` setting, which defaults to 10000. Raise it for
75    /// a run that you inspect or travel back in often. Lower it for a run that writes many events
76    /// and needs less disk.
77    ///
78    /// Dex prunes the oldest events in chunks, and only between commands, so a run keeps slightly
79    /// more or fewer events than the value. A command that changes the Flow but records no event
80    /// counts as one event. The first event of the run is always kept, so a reset to the beginning
81    /// of the run always works. History reads no longer return pruned events, and Time Travel
82    /// targets only commands inside the window.
83    ///
84    /// Set it at start through [`crate::StartFlowOptions::config_override`], or change it on an
85    /// active Flow with [`crate::Client::update_flow_config`]. A smaller value takes effect at the
86    /// run's next pruning. A larger value keeps more of the events recorded afterwards; pruned
87    /// events never come back. Once set, the value can be changed but not cleared back to the
88    /// server default: an update without this builder keeps the current value. A SubFlow inherits
89    /// the value from its parent unless its own [`crate::SubFlowOptions::config_override`] sets it.
90    ///
91    /// The value must be positive and at most the server's `history.maxWindowEvents` setting,
92    /// which defaults to 100000. StartFlow and UpdateFlowConfig return [`crate::SdkError::Service`]
93    /// whose [`crate::ServiceError::code`] is `InvalidArgument` for zero or a value above that
94    /// maximum. A value above `i32::MAX` fails locally with [`crate::SdkError::InvalidArgument`]
95    /// before any request. A Step that starts a SubFlow with an invalid override is an invalid Worker
96    /// response: the Step attempt fails and Dex retries it under the Step's retry policy. Servers
97    /// older than server-zd 0.1.21 ignore the value.
98    ///
99    /// ```no_run
100    /// # fn update(client: &dex_sdk::Client) -> dex_sdk::SdkResult<()> {
101    /// client.update_flow_config(
102    ///     "order-42",
103    ///     dex_sdk::FlowConfig::new().history_window_events(50_000),
104    /// )?;
105    /// # Ok(())
106    /// # }
107    /// ```
108    ///
109    /// Since 1.38.0.
110    #[must_use]
111    pub fn history_window_events(mut self, value: u32) -> Self {
112        self.history_window_events = Some(value);
113        self
114    }
115}
116
117#[derive(Clone, Copy, Debug, Eq, PartialEq)]
118/// Controls which active Step types Dex indexes for Flow search.
119pub enum ActiveStepSearchMode {
120    /// Indexes every active Step type, including execute-only Steps.
121    All,
122    /// Indexes a Step type only after its `wait_for` handler runs.
123    WithWaitFor,
124    /// Disables active-Step indexing for the Flow.
125    Disabled,
126}
dex_sdk/flow_config.rs

dex_sdk/
flow_config.rs
