io_conformance_util/
lib.rs

1// Copyright 2020 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#![warn(missing_docs)]
6
7//! Crate to provide fidl logging and test setup helpers for conformance tests
8//! for fuchsia.io.
9
10use async_trait::async_trait;
11use fidl::endpoints::{create_proxy, ClientEnd, ProtocolMarker, Proxy};
12use fidl::prelude::*;
13use fuchsia_async::{DurationExt, TimeoutExt};
14use futures::{StreamExt as _, TryStreamExt as _};
15use {fidl_fuchsia_io as fio, fidl_fuchsia_io_test as io_test};
16
17/// Test harness helper struct.
18pub mod test_harness;
19
20/// Utility functions for getting combinations of flags.
21pub mod flags;
22
23/// A common name for a file to create in a conformance test.
24pub const TEST_FILE: &str = "testing.txt";
25
26/// A common set of file contents to write into a test file in a conformance test.
27pub const TEST_FILE_CONTENTS: &[u8] = "abcdef".as_bytes();
28
29/// A default value for NodeAttributes, with zeros set for all fields.
30pub const EMPTY_NODE_ATTRS: fio::NodeAttributes = fio::NodeAttributes {
31    mode: 0,
32    id: 0,
33    content_size: 0,
34    storage_size: 0,
35    link_count: 0,
36    creation_time: 0,
37    modification_time: 0,
38};
39
40/// Wait for [`fio::NodeEvent::OnOpen_`] to be sent via `node_proxy` and returns its [`zx::Status`].
41pub async fn get_open_status(node_proxy: &fio::NodeProxy) -> zx::Status {
42    let mut events = Clone::clone(node_proxy).take_event_stream();
43    if let Some(result) = events.next().await {
44        match result.expect("FIDL error") {
45            fio::NodeEvent::OnOpen_ { s, info: _ } => zx::Status::from_raw(s),
46            fio::NodeEvent::OnRepresentation { .. } => panic!(
47                "This function should only be used with fuchsia.io/Directory.Open, *not* Open3!"
48            ),
49            fio::NodeEvent::_UnknownEvent { .. } => {
50                panic!("This function should only be used with fuchsia.io/Directory.Open")
51            }
52        }
53    } else {
54        zx::Status::PEER_CLOSED
55    }
56}
57
58/// Asserts that no [`fio::NodeEvent::OnOpen_`] event is sent on an opened proxy.
59pub async fn assert_on_open_not_received(node_proxy: &fio::NodeProxy) {
60    let mut events = Clone::clone(node_proxy).take_event_stream();
61    // Wait at most 200ms for an OnOpen event to appear.
62    let event = events
63        .next()
64        .on_timeout(zx::MonotonicDuration::from_millis(200).after_now(), || Option::None)
65        .await;
66    assert!(event.is_none(), "Unexpected OnOpen event received");
67}
68
69/// Converts a generic [`fio::NodeProxy`] to either [`fio::FileProxy`] or [`fio::DirectoryProxy`].
70/// **WARNING**: This function does _not_ verify that the conversion is valid.
71pub fn convert_node_proxy<T: Proxy>(proxy: fio::NodeProxy) -> T {
72    T::from_channel(proxy.into_channel().expect("Cannot convert node proxy to channel"))
73}
74
75/// Helper function to open the desired node in the root folder.
76/// Asserts that deprecated_open_node_status succeeds.
77pub async fn deprecated_open_node<T: ProtocolMarker>(
78    dir: &fio::DirectoryProxy,
79    flags: fio::OpenFlags,
80    path: &str,
81) -> T::Proxy {
82    deprecated_open_node_status::<T>(dir, flags, path).await.unwrap_or_else(|e| {
83        panic!("deprecated_open_node_status failed for {path} (flags={flags:?}): {e:?}")
84    })
85}
86
87/// Helper function to open the desired node in the root folder.
88pub async fn deprecated_open_node_status<T: ProtocolMarker>(
89    dir: &fio::DirectoryProxy,
90    flags: fio::OpenFlags,
91    path: &str,
92) -> Result<T::Proxy, zx::Status> {
93    let flags = flags | fio::OpenFlags::DESCRIBE;
94    let (node_proxy, node_server) = create_proxy::<fio::NodeMarker>();
95    dir.deprecated_open(flags, fio::ModeType::empty(), path, node_server)
96        .expect("Cannot open node");
97    let status = get_open_status(&node_proxy).await;
98
99    if status != zx::Status::OK {
100        Err(status)
101    } else {
102        Ok(convert_node_proxy(node_proxy))
103    }
104}
105
106/// Helper function to open a file with the given flags. Only use this if testing something other
107/// than the open call directly.
108pub async fn deprecated_open_file_with_flags(
109    parent_dir: &fio::DirectoryProxy,
110    flags: fio::OpenFlags,
111    path: &str,
112) -> fio::FileProxy {
113    deprecated_open_node::<fio::FileMarker>(
114        &parent_dir,
115        flags | fio::OpenFlags::NOT_DIRECTORY,
116        path,
117    )
118    .await
119}
120
121/// Helper function to open a sub-directory with the given flags. Only use this if testing
122/// something other than the open call directly.
123pub async fn deprecated_open_dir_with_flags(
124    parent_dir: &fio::DirectoryProxy,
125    flags: fio::OpenFlags,
126    path: &str,
127) -> fio::DirectoryProxy {
128    deprecated_open_node::<fio::DirectoryMarker>(
129        &parent_dir,
130        flags | fio::OpenFlags::DIRECTORY,
131        path,
132    )
133    .await
134}
135
136/// Helper function to open a sub-directory as readable and writable. Only use this if testing
137/// something other than the open call directly.
138pub async fn deprecated_open_rw_dir(
139    parent_dir: &fio::DirectoryProxy,
140    path: &str,
141) -> fio::DirectoryProxy {
142    deprecated_open_dir_with_flags(
143        parent_dir,
144        fio::OpenFlags::RIGHT_READABLE | fio::OpenFlags::RIGHT_WRITABLE,
145        path,
146    )
147    .await
148}
149
150/// Helper function to call `get_token` on a directory. Only use this if testing something
151/// other than the `get_token` call directly.
152pub async fn get_token(dir: &fio::DirectoryProxy) -> fidl::Handle {
153    let (status, token) = dir.get_token().await.expect("get_token failed");
154    assert_eq!(zx::Status::from_raw(status), zx::Status::OK);
155    token.expect("handle missing")
156}
157
158/// Helper function to read a file and return its contents. Only use this if testing something other
159/// than the read call directly.
160pub async fn read_file(dir: &fio::DirectoryProxy, path: &str) -> Vec<u8> {
161    let file = deprecated_open_file_with_flags(dir, fio::OpenFlags::RIGHT_READABLE, path).await;
162    file.read(100).await.expect("read failed").map_err(zx::Status::from_raw).expect("read error")
163}
164
165/// Attempts to open the given file, and checks the status is `NOT_FOUND`.
166pub async fn assert_file_not_found(dir: &fio::DirectoryProxy, path: &str) {
167    let (file_proxy, file_server) = create_proxy::<fio::NodeMarker>();
168    dir.deprecated_open(
169        fio::OpenFlags::RIGHT_READABLE | fio::OpenFlags::NOT_DIRECTORY | fio::OpenFlags::DESCRIBE,
170        fio::ModeType::empty(),
171        path,
172        file_server,
173    )
174    .expect("Cannot open file");
175    assert_eq!(get_open_status(&file_proxy).await, zx::Status::NOT_FOUND);
176}
177
178/// Returns the .name field from a given DirectoryEntry, otherwise panics.
179pub fn get_directory_entry_name(dir_entry: &io_test::DirectoryEntry) -> String {
180    use io_test::DirectoryEntry;
181    match dir_entry {
182        DirectoryEntry::Directory(entry) => &entry.name,
183        DirectoryEntry::RemoteDirectory(entry) => &entry.name,
184        DirectoryEntry::File(entry) => &entry.name,
185        DirectoryEntry::ExecutableFile(entry) => &entry.name,
186    }
187    .clone()
188}
189
190/// Asserts that the given `vmo_rights` align with the `expected_vmo_rights` passed to a
191/// get_backing_memory call. We check that the returned rights align with and do not exceed those
192/// in the given flags, that we have at least basic VMO rights, and that the flags align with the
193/// expected sharing mode.
194pub fn validate_vmo_rights(vmo: &zx::Vmo, expected_vmo_rights: fio::VmoFlags) {
195    let vmo_rights: zx::Rights = vmo.basic_info().expect("failed to get VMO info").rights;
196
197    // Ensure that we have at least some basic rights.
198    assert!(vmo_rights.contains(zx::Rights::BASIC));
199    assert!(vmo_rights.contains(zx::Rights::MAP));
200    assert!(vmo_rights.contains(zx::Rights::GET_PROPERTY));
201
202    // Ensure the returned rights match and do not exceed those we requested in `expected_vmo_rights`.
203    assert!(
204        vmo_rights.contains(zx::Rights::READ) == expected_vmo_rights.contains(fio::VmoFlags::READ)
205    );
206    assert!(
207        vmo_rights.contains(zx::Rights::WRITE)
208            == expected_vmo_rights.contains(fio::VmoFlags::WRITE)
209    );
210    assert!(
211        vmo_rights.contains(zx::Rights::EXECUTE)
212            == expected_vmo_rights.contains(fio::VmoFlags::EXECUTE)
213    );
214
215    // Make sure we get SET_PROPERTY if we specified a private copy.
216    if expected_vmo_rights.contains(fio::VmoFlags::PRIVATE_CLONE) {
217        assert!(vmo_rights.contains(zx::Rights::SET_PROPERTY));
218    }
219}
220
221/// Creates a directory with the given DirectoryEntry, opening the file with the given
222/// file flags, and returning a Buffer object initialized with the given vmo_flags.
223pub async fn create_file_and_get_backing_memory(
224    dir_entry: io_test::DirectoryEntry,
225    test_harness: &test_harness::TestHarness,
226    file_flags: fio::Flags,
227    vmo_flags: fio::VmoFlags,
228) -> Result<(zx::Vmo, (fio::DirectoryProxy, fio::FileProxy)), zx::Status> {
229    let file_path = get_directory_entry_name(&dir_entry);
230    let dir_proxy = test_harness.get_directory(vec![dir_entry], file_flags);
231    let file_proxy = dir_proxy.open_node::<fio::FileMarker>(&file_path, file_flags, None).await?;
232    let vmo = file_proxy
233        .get_backing_memory(vmo_flags)
234        .await
235        .expect("get_backing_memory failed")
236        .map_err(zx::Status::from_raw)?;
237    Ok((vmo, (dir_proxy, file_proxy)))
238}
239
240/// Makes a directory with a name and set of entries.
241pub fn directory(name: &str, entries: Vec<io_test::DirectoryEntry>) -> io_test::DirectoryEntry {
242    let entries: Vec<Option<Box<io_test::DirectoryEntry>>> =
243        entries.into_iter().map(|e| Some(Box::new(e))).collect();
244    io_test::DirectoryEntry::Directory(io_test::Directory { name: name.to_string(), entries })
245}
246
247/// Makes a remote directory with a name, which forwards the requests to the given directory proxy.
248pub fn remote_directory(name: &str, remote_dir: fio::DirectoryProxy) -> io_test::DirectoryEntry {
249    let remote_client = ClientEnd::<fio::DirectoryMarker>::new(
250        remote_dir.into_channel().unwrap().into_zx_channel(),
251    );
252
253    io_test::DirectoryEntry::RemoteDirectory(io_test::RemoteDirectory {
254        name: name.to_string(),
255        remote_client,
256    })
257}
258
259/// Makes a file to be placed in the test directory.
260pub fn file(name: &str, contents: Vec<u8>) -> io_test::DirectoryEntry {
261    io_test::DirectoryEntry::File(io_test::File { name: name.to_string(), contents })
262}
263
264/// Makes an executable file to be placed in the test directory.
265pub fn executable_file(name: &str) -> io_test::DirectoryEntry {
266    io_test::DirectoryEntry::ExecutableFile(io_test::ExecutableFile { name: name.to_string() })
267}
268
269/// Extension trait for [`fio::DirectoryProxy`] to make interactions with the fuchsia.io protocol
270/// less verbose.
271#[async_trait]
272pub trait DirectoryProxyExt {
273    /// Open `path` specified using `flags` and `options`, returning a proxy to the remote resource.
274    ///
275    /// Waits for [`fio::NodeEvent::OnRepresentation`] if [`fio::Flags::FLAG_SEND_REPRESENTATION`]
276    /// is specified, otherwise calls `fuchsia.io/Node.GetConnectionInfo` to verify the result.
277    async fn open_node<T: ProtocolMarker>(
278        &self,
279        path: &str,
280        flags: fio::Flags,
281        options: Option<fio::Options>,
282    ) -> Result<T::Proxy, zx::Status>;
283
284    /// Similar to [`DirectoryProxyExt::open_node`], but waits for and returns the
285    /// [`fio::NodeEvent::OnRepresentation`] event sent when opening a resource.
286    ///
287    /// Requires [`fio::Flags::FLAG_SEND_REPRESENTATION`] to be specified in `flags`.
288    async fn open_node_repr<T: ProtocolMarker>(
289        &self,
290        path: &str,
291        flags: fio::Flags,
292        options: Option<fio::Options>,
293    ) -> Result<(T::Proxy, fio::Representation), zx::Status>;
294}
295
296#[async_trait]
297impl DirectoryProxyExt for fio::DirectoryProxy {
298    async fn open_node<T: ProtocolMarker>(
299        &self,
300        path: &str,
301        flags: fio::Flags,
302        options: Option<fio::Options>,
303    ) -> Result<T::Proxy, zx::Status> {
304        open_node_impl::<T>(self, path, flags, options).await.map(|(proxy, _representation)| proxy)
305    }
306
307    async fn open_node_repr<T: ProtocolMarker>(
308        &self,
309        path: &str,
310        flags: fio::Flags,
311        options: Option<fio::Options>,
312    ) -> Result<(T::Proxy, fio::Representation), zx::Status> {
313        assert!(
314            flags.contains(fio::Flags::FLAG_SEND_REPRESENTATION),
315            "flags must specify the FLAG_SEND_REPRESENTATION flag to use this function!"
316        );
317        let (proxy, representation) = open_node_impl::<T>(self, path, flags, options).await?;
318        Ok((proxy, representation.unwrap()))
319    }
320}
321
322async fn open_node_impl<T: ProtocolMarker>(
323    dir: &fio::DirectoryProxy,
324    path: &str,
325    flags: fio::Flags,
326    options: Option<fio::Options>,
327) -> Result<(T::Proxy, Option<fio::Representation>), zx::Status> {
328    let (proxy, server) = create_proxy::<fio::NodeMarker>();
329    dir.open(path, flags, &options.unwrap_or_default(), server.into_channel())
330        .expect("Failed to call open3");
331    let representation = if flags.contains(fio::Flags::FLAG_SEND_REPRESENTATION) {
332        Some(get_on_representation_event(&proxy).await?)
333    } else {
334        // We use GetConnectionInfo to test that opening the resource succeeded.
335        proxy.get_connection_info().await.map_err(|e| {
336            if let fidl::Error::ClientChannelClosed { status, .. } = e {
337                status
338            } else {
339                panic!("Unhandled FIDL error: {:?}", e);
340            }
341        })?;
342        None
343    };
344    Ok((convert_node_proxy(proxy), representation))
345}
346
347/// Wait for and return a [`fio::NodeEvent::OnRepresentation`] event sent via `node_proxy`.
348async fn get_on_representation_event(
349    node_proxy: &fio::NodeProxy,
350) -> Result<fio::Representation, zx::Status> {
351    // Try to extract the expected NodeEvent, but map channel epitaphs to zx::Status.
352    let event = Clone::clone(node_proxy)
353        .take_event_stream()
354        .try_next()
355        .await
356        .map_err(|e| {
357            if let fidl::Error::ClientChannelClosed { status, .. } = e {
358                status
359            } else {
360                panic!("Unhandled FIDL error: {:?}", e);
361            }
362        })?
363        .expect("Missing NodeEvent in stream!");
364    let representation = match event {
365        fio::NodeEvent::OnRepresentation { payload } => payload,
366        _ => panic!("Found unexpected NodeEvent type in stream!"),
367    };
368    Ok(representation)
369}
io_conformance_util/lib.rs

io_conformance_util/
lib.rs
