// 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.io;

using zx;

/// Objective information about a filesystem node.
/// See [`Node.GetAttributes`] and [`Node.UpdateAttributes`].
///
/// The attributes of a node should be stable, independent of the
/// specific protocol used to access it.
///
/// If a particular attribute is not applicable or not supported,
/// filesystems should leave the corresponding field absent.
type NodeAttributes2 = table {
    /// Describes the kinds of representations supported by the node.
    /// Note: This is not the result of the connection-time negotiation,
    /// which is conveyed via `representation`.
    ///
    /// This attribute is read-only.
    1: protocols NodeProtocols;

    /// Describes the kinds of operations supported by the node.
    /// Note: This is distinct from the rights used at connection time.
    ///
    /// This attribute is read-only.
    2: abilities Abilities;

    /// Node size, in bytes.
    ///
    /// This attribute is read-only.
    3: content_size uint64;

    /// Space needed to store the node (possibly larger than size), in bytes.
    ///
    /// This attribute is read-only.
    4: storage_size uint64;

    /// Number of hard links to the node. It must be at least one.
    ///
    /// This attribute is read-only.
    5: link_count uint64;

    /// Time of creation in nanoseconds since the Unix epoch, UTC.
    /// It may be updated manually after creation.
    6: creation_time uint64;

    /// Time of last modification in nanoseconds since the Unix epoch, UTC.
    7: modification_time uint64;

    /// An ID for the node. See [`Id`].
    /// This `id` should be unique among all entries of a directory.
    ///
    /// This attribute is read-only.
    8: id Id;
};

/// Node defines the minimal protocol for entities which can be accessed
/// in a filesystem.
protocol Node2 {
    /// Creates another connection to the same node.
    ///
    /// + `options` options applicable to both `Open` and `Reopen`,
    ///   including negotiating protocol and restricting rights.
    ///   See [`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.
    ///
    /// For files, the cloned connection and the original connection have
    /// independent seek offsets.
    @transitional
    @selector("fuchsia.io/Node.Reopen")
    Reopen(resource struct {
        options ConnectionOptions;
        object_request zx.handle:CHANNEL;
    });

    /// Terminates the connection to the node.
    ///
    /// After calling `Close`, the client must not send any other requests.
    /// Servers, after sending the status response, should close the connection
    /// regardless of status and without sending an epitaph.
    ///
    /// Closing the client end of the channel should be semantically equivalent
    /// to calling `Close` without knowing when the close has completed or its
    /// status.
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io/Node.Close")
    Close() -> (struct {}) error zx.status;

    /// Returns extra connection information and auxiliary handles.
    ///
    /// + `query` specifies the fields in `ConnectionInfo` that the caller is
    ///   interested in.
    /// - `info` see [`ConnectionInfo`] for details on the fields.
    ///
    /// When all known bits in `query` are set, the return value matches
    /// the one from [`OnConnectionInfo`], as if the caller requested that event
    /// using [`ConnectionFlags.GET_CONNECTION_INFO`].
    ///
    /// If the `Describe` operation fails, the connection is closed with the
    /// associated error.
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io/Node.Describe")
    Describe2(struct {
        query @generated_name("ConnectionInfoQuery") strict bits : uint64 {
            /// Requests [`ConnectionInfo.representation`].
            REPRESENTATION = 0x1;

            /// Requests [`ConnectionInfo.rights`].
            RIGHTS = 0x2;

            /// Requests [`ConnectionInfo.available_operations`].
            AVAILABLE_OPERATIONS = 0x4;
        };
    }) -> (resource struct {
        info ConnectionInfo;
    });

    /// An event produced eagerly by the server if requested by
    /// [`ConnectionFlags.GET_CONNECTION_INFO`]. This event will be the
    /// first message from the server, and is sent exactly once.
    ///
    /// - `info` See [`ConnectionInfo`] for details on the fields.
    ///   All members should be present.
    ///
    /// Different from [`fuchsia.io/OnOpen`], an error during open/reopen is
    /// always manifested as an epitaph.
    @selector("fuchsia.io/Node.OnConnectionInfo")
    -> OnConnectionInfo(resource struct {
        info ConnectionInfo;
    });

    // TODO(https://fxbug.dev/77623): uncomment and implement.
    // /// Acquires a token which can be used to identify this connection at
    // /// a later point in time.
    // ///
    // /// This method does not require any rights. Note that the token identifies
    // /// the connection, hence carries the rights information on this connection.
    // @selector("fuchsia.io/Node.GetToken")
    // GetToken2() -> (resource struct {
    //     token Token;
    // }) error zx.status;

    /// Acquires information about the node.
    ///
    /// The attributes of a node should be stable, independent of the
    /// specific protocol used to access it.
    ///
    /// + `query` a bit-mask specifying which attributes to fetch. The server
    ///   should not return more than necessary.
    /// - `attributes` the returned attributes.
    ///
    /// This method requires the [`Rights.GET_ATTRIBUTES`] right.
    @transitional
    @selector("fuchsia.io/Node.GetAttributes")
    GetAttributes(struct {
        /// Set the corresponding bit to one to query that particular attribute.
        ///
        /// The elements here correspond one-to-one with [`NodeAttributes`].
        query @generated_name("NodeAttributesQuery") strict bits : uint64 {
            /// Requests [`NodeAttributes.protocols`].
            PROTOCOLS = 0x1;

            /// Requests [`NodeAttributes.abilities`].
            ABILITIES = 0x2;

            /// Requests [`NodeAttributes.content_size`].
            CONTENT_SIZE = 0x4;

            /// Requests [`NodeAttributes.storage_size`].
            STORAGE_SIZE = 0x8;

            /// Requests [`NodeAttributes.link_count`].
            LINK_COUNT = 0x10;

            /// Requests [`NodeAttributes.creation_time`].
            CREATION_TIME = 0x20;

            /// Requests [`NodeAttributes.modification_time`].
            MODIFICATION_TIME = 0x40;

            /// Requests [`NodeAttributes.id`].
            ID = 0x80;
        };
    }) -> (struct {
        attributes NodeAttributes2;
    }) error zx.status;

    /// Updates information about the node.
    ///
    /// + `attributes` the presence of a table field in `attributes` indicates
    /// the intent to update the corresponding attribute.
    ///
    /// This method requires the [`Rights.UPDATE_ATTRIBUTES`] right.
    @transitional
    @selector("fuchsia.io/Node.UpdateAttributes")
    UpdateAttributes(struct {
        attributes NodeAttributes2;
    }) -> (struct {}) error zx.status;

    /// Synchronizes updates to the node to the underlying media, if it exists.
    ///
    /// This method will return when the filesystem server has flushed the
    /// relevant updates to the underlying media, but does not guarantee the
    /// underlying media has persisted the information, nor that any information
    /// is committed to hardware. Clients may use `Sync` to ensure ordering
    /// between operations.
    ///
    /// This method does not require any rights.
    @selector("fuchsia.io/Node.Sync")
    Sync() -> (struct {}) error zx.status;
};