naidempotency_redis/
lib.rs1#![forbid(unsafe_code)]
18
19use std::sync::Arc;
20use std::time::Duration;
21
22use async_trait::async_trait;
23use nadis::RedisClient;
24use naidempotency::{
25 ExecutionLease, IdempotencyError, IdempotencyKey, IdempotencyOutcome, IdempotencyStore,
26 RequestFingerprint, StoredResponse,
27};
28use sha2::{Digest as _, Sha256};
29
30const STATE_IN_FLIGHT: u8 = 0;
32const STATE_COMPLETED: u8 = 1;
34
35const DEFAULT_INFLIGHT_TTL: Duration = Duration::from_secs(5 * 60);
37const DEFAULT_COMPLETED_TTL: Duration = Duration::from_secs(24 * 3600);
39
40const COMPLETE_LUA: &str = "\
42local v = redis.call('GET', KEYS[1]) \
43if not v then return 0 end \
44if v ~= ARGV[1] then return 0 end \
45local fp = string.sub(v, 2, 33) \
46redis.call('SET', KEYS[1], string.char(1) .. fp .. ARGV[2], 'PX', ARGV[3]) \
47return 1";
48
49const ABORT_LUA: &str = "\
51local v = redis.call('GET', KEYS[1]) \
52if not v or v ~= ARGV[1] then return 0 end \
53return redis.call('DEL', KEYS[1])";
54
55#[derive(Clone)]
57pub struct RedisIdempotencyStore {
58 client: Arc<RedisClient>,
59 inflight_ttl: Duration,
60 completed_ttl: Duration,
61}
62
63impl RedisIdempotencyStore {
64 pub fn new(client: Arc<RedisClient>) -> Self {
71 Self {
72 client,
73 inflight_ttl: DEFAULT_INFLIGHT_TTL,
74 completed_ttl: DEFAULT_COMPLETED_TTL,
75 }
76 }
77
78 pub fn with_ttls(
87 client: Arc<RedisClient>,
88 inflight_ttl: Duration,
89 completed_ttl: Duration,
90 ) -> Self {
91 Self {
92 client,
93 inflight_ttl,
94 completed_ttl,
95 }
96 }
97
98 fn redis_key(key: &IdempotencyKey) -> String {
105 const SEPARATOR: char = '\u{1f}';
106 let components = [
107 key.tenant.as_str(),
108 key.subject.as_str(),
109 key.route_id.as_str(),
110 key.client_key.as_str(),
111 ];
112 if components
113 .iter()
114 .all(|component| !component.contains(SEPARATOR))
115 {
116 return format!(
117 "idem:{}{SEPARATOR}{}{SEPARATOR}{}{SEPARATOR}{}",
118 key.tenant, key.subject, key.route_id, key.client_key
119 );
120 }
121 let mut digest = Sha256::new();
122 for component in components.map(str::as_bytes) {
123 digest.update((component.len() as u64).to_be_bytes());
124 digest.update(component);
125 }
126 let digest = digest.finalize();
127 let mut encoded = String::with_capacity("idem:v2:".len() + digest.len() * 2);
128 encoded.push_str("idem:v2:");
129 for byte in digest {
130 use std::fmt::Write as _;
131 let _ = write!(encoded, "{byte:02x}");
132 }
133 encoded
134 }
135}
136
137fn ttl_millis(ttl: Duration) -> Result<u64, IdempotencyError> {
144 let millis =
145 u64::try_from(ttl.as_millis()).map_err(|_| IdempotencyError::new("invalid ttl"))?;
146 if millis == 0 || millis > i64::MAX as u64 {
147 return Err(IdempotencyError::new("invalid ttl"));
148 }
149 Ok(millis)
150}
151
152fn encode_inflight(fingerprint: RequestFingerprint, lease: ExecutionLease) -> Vec<u8> {
160 let mut value = Vec::with_capacity(49);
161 value.push(STATE_IN_FLIGHT);
162 value.extend_from_slice(&fingerprint.0);
163 value.extend_from_slice(&lease.0);
164 value
165}
166
167fn encode_completed_suffix(response: &StoredResponse) -> Result<Vec<u8>, IdempotencyError> {
174 let headers = serde_json::to_vec(&response.headers).map_err(map_err)?;
175 let header_len =
176 u32::try_from(headers.len()).map_err(|_| IdempotencyError::new("headers too large"))?;
177 let mut suffix = Vec::with_capacity(6 + headers.len() + response.body.len());
178 suffix.extend_from_slice(&response.status.to_le_bytes());
179 suffix.extend_from_slice(&header_len.to_le_bytes());
180 suffix.extend_from_slice(&headers);
181 suffix.extend_from_slice(&response.body);
182 Ok(suffix)
183}
184
185struct Decoded {
187 state: u8,
188 fingerprint: RequestFingerprint,
189 response: Option<StoredResponse>,
190}
191
192fn decode(bytes: &[u8]) -> Option<Decoded> {
199 if bytes.len() < 33 {
200 return None;
201 }
202 let state = bytes[0];
203 if !matches!(state, STATE_IN_FLIGHT | STATE_COMPLETED) {
204 return None;
205 }
206 if state == STATE_IN_FLIGHT && bytes.len() != 49 {
207 return None;
208 }
209 let fingerprint = RequestFingerprint(bytes[1..33].try_into().ok()?);
210 let response = if state == STATE_COMPLETED {
211 if bytes.len() < 39 {
212 return None;
213 }
214 let status = u16::from_le_bytes(bytes[33..35].try_into().ok()?);
215 if !(100..=599).contains(&status) {
216 return None;
217 }
218 let headers_len = u32::from_le_bytes(bytes[35..39].try_into().ok()?) as usize;
219 let body_start = 39usize.checked_add(headers_len)?;
220 if body_start > bytes.len() {
221 return None;
222 }
223 let headers = serde_json::from_slice(&bytes[39..body_start]).ok()?;
224 Some(StoredResponse {
225 status,
226 body: bytes[body_start..].to_vec(),
227 headers,
228 })
229 } else {
230 None
231 };
232 Some(Decoded {
233 state,
234 fingerprint,
235 response,
236 })
237}
238
239#[async_trait]
240impl IdempotencyStore for RedisIdempotencyStore {
241 async fn begin(
250 &self,
251 key: &IdempotencyKey,
252 fingerprint: RequestFingerprint,
253 lease: ExecutionLease,
254 ) -> Result<IdempotencyOutcome, IdempotencyError> {
255 let redis_key = Self::redis_key(key);
256
257 let mut set = redis::cmd("SET");
259 set.arg(&redis_key)
260 .arg(encode_inflight(fingerprint, lease).as_slice())
261 .arg("NX")
262 .arg("PX")
263 .arg(ttl_millis(self.inflight_ttl)?);
264 let claimed: Option<String> = self.client.execute_raw(&set).await.map_err(map_err)?;
265 if claimed.is_some() {
266 return Ok(IdempotencyOutcome::FirstExecution);
267 }
268
269 let mut get = redis::cmd("GET");
271 get.arg(&redis_key);
272 let existing: Option<Vec<u8>> = self.client.execute_raw(&get).await.map_err(map_err)?;
273
274 let Some(bytes) = existing else {
276 return Ok(IdempotencyOutcome::ConcurrentInFlight);
277 };
278 let Some(decoded) = decode(&bytes) else {
279 return Err(IdempotencyError::new("corrupt idempotency record"));
280 };
281 if decoded.fingerprint != fingerprint {
282 return Ok(IdempotencyOutcome::FingerprintConflict);
283 }
284 if decoded.state == STATE_COMPLETED {
285 let response = decoded
286 .response
287 .ok_or_else(|| IdempotencyError::new("corrupt idempotency record"))?;
288 Ok(IdempotencyOutcome::Replay(response))
289 } else {
290 Ok(IdempotencyOutcome::ConcurrentInFlight)
291 }
292 }
293
294 async fn complete(
304 &self,
305 key: &IdempotencyKey,
306 fingerprint: RequestFingerprint,
307 lease: ExecutionLease,
308 response: StoredResponse,
309 ) -> Result<bool, IdempotencyError> {
310 let redis_key = Self::redis_key(key);
311 let mut eval = redis::cmd("EVAL");
314 eval.arg(COMPLETE_LUA)
315 .arg(1)
316 .arg(&redis_key)
317 .arg(encode_inflight(fingerprint, lease).as_slice())
318 .arg(encode_completed_suffix(&response)?.as_slice())
319 .arg(ttl_millis(self.completed_ttl)?);
320 let completed: i64 = self.client.execute_raw(&eval).await.map_err(map_err)?;
321 Ok(completed == 1)
322 }
323
324 async fn abort(
333 &self,
334 key: &IdempotencyKey,
335 fingerprint: RequestFingerprint,
336 lease: ExecutionLease,
337 ) -> Result<bool, IdempotencyError> {
338 let redis_key = Self::redis_key(key);
339 let mut eval = redis::cmd("EVAL");
341 eval.arg(ABORT_LUA)
342 .arg(1)
343 .arg(&redis_key)
344 .arg(encode_inflight(fingerprint, lease).as_slice());
345 let deleted: i64 = self.client.execute_raw(&eval).await.map_err(map_err)?;
346 Ok(deleted == 1)
347 }
348}
349
350fn map_err<E>(_error: E) -> IdempotencyError {
357 IdempotencyError::new("redis error")
358}