1use 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
24pub const DEFAULT_DEADLINE: Duration = Duration::from_secs(5);
27
28pub const START_DEADLINE: Duration = Duration::from_secs(30);
33
34pub const RELOAD_DEADLINE: Duration = Duration::from_secs(60);
42
43pub const LOG_PLANE_DEADLINE: Duration = Duration::from_secs(30);
51
52pub const TRIGGER_DEADLINE: Duration = Duration::from_secs(60);
58
59pub const STOP_DEADLINE: Duration = Duration::from_secs(60);
67
68pub const DEADLINE_GRACE: Duration = Duration::from_secs(2);
71
72#[derive(Debug, Clone, PartialEq, Eq)]
76#[non_exhaustive]
77pub enum RequestError {
78 Rpc(RpcError),
80 Timeout {
82 after: Duration,
84 },
85 Closed,
88 Wire(WireError),
90 Undecodable(WireError),
98 UnexpectedReply {
104 asked: &'static str,
106 answered: &'static str,
108 },
109}
110
111impl RequestError {
112 #[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#[derive(Debug, Clone)]
161pub(crate) enum Dial {
162 Socket(PathBuf),
164 Ssh {
166 destination: Destination,
167 options: SshOptions,
168 },
169}
170
171pub struct Client {
178 commands: mpsc::Sender<Command>,
179 ack: HelloAck,
180 dial: Dial,
181 dog_name: Option<String>,
184}
185
186impl 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 pub async fn connect(socket: &Path) -> Result<Self, ConnectError> {
208 Self::connect_with_timeout(socket, HANDSHAKE_TIMEOUT).await
209 }
210
211 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 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 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 pub async fn connect_ssh(dest: &str) -> Result<Self, ConnectError> {
310 Self::connect_ssh_with(dest, &SshOptions::default()).await
311 }
312
313 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 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 pub(crate) fn dial(&self) -> &Dial {
382 &self.dial
383 }
384
385 pub(crate) fn dog_name(&self) -> Option<&str> {
391 self.dog_name.as_deref()
392 }
393
394 pub(crate) fn replace_connection(&mut self, fresh: Self) {
401 *self = fresh;
402 }
403
404 #[must_use]
406 pub fn daemon(&self) -> &HelloAck {
407 &self.ack
408 }
409
410 pub async fn closed(&self) {
418 self.commands.closed().await;
419 }
420
421 #[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 #[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 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 pub async fn request(&self, body: Request) -> Result<Response, RequestError> {
461 self.request_with_deadline(body, None).await
462 }
463
464 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 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 pub async fn subscribe(&self, topics: Vec<String>) -> Result<EventStream, RequestError> {
526 let events = self.events().await?;
527
528 self.request(Request::Subscribe { topics }).await?;
531 Ok(events)
532 }
533
534 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 pub async fn close(self) -> Result<(), RequestError> {
562 drop(self.commands);
563 Ok(())
564 }
565}
566
567fn 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}