shell_process/
lib.rs

1// Copyright 2022 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#![deny(missing_docs)]
6
7//! Some functions to help run command line processes for tests.
8//!
9//! ## Usage:
10//! ```
11//! let mut fs = ServiceFs::new();
12//! let (svc_client_end, svc_server_end) = zx::Channel::create().expect("create channel");
13//! let svc_proxy = fidl_fuchsia_io::DirectoryProxy::from_channel(
14//!     fuchsia_async::Channel::from_channel(svc_client_end),
15//! );
16//! let env = fs.serve_connection(svc_server_end);
17//! ...
18//! let output = shell_process::run_process(
19//!     "someprocess",
20//!     ["--arg", "foo"],
21//!     [("/svc", &svc_proxy)],
22//! );
23//! assert!(output.is_ok());
24//! ```
25
26use fdio::{SpawnAction, SpawnOptions};
27use fuchsia_async::{self as fasync};
28use fuchsia_runtime::{job_default, HandleInfo, HandleType};
29use futures::prelude::*;
30use libc::{STDERR_FILENO, STDOUT_FILENO};
31use std::ffi::{CStr, CString};
32use zx::{self as zx, HandleBased, ProcessInfo};
33
34/// A struct to contain the results of a shell process.
35pub struct ProcessOutput {
36    /// The return code from a process.
37    pub return_code: i64,
38    /// The stderr text output of a process.
39    pub stderr: Vec<u8>,
40    /// The stdout text output of a process.
41    pub stdout: Vec<u8>,
42}
43
44impl ProcessOutput {
45    /// Whether or not a process ended with return_code zero.
46    pub fn is_ok(&self) -> bool {
47        self.return_code == 0
48    }
49    /// The return code with which a process ended.
50    pub fn return_code(&self) -> i64 {
51        self.return_code
52    }
53    /// The stdout text output of a process, as a &str.
54    pub fn stdout_str(&self) -> &str {
55        std::str::from_utf8(&self.stdout).unwrap()
56    }
57    /// The stderr text output of a process, as a &str.
58    pub fn stderr_str(&self) -> &str {
59        std::str::from_utf8(&self.stderr).unwrap()
60    }
61}
62
63/// Runs a binary with some arguments asynchronously; returns a delayed exit
64/// code and two sockets with stdout and stderr. For a simpler API, use
65/// run_process().
66pub async fn run_process_async<'a>(
67    binary_path: &'a str,
68    args: impl IntoIterator<Item = &'a str>,
69    proxies: impl IntoIterator<Item = (&'a str, &fidl_fuchsia_io::DirectoryProxy)>,
70) -> (fasync::Task<i64>, fasync::Socket, fasync::Socket) {
71    //
72    let (stdout_reader, stdout_writer) = zx::Socket::create_stream();
73    let (stderr_reader, stderr_writer) = zx::Socket::create_stream();
74    // The reader-ends should not write.
75    let () = stdout_writer.half_close().expect("stdout_reader.half_close");
76    let () = stderr_writer.half_close().expect("stderr_reader.half_close");
77
78    let args: Vec<CString> = std::iter::once(binary_path)
79        .chain(args)
80        .map(|a| CString::new(a).unwrap_or_else(|e| panic!("failed to parse {a} to CString: {e}")))
81        .collect();
82    let args: Vec<&CStr> = args.iter().map(|s| s.as_c_str()).collect();
83
84    let mut spawn_actions = vec![];
85
86    let proxy_by_path_cstring: Vec<(CString, &fidl_fuchsia_io::DirectoryProxy)> =
87        proxies.into_iter().map(|(path, dir)| (CString::new(path).unwrap(), dir)).collect();
88    let proxy_by_path_cstr: Vec<(&CStr, &fidl_fuchsia_io::DirectoryProxy)> =
89        proxy_by_path_cstring.iter().map(|(path, dir)| (path.as_c_str(), *dir)).collect();
90
91    for (path, proxy) in proxy_by_path_cstr {
92        let (proxy_client_end, proxy_server_end) = fidl::endpoints::create_endpoints();
93        fuchsia_fs::directory::clone_onto(proxy, proxy_server_end).unwrap();
94        let proxy_client_channel = proxy_client_end.into_channel();
95        spawn_actions
96            .push(SpawnAction::add_namespace_entry(path, proxy_client_channel.into_handle()));
97    }
98
99    spawn_actions.push(SpawnAction::add_handle(
100        HandleInfo::new(
101            HandleType::FileDescriptor,
102            STDOUT_FILENO.try_into().expect("STDOUT_FILENO.try_into"),
103        ),
104        stdout_writer.into(),
105    ));
106
107    spawn_actions.push(SpawnAction::add_handle(
108        HandleInfo::new(
109            HandleType::FileDescriptor,
110            STDERR_FILENO.try_into().expect("STDERR_FILENO.try_into"),
111        ),
112        stderr_writer.into(),
113    ));
114
115    let process = fdio::spawn_etc(
116        /*job=*/ &job_default(),
117        /*options=*/ SpawnOptions::DEFAULT_LOADER,
118        /*path=*/ CString::new(binary_path).expect("cstring path").as_c_str(),
119        /*argv=*/ &args[..],
120        /*environ=*/ None,
121        /*actions=*/ &mut spawn_actions,
122    )
123    .expect("spawn process");
124
125    (
126        fasync::Task::spawn(async move {
127            assert_eq!(
128                fasync::OnSignals::new(&process, zx::Signals::PROCESS_TERMINATED)
129                    .await
130                    .expect("wait for process termination"),
131                zx::Signals::PROCESS_TERMINATED
132            );
133            let ProcessInfo { return_code, start_time: _, flags: _ } =
134                process.info().expect("process info");
135            return_code
136        }),
137        fasync::Socket::from_socket(stdout_reader),
138        fasync::Socket::from_socket(stderr_reader),
139    )
140}
141
142/// Runs a binary with some arguments synchronously; returns a struct with exit
143/// code, stdout, and stderr.
144pub async fn run_process<'a>(
145    binary_path: &'a str,
146    args: impl IntoIterator<Item = &'a str>,
147    proxies: impl IntoIterator<Item = (&'a str, &fidl_fuchsia_io::DirectoryProxy)>,
148) -> ProcessOutput {
149    let (update, stdout_reader, stderr_reader) =
150        run_process_async(binary_path, args, proxies).await;
151
152    let drain = |pipe: fasync::Socket| pipe.into_datagram_stream().try_concat().err_into();
153
154    future::try_join3(
155        update.map(Result::<_, anyhow::Error>::Ok),
156        drain(stdout_reader),
157        drain(stderr_reader),
158    )
159    .map_ok(|(return_code, stdout, stderr)| ProcessOutput { return_code, stdout, stderr })
160    .await
161    .unwrap()
162}
shell_process/lib.rs

shell_process/
lib.rs
