Skip to main content

dayzmake_core/navmesh/
client.rs

1//! A TCP client for the navmesh data server (spec 3.1, 3.6).
2//!
3//! IPv4 only, `TCP_NODELAY`, one outstanding request per connection. A tile request that fails with a
4//! network-class error is retried on a fresh connection ([`RetryPolicy`]); a malformed answer is not.
5
6use std::fmt;
7use std::io::{self, Read, Write};
8use std::net::{SocketAddr, TcpStream, ToSocketAddrs};
9use std::time::{Duration, Instant};
10
11use crate::navmesh::wire::{DEFAULT_PORT, TileInput, WorldParams, encode_tile_request};
12
13const MSG_WORLD_PARAMS_REQUEST: u32 = 2;
14const MSG_TILE_REQUEST: u32 = 3;
15const MSG_WORLD_PARAMS: u32 = 4;
16const MSG_TILE: u32 = 5;
17/// Largest frame length field the server may send (spec 3.1).
18pub(crate) const MAX_FRAME: u32 = 1 << 30;
19/// Frames are read in chunks of at most this size, so a hostile length never allocates at once.
20pub(crate) const READ_CHUNK: usize = 16 << 20;
21
22/// How the client connects and retries a failed tile request.
23#[derive(Debug, Clone, PartialEq, Eq)]
24#[non_exhaustive]
25pub struct RetryPolicy {
26    /// Attempts per tile (the first try included).
27    pub attempts: u32,
28    /// After failed attempt `n` (counting from 0) the client waits `delay_unit * (n + 1)`. With the
29    /// defaults (5 attempts, 1 s) that is 1, 2, 3 and 4 s: 10 s of waiting in all. Every attempt can also
30    /// take up to `connect_timeout` to connect, so a host that does not answer at all costs up to
31    /// 5 * `connect_timeout` more.
32    pub delay_unit: Duration,
33    /// Connect timeout.
34    pub connect_timeout: Duration,
35    /// How long each receive waits for a complete message.
36    pub recv_timeout: Duration,
37}
38
39impl Default for RetryPolicy {
40    fn default() -> Self {
41        Self {
42            attempts: 5,
43            delay_unit: Duration::from_secs(1),
44            connect_timeout: Duration::from_secs(10),
45            recv_timeout: Duration::from_secs(600),
46        }
47    }
48}
49
50/// A data server address: a host name or IPv4 address and a port.
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct Host {
53    name: String,
54    port: u16,
55}
56
57impl Host {
58    /// Parses `host` or `host:port`; the port defaults to [`DEFAULT_PORT`].
59    ///
60    /// # Errors
61    ///
62    /// Fails for an empty host or port, a port that is not a number in `1..=65535`, and more than
63    /// one `:` (IPv6 is not supported).
64    pub fn parse(text: &str) -> io::Result<Self> {
65        let (name, port) = match text.split_once(':') {
66            None => (text, DEFAULT_PORT),
67            Some((name, port)) => {
68                let port = port
69                    .parse::<u16>()
70                    .ok()
71                    .filter(|p| *p != 0)
72                    .ok_or_else(|| error!("invalid port in host \"{text}\""))?;
73                (name, port)
74            }
75        };
76        if name.is_empty() || name.contains(':') {
77            return Err(error!("invalid host \"{text}\""));
78        }
79        Ok(Self {
80            name: name.to_owned(),
81            port,
82        })
83    }
84
85    /// The host name or address.
86    #[must_use]
87    pub fn name(&self) -> &str {
88        &self.name
89    }
90
91    /// The port.
92    #[must_use]
93    pub fn port(&self) -> u16 {
94        self.port
95    }
96}
97
98impl fmt::Display for Host {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        write!(f, "{}:{}", self.name, self.port)
101    }
102}
103
104/// Why fetching a tile failed.
105#[derive(Debug)]
106#[non_exhaustive]
107pub enum FetchError {
108    /// A network-class failure (connect, send, receive, timeout, peer closed, invalid frame, wrong
109    /// message, wrong tile, unknown cell class) that persisted through every attempt.
110    Network(io::Error),
111    /// The tile payload is malformed. Not retried.
112    Wire(io::Error),
113}
114
115impl fmt::Display for FetchError {
116    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
117        match self {
118            Self::Network(e) | Self::Wire(e) => e.fmt(f),
119        }
120    }
121}
122
123impl std::error::Error for FetchError {
124    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
125        match self {
126            Self::Network(e) | Self::Wire(e) => Some(e),
127        }
128    }
129}
130
131/// Reads `len` bytes in chunks of at most 16 MiB; the buffer only grows as data arrives.
132pub(crate) fn read_chunked(r: &mut impl Read, len: usize) -> io::Result<Vec<u8>> {
133    let mut out = Vec::new();
134    while out.len() < len {
135        let want = (len - out.len()).min(READ_CHUNK);
136        let before = out.len();
137        let got = r
138            .take(u64::try_from(want).unwrap_or(u64::MAX))
139            .read_to_end(&mut out)?;
140        if got != want || out.len() != before + want {
141            return Err(io::Error::new(
142                io::ErrorKind::UnexpectedEof,
143                "frame truncated",
144            ));
145        }
146    }
147    Ok(out)
148}
149
150/// Reads one frame: `u32 length`, `u32 messageId`, `length - 4` payload bytes.
151///
152/// # Errors
153///
154/// "invalid frame length N" for a length below 4 or above 2^30; an I/O error when the stream ends.
155pub(crate) fn read_frame(r: &mut impl Read) -> io::Result<(u32, Vec<u8>)> {
156    let mut head = [0u8; 8];
157    r.read_exact(&mut head[..4])?;
158    let length = u32::from_le_bytes([head[0], head[1], head[2], head[3]]);
159    if !(4..=MAX_FRAME).contains(&length) {
160        return Err(error!("invalid frame length {length}"));
161    }
162    r.read_exact(&mut head[4..])?;
163    let id = u32::from_le_bytes([head[4], head[5], head[6], head[7]]);
164    let payload_len =
165        usize::try_from(length - 4).map_err(|_| error!("invalid frame length {length}"))?;
166    Ok((id, read_chunked(r, payload_len)?))
167}
168
169/// Writes one frame.
170pub(crate) fn write_frame(w: &mut impl Write, id: u32, payload: &[u8]) -> io::Result<()> {
171    let length = payload
172        .len()
173        .checked_add(4)
174        .and_then(|n| u32::try_from(n).ok())
175        .filter(|n| *n <= MAX_FRAME)
176        .ok_or_else(|| error!("frame too large"))?;
177    let mut out = Vec::with_capacity(payload.len() + 8);
178    out.extend_from_slice(&length.to_le_bytes());
179    out.extend_from_slice(&id.to_le_bytes());
180    out.extend_from_slice(payload);
181    w.write_all(&out)?;
182    w.flush()
183}
184
185/// A reader that gives every `read` only the time left until the message deadline, so the receive
186/// timeout covers the whole message and not each `read` call.
187struct DeadlineReader<'a> {
188    stream: &'a TcpStream,
189    /// `None` when the deadline is not representable (a huge timeout): no limit.
190    deadline: Option<Instant>,
191}
192
193impl Read for DeadlineReader<'_> {
194    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
195        if let Some(deadline) = self.deadline {
196            let left = deadline
197                .checked_duration_since(Instant::now())
198                .filter(|d| !d.is_zero())
199                .ok_or_else(|| io::Error::new(io::ErrorKind::TimedOut, "receive timed out"))?;
200            self.stream
201                .set_read_timeout(Some(at_least_a_millisecond(left)))?;
202        }
203        // An expired socket timeout is `WouldBlock` on Unix and `TimedOut` on Windows.
204        self.stream.read(buf).map_err(|e| match e.kind() {
205            io::ErrorKind::WouldBlock | io::ErrorKind::TimedOut => {
206                io::Error::new(io::ErrorKind::TimedOut, "receive timed out")
207            }
208            _ => e,
209        })
210    }
211}
212
213/// A connection to a data server.
214#[derive(Debug)]
215pub struct Client {
216    host: Host,
217    policy: RetryPolicy,
218    stream: Option<TcpStream>,
219    /// The last failed try got a complete answer that was wrong (not a tile, the wrong tile, an unknown
220    /// cell class), as opposed to a connect, send or receive failure.
221    answer_failed: bool,
222}
223
224/// Names the server in an I/O error of an exchange; a stream that ends is "closed by the server".
225fn with_host(e: &io::Error, target: &str) -> io::Error {
226    let kind = e.kind();
227    if kind == io::ErrorKind::UnexpectedEof {
228        io::Error::new(kind, format!("connection to {target} closed by the server"))
229    } else {
230        io::Error::new(kind, format!("{target}: {e}"))
231    }
232}
233
234fn at_least_a_millisecond(d: Duration) -> Duration {
235    d.max(Duration::from_millis(1))
236}
237
238fn open(host: &Host, policy: &RetryPolicy) -> io::Result<TcpStream> {
239    let target = host.to_string();
240    let hint = "start DayZDiag_x64.exe with -server -startNavmeshDataServer";
241    let addr: SocketAddr = (host.name.as_str(), host.port)
242        .to_socket_addrs()
243        .map_err(|e| error!("cannot resolve {target}: {e}"))?
244        .find(SocketAddr::is_ipv4)
245        .ok_or_else(|| error!("no IPv4 address for {target}"))?;
246    let stream = TcpStream::connect_timeout(&addr, at_least_a_millisecond(policy.connect_timeout))
247        .map_err(|e| error!("cannot connect to {target}: {e}; {hint}"))?;
248    stream.set_nodelay(true)?;
249    let t = Some(at_least_a_millisecond(policy.recv_timeout));
250    stream.set_read_timeout(t)?;
251    stream.set_write_timeout(t)?;
252    Ok(stream)
253}
254
255impl Client {
256    /// Connects to `host`.
257    ///
258    /// # Errors
259    ///
260    /// Fails when the name does not resolve to an IPv4 address or the connection fails. The message
261    /// names `host:port` and says to start `DayZDiag_x64.exe` with `-server -startNavmeshDataServer`.
262    pub fn connect(host: &Host, policy: &RetryPolicy) -> io::Result<Self> {
263        Ok(Self {
264            host: host.clone(),
265            policy: policy.clone(),
266            stream: Some(open(host, policy)?),
267            answer_failed: false,
268        })
269    }
270
271    /// A client that has not connected yet: the first request connects, and a failed connect is
272    /// retried like any other network-class failure of [`Client::tile`].
273    pub(crate) fn lazy(host: &Host, policy: &RetryPolicy) -> Self {
274        Self {
275            host: host.clone(),
276            policy: policy.clone(),
277            stream: None,
278            answer_failed: false,
279        }
280    }
281
282    /// Whether the last failure of [`Client::tile`] was a complete but wrong answer. The frame was read
283    /// whole, so the stream is in sync (and the failed try closed the connection anyway): the fault is the
284    /// tile's, not the connection's.
285    pub(crate) fn last_failure_was_answer(&self) -> bool {
286        self.answer_failed
287    }
288
289    /// Requests the world params. One attempt, no retry.
290    ///
291    /// # Errors
292    ///
293    /// Fails on I/O errors, on an answer that is not message 4 ("expected world params, got message
294    /// N") and on a malformed or wrong-version payload.
295    pub fn world_params(&mut self) -> io::Result<WorldParams> {
296        let result = self
297            .exchange(MSG_WORLD_PARAMS_REQUEST, &[])
298            .and_then(|(id, payload)| {
299                if id == MSG_WORLD_PARAMS {
300                    WorldParams::parse_message(&payload)
301                } else {
302                    Err(error!("expected world params, got message {id}"))
303                }
304            });
305        if result.is_err() {
306            self.stream = None;
307        }
308        result
309    }
310
311    /// Fetches tile `(x, z)`.
312    ///
313    /// A network-class failure closes the connection, waits `delay_unit * (attempt + 1)` and retries
314    /// on a fresh connection; the last allowed attempt's failure is final ([`FetchError::Network`]).
315    /// A malformed payload is a [`FetchError::Wire`] at once.
316    ///
317    /// # Errors
318    ///
319    /// See above. The answer must carry the requested `(x, z)` and a cell class that exists in
320    /// `world`.
321    pub fn tile(&mut self, x: i32, z: i32, world: &WorldParams) -> Result<TileInput, FetchError> {
322        let attempts = self.policy.attempts.max(1);
323        let mut attempt = 0u32;
324        loop {
325            match self.try_tile(x, z, world) {
326                Ok(t) => return Ok(t),
327                Err(e @ FetchError::Wire(_)) => return Err(e),
328                Err(FetchError::Network(e)) => {
329                    self.stream = None;
330                    attempt += 1;
331                    if attempt >= attempts {
332                        return Err(FetchError::Network(e));
333                    }
334                    std::thread::sleep(self.policy.delay_unit.saturating_mul(attempt));
335                }
336            }
337        }
338    }
339
340    fn try_tile(&mut self, x: i32, z: i32, world: &WorldParams) -> Result<TileInput, FetchError> {
341        self.answer_failed = false;
342        let request = encode_tile_request(x, z, &world.world);
343        let (id, payload) = self
344            .exchange(MSG_TILE_REQUEST, &request)
345            .map_err(FetchError::Network)?;
346        if id != MSG_TILE {
347            self.answer_failed = true;
348            return Err(FetchError::Network(error!(
349                "expected tile, got message {id}"
350            )));
351        }
352        let tile = TileInput::parse(&payload).map_err(FetchError::Wire)?;
353        if tile.x != x || tile.z != z {
354            self.answer_failed = true;
355            return Err(FetchError::Network(error!(
356                "the server answered with tile ({},{})",
357                tile.x, tile.z
358            )));
359        }
360        let class = usize::try_from(tile.cell_class).unwrap_or(usize::MAX);
361        if class >= world.cell_classes.len() {
362            self.answer_failed = true;
363            return Err(FetchError::Network(error!(
364                "unknown cell class {}",
365                tile.cell_class
366            )));
367        }
368        Ok(tile)
369    }
370
371    /// Sends one request on the current connection (opening one if needed) and reads the answer.
372    fn exchange(&mut self, id: u32, payload: &[u8]) -> io::Result<(u32, Vec<u8>)> {
373        let stream = match &mut self.stream {
374            Some(s) => s,
375            slot => slot.insert(open(&self.host, &self.policy)?),
376        };
377        let target = self.host.to_string();
378        write_frame(stream, id, payload).map_err(|e| with_host(&e, &target))?;
379        // One deadline for the whole message (spec 3.1), not one per `read`.
380        let deadline = Instant::now().checked_add(at_least_a_millisecond(self.policy.recv_timeout));
381        read_frame(&mut DeadlineReader { stream, deadline }).map_err(|e| with_host(&e, &target))
382    }
383}
384
385#[cfg(test)]
386mod tests {
387    use super::*;
388    use std::io::Cursor;
389
390    fn frame(length: u32, id: u32, payload: &[u8]) -> Vec<u8> {
391        let mut v = length.to_le_bytes().to_vec();
392        v.extend_from_slice(&id.to_le_bytes());
393        v.extend_from_slice(payload);
394        v
395    }
396
397    #[test]
398    fn the_default_backoff_is_five_tries_in_ten_seconds() {
399        let p = RetryPolicy::default();
400        assert_eq!(p.attempts, 5);
401        let total: Duration = (1..p.attempts).map(|n| p.delay_unit * n).sum();
402        assert_eq!(total, Duration::from_secs(10));
403    }
404
405    #[test]
406    fn read_frame_rules() {
407        let (id, p) = read_frame(&mut Cursor::new(frame(7, 5, &[1, 2, 3]))).expect("ok");
408        assert_eq!((id, p), (5, vec![1, 2, 3]));
409        let (id, p) = read_frame(&mut Cursor::new(frame(4, 9, &[]))).expect("empty");
410        assert_eq!((id, p), (9, vec![]));
411        for bad in [0u32, 3, MAX_FRAME + 1, u32::MAX] {
412            let e = read_frame(&mut Cursor::new(frame(bad, 5, &[0; 8]))).expect_err("bad");
413            assert!(e.to_string().contains("invalid frame"), "{e}");
414        }
415    }
416
417    #[test]
418    fn read_frame_longer_than_the_stream_is_truncated_not_allocated() {
419        // Announces 1 GiB, delivers 5 bytes: an error, and only 5 bytes were ever buffered.
420        let e = read_frame(&mut Cursor::new(frame(MAX_FRAME, 5, &[1; 5]))).expect_err("short");
421        assert_eq!(e.kind(), io::ErrorKind::UnexpectedEof);
422    }
423
424    #[test]
425    fn read_chunked_crosses_chunk_boundaries() {
426        let data = vec![7u8; READ_CHUNK + 5];
427        let out = read_chunked(&mut Cursor::new(&data), data.len()).expect("ok");
428        assert_eq!(out.len(), data.len());
429        assert!(read_chunked(&mut Cursor::new(&data), data.len() + 1).is_err());
430    }
431
432    #[test]
433    fn lazy_client_retries_the_first_connect() {
434        // A closed port: every connect is refused. With attempts 3 the client sleeps
435        // `delay_unit * 1` and `delay_unit * 2` between them, a lower bound on the time taken.
436        let port = {
437            let l = std::net::TcpListener::bind("127.0.0.1:0").expect("bind");
438            l.local_addr().expect("addr").port()
439        };
440        let policy = RetryPolicy {
441            attempts: 3,
442            delay_unit: Duration::from_millis(30),
443            ..RetryPolicy::default()
444        };
445        let host = Host::parse(&format!("127.0.0.1:{port}")).expect("host");
446        let mut client = Client::lazy(&host, &policy);
447        let world = WorldParams::default();
448        let started = Instant::now();
449        let e = client.tile(0, 0, &world).expect_err("refused");
450        assert!(matches!(e, FetchError::Network(_)), "{e}");
451        assert!(started.elapsed() >= Duration::from_millis(90));
452    }
453
454    #[test]
455    fn write_frame_layout() {
456        let mut out = Vec::new();
457        write_frame(&mut out, 3, &[9, 8]).expect("ok");
458        assert_eq!(out, frame(6, 3, &[9, 8]));
459    }
460}