hatchet_client/declare/
idempotency.rs1use std::time::Duration;
5
6use hatchet_proto::v1;
7
8#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub enum IdempotencyMethod {
11 Ttl,
13 Status,
16}
17
18#[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 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 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 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 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}