Skip to main content

turnloop_mongodb/
operation.rs

1//! Retry orchestration for an operation across server selection and pool checkout.
2//! retryable-reads/retryable-reads.md § Executing Retryable Read Commands;
3//! retryable-writes/retryable-writes.md § Executing Retryable Write Commands.
4//! The adapter performs the action returned by `action` and reports its outcome.
5//! Input BSON and wire templates are copied into retained buffers once per command.
6use crate::Instant;
7use crate::{
8    Connection, Error, ErrorKind, Result,
9    retry::{Retry, RetryKind},
10    uri::ReadPreference,
11    wire::{self, BsonWriter, Message},
12};
13use bson::raw::{RawBsonRef, RawDocument};
14use std::time::Duration;
15#[derive(Clone, Copy, Debug, PartialEq, Eq)]
16pub enum OperationKind {
17    Read,
18    Write,
19    RunCommand,
20}
21#[derive(Clone, Copy, Debug)]
22pub struct RetrySession {
23    pub id: [u8; 16],
24    pub txn_number: i64,
25}
26#[derive(Clone, Debug)]
27pub struct OperationOptions {
28    pub token: u64,
29    pub kind: OperationKind,
30    pub retry: bool,
31    pub timeout: Option<Duration>,
32    pub session: Option<RetrySession>,
33    pub read_preference: ReadPreference,
34}
35impl Default for OperationOptions {
36    fn default() -> Self {
37        Self {
38            token: 0,
39            kind: OperationKind::RunCommand,
40            retry: false,
41            timeout: None,
42            session: None,
43            read_preference: ReadPreference::Primary,
44        }
45    }
46}
47#[derive(Clone, Copy, Debug)]
48pub struct ServerCapabilities {
49    pub wire_version: i32,
50    pub sessions: bool,
51    pub standalone: bool,
52    pub direct: bool,
53}
54#[derive(Clone, Copy, Debug, PartialEq, Eq)]
55enum State {
56    Idle,
57    Select,
58    Checkout,
59    Send,
60    Waiting,
61    Complete,
62    Failed,
63}
64#[derive(Debug)]
65pub enum OperationAction<'a> {
66    Idle,
67    Select {
68        deprioritized: Option<&'a str>,
69        read_preference: ReadPreference,
70    },
71    Checkout {
72        address: &'a str,
73    },
74    Send {
75        address: &'a str,
76    },
77    Waiting,
78    Complete {
79        token: u64,
80    },
81    Failed {
82        token: u64,
83        error: &'a Error,
84    },
85}
86pub struct Operation {
87    state: State,
88    options: OperationOptions,
89    original: Vec<u8>,
90    outgoing: Vec<u8>,
91    writer: BsonWriter,
92    server: String,
93    failed_server: String,
94    deadline: Option<Instant>,
95    policy: Retry,
96    first_error: Option<Error>,
97    error: Option<Error>,
98}
99impl Default for Operation {
100    fn default() -> Self {
101        Self::new()
102    }
103}
104impl Operation {
105    pub fn new() -> Self {
106        Self {
107            state: State::Idle,
108            options: OperationOptions::default(),
109            original: Vec::with_capacity(8192),
110            outgoing: Vec::with_capacity(8192),
111            writer: BsonWriter::new(),
112            server: String::with_capacity(256),
113            failed_server: String::with_capacity(256),
114            deadline: None,
115            policy: Retry {
116                kind: RetryKind::Never,
117                enabled: false,
118                attempts: 0,
119                in_transaction: false,
120                wire_version: 0,
121                sessions_supported: false,
122                standalone: false,
123                acknowledged: true,
124            },
125            first_error: None,
126            error: None,
127        }
128    }
129    pub fn begin(
130        &mut self,
131        body: &RawDocument,
132        sequences: &[(&str, &[&RawDocument])],
133        mut options: OperationOptions,
134        now: Instant,
135    ) -> Result<()> {
136        if !matches!(self.state, State::Idle | State::Complete | State::Failed) {
137            return Err(Error::protocol("Operation already active"));
138        }
139        if body.get_str("$db").is_err() {
140            return Err(Error::protocol("Command requires $db"));
141        }
142        if body
143            .get("writeConcern")
144            .ok()
145            .flatten()
146            .and_then(|v| v.as_document())
147            .is_some_and(|d| {
148                matches!(
149                    d.get("w"),
150                    Ok(Some(RawBsonRef::Int32(0) | RawBsonRef::Int64(0)))
151                )
152            })
153        {
154            return Err(Error::new(
155                ErrorKind::InvalidArgument,
156                "Use Connection::command for unacknowledged writes",
157            ));
158        }
159        if let Some(lsid) = body
160            .get("lsid")
161            .ok()
162            .flatten()
163            .and_then(|v| v.as_document())
164        {
165            let id = lsid
166                .get_binary("id")
167                .map_err(|_| Error::protocol("Invalid session id"))?;
168            if id.bytes.len() != 16 || id.subtype != bson::spec::BinarySubtype::Uuid {
169                return Err(Error::protocol("Session id must be UUID binary"));
170            }
171            let id: [u8; 16] = id.bytes.try_into().unwrap();
172            if options.session.is_some_and(|s| s.id != id) {
173                return Err(Error::protocol("Conflicting session identities"));
174            }
175            // Explicit sessions preserve the caller's already decorated txnNumber.
176            options.session = body
177                .get("txnNumber")
178                .ok()
179                .flatten()
180                .and_then(|v| v.as_i64())
181                .map(|txn_number| RetrySession { id, txn_number });
182        }
183        wire::encode(
184            &mut self.original,
185            1,
186            0,
187            0,
188            body,
189            sequences,
190            wire::DEFAULT_MAX_MESSAGE,
191        )?;
192        let m = Message::parse(&self.original, wire::DEFAULT_MAX_MESSAGE)?;
193        let name = m
194            .body
195            .iter_elements()
196            .next()
197            .transpose()
198            .map_err(|_| Error::protocol("Invalid command"))?
199            .ok_or_else(|| Error::protocol("Empty command"))?;
200        let transaction = m.body.get("autocommit").ok().flatten().is_some();
201        let kind = if transaction {
202            RetryKind::Never
203        } else {
204            match options.kind {
205                OperationKind::RunCommand => RetryKind::Never,
206                OperationKind::Read => {
207                    if Retry::read_command(name.key().as_str()) && !writes_pipeline(body) {
208                        RetryKind::Read
209                    } else {
210                        RetryKind::Never
211                    }
212                }
213                OperationKind::Write => {
214                    if retryable_write(&m)? {
215                        RetryKind::Write
216                    } else {
217                        RetryKind::Never
218                    }
219                }
220            }
221        };
222        self.policy = Retry {
223            kind,
224            enabled: options.retry,
225            attempts: 0,
226            in_transaction: transaction,
227            wire_version: 0,
228            sessions_supported: false,
229            standalone: false,
230            acknowledged: true,
231        };
232        self.deadline = options.timeout.and_then(|d| now.checked_add(d));
233        self.options = options;
234        self.state = State::Select;
235        self.first_error = None;
236        self.error = None;
237        self.server.clear();
238        self.failed_server.clear();
239        Ok(())
240    }
241    pub fn action(&self) -> OperationAction<'_> {
242        match self.state {
243            State::Idle => OperationAction::Idle,
244            State::Select => OperationAction::Select {
245                deprioritized: if self.failed_server.is_empty() {
246                    None
247                } else {
248                    Some(&self.failed_server)
249                },
250                read_preference: if self.options.kind == OperationKind::Write {
251                    ReadPreference::Primary
252                } else {
253                    self.options.read_preference
254                },
255            },
256            State::Checkout => OperationAction::Checkout {
257                address: &self.server,
258            },
259            State::Send => OperationAction::Send {
260                address: &self.server,
261            },
262            State::Waiting => OperationAction::Waiting,
263            State::Complete => OperationAction::Complete {
264                token: self.options.token,
265            },
266            State::Failed => OperationAction::Failed {
267                token: self.options.token,
268                error: self.error.as_ref().unwrap(),
269            },
270        }
271    }
272    pub fn selected(&mut self, address: &str, capabilities: ServerCapabilities) -> Result<()> {
273        if self.state != State::Select {
274            return Err(Error::protocol("Operation is not selecting a server"));
275        }
276        self.policy.wire_version = capabilities.wire_version;
277        self.policy.sessions_supported = capabilities.sessions;
278        self.policy.standalone = capabilities.standalone;
279        let can_write_retry = capabilities.sessions
280            && !capabilities.standalone
281            && capabilities.wire_version >= 6
282            && self.options.session.is_some();
283        if self.policy.attempts > 0
284            && ((self.policy.kind == RetryKind::Write && !can_write_retry)
285                || capabilities.wire_version < 6)
286        {
287            let err = self.first_error.take().unwrap();
288            self.finish_error(err);
289            return Ok(());
290        }
291        if self.policy.kind == RetryKind::Write && !can_write_retry {
292            self.policy.enabled = false;
293        }
294        self.server.clear();
295        self.server.push_str(address);
296        let message = Message::parse(&self.original, wire::DEFAULT_MAX_MESSAGE)?;
297        self.writer.clear();
298        self.writer.append_fields(message.body, &[])?;
299        if let Some(session) = self.options.session
300            && capabilities.sessions
301            && !self.policy.in_transaction
302            && message.body.get("lsid").ok().flatten().is_none()
303        {
304            let l = self.writer.start_document("lsid", false)?;
305            self.writer.binary("id", 4, &session.id)?;
306            self.writer.end_document(l)?;
307            if self.policy.kind == RetryKind::Write && self.policy.enabled {
308                self.writer.int64("txnNumber", session.txn_number)?;
309            }
310        }
311        let pref = if capabilities.direct && self.options.read_preference == ReadPreference::Primary
312        {
313            ReadPreference::PrimaryPreferred
314        } else {
315            self.options.read_preference
316        };
317        if self.options.kind == OperationKind::Read
318            && pref != ReadPreference::Primary
319            && message.body.get("$readPreference").ok().flatten().is_none()
320        {
321            let p = self.writer.start_document("$readPreference", false)?;
322            self.writer.string("mode", pref.as_str())?;
323            self.writer.end_document(p)?;
324        }
325        let body = self.writer.finish()?;
326        message.encode_with_body(&mut self.outgoing, body, wire::DEFAULT_MAX_MESSAGE)?;
327        self.state = State::Checkout;
328        Ok(())
329    }
330    pub fn checked_out(&mut self) -> Result<()> {
331        if self.state != State::Checkout {
332            return Err(Error::protocol(
333                "Operation is not checking out a connection",
334            ));
335        }
336        self.state = State::Send;
337        Ok(())
338    }
339    pub fn encoded_command(&self) -> Result<&[u8]> {
340        if self.state != State::Send {
341            return Err(Error::protocol("Operation is not ready to send"));
342        }
343        Ok(&self.outgoing)
344    }
345    pub fn send(&mut self, connection: &mut Connection, now: Instant) -> Result<()> {
346        if self.state != State::Send {
347            return Err(Error::protocol("Operation is not ready to send"));
348        }
349        connection.command_encoded(self.options.token, &self.outgoing, now)?;
350        self.state = State::Waiting;
351        Ok(())
352    }
353    /// For a host transport that sends encoded_command directly (e.g. a test driver).
354    pub fn sent(&mut self) -> Result<()> {
355        if self.state != State::Send {
356            return Err(Error::protocol("Operation is not ready to send"));
357        }
358        self.state = State::Waiting;
359        Ok(())
360    }
361    /// Returns true only for the terminal successful reply. Host releases the
362    /// connection's reply buffer after handling this result; retries do not escape.
363    pub fn response(&mut self, reply: &RawDocument) -> Result<bool> {
364        if self.state != State::Waiting {
365            return Err(Error::protocol("Unexpected operation reply"));
366        }
367        match Error::from_response(reply) {
368            Ok(()) => {
369                self.state = State::Complete;
370                self.deadline = None;
371                Ok(true)
372            }
373            Err(e) => {
374                self.failed(e);
375                Ok(false)
376            }
377        }
378    }
379    pub fn failed(&mut self, mut error: Error) {
380        if matches!(self.state, State::Complete | State::Failed | State::Idle) {
381            return;
382        }
383        if self.state == State::Select {
384            let e = self.first_error.take().unwrap_or(error);
385            self.finish_error(e);
386            return;
387        }
388        if self.policy.kind == RetryKind::Write
389            && self.policy.enabled
390            && !error.has_label("RetryableWriteError")
391        {
392            let local = matches!(
393                error.kind,
394                ErrorKind::Network | ErrorKind::Timeout | ErrorKind::PoolCleared
395            );
396            let old_server = self.policy.wire_version < 9
397                && error.kind != ErrorKind::BulkWrite
398                && error.code.is_some_and(|c| {
399                    matches!(
400                        c,
401                        6 | 7 | 89 | 91 | 189 | 262 | 9001 | 10107 | 11600 | 11602 | 13435 | 13436
402                    )
403                });
404            if local || old_server {
405                error.labels.push("RetryableWriteError".into());
406            }
407        }
408        if self.policy.retry(&error) {
409            self.first_error = Some(error);
410            self.failed_server.clear();
411            self.failed_server.push_str(&self.server);
412            self.state = State::Select;
413        } else {
414            let e = if error.has_label("NoWritesPerformed") {
415                self.first_error.take().unwrap_or(error)
416            } else {
417                error
418            };
419            self.finish_error(e);
420        }
421    }
422    fn finish_error(&mut self, error: Error) {
423        self.error = Some(error);
424        self.state = State::Failed;
425        self.deadline = None;
426    }
427    /// Number of retries actually scheduled for the current operation.
428    pub fn retry_count(&self) -> u8 {
429        self.policy.attempts
430    }
431    /// The failure which triggered the current retry, or the terminal failure.
432    pub fn last_error(&self) -> Option<&Error> {
433        self.error.as_ref().or(self.first_error.as_ref())
434    }
435    pub fn next_timeout(&self) -> Option<Instant> {
436        self.deadline
437    }
438    pub fn handle_timeout(&mut self, now: Instant) {
439        if self.deadline.is_some_and(|d| d <= now) {
440            self.finish_error(Error::new(
441                ErrorKind::OperationTimeout,
442                "MongoDB operation timed out",
443            ));
444        }
445    }
446    pub fn cancel(&mut self) {
447        if !matches!(self.state, State::Idle | State::Complete | State::Failed) {
448            self.finish_error(Error::new(
449                ErrorKind::Cancelled,
450                "MongoDB operation cancelled",
451            ));
452        }
453    }
454}
455fn writes_pipeline(body: &RawDocument) -> bool {
456    body.get("pipeline")
457        .ok()
458        .flatten()
459        .and_then(|v| v.as_array())
460        .is_some_and(|a| {
461            a.into_iter().any(|v| {
462                v.ok().and_then(|v| v.as_document()).is_some_and(|d| {
463                    ["$out", "$merge"]
464                        .iter()
465                        .any(|k| d.get(k).ok().flatten().is_some())
466                })
467            })
468        })
469}
470fn retryable_write(m: &Message<'_>) -> Result<bool> {
471    let first = m
472        .body
473        .iter_elements()
474        .next()
475        .transpose()
476        .map_err(|_| Error::protocol("Invalid command"))?
477        .ok_or_else(|| Error::protocol("Empty command"))?;
478    let name = first.key().as_str();
479    match name {
480        "insert" | "findAndModify" => Ok(true),
481        "update" | "delete" => {
482            let key = if name == "update" {
483                "updates"
484            } else {
485                "deletes"
486            };
487            let eligible = |d: &RawDocument| {
488                if name == "update" {
489                    !matches!(d.get("multi"), Ok(Some(RawBsonRef::Boolean(true))))
490                } else {
491                    matches!(
492                        d.get("limit"),
493                        Ok(Some(RawBsonRef::Int32(1) | RawBsonRef::Int64(1)))
494                    )
495                }
496            };
497            let mut count = 0;
498            for seq in m.sequences() {
499                if seq.identifier == key {
500                    for d in seq.documents() {
501                        count += 1;
502                        if !eligible(d) {
503                            return Ok(false);
504                        }
505                    }
506                }
507            }
508            if let Some(a) = m.body.get(key).ok().flatten().and_then(|v| v.as_array()) {
509                for v in a {
510                    let v = v.map_err(|_| Error::protocol("Invalid write model"))?;
511                    let d = v
512                        .as_document()
513                        .ok_or_else(|| Error::protocol("Write model must be document"))?;
514                    count += 1;
515                    if !eligible(d) {
516                        return Ok(false);
517                    }
518                }
519            }
520            Ok(count > 0)
521        }
522        _ => Ok(false),
523    }
524}