// 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 zx;

/// The fields of 'attributes' which are used to update the Node are indicated
/// by the 'flags' argument.
type NodeAttributeFlags = strict bits : uint32 {
    CREATION_TIME = 0x00000001;
    MODIFICATION_TIME = 0x00000002;
};

/// 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 MODE_PROTECTION_MASK uint32 = 0x00FFF;

// Chosen to match S_IFDIR.
const MODE_TYPE_DIRECTORY uint32 = 0x04000;
// Chosen to match S_IFBLK.
const MODE_TYPE_BLOCK_DEVICE uint32 = 0x06000;
// Chosen to match S_IFREG.
const MODE_TYPE_FILE uint32 = 0x08000;
// Chosen to match S_IFLNK.
@available(added=HEAD)
const MODE_TYPE_SYMLINK uint32 = 0x0A000;
// Chosen arbitrarily.
const MODE_TYPE_SERVICE uint32 = 0x10000;

/// 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 MODE_TYPE_MASK uint32 = 0xFF000;

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

const MAX_FS_NAME_BUFFER uint64 = 32;

closed protocol Node {
    compose Node1;
    compose Node2;
};

/// Node defines the minimal interface for entities which can be accessed in a filesystem.
closed protocol Node1 {
    /// Create another connection to the same remote object.
    ///
    /// `flags` may be any of:
    ///
    /// - `OpenFlags.RIGHT_*`
    /// - `OpenFlags.APPEND`
    /// - `OpenFlags.DESCRIBE`
    /// - `OpenFlags.CLONE_SAME_RIGHTS`
    ///
    /// All other flags are ignored.
    ///
    /// The `OpenFlags.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 `OpenFlags.CLONE_SAME_RIGHTS` to inherit the rights on the source connection.
    /// It is invalid to pass any of the `OpenFlags.RIGHT_*` flags together with
    /// `OpenFlags.CLONE_SAME_RIGHTS`.
    @selector("fuchsia.io1/Node.Clone")
    strict Clone(resource struct {
        flags OpenFlags;
        object server_end:Node;
    });

    /// An event produced eagerly by a FIDL server if requested by `OpenFlags.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`).
    @selector("fuchsia.io1/Node.OnOpen")
    strict -> OnOpen(resource struct {
        s zx.Status;
        info @generated_name("NodeInfoDeprecated") strict resource union {
            /// No protocol information was supplied by the connection.
            1: service struct {};

            /// The connection composes [`File`].
            2: file @generated_name("FileObject") resource struct {
                /// 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.
                event zx.Handle:<EVENT, optional>;

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

            /// The connection composes [`Directory`].
            3: directory @generated_name("DirectoryObject") struct {};

            /// The connection composes ['Symlink'].
            @available(added=HEAD)
            4: symlink @generated_name("SymlinkObject") struct {
                target SymlinkTarget;
            };
        }:optional;
    });

    /// Acquires information about the node.
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io1/Node.GetAttr")
    strict GetAttr() -> (struct {
        s zx.Status;
        attributes NodeAttributes;
    });

    /// Updates information about the node.
    ///
    /// This method requires following rights: `OpenFlags.RIGHT_WRITABLE`, otherwise returns
    /// `ZX_ERR_BAD_HANDLE`.
    @selector("fuchsia.io1/Node.SetAttr")
    strict SetAttr(struct {
        flags NodeAttributeFlags;
        attributes NodeAttributes;
    }) -> (struct {
        s zx.Status;
    });

    /// Acquires the `Directory.Open` rights and flags used to access this file.
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io1/Node.NodeGetFlags")
    strict GetFlags() -> (struct {
        s zx.Status;
        flags OpenFlags;
    });

    /// Changes the `Directory.Open` flags used to access the file.
    /// Supported flags which can be turned on / off:
    /// - `OpenFlags.APPEND`
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io1/Node.NodeSetFlags")
    strict SetFlags(struct {
        flags OpenFlags;
    }) -> (struct {
        s zx.Status;
    });

    /// Query the filesystem for filesystem-specific information.
    @selector("fuchsia.io.admin/DirectoryAdmin.QueryFilesystem")
    strict QueryFilesystem() -> (struct {
        s zx.Status;
        info box<@generated_name("FilesystemInfo") struct {
            /// The number of data bytes which may be stored in a filesystem. This does not count
            /// metadata or other filesystem overhead like block rounding.
            total_bytes uint64;

            /// The number of data bytes which are in use by the filesystem. This does not count
            /// metadata or other filesystem overhead like block rounding.
            used_bytes uint64;

            /// The number of nodes which may be stored in the filesystem.
            total_nodes uint64;

            /// The number of nodes used by the filesystem.
            used_nodes uint64;

            /// The amount of additional space which may be allocated from the underlying volume
            /// manager. If unsupported or there is no space for the filesystem to grow, this will
            /// be zero.
            free_shared_pool_bytes uint64;

            /// A unique identifier for this filesystem instance. Will not be preserved across
            /// reboots.
            ///
            /// Implementors should create a kernel object (normally an event) and use its koid for
            /// the filesystem ID. This koid guarantees uniqueness in the system.
            fs_id uint64;

            /// The size in bytes of a single filesystem block.
            block_size uint32;

            /// The maximum length of a filesystem name.
            max_filename_size uint32;

            /// A unique identifier for the type of the underlying filesystem.
            fs_type uint32;

            padding uint32;

            // TODO: Replace this field with a string when supported by the "Simple" interface. At
            // the moment, name is a fixed-size, null-terminated buffer.
            name array<int8, MAX_FS_NAME_BUFFER>;
        }>;
    });
};