sdk/fidl/fuchsia.io.test/io.test.fidl

// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.io.test;

using fuchsia.io;

/// Conformance test harnesses will implement this protocol to setup its
/// associated filesystem servers with the described directory layout,
/// allowing their implementation of `fuchsia.io` and `fuchsia.io2` protocols
/// to be verified by a common test suite.
///
/// Different test cases will not interact with one another during the
/// conformance test, and only one test case will be active at a time per
/// tested filesystem. So it is possible to host all cases as different
/// sub-directories under a common filesystem instance, to simplify the
/// lifecycle and implementation.
///
/// If a test case has mutable bits, each method call should be implemented
/// to obtain the directory in its original state. In other words, repeated
/// test case set up should "as-if" yield new directories.
///
/// See `src/storage/conformance/README.md` for an overview of io conformance
/// testing.
///
/// `HarnessConfig` lets the test harness modulate the set of expected outcomes and
/// behaviors validated by the test suite, by declaring specific properties
/// about the filesystem implementation. For example, setting [`ImmutableFile`]
/// to true informs the test suites that files hosted by this harness do not
/// support mutation.
type HarnessConfig = struct {
    /// ExecutableFile objects are supported.
    supports_executable_file bool;

    /// Supports writing to files and updating file attributes.
    supports_mutable_file bool;

    /// GetBackingMemory is supported.
    supports_get_backing_memory bool;

    /// Remote directories are supported.
    supports_remote_dir bool;

    /// GetToken is supported.
    supports_get_token bool;

    /// Supports fuchsia.io's LinkInto method.
    supports_link_into bool;

    /// Files can be opened in append mode.
    supports_append bool;

    /// Files can be truncated (resized).
    supports_truncate bool;

    /// The set of attributes the filesystem supports. If mutable attributes are reported, the
    /// harness must support [`fuchsia.io/Node.SetAttr`] and [`fuchsia.io/Node.UpdateAttributes`].
    supported_attributes fuchsia.io.NodeAttributesQuery;

    /// Directories support creating files, Rename, Link, and Unlink.
    supports_modify_directory bool;

    /// Supports services.
    supports_services bool;

    /// Supports unnamed temporary files.
    supports_unnamed_temporary_file bool;
};

/// Directory entries should support opening with any combination of read/write/execute rights.
type Directory = resource struct {
    name fuchsia.io.Name;
    entries vector<DirectoryEntry:optional>:MAX;
};

/// Remote directory which forwards FIDL requests from the server to the specified directory.
type RemoteDirectory = resource struct {
    name fuchsia.io.Name;
    remote_client client_end:fuchsia.io.Directory;
};

/// File object which supports reading and writing. Use [`ExecutableFile`] if execute rights are
/// required.
type File = struct {
    name fuchsia.io.Name;
    contents vector<uint8>:MAX;
};

/// Adds an executable file that supports opening as readable + executable. The file has a non-zero
/// size, but the contents are otherwise unspecified.
///
/// Enabled via the `supports_executable_file` configuration option. `ExecutableFile` objects should
/// support fuchsia.io/File.GetBackingMemory.
type ExecutableFile = struct {
    name fuchsia.io.Name;
};

type DirectoryEntry = strict resource union {
    1: directory Directory;
    2: remote_directory RemoteDirectory;
    3: file File;
    5: executable_file ExecutableFile;
};

@discoverable
closed protocol TestHarness {
    /// Returns the list of properties of the filesystem.
    strict GetConfig() -> (struct {
        config HarnessConfig;
    });

    /// Creates a directory with the given `contents` and opens it with the specified `flags`.
    strict CreateDirectory(resource struct {
        contents vector<DirectoryEntry:optional>:MAX;
        flags fuchsia.io.Flags;
        object_request server_end:fuchsia.io.Directory;
    });

    /// Serves a service directory that contains a fuchsia.test.placeholders/Echo instance.
    /// The test harness must have `supports_services` reported in it's config to use this method,
    /// and the service instance should match the discoverable protocol name.
    strict OpenServiceDirectory() -> (resource struct {
        object_request client_end:fuchsia.io.Directory;
    });
};