Skip to main content

hatchet_client/declare/
idempotency.rs

1//! Idempotency: letting the engine compute a key from a run's input and
2//! refuse a second run that computes the same one.
3
4use std::time::Duration;
5
6use hatchet_proto::v1;
7
8/// How long an idempotency key stays claimed.
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum IdempotencyMethod {
11    /// The key is released a fixed window after it was claimed.
12    Ttl,
13    /// The key is held until the run that claimed it reaches a terminal
14    /// state, with the window as a cap on how long that can take.
15    Status,
16}
17
18/// Makes the engine compute a key from each run's input and refuse a
19/// second run that computes the same one.
20///
21/// The key is **not** something a caller passes per run — there is no
22/// idempotency key field on the trigger request. It is declared here, as a
23/// CEL expression the engine evaluates against the run's input, and a
24/// trigger whose key is already claimed fails with
25/// [`Error::IdempotencyCollision`](crate::Error::IdempotencyCollision)
26/// naming the run that holds it. This is the shape the official Go and
27/// Python SDKs have too.
28///
29/// Observed against `hatchet-lite`: enforced on v0.107.0 (the second
30/// trigger with the same key fails, and the key is released once the
31/// window elapses); **silently ignored on v0.80.0** (the second trigger
32/// just starts a new run). The exact engine version where enforcement was
33/// introduced, between v0.80.0 and v0.107.0, was not measured.
34/// [`WorkerBuilder::build`](crate::WorkerBuilder::build) refuses to
35/// register a declaration with idempotency against an engine reporting a
36/// version below [`IDEMPOTENCY_MIN_ENGINE_VERSION`](crate::IDEMPOTENCY_MIN_ENGINE_VERSION)
37/// (currently v0.107.0) with
38/// [`Error::UnsupportedFeature`](crate::Error::UnsupportedFeature), rather
39/// than registering it and letting the engine quietly ignore it.
40///
41/// ```
42/// use std::time::Duration;
43///
44/// use hatchet_client::{Idempotency, TaskBuilder};
45///
46/// // One charge per order, however many times the caller retries.
47/// let charge = TaskBuilder::<(), ()>::new("charge")
48///     .idempotency(Idempotency::ttl("input.order_id", Duration::from_secs(600)))
49///     .handler(|_ctx, _input| async { Ok(()) });
50/// # let _ = charge;
51/// ```
52#[derive(Clone, Debug, PartialEq, Eq)]
53#[must_use = "an idempotency config does nothing until it is given to a declaration"]
54pub struct Idempotency {
55    expression: String,
56    window: Duration,
57    method: IdempotencyMethod,
58}
59
60impl Idempotency {
61    /// The key computed by `expression` is held for `window`, whatever
62    /// happens to the run that claimed it.
63    ///
64    /// `expression` is CEL over the run's input, e.g. `"input.order_id"`.
65    pub fn ttl(expression: impl Into<String>, window: Duration) -> Self {
66        Self {
67            expression: expression.into(),
68            window,
69            method: IdempotencyMethod::Ttl,
70        }
71    }
72
73    /// The key computed by `expression` is held until the run that claimed
74    /// it ends, and in no case longer than `fallback`.
75    pub fn until_run_ends(expression: impl Into<String>, fallback: Duration) -> Self {
76        Self {
77            expression: expression.into(),
78            window: fallback,
79            method: IdempotencyMethod::Status,
80        }
81    }
82
83    /// Checks that this configuration can be sent to the engine.
84    pub(crate) fn validate(&self) -> Result<(), String> {
85        if self.expression.trim().is_empty() {
86            return Err(
87                "an idempotency expression must not be empty; it is CEL over the \
88                        run's input, such as `input.order_id`"
89                    .to_string(),
90            );
91        }
92        if self.window.as_millis() == 0 {
93            return Err(
94                "an idempotency window must not round down to a zero ttl in \
95                        milliseconds; the engine rejects a zero ttl at registration on \
96                        v0.107.0, and what it does with it on older engines is not \
97                        documented, so the SDK refuses it rather than letting idempotency \
98                        quietly not apply"
99                    .to_string(),
100            );
101        }
102        Ok(())
103    }
104
105    pub(crate) fn to_proto(&self) -> v1::IdempotencyConfig {
106        let method = match self.method {
107            IdempotencyMethod::Ttl => v1::IdempotencyMethod::Ttl,
108            IdempotencyMethod::Status => v1::IdempotencyMethod::Status,
109        };
110        v1::IdempotencyConfig {
111            expression: self.expression.clone(),
112            ttl_ms: i64::try_from(self.window.as_millis()).unwrap_or(i64::MAX),
113            // Always sent, as Go and Python both do, so the engine's own
114            // default can never differ from what was declared.
115            method: Some(method as i32),
116        }
117    }
118}
119
120#[cfg(test)]
121mod tests {
122    use super::*;
123    use hatchet_proto::v1;
124
125    #[test]
126    fn a_ttl_config_sends_the_expression_the_window_and_the_method() {
127        assert_eq!(
128            Idempotency::ttl("input.order_id", Duration::from_secs(600)).to_proto(),
129            v1::IdempotencyConfig {
130                expression: "input.order_id".to_string(),
131                ttl_ms: 600_000,
132                method: Some(v1::IdempotencyMethod::Ttl as i32),
133            }
134        );
135    }
136
137    #[test]
138    fn a_status_config_sends_its_fallback_as_the_ttl() {
139        assert_eq!(
140            Idempotency::until_run_ends("input.order_id", Duration::from_secs(10)).to_proto(),
141            v1::IdempotencyConfig {
142                expression: "input.order_id".to_string(),
143                ttl_ms: 10_000,
144                method: Some(v1::IdempotencyMethod::Status as i32),
145            }
146        );
147    }
148
149    #[test]
150    fn sub_millisecond_windows_are_truncated_to_whole_milliseconds() {
151        let config = Idempotency::ttl("input.id", Duration::from_micros(1_500));
152        assert_eq!(config.to_proto().ttl_ms, 1);
153    }
154
155    #[test]
156    fn an_empty_expression_is_invalid() {
157        let reason = Idempotency::ttl("   ", Duration::from_secs(60))
158            .validate()
159            .unwrap_err();
160        assert!(reason.contains("expression"), "{reason}");
161    }
162
163    #[test]
164    fn a_zero_window_is_invalid() {
165        let reason = Idempotency::ttl("input.id", Duration::ZERO)
166            .validate()
167            .unwrap_err();
168        assert!(reason.contains("zero"), "{reason}");
169    }
170
171    #[test]
172    fn a_window_longer_than_i64_milliseconds_saturates_rather_than_panicking() {
173        let config = Idempotency::ttl("input.id", Duration::MAX);
174        assert_eq!(config.to_proto().ttl_ms, i64::MAX);
175    }
176
177    #[test]
178    fn a_window_under_one_millisecond_is_invalid() {
179        let reason = Idempotency::ttl("input.id", Duration::from_micros(500))
180            .validate()
181            .unwrap_err();
182        assert!(reason.contains("zero"), "{reason}");
183    }
184}