Skip to main content

turnloop_mongodb/
connection.rs

1//! mongodb-handshake/handshake.md §§ Connection Handshake, Speculative Authentication.
2//! Events are pull-based. A token is accepted only on successful `command`, and
3//! is settled exactly once before reuse: by a Failed or Unacknowledged event, or
4//! by `release_reply()` after its Reply event. `fail()` before that release
5//! revokes the reply and settles the token with Failed instead; `close()` keeps
6//! a received reply readable until it is released.
7use crate::Instant;
8use crate::{
9    Error, ErrorKind, Result,
10    auth::{Mechanism, Scram},
11    uri::Options,
12    wire::{self, Decoder, Message},
13};
14use bson::{Document, doc, raw::RawDocument};
15use std::collections::VecDeque;
16#[derive(Debug)]
17pub enum ConnectionEvent {
18    UpgradeTls,
19    Ready,
20    Reply { token: u64 },
21    Unacknowledged { token: u64 },
22    Failed { token: Option<u64>, error: Error },
23    Closed,
24}
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26enum State {
27    New,
28    Tls,
29    Handshake,
30    Auth,
31    Ready,
32    Command,
33    UnackSending,
34    Reply,
35    Closed,
36}
37pub struct Connection {
38    options: Options,
39    state: State,
40    tx: Vec<u8>,
41    tx_at: usize,
42    decoder: Decoder,
43    expanded: Vec<u8>,
44    compressed: Vec<u8>,
45    compressor: flate2::Compress,
46    decompressor: flate2::Decompress,
47    zlib: bool,
48    events: VecDeque<ConnectionEvent>,
49    request_id: i32,
50    expected: i32,
51    token: Option<u64>,
52    deadline: Option<Instant>,
53    scram: Option<Scram>,
54    nonce: String,
55    pub hello: Option<Document>,
56    pub max_message_size: usize,
57    pub max_bson_size: usize,
58    pub max_write_batch_size: usize,
59}
60impl Connection {
61    pub fn new(options: Options) -> Self {
62        Self {
63            options,
64            state: State::New,
65            tx: Vec::with_capacity(8192),
66            tx_at: 0,
67            decoder: Decoder::new(wire::DEFAULT_MAX_MESSAGE),
68            expanded: Vec::with_capacity(8192),
69            compressed: Vec::with_capacity(8192),
70            // Raw deflate: zlib.rs writes the RFC 1950 wrapper per message.
71            compressor: flate2::Compress::new(flate2::Compression::default(), false),
72            decompressor: flate2::Decompress::new(true),
73            zlib: false,
74            events: VecDeque::with_capacity(8),
75            request_id: 0,
76            expected: 0,
77            token: None,
78            deadline: None,
79            scram: None,
80            nonce: String::new(),
81            hello: None,
82            max_message_size: wire::DEFAULT_MAX_MESSAGE,
83            max_bson_size: 16 * 1024 * 1024,
84            max_write_batch_size: 100_000,
85        }
86    }
87    /// `nonce` must come from a host CSPRNG if credentials are configured: at least
88    /// 16 printable bytes, fresh per connection. See the crate's
89    /// [host entropy](crate#host-entropy) obligations.
90    pub fn connected(&mut self, now: Instant, nonce: &str) -> Result<()> {
91        if self.state != State::New {
92            return Err(Error::protocol("Connection already started"));
93        }
94        self.nonce.push_str(nonce);
95        self.deadline = if self.options.connect_timeout.is_zero() {
96            None
97        } else {
98            Some(now + self.options.connect_timeout)
99        };
100        if self.options.tls {
101            self.state = State::Tls;
102            self.events.push_back(ConnectionEvent::UpgradeTls);
103            Ok(())
104        } else {
105            self.handshake()
106        }
107    }
108    pub fn tls_established(&mut self) -> Result<()> {
109        if self.state != State::Tls {
110            return Err(Error::protocol("Unexpected TLS completion"));
111        }
112        self.handshake()
113    }
114    fn handshake(&mut self) -> Result<()> {
115        let mut d = doc! {"isMaster":1,"helloOk":true,"client":{"driver":{"name":"turnloop-mongodb","version":env!("CARGO_PKG_VERSION")},"os":{"type":std::env::consts::OS}},"compression":self.options.compressors.clone(),"$db":"admin"};
116        if let Some(app) = &self.options.app_name {
117            d.get_document_mut("client")
118                .unwrap()
119                .insert("application", doc! {"name":app});
120        }
121        if let Some(c) = &self.options.credential {
122            if c.mechanism.is_none() {
123                d.insert("saslSupportedMechs", format!("{}.{}", c.source, c.username));
124            }
125            let mut scram = Scram::new(c, c.mechanism.unwrap_or(Mechanism::Sha256), &self.nonce)?;
126            d.insert("speculativeAuthenticate", scram.start(&c.source, true));
127            self.scram = Some(scram);
128        }
129        self.state = State::Handshake;
130        self.send_document(&d)?;
131        Ok(())
132    }
133    fn send_document(&mut self, d: &Document) -> Result<()> {
134        let raw = bson::raw::RawDocumentBuf::try_from(d)
135            .map_err(|_| Error::protocol("Cannot encode BSON command"))?;
136        self.send(&raw, &[], 0)
137    }
138    fn send(
139        &mut self,
140        body: &RawDocument,
141        seq: &[(&str, &[&RawDocument])],
142        flags: u32,
143    ) -> Result<()> {
144        let id = self.request_id.wrapping_add(1).max(1);
145        wire::encode(&mut self.tx, id, 0, flags, body, seq, self.max_message_size)?;
146        self.request_id = id;
147        self.expected = id;
148        self.tx_at = 0;
149        let command = body
150            .iter_elements()
151            .next()
152            .transpose()
153            .map_err(|_| Error::protocol("Invalid command"))?
154            .ok_or_else(|| Error::protocol("Empty command"))?;
155        self.compress(command.key().as_str())
156    }
157    fn compress(&mut self, command: &str) -> Result<()> {
158        // Compression spec § Commands Not to Compress: includes authentication secrets.
159        if self.zlib
160            && !matches!(
161                command,
162                "hello"
163                    | "isMaster"
164                    | "ismaster"
165                    | "saslStart"
166                    | "saslContinue"
167                    | "authenticate"
168                    | "getnonce"
169                    | "createUser"
170                    | "updateUser"
171                    | "copydbSaslStart"
172                    | "copydbgetnonce"
173                    | "copydb"
174            )
175        {
176            self.compressed.clear();
177            self.compressed.extend_from_slice(&self.tx[..16]);
178            self.compressed[12..16].copy_from_slice(&wire::OP_COMPRESSED.to_le_bytes());
179            self.compressed
180                .extend_from_slice(&wire::OP_MSG.to_le_bytes());
181            self.compressed
182                .extend_from_slice(&((self.tx.len() - 16) as i32).to_le_bytes());
183            self.compressed.push(2);
184            // One retained deflate state, one zlib stream per message; see zlib.rs.
185            crate::zlib::append_stream(&mut self.compressor, &self.tx[16..], &mut self.compressed)
186                .map_err(Error::protocol)?;
187            let n = self.compressed.len() as i32;
188            self.compressed[..4].copy_from_slice(&n.to_le_bytes());
189            std::mem::swap(&mut self.tx, &mut self.compressed);
190        }
191        Ok(())
192    }
193    pub fn is_ready(&self) -> bool {
194        self.state == State::Ready
195    }
196    pub fn transmit(&self) -> &[u8] {
197        &self.tx[self.tx_at..]
198    }
199    pub fn consume_transmit(&mut self, n: usize) -> Result<()> {
200        if n > self.tx.len() - self.tx_at {
201            return Err(Error::protocol("Transmit consumption exceeds bytes"));
202        }
203        self.tx_at += n;
204        if self.tx_at == self.tx.len() {
205            self.tx.clear();
206            self.tx_at = 0;
207            if self.state == State::UnackSending {
208                self.state = State::Ready;
209                self.deadline = None;
210                self.events.push_back(ConnectionEvent::Unacknowledged {
211                    token: self.token.take().unwrap(),
212                });
213            }
214        }
215        Ok(())
216    }
217    /// Whether `receive` would accept bytes now: a handshake, authentication or
218    /// command reply is outstanding. This is the exact check `receive` makes, so
219    /// a host need not shadow the state machine to decide when to read. It is
220    /// false before `connected`, during a TLS upgrade, when idle, while an
221    /// unacknowledged write drains, while a reply is unreleased and after close.
222    pub fn accepts_receive(&self) -> bool {
223        matches!(self.state, State::Handshake | State::Auth | State::Command)
224    }
225    /// Feed may consume only a frame prefix; retain and feed the remaining bytes.
226    pub fn receive(&mut self, input: &[u8]) -> Result<usize> {
227        if !self.accepts_receive() {
228            return Err(Error::protocol("Connection is not expecting a reply"));
229        }
230        let result = self.receive_inner(input);
231        if let Err(e) = &result {
232            self.fail(e.clone());
233        }
234        result
235    }
236    fn receive_inner(&mut self, input: &[u8]) -> Result<usize> {
237        let n = self.decoder.feed(input)?;
238        if !self.decoder.complete() {
239            return Ok(n);
240        }
241        self.expanded.clear();
242        if wire::i32_at(self.decoder.bytes(), 12)? == wire::OP_COMPRESSED {
243            if !self.zlib {
244                return Err(Error::protocol("Unnegotiated compressed reply"));
245            }
246            let b = self.decoder.bytes();
247            if b.len() < 25 || wire::i32_at(b, 16)? != wire::OP_MSG || b[24] != 2 {
248                return Err(Error::protocol("Invalid compressed envelope"));
249            }
250            let size = wire::i32_at(b, 20)?;
251            if size < 10 || size as usize > self.max_message_size - 16 {
252                return Err(Error::protocol("Decompressed size out of range"));
253            }
254            self.expanded.extend_from_slice(&b[..16]);
255            self.expanded[..4].copy_from_slice(&(size + 16).to_le_bytes());
256            self.expanded[12..16].copy_from_slice(&wire::OP_MSG.to_le_bytes());
257            self.expanded.resize(16 + size as usize, 0);
258            self.decompressor.reset(true);
259            let status = self
260                .decompressor
261                .decompress(
262                    &b[25..],
263                    &mut self.expanded[16..],
264                    flate2::FlushDecompress::Finish,
265                )
266                .map_err(|_| Error::protocol("Invalid zlib reply"))?;
267            if status != flate2::Status::StreamEnd
268                || self.decompressor.total_out() != size as u64
269                || self.decompressor.total_in() != b.len() as u64 - 25
270            {
271                return Err(Error::protocol("Compressed reply size mismatch"));
272            }
273        }
274        let m = Message::parse(self.frame(), self.max_message_size)?;
275        if m.response_to != self.expected {
276            return Err(Error::protocol("MongoDB responseTo does not match request"));
277        }
278        if m.flags & wire::MORE_TO_COME != 0 {
279            return Err(Error::protocol("Unexpected exhaust reply"));
280        }
281        if self.state == State::Command {
282            self.state = State::Reply;
283            self.deadline = None;
284            self.events.push_back(ConnectionEvent::Reply {
285                token: self.token.unwrap(),
286            });
287            return Ok(n);
288        }
289        Error::from_response(m.body)?;
290        let d: Document = m
291            .body
292            .try_into()
293            .map_err(|_| Error::protocol("Malformed handshake BSON"))?;
294        self.decoder.clear();
295        self.expanded.clear();
296        if self.state == State::Handshake {
297            let wire_version = d.get_i32("maxWireVersion").unwrap_or(0);
298            if wire_version < 6 || d.get_i32("minWireVersion").unwrap_or(0) > 27 {
299                return Err(Error::protocol(
300                    "MongoDB server wire version is incompatible (client supports 6 through 27)",
301                ));
302            }
303            for (key, target, min) in [
304                ("maxMessageSizeBytes", &mut self.max_message_size, 26),
305                ("maxBsonObjectSize", &mut self.max_bson_size, 5),
306                ("maxWriteBatchSize", &mut self.max_write_batch_size, 1),
307            ] {
308                if let Ok(v) = d.get_i32(key) {
309                    if v < min {
310                        return Err(Error::protocol("Invalid handshake size limit"));
311                    }
312                    *target = v as usize;
313                }
314            }
315            self.max_message_size = self.max_message_size.min(wire::DEFAULT_MAX_MESSAGE);
316            self.decoder.set_max(self.max_message_size);
317            self.zlib = self.options.compressors.iter().any(|c| c == "zlib")
318                && d.get_array("compression")
319                    .ok()
320                    .is_some_and(|a| a.iter().any(|b| b.as_str() == Some("zlib")));
321            self.hello = Some(d.clone());
322            if let Some(c) = &self.options.credential
323                && !d.get_bool("arbiterOnly").unwrap_or(false)
324            {
325                self.state = State::Auth;
326                let next = if let Ok(spec) = d.get_document("speculativeAuthenticate") {
327                    self.scram.as_mut().unwrap().receive(spec, &c.source)?
328                } else {
329                    let mechanism = c.mechanism.unwrap_or_else(|| {
330                        if d.get_array("saslSupportedMechs")
331                            .ok()
332                            .is_some_and(|a| a.iter().any(|b| b.as_str() == Some("SCRAM-SHA-256")))
333                        {
334                            Mechanism::Sha256
335                        } else {
336                            Mechanism::Sha1
337                        }
338                    });
339                    let mut scram = Scram::new(c, mechanism, &self.nonce)?;
340                    let start = scram.start(&c.source, false);
341                    self.scram = Some(scram);
342                    Some(start)
343                };
344                if let Some(next) = next {
345                    self.send_document(&next)?;
346                    return Ok(n);
347                }
348            }
349        } else if self.state == State::Auth {
350            let source = &self.options.credential.as_ref().unwrap().source;
351            let next = self.scram.as_mut().unwrap().receive(&d, source)?;
352            if let Some(next) = next {
353                self.send_document(&next)?;
354                return Ok(n);
355            }
356        }
357        self.scram = None;
358        self.nonce.clear();
359        self.state = State::Ready;
360        self.deadline = None;
361        self.events.push_back(ConnectionEvent::Ready);
362        Ok(n)
363    }
364    fn frame(&self) -> &[u8] {
365        if self.expanded.is_empty() {
366            self.decoder.bytes()
367        } else {
368            &self.expanded
369        }
370    }
371    pub fn reply(&self) -> Result<&RawDocument> {
372        if self.state != State::Reply
373            && !(self.state == State::Closed && self.token.is_some() && self.decoder.complete())
374        {
375            return Err(Error::protocol("No reply available"));
376        }
377        Ok(Message::parse(self.frame(), self.max_message_size)?.body)
378    }
379    pub fn release_reply(&mut self) -> Result<()> {
380        if self.state != State::Reply
381            && !(self.state == State::Closed && self.token.is_some() && self.decoder.complete())
382        {
383            return Err(Error::protocol("No reply to release"));
384        }
385        self.token = None;
386        self.decoder.clear();
387        self.expanded.clear();
388        if self.state != State::Closed {
389            self.state = State::Ready;
390        }
391        Ok(())
392    }
393    pub fn poll_event(&mut self) -> Option<ConnectionEvent> {
394        self.events.pop_front()
395    }
396    pub fn command(
397        &mut self,
398        token: u64,
399        body: &RawDocument,
400        sequences: &[(&str, &[&RawDocument])],
401        now: Instant,
402    ) -> Result<()> {
403        if self.state != State::Ready || !self.tx.is_empty() {
404            return Err(Error::protocol("Connection busy"));
405        }
406        if body.get_str("$db").is_err() {
407            return Err(Error::protocol("Command requires $db"));
408        }
409        if body.as_bytes().len() > self.max_bson_size
410            || sequences.iter().any(|(_, docs)| {
411                docs.len() > self.max_write_batch_size
412                    || docs.iter().any(|d| d.as_bytes().len() > self.max_bson_size)
413            })
414        {
415            return Err(Error::protocol(
416                "Command exceeds negotiated BSON or batch size",
417            ));
418        }
419        let unack = body
420            .get("writeConcern")
421            .ok()
422            .flatten()
423            .and_then(|v| v.as_document())
424            .is_some_and(|d| {
425                matches!(
426                    d.get("w"),
427                    Ok(Some(
428                        bson::raw::RawBsonRef::Int32(0) | bson::raw::RawBsonRef::Int64(0)
429                    ))
430                )
431            });
432        self.send(body, sequences, if unack { wire::MORE_TO_COME } else { 0 })?;
433        if unack {
434            self.token = Some(token);
435            self.state = State::UnackSending;
436            self.deadline = if self.options.socket_timeout.is_zero() {
437                None
438            } else {
439                Some(now + self.options.socket_timeout)
440            };
441        } else {
442            self.token = Some(token);
443            self.state = State::Command;
444            self.deadline = if self.options.socket_timeout.is_zero() {
445                None
446            } else {
447                Some(now + self.options.socket_timeout)
448            };
449        }
450        Ok(())
451    }
452    /// Sends an already encoded OP_MSG template with a fresh wire request id.
453    /// Used by Operation to retain sequence storage and session identity on retries.
454    pub fn command_encoded(&mut self, token: u64, frame: &[u8], now: Instant) -> Result<()> {
455        if self.state != State::Ready || !self.tx.is_empty() {
456            return Err(Error::protocol("Connection busy"));
457        }
458        let message = Message::parse(frame, self.max_message_size)?;
459        if message.flags != 0 || message.body.get_str("$db").is_err() {
460            return Err(Error::protocol(
461                "Operation template requires $db and no wire flags",
462            ));
463        }
464        if message
465            .body
466            .get("writeConcern")
467            .ok()
468            .flatten()
469            .and_then(|v| v.as_document())
470            .is_some_and(|d| {
471                matches!(
472                    d.get("w"),
473                    Ok(Some(
474                        bson::raw::RawBsonRef::Int32(0) | bson::raw::RawBsonRef::Int64(0)
475                    ))
476                )
477            })
478        {
479            return Err(Error::protocol(
480                "Unacknowledged writes require Connection::command",
481            ));
482        }
483        if message.body.as_bytes().len() > self.max_bson_size {
484            return Err(Error::protocol("Command exceeds maxBsonObjectSize"));
485        }
486        for seq in message.sequences() {
487            let mut n = 0;
488            for d in seq.documents() {
489                n += 1;
490                if n > self.max_write_batch_size || d.as_bytes().len() > self.max_bson_size {
491                    return Err(Error::protocol("Write sequence exceeds server limits"));
492                }
493            }
494        }
495        let command = message
496            .body
497            .iter_elements()
498            .next()
499            .transpose()
500            .map_err(|_| Error::protocol("Invalid command"))?
501            .ok_or_else(|| Error::protocol("Empty command"))?;
502        self.tx.clear();
503        self.tx.extend_from_slice(frame);
504        self.request_id = self.request_id.wrapping_add(1).max(1);
505        self.expected = self.request_id;
506        self.tx[4..8].copy_from_slice(&self.request_id.to_le_bytes());
507        self.tx_at = 0;
508        if let Err(e) = self.compress(command.key().as_str()) {
509            self.tx.clear();
510            return Err(e);
511        }
512        self.token = Some(token);
513        self.state = State::Command;
514        self.deadline = if self.options.socket_timeout.is_zero() {
515            None
516        } else {
517            Some(now + self.options.socket_timeout)
518        };
519        Ok(())
520    }
521    pub fn next_timeout(&self) -> Option<Instant> {
522        self.deadline
523    }
524    pub fn handle_timeout(&mut self, now: Instant) {
525        if self.deadline.is_some_and(|d| now >= d) {
526            self.fail(Error::new(
527                ErrorKind::Timeout,
528                "MongoDB connection timed out",
529            ));
530        }
531    }
532    /// Closes the connection after a transport or protocol failure. An
533    /// outstanding command, or a reply not yet released, settles with `Failed`.
534    /// Such a reply is revoked: `reply()` and `release_reply()` then fail, and
535    /// its `Reply` event is withdrawn if the host has not yet polled it.
536    pub fn fail(&mut self, error: Error) {
537        if self.state == State::Closed {
538            return;
539        }
540        let token = self.token.take();
541        if self.state == State::Reply {
542            self.decoder.clear();
543            self.expanded.clear();
544            self.events
545                .retain(|e| !matches!(e, ConnectionEvent::Reply { token: t } if Some(*t) == token));
546        }
547        self.events
548            .push_back(ConnectionEvent::Failed { token, error });
549        self.state = State::Closed;
550        self.deadline = None;
551        self.tx.clear();
552        self.tx_at = 0;
553        self.events.push_back(ConnectionEvent::Closed);
554    }
555    pub fn close(&mut self) {
556        if self.state == State::Closed {
557            return;
558        }
559        if self.token.is_some() && self.state != State::Reply {
560            self.events.push_back(ConnectionEvent::Failed {
561                token: self.token.take(),
562                error: Error::new(
563                    ErrorKind::Cancelled,
564                    "Operation cancelled by connection close",
565                ),
566            });
567        }
568        self.state = State::Closed;
569        self.deadline = None;
570        self.tx.clear();
571        self.tx_at = 0;
572        self.events.push_back(ConnectionEvent::Closed);
573    }
574}