// Copyright 2019 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.io2;

using zx;

/// A [`fuchsia.io2/Node`] that is capable of containing other nodes.
protocol Directory {
    compose Node;

    /// Opens or creates a new node relative to this directory node.
    ///
    /// + `path` identifies the node to open.
    ///   If `path` contains multiple segments, then the directory is traversed,
    ///   one segment at a time, relative to the directory represented by this
    ///   connection.
    ///   See [`fuchsia.io2/Path`] for what constitutes a valid path.
    ///   To open another connection to the current directory, use
    ///   [`fuchsia.io2/Node.Reopen`] instead.
    /// + `mode` controls whether to open existing/create new etc.
    /// + `options` additional options applicable to both `Open` and `Reopen`,
    ///   including negotiating protocol and restricting rights.
    ///   See [`fuchsia.io2/ConnectionOptions`].
    /// + `object_request` is the server end of a channel created for the new
    ///   connection. The caller may proceed to send messages on the
    ///   corresponding client end right away.
    ///
    /// This method requires the following rights on the current connection:
    ///
    /// * [`Rights.ENUMERATE`]
    /// * [`Rights.TRAVERSE`]
    ///
    /// Errors are presented as an epitaph on the `object_request` channel.
    ///
    /// * error `ZX_ERR_ACCESS_DENIED` if the requested rights exceeds
    ///   what is allowed.
    /// * error `ZX_ERR_BAD_PATH` if `path` is invalid.
    Open(Path path,
         OpenMode mode,
         ConnectionOptions options,
         zx.handle:CHANNEL object_request);

    /// Adds a new inotify filter for an object relative to this directory object.
    ///
    /// + 'filter` 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 filter with events on this filter.
    ///
    /// + `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.
    ///
    /// + `controller` is the server end of a channel and is per filter in the vnode so that
    ///   we can remove the specific inotify filter when the controller is closed by the server
    ///   or the client.
    ///
    ///   Errors are presented as an epitaph on the `controller` channel.
    /// * error `ZX_ERR_ACCESS_DENIED` if the requested rights exceeds
    ///   what is allowed.
    /// * error `ZX_ERR_BAD_PATH` if `path` is invalid.
    AddInotifyFilter(Path path, InotifyWatchMask filter, uint32 watch_descriptor,
                     zx.handle:SOCKET socket) -> ();

    /// 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`]
    Unlink(Path path) -> () error zx.status;
    [Transitional]
    Unlink2(Name name, UnlinkOptions options) -> () error zx.status;

    /// Initiates a directory listing operation over the input channel,
    /// starting at seek offset 0.
    ///
    /// This method requires the [`Rights.ENUMERATE`] right. If this right is
    /// absent, `iterator` will be closed with a `ZX_ERR_ACCESS_DENIED` epitaph.
    Enumerate(DirectoryEnumerateOptions options,
              request<DirectoryIterator> iterator);

    /// 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.
    Rename(Name src,
           Token dst_parent_token,
           Name dst) -> () error zx.status;

    /// Creates a link to a node named `src` by the name `dst`,
    /// in a directory represented by `dst_parent_token`.
    ///
    /// Directories cannot be linked, to prevent reference cycles.
    ///
    /// `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.
    /// * error `ZX_ERR_INVALID_ARGS` if `src` is a directory.
    Link(Name src,
         Token dst_parent_token,
         Name dst) -> () error zx.status;

    /// Watches a directory, monitoring events for children being added or
    /// removed on the server end of the `watcher` channel.
    ///
    /// Mask specifies a bit mask of events to observe.
    ///
    /// This method requires the [`Rights.ENUMERATE`] right. If this right is
    /// absent, `watcher` will be closed with a `ZX_ERR_ACCESS_DENIED` epitaph.
    Watch(DirectoryWatchMask mask,
          DirectoryWatchOptions options,
          request<DirectoryWatcher> watcher);
};

/// Options related to node creation during [`Directory.Open`].
enum OpenMode : uint32 {
    /// Only succeed if the object exists.
    OPEN_EXISTING = 1;

    /// Create the object if it does not exist, otherwise open existing.
    /// The check and the creation are performed in one atomic step.
    MAYBE_CREATE = 2;

    /// Assert that the object does not exist, then create it.
    /// The assertion and creation are performed in one atomic step.
    ALWAYS_CREATE = 3;

    /// If the object is a mount point, open the local directory
    /// instead of forwarding the request. The object must be a directory.
    ///
    /// This option implies the behavior of `OPEN_EXISTING`.
    [Deprecated = "Mount points will be replaced by components."]
    OPEN_MOUNT_POINT = 0x10000000;
};

/// Auxiliary data for the directory representation of a node.
/// The selection of this variant in [`Representation`] implies that the
/// connection speaks the [`fuchsia.io2/Directory`] protocol.
table DirectoryInfo {
};

/// Options for [`Directory.Unlink`].
table UnlinkOptions {
    1: UnlinkFlags flags;
};

/// Flags for [`Directory.Unlink`].
bits UnlinkFlags : uint64 {
    /// If set, the unlink will fail (with ZX_ERR_NOT_DIR) if the object is not a directory.
    MUST_BE_DIRECTORY = 0x01;
};