// Copyright 2018 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.

library fuchsia.io;

using fuchsia.io2;
using fuchsia.mem;
using zx;

/// Describes how the connection to an should be handled, as well as
/// how to interpret the optional handle.
///
/// Refer to `Node.Describe()` and `Node.OnOpen()` for usage.
resource union NodeInfo {
    1: Service service;
    2: FileObject file;
    3: DirectoryObject directory;
    4: Pipe pipe;
    5: Vmofile vmofile;
    6: Device device;
    7: Tty tty;
    8: reserved;
    9: DatagramSocket datagram_socket;
    10: StreamSocket stream_socket;
};

/// The default protocol, interface information must be acquired some
/// other way.
struct Service {
};

/// Indicates the file is ready for reading.
const uint32 FILE_SIGNAL_READABLE = 0x01000000; // ZX_USER_SIGNAL_0
/// Indicates the file is ready for writing.
const uint32 FILE_SIGNAL_WRITABLE = 0x02000000; // ZX_USER_SIGNAL_1

/// The object may be cast to interface 'File'.
resource struct FileObject {
    /// An optional event which transmits information about an object's readability
    /// or writability. This event relays information about the underlying object, not
    /// the capability granted to client: this event may be signalled "readable" on a
    /// connection that does not have the capability to read.
    ///
    /// The "`FILE_SIGNAL_`" values may be observed on this event.
    zx.handle:EVENT? event;

    /// A placeholder for future stream support.
    ///
    /// Currently, servers are required not to send a handle in this field.
    zx.handle:STREAM? stream;
};

/// The object may be cast to interface 'Directory'.
struct DirectoryObject {
};

/// The object is accompanied by a pipe.
resource struct Pipe {
    zx.handle:SOCKET socket;
};

/// The object is a file which is represented as an immutable VMO.
/// Although a VMO is returned as a part of this structure, this underlying object
/// may represent multiple Vmofiles. To identify the logical portion of the VMO
/// that represents the single file, an offset and length parameter are also supplied.
resource struct Vmofile {
    /// The VMO which backs this file.
    zx.handle:VMO vmo;
    /// The index into `vmo` which represents the first byte of the file.
    uint64 offset;
    /// The number of bytes, starting at `offset`, which may be used to represent this file.
    uint64 length;
};

/// Indicates the device is ready for reading.
const uint32 DEVICE_SIGNAL_READABLE = 0x01000000; // ZX_USER_SIGNAL_0
/// Indicates an out-of-band state transition has occurred.
const uint32 DEVICE_SIGNAL_OOB = 0x02000000; // ZX_USER_SIGNAL_1
/// Indicates the device is ready for writing.
const uint32 DEVICE_SIGNAL_WRITABLE = 0x04000000; // ZX_USER_SIGNAL_2
/// Indicates the device has encountered an error state.
const uint32 DEVICE_SIGNAL_ERROR = 0x08000000; // ZX_USER_SIGNAL_3
/// Indicates the device has hung up on the current connection.
const uint32 DEVICE_SIGNAL_HANGUP = 0x10000000; // ZX_USER_SIGNAL_4

/// The object may be cast to interface 'Device'.
resource struct Device {
    /// An optional event which transmits information about a device's state.
    ///
    /// The "`DEVICE_SIGNAL_`" values may be observed on this event.
    zx.handle:EVENTPAIR? event;
};

/// The object may be cast to interface 'Tty'
resource struct Tty {
    zx.handle:EVENTPAIR? event;
};

/// The object may be cast to interface [`fuchsia.posix.socket.DatagramSocket`].
resource struct DatagramSocket {
    /// See [`fuchsia.posix.socket.DatagramSocket`] for details.
    zx.handle:EVENTPAIR event;
};

/// The object may be cast to interface [`fuchsia.posix.socket.StreamSocket`].
resource struct StreamSocket {
    zx.handle:SOCKET socket;
};

/// Can read from target object.
const uint32 OPEN_RIGHT_READABLE = 0x00000001;
/// Can write to target object.
const uint32 OPEN_RIGHT_WRITABLE = 0x00000002;
/// Connection can mount/umount filesystem.
const uint32 OPEN_RIGHT_ADMIN = 0x00000004;
/// Connection can map target object executable.
const uint32 OPEN_RIGHT_EXECUTABLE = 0x00000008;

/// Create the object if it doesn't exist.
const uint32 OPEN_FLAG_CREATE = 0x00010000;
/// (with Create) Fail if the object already exists.
const uint32 OPEN_FLAG_CREATE_IF_ABSENT = 0x00020000;
/// Truncate the object before usage.
const uint32 OPEN_FLAG_TRUNCATE = 0x00040000;
/// Assert that the object to be opened is a directory.
/// Return an error if the target object is not a directory.
const uint32 OPEN_FLAG_DIRECTORY = 0x00080000;
/// Seek to the end of the object before all writes.
const uint32 OPEN_FLAG_APPEND = 0x00100000;
/// If the object is a mount point, open the local directory.
const uint32 OPEN_FLAG_NO_REMOTE = 0x00200000;
/// Open a reference to the object, not the object itself.
/// It is ONLY valid to pass the following flags together with `OPEN_FLAG_NODE_REFERENCE`:
/// - `OPEN_FLAG_DIRECTORY`
/// - `OPEN_FLAG_NOT_DIRECTORY`
/// - `OPEN_FLAG_DESCRIBE`
/// otherwise an error is returned.
/// If an object is opened or cloned using this method, the resulting connection does not carry
/// any permission flags.
/// The resulting node allows a limited set of operations: `GetAttr`, `Clone`, `Close`, `Describe`,
/// and, if the node is a file, these extra operations: `GetFlags`, `SetFlags`.
const uint32 OPEN_FLAG_NODE_REFERENCE = 0x00400000;
/// Binary OR of `OPEN_FLAG_DIRECTORY`, OPEN_FLAG_NOT_DIRECTORY, OPEN_FLAG_DESCRIBE, and
/// `OPEN_FLAG_NODE_REFERENCE`. Flags used when opening a node reference must fall within this mask.
const uint32 OPEN_FLAGS_ALLOWED_WITH_NODE_REFERENCE = 0x02c80000;
/// Requests that an "OnOpen" event is sent to the interface request.
/// The event will contain a non-null NodeInfo if the open/clone is successful.
const uint32 OPEN_FLAG_DESCRIBE = 0x00800000;
/// Specify this flag to request POSIX-compatibility. Currently, it affects permission handling.
/// During Open:
/// - If the target path is a directory, the rights on the new connection expand to include
///   `OPEN_RIGHT_WRITABLE` if and only if the current connection and all intermediate mount points
///   are writable, and to include `OPEN_RIGHT_EXECUTABLE` if and only if the current connection and
///   all intermediate mount points are executable.
/// - Otherwise, this flag is ignored. It is an access denied error to request more rights
///   than those on the current connection, or any intermediate mount points.
///
/// If the posix compatibility flag is not specified, opening always uses the requested rights,
/// failing the operation with access denied error if requested rights exceeds the rights attached
/// to the current connection.
///
/// If the requesting connection is read-only and the requested rights are read-only, the flag
/// may be ignored by the server, and is not forwarded downstream. This is an implementation detail,
/// necessary to enforce hierarchical permissions across mount points, and should have no effect
/// on the expected behavior for clients.
const uint32 OPEN_FLAG_POSIX = 0x01000000;
/// Assert that the object to be opened is not a directory.
/// Return an error if the target object is a directory.
const uint32 OPEN_FLAG_NOT_DIRECTORY = 0x02000000;
/// When used during clone, the new connection inherits the rights on the source connection,
/// regardless if it is a file or directory. Otherwise, clone attempts to use the requested rights.
/// It is invalid to pass any of the `OPEN_RIGHT_*` flags together with `CLONE_FLAG_SAME_RIGHTS`.
const uint32 CLONE_FLAG_SAME_RIGHTS = 0x04000000;

/// Node defines the minimal interface for entities which can be accessed in a filesystem.
protocol Node {
    /// Create another connection to the same remote object.
    ///
    /// `flags` may be any of:
    ///
    /// - `OPEN_RIGHT_*`
    /// - `OPEN_FLAG_APPEND`
    /// - `OPEN_FLAG_NO_REMOTE`
    /// - `OPEN_FLAG_DESCRIBE`
    /// - `CLONE_FLAG_SAME_RIGHTS`
    ///
    /// All other flags are ignored.
    ///
    /// The `OPEN_RIGHT_*` bits in `flags` request corresponding rights over the resulting
    /// cloned object.
    /// The cloned object must have rights less than or equal to the original object, otherwise
    /// returns `ZX_ERR_ACCESS_DENIED`.
    /// Alternatively, pass `CLONE_FLAG_SAME_RIGHTS` to inherit the rights on the source connection.
    /// It is invalid to pass any of the `OPEN_RIGHT_*` flags together with
    /// `CLONE_FLAG_SAME_RIGHTS`.
    Clone(uint32 flags, request<Node> object);

    /// Terminates connection with object.
    ///
    /// This method does not require any rights.
    Close() -> (zx.status s);

    /// Returns extra information about the type of the object.
    /// If the `Describe` operation fails, the connection is closed.
    ///
    /// This method does not require any rights.
    Describe() -> (NodeInfo info);

    /// An event produced eagerly by a FIDL server if requested by `OPEN_FLAG_DESCRIBE`.
    ///
    /// Indicates the success or failure of the open operation, and optionally describes the
    /// object. If the status is `ZX_OK`, `info` contains descriptive information about the object
    /// (the same as would be returned by `Describe`).
    -> OnOpen(zx.status s, NodeInfo? info);

    /// Synchronizes updates to the node to the underlying media, if it exists.
    ///
    /// This method does not require any rights.
    Sync() -> (zx.status s);

    /// Acquires information about the node.
    ///
    /// This method does not require any rights.
    GetAttr() -> (zx.status s, NodeAttributes attributes);

    /// Updates information about the node.
    /// `flags` may be any of `NODE_ATTRIBUTE_FLAG_*`.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    SetAttr(uint32 flags, NodeAttributes attributes) -> (zx.status s);

    /// Acquires the `Directory.Open` rights and flags used to access this file.
    ///
    /// This method does not require any rights.
    /// This method has the same functionality as GetFlags for File and is
    /// meant as an in-progress replacement.
    [Transitional]
    NodeGetFlags() -> (zx.status s, uint32 flags);

    /// Changes the `Directory.Open` flags used to access the file.
    /// Supported flags which can be turned on / off:
    /// - `OPEN_FLAG_APPEND`
    ///
    /// This method does not require any rights.
    /// This method has the same functionality as SetFlags for File and is
    /// meant as an in-progress replacement.
    [Transitional]
    NodeSetFlags(uint32 flags) -> (zx.status s);
};

/// Bits reserved for posix protections. Native fuchsia filesystems
/// are not required to set bits contained within `MODE_PROTECTION_MASK`,
/// but filesystems that wish to do so may refer to sys/stat.h for their
/// definitions.
const uint32 MODE_PROTECTION_MASK = 0x00FFF;
/// Bits indicating node type. The canonical mechanism to check
/// for a node type is to take 'mode', bitwise AND it with the
/// `MODE_TYPE_MASK`, and check exact equality against a mode type.
const uint32 MODE_TYPE_MASK = 0xFF000;
const uint32 MODE_TYPE_DIRECTORY = 0x04000;
const uint32 MODE_TYPE_BLOCK_DEVICE = 0x06000;
const uint32 MODE_TYPE_FILE = 0x08000;
const uint32 MODE_TYPE_SOCKET = 0x0C000;
const uint32 MODE_TYPE_SERVICE = 0x10000;

/// NodeAttributes defines generic information about a filesystem node.
struct NodeAttributes {
    /// Protection bits and node type information describe in 'mode'.
    uint32 mode;
    /// A filesystem-unique ID.
    uint64 id;
    /// Node size, in bytes.
    uint64 content_size;
    /// Space needed to store node (possibly larger than size), in bytes.
    uint64 storage_size;
    /// Hard link count.
    uint64 link_count;
    /// Time of creation (may be updated manually after creation) in ns since Unix epoch, UTC.
    uint64 creation_time;
    /// Time of last modification in ns since Unix epoch, UTC.
    uint64 modification_time;
};

/// The maximal buffer size which can be transmitted for buffered operations.
/// This capacity is currently set somewhat arbitrarily.
const uint64 MAX_BUF = 8192;
/// The maximum length, in bytes, of a filesystem string.
// TODO(smklein): Update to 4095. +1 is for null-terminator, which shouldn't be
// part of the FIDL length.
const uint64 MAX_PATH = 4096;
/// The maximum length, in bytes, of a single filesystem component.
const uint64 MAX_FILENAME = 255;

/// The fields of 'attributes' which are used to update the Node are indicated
/// by the 'flags' argument.
const uint32 NODE_ATTRIBUTE_FLAG_CREATION_TIME = 0x00000001;
const uint32 NODE_ATTRIBUTE_FLAG_MODIFICATION_TIME = 0x00000002;

/// Update the Seek offset.
enum SeekOrigin : uint32 {
    /// Seek from the start of the file.
    START = 0;
    /// Seek from the current position in the file.
    CURRENT = 1;
    /// Seek from the end of the file.
    END = 2;
};

/// Requests that the VMO be readable.
const uint32 VMO_FLAG_READ = 0x00000001;

/// Requests that the VMO be writable.
const uint32 VMO_FLAG_WRITE = 0x00000002;

/// Requests that the VMO be executable.
const uint32 VMO_FLAG_EXEC = 0x00000004;

/// Require a copy-on-write clone of the underlying VMO.
/// The request should fail if the VMO is not cloned.
/// May not be supplied with fuchsia_io_`VMO_FLAG_EXACT`.
const uint32 VMO_FLAG_PRIVATE = 0x00010000;

/// Require an exact (non-cloned) handle to the underlying VMO.
/// The request should fail if a handle to the exact VMO is not returned.
/// May not be supplied with `VMO_FLAG_PRIVATE`.
const uint32 VMO_FLAG_EXACT = 0x00020000;

/// File defines the interface of a node which contains a flat layout of data.
protocol File {
    compose Node;
    compose fuchsia.io2.AdvisoryLocking;

    /// Reads `count` bytes at the seek offset.
    /// The seek offset is moved forward by the number of bytes read.
    ///
    /// This method requires following rights: `OPEN_RIGHT_READABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Read(uint64 count) -> (zx.status s, vector<uint8>:MAX_BUF data);

    /// Reads `count` bytes at the provided offset.
    /// Does not affect the seek offset.
    ///
    /// This method requires following rights: `OPEN_RIGHT_READABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    ReadAt(uint64 count, uint64 offset) -> (zx.status s, vector<uint8>:MAX_BUF data);

    /// Writes data at the seek offset.
    /// The seek offset is moved forward by the number of bytes written.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Write(vector<uint8>:MAX_BUF data) -> (zx.status s, uint64 actual);

    /// Writes data to the provided offset.
    /// Does not affect the seek offset.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    WriteAt(vector<uint8>:MAX_BUF data, uint64 offset) -> (zx.status s, uint64 actual);

    /// Moves the offset at which the next invocation of `Read()` or `Write()` will
    /// occur.
    ///
    /// This method does not require any rights.
    Seek(int64 offset, SeekOrigin start) -> (zx.status s, uint64 offset);

    /// Shrinks the file size to 'length' bytes.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Truncate(uint64 length) -> (zx.status s);

    /// Acquires the `Directory.Open` rights and flags used to access this file.
    ///
    /// This method does not require any rights.
    GetFlags() -> (zx.status s, uint32 flags);

    /// Changes the `Directory.Open` flags used to access the file.
    /// Supported flags which can be turned on / off:
    /// - `OPEN_FLAG_APPEND`
    ///
    /// This method does not require any rights.
    SetFlags(uint32 flags) -> (zx.status s);

    /// Acquires a buffer representing this file, if there is one, with the
    /// requested access rights.
    ///
    /// `flags` may be any of `VMO_FLAG_*`.
    ///
    /// This method requires following rights:
    ///
    /// - `OPEN_RIGHT_WRITABLE` if `flags` includes `VMO_FLAG_WRITE`.
    /// - `OPEN_RIGHT_READABLE` if `flags` includes `VMO_FLAG_READ` or `VMO_FLAG_EXEC`.
    GetBuffer(uint32 flags) -> (zx.status s, fuchsia.mem.Buffer? buffer);
};

// Dirent type information associated with the results of ReadDirents.
// The following values are aligned with the values from libc's "dirent.h" "DT_...".

/// A dirent with an unknown type.
const uint8 DIRENT_TYPE_UNKNOWN = 0;
/// A dirent representing a directory object.
const uint8 DIRENT_TYPE_DIRECTORY = 4;
/// A dirent representing a block device object.
const uint8 DIRENT_TYPE_BLOCK_DEVICE = 6;
/// A dirent representing a file object.
const uint8 DIRENT_TYPE_FILE = 8;
/// A dirent representing a socket object.
const uint8 DIRENT_TYPE_SOCKET = 12;
/// A dirent representing a service object.
const uint8 DIRENT_TYPE_SERVICE = 16;

/// Nodes which do not have ino values should return this value
/// from Readdir and GetAttr.
const uint64 INO_UNKNOWN = 0xFFFFFFFFFFFFFFFF;

/// Indicates the directory being watched has been deleted.
const uint8 WATCH_EVENT_DELETED = 0;
/// Indicates a node has been created (either new or moved) into a directory.
const uint8 WATCH_EVENT_ADDED = 1;
/// Identifies a node has been removed (either deleted or moved) from the directory.
const uint8 WATCH_EVENT_REMOVED = 2;
/// Identifies a node already existed in the directory when watching started.
const uint8 WATCH_EVENT_EXISTING = 3;
/// Identifies that no more `WATCH_EVENT_EXISTING` events will be sent.
const uint8 WATCH_EVENT_IDLE = 4;

/// Used by `Directory.Watch`. Requests transmission of `WATCH_EVENT_DELETED`.
const uint32 WATCH_MASK_DELETED = 0x00000001;
/// Used by `Directory.Watch`. Requests transmission of `WATCH_EVENT_ADDED`.
const uint32 WATCH_MASK_ADDED = 0x00000002;
/// Used by `Directory.Watch`. Requests transmission of `WATCH_EVENT_REMOVED`.
const uint32 WATCH_MASK_REMOVED = 0x00000004;
/// Used by `Directory.Watch`. Requests transmission of `WATCH_EVENT_EXISTING`.
const uint32 WATCH_MASK_EXISTING = 0x00000008;
/// Used by `Directory.Watch`. Requests transmission of `WATCH_EVENT_IDLE`.
const uint32 WATCH_MASK_IDLE = 0x00000010;
/// Used by `Directory.Watch`. Requests transmission of all watcher events.
const uint32 WATCH_MASK_ALL = 0x0000001F;

// TODO(fxbug.dev/7903): Unused.
/// WatchedEvent describes events returned from a DirectoryWatcher.
struct WatchedEvent {
    uint8 event;
    uint8 len;
    vector<uint8>:MAX_FILENAME name;
};

// TODO(fxbug.dev/7903): Unused.
/// DirectoryWatcher transmits messages from a filesystem server
/// about events happening in the filesystem. Clients can register
/// new watchers using the `Directory.Watch` method, where they can
/// filter which events they want to receive notifications for.
protocol DirectoryWatcher {
    // TODO(smklein): Convert this to a vector of WatchedEvents, when possible.
    OnEvent(vector<uint8>:MAX_BUF events);
};

/// Directory defines a node which is capable of containing other Objects.
protocol Directory {
    compose Node;
    compose fuchsia.io2.AdvisoryLocking;

    /// Opens a new object relative to this directory object.
    ///
    /// `path` may contain multiple segments, separated by "/" characters,
    /// and should never be empty; i.e., "" is an invalid path. Paths should not contain
    /// a leading "/".
    ///
    /// `flags` may be any of the `OPEN_FLAG_*` and `OPEN_RIGHT_*` values, bitwise ORed together.
    /// The `OPEN_FLAG_DESCRIBE` flag may cause an `OnOpen` event to be transmitted
    /// on the `object` handle, indicating the type of object opened.
    ///
    /// If an unknown value is sent for either flags or mode, the connection should
    /// be closed.
    ///
    /// `OPEN_RIGHT_*` flags provided in `flags` will restrict access rights on
    /// the `object` channel which will be connected to the opened entity.
    ///
    /// Rights are never increased. When you open a nested entity within a directory, you may only
    /// request the same rights as what the directory connection already has, or a subset of those.
    /// Exceeding those rights causes an access denied error to be transmitted in the
    /// `OnOpen` event if applicable, and the `object` connection closed.
    ///
    /// The caller must specify either one or more of the `OPEN_RIGHT_*` flags, or
    /// the `OPEN_FLAG_NODE_REFERENCE` flag.
    // TODO(smklein): Who uses mode? Can it be removed?
    Open(uint32 flags, uint32 mode, string:MAX_PATH path, request<Node> object);

    /// Adds a new inotify filter for an object relative to this directory object.
    ///
    /// + 'filters` is a mask of different inotify events that need to be watched by the server
    ///   for a specific file/directory.
    ///
    /// + `path` may contain multiple segments, separated by "/" characters,
    ///   and should never be empty; i.e., "" is an invalid path. Paths should not contain
    ///   a leading "/".
    ///
    /// +`watch_descriptor` is client assigned value to identify a filter.
    ///   Server shouldn't trust the client-assigned watch_descriptor. They should just send it
    ///   back to the client in the socket.
    ///   This value is not used by server, but it is returned back as part of InotifyEvent,
    ///   to help the client correlate filters with events on these filters.
    ///
    /// + `socket` is shared between different filter objects i.e every new filter will
    ///   have a different server end of the socket and there will be a single client end per
    ///   inotify instance on inotify init.
    ///
    AddInotifyFilter(fuchsia.io2.Path path, fuchsia.io2.InotifyWatchMask filters,
                     uint32 watch_descriptor, zx.handle:SOCKET socket) -> ();

    /// Detaches an object from this directory object.
    ///
    /// The underlying object may or may not be deleted after this method
    /// completes: although the link will be removed from the containing directory,
    /// objects with multiple references (such as files which are still open)
    /// will not actually be destroyed until all references are removed.
    ///
    /// If a directory is unlinked while it still has an open reference,
    /// it must become read-only, preventing new entries from being created
    /// until all references close and the directory is destroyed.
    ///
    /// `path` identifies the file which should be detached.
    /// If `path` contains multiple segments, separated by "/" characters,
    /// then the directory is traversed, one segment at a time, relative to the
    /// originally accessed Directory.
    ///
    /// Returns:
    ///   `ZX_ERR_ACCESS_DENIED` if the connection (or the underlying filesystem) does not
    ///     allow writable access.
    ///   `ZX_ERR_INVALID_ARGS` if `path` contains ".." segments.
    ///   `ZX_ERR_NOT_EMPTY` if `path` refers to a non-empty directory.
    ///   `ZX_ERR_UNAVAILABLE` if `path` refers to a mount point, containing a remote channel.
    ///   `ZX_ERR_UNAVAILABLE` if `path` is ".".
    ///
    /// Other errors may be returned for filesystem-specific reasons.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Unlink(string:MAX_PATH path) -> (zx.status s);

    /// Removes a child node from the this directory's list of entries.
    ///
    /// Note: this does not guarantee that the underlying object is destroyed.
    /// Although the link will be removed from the containing directory,
    /// objects with multiple references (such as files which are still open)
    /// will not actually be destroyed until all references are closed.
    ///
    /// * error `ZX_ERR_ACCESS_DENIED` if the connection does not have
    ///   [`Rights.WRITE_BYTES`].
    /// * error `ZX_ERR_NOT_SUPPORTED` if the underlying filesystem does not
    ///   support writing.
    /// * error `ZX_ERR_BAD_PATH` if `name` is invalid.
    /// * error `ZX_ERR_NOT_EMPTY` if `name` refers to a non-empty directory.
    /// * error `ZX_ERR_UNAVAILABLE` if `name` refers to a mount point,
    ///   containing a remote channel.
    /// * error `ZX_ERR_NOT_DIR` if the options requested a directory but something other than a
    ///     directory was found.
    ///
    /// Other errors may be returned for filesystem-specific reasons.
    ///
    /// This method requires the following rights:
    ///
    /// * [`Rights.ENUMERATE`]
    /// * [`Rights.MODIFY_DIRECTORY`]
    [Selector = "fuchsia.io/Directory.Unlink", Transitional]
    Unlink2(fuchsia.io2.Name name, fuchsia.io2.UnlinkOptions options) -> () error zx.status;

    /// Reads a collection of variably sized dirents into a buffer.
    /// The number of dirents in a directory may be very large: akin to
    /// calling read multiple times on a file, directories have a seek
    /// offset which is updated on subsequent calls to ReadDirents.
    ///
    /// These dirents are of the form:
    /// ```
    /// struct dirent {
    ///   // Describes the inode of the entry.
    ///   uint64 ino;
    ///   // Describes the length of the dirent name in bytes.
    ///   uint8 size;
    ///   // Describes the type of the entry. Aligned with the
    ///   // POSIX d_type values. Use `DIRENT_TYPE_*` constants.
    ///   uint8 type;
    ///   // Unterminated name of entry.
    ///   char name[0];
    /// }
    /// ```
    ///
    /// This method does not require any rights, since one could always probe for
    /// directory contents by triggering name conflicts during file creation.
    // TODO(smklein): Convert to a vector of variable-length objects, when
    // llcpp arrives.
    // TODO(smklein): Get rid of "max_bytes".
    // TODO(smklein): Document the behavior when the seek pointer reaches the end of the directory.
    ReadDirents(uint64 max_bytes) -> (zx.status s, vector<uint8>:MAX_BUF dirents);

    /// Resets the directory seek offset.
    ///
    /// This method does not require any rights, similar to ReadDirents.
    Rewind() -> (zx.status s);

    /// Acquires a token to a Directory which can be used to identify
    /// access to it at a later point in time.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    GetToken() -> (zx.status s, handle? token);

    /// Renames an object named src to the name dst, in a directory represented by token.
    ///
    /// `src/dst` must be resolved object names. Including "/" in any position
    /// other than the end of the string will return `ZX_ERR_INVALID_ARGS`.
    /// Returning "/" at the end of either string implies that it must be a
    /// directory, or else `ZX_ERR_NOT_DIR` should be returned.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Rename(string:MAX_PATH src, zx.handle dst_parent_token, string:MAX_PATH dst) -> (zx.status s);

    /// Renames a node named `src` to the name `dst`, in a directory represented
    /// by `dst_parent_token`.
    ///
    /// `src` and `dst` must be valid node names.
    /// See [`fuchsia.io2/Name`] for what constitutes a valid name.
    ///
    /// This method requires the following rights on both the current
    /// connection, and the connection identified by `dst_parent_token`:
    ///
    /// * [`Rights.ENUMERATE`]
    /// * [`Rights.MODIFY_DIRECTORY`]
    ///
    /// * error `ZX_ERR_INVALID_ARGS` if `src` or `dst` is invalid.
    [Selector = "fuchsia.io/Directory.Rename"]
    Rename2(fuchsia.io2.Name src,
            fuchsia.io2.Token dst_parent_token,
            fuchsia.io2.Name dst) -> () error zx.status;

    /// Creates a link to an object named src by the name dst, within a directory represented by
    /// token.
    ///
    /// `src` must be a resolved object name. Including "/" in the string will
    /// return `ZX_ERR_INVALID_ARGS`.
    ///
    /// `dst` must be a resolved object name. Including "/" in the string will
    /// return `ZX_ERR_INVALID_ARGS`.
    ///
    /// This method requires following rights: `OPEN_RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    Link(string:MAX_PATH src, zx.handle dst_parent_token, string:MAX_PATH dst) -> (zx.status s);

    // TODO(smklein): When stablized, remove the "This API is unstable" comment
    /// Watches a directory, receiving events of added messages on the
    /// watcher request channel.
    ///
    /// The `watcher` handle will send messages of the form:
    /// ```
    /// struct {
    ///   uint8 event;
    ///   uint8 len;
    ///   char name[];
    /// };
    /// ```
    /// Where names are NOT null-terminated.
    ///
    /// This API is unstable; in the future, watcher will be a `DirectoryWatcher` client.
    ///
    /// Mask specifies a bitmask of events to observe.
    /// Options must be zero; it is reserved.
    ///
    /// This method does not require any rights, similar to ReadDirents.
    Watch(uint32 mask, uint32 options, zx.handle:CHANNEL watcher) -> (zx.status s);
};

const uint32 MOUNT_CREATE_FLAG_REPLACE = 0x00000001;

const uint64 MAX_FS_NAME_BUFFER = 32;

struct FilesystemInfo {
    /// The number of data bytes which may be stored in a filesystem.
    uint64 total_bytes;
    /// The number of data bytes which are in use by the filesystem.
    uint64 used_bytes;
    /// The number of nodes which may be stored in the filesystem.
    uint64 total_nodes;
    /// The number of nodes used by the filesystem.
    uint64 used_nodes;
    /// The amount of space which may be allocated from the underlying
    /// volume manager. If unsupported, this will be zero.
    uint64 free_shared_pool_bytes;
    /// A unique identifier for this filesystem instance. Will not be preserved
    /// across reboots.
    uint64 fs_id;
    /// The size of a single filesystem block.
    uint32 block_size;
    /// The maximum length of a filesystem name.
    uint32 max_filename_size;
    /// A unique identifier for the type of the underlying filesystem.
    uint32 fs_type;
    uint32 padding;
    // TODO(smklein): Replace this field with a string when supported
    // by the "Simple" interface. At the moment, name is a fixed-size,
    // null-terminated buffer.
    array<int8>:MAX_FS_NAME_BUFFER name;
};

/// DirectoryAdmin defines a directory which is capable of handling
/// administrator tasks within the filesystem.
protocol DirectoryAdmin {
    compose Directory;

    /// Mount a channel representing a remote filesystem onto this directory.
    /// All future requests to this node will be forwarded to the remote filesystem.
    /// To re-open a node without forwarding to the remote target, the node
    /// should be opened with `OPEN_FLAG_NO_REMOTE`.
    Mount(Directory remote) -> (zx.status s);

    /// Atomically create a directory with a provided path, and mount the
    /// remote handle to the newly created directory.
    MountAndCreate(Directory remote, string:MAX_FILENAME name, uint32 flags) -> (zx.status s);

    /// Unmount this filesystem. After this function returns successfully,
    /// all connections to the filesystem will be terminated.
    Unmount() -> (zx.status s);

    /// Detach a node which was previously attached to this directory
    /// with Mount.
    UnmountNode() -> (zx.status s, Directory? remote);

    /// Query the filesystem for filesystem-specific information.
    QueryFilesystem() -> (zx.status s, FilesystemInfo? info);

    /// Acquire the path to the device backing this filesystem, if there is one.
    GetDevicePath() -> (zx.status s, string:MAX_PATH? path);
};