Skip to main content

shep_client/
client.rs

1//! The connected [`Client`] handle: [`Client::connect`], [`Client::request`],
2//! [`RequestError`].
3//!
4//! A `Client` is a thin, actor-backed handle: the socket itself is owned by
5//! the task [`crate::actor::spawn`] starts, and every method here sends a
6//! command to that task and awaits the answer. `&self` is enough for every
7//! method, so concurrent callers share one `Client` (behind an `Arc`, or
8//! just a shared reference) instead of cloning a handle per caller.
9
10use core::fmt;
11use std::path::{Path, PathBuf};
12use std::time::Duration;
13
14use tokio::sync::{mpsc, oneshot};
15
16use shep_core::destination::Destination;
17use shep_core::protocol::{HelloAck, Request, Response, RpcError, RpcErrorCode, WireError};
18
19use crate::actor::{self, Command};
20use crate::connection::{ConnectError, Connection, HANDSHAKE_TIMEOUT};
21use crate::events::EventStream;
22use crate::ssh::{self, SshOptions};
23
24/// Daemon-side budget applied when a caller names none. Mirrors the daemon's
25/// own `DEFAULT_DEADLINE_MS = 5_000` (`shep-daemon/src/rpc.rs`).
26pub const DEFAULT_DEADLINE: Duration = Duration::from_secs(5);
27
28/// Budget for `Request::Start`. A cold spawn plus a readiness probe routinely
29/// outruns the 5s default, and the daemon clamps anything over
30/// `MAX_DEADLINE_MS = 60_000` (`shep-daemon/src/rpc.rs:38`), so this is well
31/// inside what the daemon will honour.
32pub const START_DEADLINE: Duration = Duration::from_secs(30);
33
34/// Budget for `Request::Reload`.
35///
36/// A reload walks several sheep in dependency order. It holds every stage
37/// for the drains and readiness waits a later stage needs. Two stages at
38/// the default timeouts already pass [`START_DEADLINE`]. This asks for the
39/// daemon's whole `MAX_DEADLINE_MS` (60s), the most it honours. Four
40/// default single-instance stages need 64s, past even that.
41pub const RELOAD_DEADLINE: Duration = Duration::from_secs(60);
42
43/// Budget for the log-plane verbs that walk the flock file by file:
44/// `Request::Reopen` and `Request::Flush`.
45///
46/// The daemon visits matched sheep one after another with no per-sheep
47/// bound, so a wedged or NFS-backed log directory can make the whole walk
48/// take as long as the kernel does. Same 30s as [`START_DEADLINE`],
49/// comfortably inside the daemon's own clamp.
50pub const LOG_PLANE_DEADLINE: Duration = Duration::from_secs(30);
51
52/// Budget for `Request::Trigger`.
53///
54/// An app's own `AppConfig::action_timeout` can reach `MAX_ACTION_TIMEOUT`
55/// (58s), 2s under the daemon's own 60s clamp, so this asks for the full
56/// 60s rather than abandon a reply the daemon is still building.
57pub const TRIGGER_DEADLINE: Duration = Duration::from_secs(60);
58
59/// Budget for `Request::Stop` and `Request::Delete`.
60///
61/// A stop runs the kill ladder, then the lamb sweep. Each is bounded by a
62/// sheep's `kill_timeout`, and a selector can match many sheep. The client
63/// cannot size that: asking the daemon for each `kill_timeout` costs a
64/// round trip and still races the actor. This asks for the daemon's whole
65/// `MAX_DEADLINE_MS` (60s) instead.
66pub const STOP_DEADLINE: Duration = Duration::from_secs(60);
67
68/// How much longer the client waits than the deadline it asked the daemon
69/// to honour, so it doesn't report a timeout for work that succeeded.
70pub const DEADLINE_GRACE: Duration = Duration::from_secs(2);
71
72/// Why a [`Client::request`] (or [`Client::request_with_deadline`]) call failed.
73///
74/// Non-exhaustive: expect more variants.
75#[derive(Debug, Clone, PartialEq, Eq)]
76#[non_exhaustive]
77pub enum RequestError {
78    /// The daemon accepted the request and answered it with a structured error.
79    Rpc(RpcError),
80    /// No reply arrived within the request's own deadline plus [`DEADLINE_GRACE`].
81    Timeout {
82        /// The client-side budget that was exceeded.
83        after: Duration,
84    },
85    /// The connection closed (daemon exit, crash, or a prior [`Client::close`])
86    /// before this request's reply arrived.
87    Closed,
88    /// `body` failed to encode onto the wire.
89    Wire(WireError),
90    /// The daemon's reply arrived but this build could not decode it.
91    ///
92    /// Distinct from [`Self::Rpc`]: the daemon did not report a structured
93    /// error, it answered with something (a `Reply` or an unrecognized
94    /// `ServerFrame` variant) that does not match the shapes this build
95    /// knows. The likely cause is a daemon newer than this client, not a
96    /// daemon-side failure, so the message says which side could not read.
97    Undecodable(WireError),
98    /// The daemon answered with a [`Response`] other than the one a typed
99    /// request expects, such as a `Flock` for a `DogConfig`.
100    ///
101    /// Names both by variant alone: a listing or a dog's section never
102    /// reaches the message.
103    UnexpectedReply {
104        /// The request sent, by its `Request` variant name.
105        asked: &'static str,
106        /// The answer received, by [`Response::name`].
107        answered: &'static str,
108    },
109}
110
111impl RequestError {
112    /// The [`shep_core::exit`] code a process stopping on this error uses.
113    ///
114    /// A refusal takes its own code's number, and a closed connection is
115    /// nothing answering. A reply this build cannot decode is a plain
116    /// failure, since neither side is known to be at fault.
117    #[must_use]
118    pub const fn exit_code(&self) -> u8 {
119        use shep_core::exit;
120        match self {
121            Self::Rpc(rpc) => rpc.code.exit_code(),
122            Self::Timeout { .. } => exit::DEADLINE_EXCEEDED,
123            Self::Closed => exit::DAEMON_UNREACHABLE,
124            Self::Wire(_) | Self::UnexpectedReply { .. } => exit::INTERNAL,
125            Self::Undecodable(_) => exit::FAILURE,
126        }
127    }
128}
129
130impl fmt::Display for RequestError {
131    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
132        match self {
133            Self::Rpc(err) => write!(f, "the daemon reported {:?}: {}", err.code, err.message),
134            Self::Timeout { after } => write!(f, "no reply within {after:?}"),
135            Self::Closed => f.write_str("the connection closed before a reply arrived"),
136            Self::Wire(err) => write!(f, "request frame error: {err}"),
137            Self::Undecodable(err) => write!(
138                f,
139                "this client could not decode the daemon's reply ({err}); the daemon is likely newer than this build"
140            ),
141            Self::UnexpectedReply { asked, answered } => {
142                write!(f, "the daemon answered {asked} with {answered}")
143            }
144        }
145    }
146}
147
148impl core::error::Error for RequestError {
149    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
150        match self {
151            Self::Wire(err) | Self::Undecodable(err) => Some(err),
152            Self::Rpc(_) | Self::Timeout { .. } | Self::Closed | Self::UnexpectedReply { .. } => {
153                None
154            }
155        }
156    }
157}
158
159/// How a [`Client`] was dialled, kept so a reconnect dials the same way.
160#[derive(Debug, Clone)]
161pub(crate) enum Dial {
162    /// A shepherd's socket on this host.
163    Socket(PathBuf),
164    /// A shepherd on another host, through the system ssh.
165    Ssh {
166        destination: Destination,
167        options: SshOptions,
168    },
169}
170
171/// A live connection to the daemon.
172///
173/// Backed by one actor task (see the crate's `actor` module) that owns the
174/// socket; `request`/`request_with_deadline`/`close` all take `&self`, so
175/// callers share one `Client` behind an `Arc` or a reference rather than
176/// cloning a handle per caller.
177pub struct Client {
178    commands: mpsc::Sender<Command>,
179    ack: HelloAck,
180    dial: Dial,
181    /// The name this client announces itself as a dog under, re-sent on
182    /// every [`Client::reconnect`]. See [`Self::connect_as`].
183    dog_name: Option<String>,
184}
185
186// Manual, not derived: a path, a host, an ack and a dog's name carry no
187// secret, and none of them is what a derived impl would lead with. The command
188// channel says nothing a reader can act on.
189impl fmt::Debug for Client {
190    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
191        f.debug_struct("Client")
192            .field("socket", &self.socket())
193            .field("host", &self.host())
194            .field("ack", &self.ack)
195            .field("dog_name", &self.dog_name)
196            .finish_non_exhaustive()
197    }
198}
199
200impl Client {
201    /// Connects to `socket` and performs the version handshake, bounded by
202    /// [`HANDSHAKE_TIMEOUT`].
203    ///
204    /// # Errors
205    ///
206    /// See [`Self::connect_with_timeout`].
207    pub async fn connect(socket: &Path) -> Result<Self, ConnectError> {
208        Self::connect_with_timeout(socket, HANDSHAKE_TIMEOUT).await
209    }
210
211    /// As [`Self::connect`], but with a caller-supplied handshake timeout.
212    ///
213    /// # Errors
214    ///
215    /// - [`ConnectError::Connect`]: the initial `connect(2)` call failed.
216    /// - [`ConnectError::Wire`]: `Hello` failed to encode, or the reply failed to decode.
217    /// - [`ConnectError::Io`]: a framed read or write failed after connect.
218    /// - [`ConnectError::HandshakeClosed`]: the peer closed before a `HelloReply`.
219    /// - [`ConnectError::HandshakeTimeout`]: no `HelloReply` arrived within `timeout`.
220    /// - [`ConnectError::ProtocolMismatch`]: the daemon refused on protocol-version skew.
221    pub async fn connect_with_timeout(
222        socket: &Path,
223        timeout: Duration,
224    ) -> Result<Self, ConnectError> {
225        Self::connect_as(socket, timeout, None).await
226    }
227
228    /// As [`Self::connect_with_timeout`], but announcing this client as the
229    /// dog registered under `dog_name`.
230    ///
231    /// Crate-private: the public constructors above pass `None`, and only
232    /// [`ReconnectingClient`](crate::ReconnectingClient) passes a name. A
233    /// client that could claim an arbitrary dog name could get that dog
234    /// restarted on its own say-so.
235    ///
236    /// # Errors
237    ///
238    /// See [`Self::connect_with_timeout`].
239    pub(crate) async fn connect_as(
240        socket: &Path,
241        timeout: Duration,
242        dog_name: Option<&str>,
243    ) -> Result<Self, ConnectError> {
244        let connection = Connection::open(socket, timeout, dog_name).await?;
245        Ok(Self::from_connection(
246            connection,
247            Dial::Socket(socket.to_path_buf()),
248            dog_name,
249        ))
250    }
251
252    /// As [`Self::connect_as`], over `stream`, a connection the shepherd
253    /// already opened. Dialled again through `socket` on a reconnect.
254    ///
255    /// # Errors
256    ///
257    /// See [`Self::connect_with_timeout`], bar [`ConnectError::Connect`]:
258    /// there is no `connect(2)` to fail.
259    pub(crate) async fn connect_over(
260        stream: shep_core::transport::ClientStream,
261        socket: &Path,
262        timeout: Duration,
263        dog_name: Option<&str>,
264    ) -> Result<Self, ConnectError> {
265        let connection = tokio::time::timeout(timeout, Connection::open_over(stream, dog_name))
266            .await
267            .map_err(|_elapsed| ConnectError::HandshakeTimeout { after: timeout })??;
268        Ok(Self::from_connection(
269            connection,
270            Dial::Socket(socket.to_path_buf()),
271            dog_name,
272        ))
273    }
274
275    fn from_connection(connection: Connection, dial: Dial, dog_name: Option<&str>) -> Self {
276        let (frames, ack) = connection.into_parts();
277        let commands = actor::spawn(frames);
278        Self {
279            commands,
280            ack,
281            dial,
282            dog_name: dog_name.map(str::to_owned),
283        }
284    }
285
286    /// Connects to the shepherd on another host through the system `ssh`,
287    /// with [`SshOptions::default`].
288    ///
289    /// Shorthand for [`Self::connect_ssh_with`].
290    ///
291    /// # Example
292    ///
293    /// ```no_run
294    /// use shep_client::Client;
295    /// use shep_client::shep_core::protocol::Request;
296    ///
297    /// # async fn list() -> Result<(), Box<dyn core::error::Error>> {
298    /// let client = Client::connect_ssh("deploy@build-01").await?;
299    /// let flock = client.request(Request::ListFlock).await?;
300    /// # let _ = flock;
301    /// # Ok(())
302    /// # }
303    /// # let _ = list;
304    /// ```
305    ///
306    /// # Errors
307    ///
308    /// See [`Self::connect_ssh_with`].
309    pub async fn connect_ssh(dest: &str) -> Result<Self, ConnectError> {
310        Self::connect_ssh_with(dest, &SshOptions::default()).await
311    }
312
313    /// Connects to the shepherd on another host by running
314    /// `ssh -T [-o BatchMode=yes] -- <dest> shep dial-stdio` and handshaking
315    /// over the child's pipes.
316    ///
317    /// # Example
318    ///
319    /// ```no_run
320    /// use std::time::Duration;
321    /// use shep_client::{Client, SshOptions};
322    ///
323    /// # async fn dial() -> Result<(), Box<dyn core::error::Error>> {
324    /// let options = SshOptions::default()
325    ///     .batch_mode(true)
326    ///     .timeout(Some(Duration::from_secs(10)));
327    /// let client = Client::connect_ssh_with("build-01", &options).await?;
328    /// assert_eq!(client.host(), Some("build-01"));
329    /// # Ok(())
330    /// # }
331    /// # let _ = dial;
332    /// ```
333    /// # Errors
334    ///
335    /// - [`ConnectError::Destination`]: `dest` is not a destination ssh can be handed
336    ///   safely. ssh would read `-oProxyCommand=..` as an option and run it.
337    /// - [`ConnectError::Ssh`]: ssh could not run, reach the host, or be served by the far side.
338    /// - [`ConnectError::Wire`], [`ConnectError::Io`]: a frame failed to encode or decode.
339    /// - [`ConnectError::HandshakeClosed`]: the stream closed before a `HelloReply`.
340    /// - [`ConnectError::HandshakeTimeout`]: the phase ran past [`SshOptions::timeout`].
341    /// - [`ConnectError::ProtocolMismatch`]: the shepherd refused on version skew.
342    pub async fn connect_ssh_with(dest: &str, options: &SshOptions) -> Result<Self, ConnectError> {
343        let destination = Destination::parse(dest).map_err(ConnectError::Destination)?;
344        let dial = Dial::Ssh {
345            destination,
346            options: options.clone(),
347        };
348        Self::connect_dial(&dial, options.timeout_or(None), None).await
349    }
350
351    /// Dials `dial` again, as a reconnect does, or for the first time.
352    ///
353    /// `budget` bounds the attempt: a socket dial takes it as is, and an ssh
354    /// dial takes the smaller of it and [`SshOptions::timeout`]. `None` leaves
355    /// an ssh dial to its options alone.
356    ///
357    /// # Errors
358    ///
359    /// See [`Self::connect_with_timeout`] and [`Self::connect_ssh_with`].
360    pub(crate) async fn connect_dial(
361        dial: &Dial,
362        budget: Option<Duration>,
363        dog_name: Option<&str>,
364    ) -> Result<Self, ConnectError> {
365        match dial {
366            Dial::Socket(socket) => {
367                Self::connect_as(socket, budget.unwrap_or(HANDSHAKE_TIMEOUT), dog_name).await
368            }
369            Dial::Ssh {
370                destination,
371                options,
372            } => {
373                let connection =
374                    ssh::open(destination, options, options.timeout_or(budget), dog_name).await?;
375                Ok(Self::from_connection(connection, dial.clone(), dog_name))
376            }
377        }
378    }
379
380    /// How this client was dialled.
381    pub(crate) fn dial(&self) -> &Dial {
382        &self.dial
383    }
384
385    /// The name this client announces itself as a dog under, or `None` for
386    /// a caller that is not one.
387    ///
388    /// Crate-private for the reason [`Self::connect_as`] is: only this
389    /// crate may set a name, so only this crate may report one.
390    pub(crate) fn dog_name(&self) -> Option<&str> {
391        self.dog_name.as_deref()
392    }
393
394    /// Takes over `fresh`'s connection, dropping this handle's own.
395    ///
396    /// Dropping the old command channel signals its actor rather than
397    /// stopping it where it stands. An actor already awaiting a write
398    /// finishes that write, sees the closed channel when it next reaches
399    /// its select, and only then drops the old socket.
400    pub(crate) fn replace_connection(&mut self, fresh: Self) {
401        *self = fresh;
402    }
403
404    /// The daemon's handshake acknowledgement.
405    #[must_use]
406    pub fn daemon(&self) -> &HelloAck {
407        &self.ack
408    }
409
410    /// Resolves once this connection has ended: daemon exit, crash,
411    /// `execve`, a write failure, or a prior [`Self::close`]. Resolves
412    /// immediately if already gone, and may be awaited more than once.
413    ///
414    /// This does not reconnect, and [`Self::request`] does not retry. See
415    /// [`ReconnectingClient`](crate::ReconnectingClient) for the supervised
416    /// wrapper.
417    pub async fn closed(&self) {
418        self.commands.closed().await;
419    }
420
421    /// The path this client is connected through.
422    ///
423    /// `HelloAck` doesn't carry the socket path, so the `Client` keeps the
424    /// `PathBuf` it connected with, for a caller that needs it after
425    /// teardown. Empty for a client from [`Self::connect_ssh`], which has no
426    /// socket on this host: see [`Self::host`].
427    #[must_use]
428    pub fn socket(&self) -> &Path {
429        match &self.dial {
430            Dial::Socket(socket) => socket,
431            Dial::Ssh { .. } => Path::new(""),
432        }
433    }
434
435    /// The destination this client reached over ssh, or `None` for a client
436    /// connected to a socket on this host.
437    #[must_use]
438    pub fn host(&self) -> Option<&str> {
439        match &self.dial {
440            Dial::Socket(_) => None,
441            Dial::Ssh { destination, .. } => Some(destination.as_str()),
442        }
443    }
444
445    /// Hands `command` to the actor task behind this handle.
446    async fn send_command(&self, command: Command) -> Result<(), RequestError> {
447        self.commands
448            .send(command)
449            .await
450            .map_err(|_send_error| RequestError::Closed)
451    }
452
453    /// Sends `body` with [`DEFAULT_DEADLINE`].
454    ///
455    /// Shorthand for [`Self::request_with_deadline`]`(body, None)`.
456    ///
457    /// # Errors
458    ///
459    /// See [`Self::request_with_deadline`].
460    pub async fn request(&self, body: Request) -> Result<Response, RequestError> {
461        self.request_with_deadline(body, None).await
462    }
463
464    /// Sends `body` with `deadline`, or [`DEFAULT_DEADLINE`] if `None`. The
465    /// client waits `deadline` plus [`DEADLINE_GRACE`] for a reply before
466    /// giving up locally.
467    ///
468    /// # Errors
469    ///
470    /// - [`RequestError::Rpc`]: the daemon answered with a structured error,
471    ///   or `body` carries a key a shepherd below its protocol version would
472    ///   drop (`dogs.sandbox`, `sandbox`, `listen`, `memory_enforce`, `max_cpu_cores`, `max_tasks`, `pty`; see [`Request::gated_key_dropped_at`]),
473    ///   which is refused as `Unsupported` before anything is sent.
474    /// - [`RequestError::Timeout`]: no reply within `deadline + DEADLINE_GRACE`.
475    /// - [`RequestError::Closed`]: the connection closed before a reply arrived.
476    /// - [`RequestError::Wire`]: `body` failed to encode.
477    pub async fn request_with_deadline(
478        &self,
479        body: Request,
480        deadline: Option<Duration>,
481    ) -> Result<Response, RequestError> {
482        if let Some(gated) = body.gated_key_dropped_at(self.ack.protocol) {
483            return Err(RequestError::Rpc(RpcError {
484                code: RpcErrorCode::Unsupported,
485                message: format!(
486                    "this shepherd speaks protocol {} and `{}` needs protocol {}, so it would not \
487                     run the sheep as configured. Restart the shepherd and run this again; \
488                     nothing was sent",
489                    self.ack.protocol, gated.key, gated.since
490                ),
491                daemon_version: None,
492            }));
493        }
494        let deadline = deadline.unwrap_or(DEFAULT_DEADLINE);
495        let (reply_to, reply_rx) = oneshot::channel();
496        self.send_command(Command::Request {
497            body,
498            deadline_ms: Some(millis(deadline)),
499            reply_to,
500        })
501        .await?;
502
503        // Saturating: `deadline` is the caller's, and `Duration`'s `Add`
504        // panics rather than saturating on overflow.
505        let budget = deadline.saturating_add(DEADLINE_GRACE);
506        match tokio::time::timeout(budget, reply_rx).await {
507            Ok(Ok(outcome)) => outcome,
508            Ok(Err(_recv_error)) => Err(RequestError::Closed),
509            Err(_elapsed) => Err(RequestError::Timeout { after: budget }),
510        }
511    }
512
513    /// Subscribes this connection to `topics`: dotted glob patterns matched
514    /// against [`shep_core::protocol::BusEvent::topic`] (`process.*`,
515    /// `log.*`, `daemon.*`, ...).
516    ///
517    /// A second call on the same `Client` replaces the daemon-side filter
518    /// rather than adding to it; a caller wanting two topic sets needs two
519    /// `Client`s. The returned [`EventStream`]'s receiver is installed
520    /// before the `Subscribe` request is sent, so no pushed event is missed.
521    ///
522    /// # Errors
523    ///
524    /// Same as [`Self::request`].
525    pub async fn subscribe(&self, topics: Vec<String>) -> Result<EventStream, RequestError> {
526        let events = self.events().await?;
527
528        // reply is `Response::Subscribed`; unchecked, since interpreting
529        // `Response` variants is shep-cli's job, not this crate's
530        self.request(Request::Subscribe { topics }).await?;
531        Ok(events)
532    }
533
534    /// A stream of what this connection is already being sent, with no
535    /// `Subscribe` to change what that is.
536    ///
537    /// For the events a request opens on its own, such as the `pty.out`
538    /// frames after a `Request::Attach`. Open it before sending that request:
539    /// a receiver sees nothing sent before it existed.
540    ///
541    /// # Errors
542    ///
543    /// [`RequestError::Closed`]: the connection is already gone.
544    pub async fn events(&self) -> Result<EventStream, RequestError> {
545        let (reply_to, reply_rx) = oneshot::channel();
546        self.send_command(Command::Subscribe { reply_to }).await?;
547        let receiver = reply_rx.await.map_err(|_recv_error| RequestError::Closed)?;
548        Ok(EventStream::new(receiver))
549    }
550
551    /// Closes the connection.
552    ///
553    /// Drops the command channel to the actor task, which ends the actor's
554    /// loop and drops the underlying socket.
555    ///
556    /// # Errors
557    ///
558    /// Never fails today. `Result` leaves room for a later, more graceful
559    /// teardown (draining in-flight requests before dropping, say) to start
560    /// returning one without an API break.
561    pub async fn close(self) -> Result<(), RequestError> {
562        drop(self.commands);
563        Ok(())
564    }
565}
566
567/// Saturating `Duration` to wire milliseconds. A caller-supplied `Duration`
568/// above the wire range saturates at `u64::MAX` ms rather than overflowing.
569fn millis(d: Duration) -> u64 {
570    u64::try_from(d.as_millis()).unwrap_or(u64::MAX)
571}
572
573#[cfg(test)]
574mod tests {
575    use shep_core::config::MemoryEnforce;
576    use shep_core::exit;
577    use shep_core::protocol::{
578        LISTEN_SINCE, MAX_CPU_CORES_SINCE, MAX_TASKS_SINCE, MEMORY_ENFORCE_SINCE, PTY_SINCE,
579        RpcErrorCode, SANDBOX_DOG_SINCE,
580    };
581
582    use super::*;
583
584    #[test]
585    fn a_request_error_exits_on_its_causes_code() {
586        let unsupported = RequestError::Rpc(RpcError {
587            code: RpcErrorCode::Unsupported,
588            message: "no such verb".to_owned(),
589            daemon_version: None,
590        });
591        let cases = [
592            (unsupported, exit::UNSUPPORTED),
593            (RequestError::Closed, exit::DAEMON_UNREACHABLE),
594            (
595                RequestError::Timeout {
596                    after: Duration::from_secs(7),
597                },
598                exit::DEADLINE_EXCEEDED,
599            ),
600            (
601                RequestError::UnexpectedReply {
602                    asked: "ListFlock",
603                    answered: "Pong",
604                },
605                exit::INTERNAL,
606            ),
607        ];
608        for (err, code) in cases {
609            assert_eq!(err.exit_code(), code, "{err}");
610        }
611    }
612
613    fn sandboxed_start() -> Request {
614        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
615        app.dogs.insert(
616            "sandbox".to_owned(),
617            serde_json::from_value(serde_json::json!({"profile": "strict"})).unwrap(),
618        );
619        Request::Start { apps: vec![app] }
620    }
621
622    #[tokio::test]
623    async fn a_sandbox_dog_table_is_not_sent_to_a_shepherd_below_protocol_15() {
624        let dir = tempfile::tempdir().unwrap();
625        let path = crate::testing::control_address(dir.path());
626        let ack = HelloAck {
627            protocol: SANDBOX_DOG_SINCE - 1,
628            ..crate::testing::sample_ack()
629        };
630        let (client, mut sent) =
631            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
632
633        let refused = client.request(sandboxed_start()).await.unwrap_err();
634
635        let RequestError::Rpc(rpc) = &refused else {
636            panic!("expected a refusal, got {refused:?}");
637        };
638        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
639        assert!(rpc.message.contains("`dogs.sandbox`"), "{}", rpc.message);
640        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
641        assert_eq!(refused.exit_code(), exit::UNSUPPORTED);
642        assert!(sent.try_recv().is_err(), "the request reached the wire");
643    }
644
645    fn listening_start() -> Request {
646        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
647        app.listen
648            .insert("http".to_owned(), "0.0.0.0:8080".to_owned());
649        Request::Start { apps: vec![app] }
650    }
651
652    #[tokio::test]
653    async fn a_listen_is_refused_before_it_reaches_an_older_shepherd() {
654        let dir = tempfile::tempdir().unwrap();
655        let path = crate::testing::control_address(dir.path());
656        let ack = HelloAck {
657            protocol: LISTEN_SINCE - 1,
658            ..crate::testing::sample_ack()
659        };
660        let (client, mut sent) =
661            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
662
663        let refused = client.request(listening_start()).await.unwrap_err();
664
665        let RequestError::Rpc(rpc) = &refused else {
666            panic!("expected a refusal, got {refused:?}");
667        };
668        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
669        assert!(rpc.message.contains("`listen`"), "{}", rpc.message);
670        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
671        assert_eq!(refused.exit_code(), exit::UNSUPPORTED);
672        assert!(sent.try_recv().is_err(), "the request reached the wire");
673    }
674
675    #[tokio::test]
676    async fn a_listen_is_sent_to_a_shepherd_that_binds_one() {
677        let dir = tempfile::tempdir().unwrap();
678        let path = crate::testing::control_address(dir.path());
679        let ack = HelloAck {
680            protocol: LISTEN_SINCE,
681            ..crate::testing::sample_ack()
682        };
683        let (client, mut sent) =
684            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
685
686        let _ = client.request(listening_start()).await;
687
688        assert!(
689            sent.try_recv().is_ok(),
690            "the request never reached the wire"
691        );
692    }
693
694    #[tokio::test]
695    async fn a_sandbox_dog_table_is_sent_to_a_shepherd_at_protocol_15() {
696        let dir = tempfile::tempdir().unwrap();
697        let path = crate::testing::control_address(dir.path());
698        let ack = HelloAck {
699            protocol: SANDBOX_DOG_SINCE,
700            ..crate::testing::sample_ack()
701        };
702        let (client, mut sent) =
703            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
704
705        let _ = client.request(sandboxed_start()).await;
706
707        assert!(
708            sent.try_recv().is_ok(),
709            "the request never reached the wire"
710        );
711    }
712
713    fn kernel_enforced_start() -> Request {
714        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
715        app.max_memory = Some("512M".parse().unwrap());
716        app.memory_enforce = MemoryEnforce::Kernel;
717        Request::Start { apps: vec![app] }
718    }
719
720    #[tokio::test]
721    async fn a_memory_enforce_key_is_not_sent_to_an_older_shepherd() {
722        let dir = tempfile::tempdir().unwrap();
723        let path = crate::testing::control_address(dir.path());
724        let ack = HelloAck {
725            protocol: MEMORY_ENFORCE_SINCE - 1,
726            ..crate::testing::sample_ack()
727        };
728        let (client, mut sent) =
729            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
730
731        let refused = client.request(kernel_enforced_start()).await.unwrap_err();
732
733        let RequestError::Rpc(rpc) = &refused else {
734            panic!("expected a refusal, got {refused:?}");
735        };
736        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
737        assert!(rpc.message.contains("`memory_enforce`"), "{}", rpc.message);
738        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
739        assert!(sent.try_recv().is_err(), "the request reached the wire");
740    }
741
742    #[tokio::test]
743    async fn a_memory_enforce_key_is_sent_to_a_shepherd_that_reads_it() {
744        let dir = tempfile::tempdir().unwrap();
745        let path = crate::testing::control_address(dir.path());
746        let ack = HelloAck {
747            protocol: MEMORY_ENFORCE_SINCE,
748            ..crate::testing::sample_ack()
749        };
750        let (client, mut sent) =
751            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
752
753        let _ = client.request(kernel_enforced_start()).await;
754
755        assert!(
756            sent.try_recv().is_ok(),
757            "the request never reached the wire"
758        );
759    }
760
761    fn cpu_capped_start() -> Request {
762        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
763        app.max_cpu_cores = Some(shep_core::config::CpuCores::from_cores(1.5));
764        Request::Start { apps: vec![app] }
765    }
766
767    #[tokio::test]
768    async fn a_max_cpu_cores_key_is_not_sent_to_an_older_shepherd() {
769        let dir = tempfile::tempdir().unwrap();
770        let path = crate::testing::control_address(dir.path());
771        let ack = HelloAck {
772            protocol: MAX_CPU_CORES_SINCE - 1,
773            ..crate::testing::sample_ack()
774        };
775        let (client, mut sent) =
776            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
777
778        let refused = client.request(cpu_capped_start()).await.unwrap_err();
779
780        let RequestError::Rpc(rpc) = &refused else {
781            panic!("expected a refusal, got {refused:?}");
782        };
783        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
784        assert!(rpc.message.contains("`max_cpu_cores`"), "{}", rpc.message);
785        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
786        assert!(sent.try_recv().is_err(), "the request reached the wire");
787    }
788
789    #[tokio::test]
790    async fn a_max_cpu_cores_key_is_sent_to_a_shepherd_that_reads_it() {
791        let dir = tempfile::tempdir().unwrap();
792        let path = crate::testing::control_address(dir.path());
793        let ack = HelloAck {
794            protocol: MAX_CPU_CORES_SINCE,
795            ..crate::testing::sample_ack()
796        };
797        let (client, mut sent) =
798            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
799
800        let _ = client.request(cpu_capped_start()).await;
801
802        assert!(
803            sent.try_recv().is_ok(),
804            "the request never reached the wire"
805        );
806    }
807
808    fn task_capped_start() -> Request {
809        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
810        app.max_tasks = Some(256);
811        Request::Start { apps: vec![app] }
812    }
813
814    #[tokio::test]
815    async fn a_max_tasks_key_is_not_sent_to_an_older_shepherd() {
816        let dir = tempfile::tempdir().unwrap();
817        let path = crate::testing::control_address(dir.path());
818        let ack = HelloAck {
819            protocol: MAX_TASKS_SINCE - 1,
820            ..crate::testing::sample_ack()
821        };
822        let (client, mut sent) =
823            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
824
825        let refused = client.request(task_capped_start()).await.unwrap_err();
826
827        let RequestError::Rpc(rpc) = &refused else {
828            panic!("expected a refusal, got {refused:?}");
829        };
830        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
831        assert!(rpc.message.contains("`max_tasks`"), "{}", rpc.message);
832        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
833        assert!(sent.try_recv().is_err(), "the request reached the wire");
834    }
835
836    fn pty_start() -> Request {
837        let mut app = shep_core::config::AppConfig::minimal("web", "./srv");
838        app.pty = true;
839        Request::Start { apps: vec![app] }
840    }
841
842    #[tokio::test]
843    async fn a_pty_key_is_not_sent_to_an_older_shepherd() {
844        let dir = tempfile::tempdir().unwrap();
845        let path = crate::testing::control_address(dir.path());
846        let ack = HelloAck {
847            protocol: PTY_SINCE - 1,
848            ..crate::testing::sample_ack()
849        };
850        let (client, mut sent) =
851            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
852
853        let refused = client.request(pty_start()).await.unwrap_err();
854
855        let RequestError::Rpc(rpc) = &refused else {
856            panic!("expected a refusal, got {refused:?}");
857        };
858        assert_eq!(rpc.code, RpcErrorCode::Unsupported);
859        assert!(rpc.message.contains("`pty`"), "{}", rpc.message);
860        assert!(rpc.message.contains("nothing was sent"), "{}", rpc.message);
861        assert!(sent.try_recv().is_err(), "the request reached the wire");
862    }
863
864    #[tokio::test]
865    async fn a_max_tasks_key_is_sent_to_a_shepherd_that_reads_it() {
866        let dir = tempfile::tempdir().unwrap();
867        let path = crate::testing::control_address(dir.path());
868        let ack = HelloAck {
869            protocol: MAX_TASKS_SINCE,
870            ..crate::testing::sample_ack()
871        };
872        let (client, mut sent) =
873            crate::testing::fake_client_capturing_envelopes_with_ack(&path, ack).await;
874
875        let _ = client.request(task_capped_start()).await;
876
877        assert!(
878            sent.try_recv().is_ok(),
879            "the request never reached the wire"
880        );
881    }
882
883    #[cfg(unix)]
884    #[tokio::test]
885    async fn an_ssh_client_has_a_host_and_no_socket() {
886        let dir = tempfile::tempdir().unwrap();
887        crate::ssh::stand_in::write_reply(dir.path());
888        let program = crate::ssh::stand_in::stand_in(
889            dir.path(),
890            "cat \"$(dirname \"$0\")/reply.bin\"\ncat >/dev/null",
891        );
892
893        let client =
894            Client::connect_ssh_with("deploy@build-01", &SshOptions::default().program(program))
895                .await
896                .unwrap();
897
898        assert_eq!(client.host(), Some("deploy@build-01"));
899        assert_eq!(client.socket(), Path::new(""));
900        let shown = format!("{client:?}");
901        assert!(shown.contains("host: Some(\"deploy@build-01\")"), "{shown}");
902    }
903
904    #[tokio::test]
905    async fn a_socket_client_has_a_socket_and_no_host() {
906        let dir = tempfile::tempdir().unwrap();
907        let path = crate::testing::control_address(dir.path());
908        let (client, _daemon) = crate::testing::fake_client_on(&path).await;
909
910        assert_eq!(client.host(), None);
911        assert_eq!(client.socket(), path);
912    }
913}