/*
  FSKitExt <-> Backend RPC Protocol
  ---------------------------------
  File: FSKitExt/protocol.proto
  Source (persistent URL):
    https://github.com/debox-network/FSKitBridge/blob/main/FSKitExt/protocol.proto

  Purpose:
    Language-neutral wire format between FSKitExt (Swift/ExtensionKit) and the
    backend (e.g., Rust via fskit-fs). This protocol carries file system
    operations (lookup, attributes, read/write, etc).

  License:
    SPDX-License-Identifier: MIT OR Apache-2.0
    Copyright (c) 2025 Debox Network

  This file is part of FSKitBridge. See LICENSE-MIT and LICENSE-APACHE at repo root.
*/
syntax = "proto3";

package pb;

import "google/protobuf/timestamp.proto";

// Get the resource identifier and name.
message GetResourceIdentifier {}

// Get the volume identifier and name.
message GetVolumeIdentifier {}

// Get options that tell FSKit to declare behaviors and selectively inhibit
// operation protocols.
message GetVolumeBehavior {}

// Get properties implemented by volumes that support providing the values of
// system limits or options.
message GetPathConfOperations {}

// Get properties that provide the supported capabilities of the volume.
message GetVolumeCapabilities {}

// Get properties that provide up-to-date statistics of the volume.
message GetVolumeStatistics {}

// A class that passes command options to a task, optionally providing
// security-scoped URLs.
message TaskOptions {
  // An array of strings that represent command-line options for the task.
  //
  // This property is equivalent to the `argv` array of C strings passed to
  // a command-line tool.
  repeated string task_options = 1;
}

// Mounts this volume, using the specified options.
//
// FSKit calls this method as a signal that some process is trying to mount this volume.
// Your file system receives a call to ``activate(options:)`` prior to receiving
// any mount calls.
message Mount {
  // Options to apply to the mount.
  // These can include security-scoped file paths.
  // There are no defined options currently.
  TaskOptions options = 1;
}

// Unmounts this volume.
//
// Clear and flush all cached state in your implementation of this method.
message Unmount {}

// Synchronizes the volume with its underlying resource.
//
// After calling this method, FSKit assumes that the volume has sent all pending
// I/O or metadata to its resource.
message Synchronize {
  // Behavior flags for use with synchronization calls.
  //
  // These values are based on flags defined in `mount.h`.
  // Since there are system-defined flags that are valid in the kernel but not in FSKit,
  // this type defines its members as options rather than use an enumeration.
  enum SyncFlags {
    NONE = 0;

    // A flag for synchronized I/O with file-integrity completion.
    WAIT = 1;

    // A flag for synchronized I/O that starts I/O but doesn't wait for it.
    NO_WAIT = 2;

    // A flag for synchronized I/O with data-integrity completion.
    D_WAIT = 4;
  }

  // Timing flags, as defined in `mount.h`.
  // These flags let the file system know whether to run the operation in
  // a blocking or nonblocking fashion.
  SyncFlags flags = 1;
}

// Fetches attributes for the given item.
//
// For file systems that don't support hard links, set ``FSItemAttributes/linkCount``
// to `1` for regular files and symbolic links.
//
// If the item's `bsdFlags` contain the `UF_COMPRESSED` flag, your file system
// returns the uncompressed size of the file.
message GetAttributes {
  // The item to get attributes for.
  uint64 item_id = 1;
}

// Sets the given attributes on an item.
//
// Several attributes are considered "read-only", and an attempt to set these
// attributes results in an error with the code `EINVAL`.
//
// A request may set ``FSItem/Attributes/size`` beyond the end of the file.
// If the underlying file system doesn't support sparse files, allocate space to
// fill the new file size.
// Either fill this space with zeroes, or configure it to read as zeroes.
//
// If a request sets the file size below the current end-of-file, truncate the
// file and return any unused space to the file system as free space.
//
// Ignore attempts to set the size of directories or symbolic links; don't
// produce an error.
//
// If the caller attempts to set an attribute not supported by the on-disk file
// system format, don't produce an error.
// The upper layers of the framework will detect this situation.
message SetAttributes {
  // A request containing the attributes to set.
  ItemAttributes attributes = 1;

  // The item on which to set the attributes.
  uint64 item_id = 2;
}

// Looks up an item within a directory.
//
// If no item matching `name` exists in the directory indicated by `directory`,
// complete the request with an error with a domain of
// <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
// and a code of `ENOENT`.
//
// > Tip: The ``FSFileName`` sent back to the caller may differ from the `name`
// parameter.
// This flexibility allows your implementation to handle case-insensitive and
// case-sensitive file systems.
// It might also be the case that `name` uses a composed Unicode string, but the
// name maintained by the file system and provided to the caller is uncomposed Unicode.
message LookupItem {
  // The name of the item to look up.
  bytes name = 1;

  // The directory in which to look up the item.
  uint64 directory_id = 2;
}

// Reclaims an item, releasing any resources allocated for the item.
//
// FSKit guarantees that for every ``FSItem`` returned by the volume,
// a corresponding reclaim operation occurs after the upper layers no longer
// reference that item.
//
// > Note: Block device file systems may assess whether an underlying resource
// terminates before processing reclaim operations.
// On unary file systems, for example, the associated volumes unmount when such
// resources disconnect from the system.
// The unmount triggers a reclaiming of all items.
// Some implementations benefit greatly from short-circuiting in such cases.
// With a terminated resource, all I/O results in an error, making short-circuiting
// the most efficient response.
message ReclaimItem {
  // The item to reclaim.
  uint64 item_id = 1;
}

// Reads a symbolic link.
message ReadSymbolicLink {
  // The symbolic link to read from.
  // FSKit guarantees this item is of type ``FSItem/ItemType/symlink``.
  uint64 item_id = 1;
}

// An enumeration of item types, such as file, directory, or symbolic link.
enum ItemType {
  UNKNOWN = 0;
  FILE = 1;
  DIRECTORY = 2;
  SYMLINK = 3;
  FIFO = 4;
  CHAR_DEVICE = 5;
  BLOCK_DEVICE = 6;
  SOCKET = 7;
}

// Creates a new file or directory item.
//
// If an item named `name` already exists in the directory indicated by
// `directory`, complete the request with an error with a domain of
// <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
// and a code of `EEXIST`.
message CreateItem {
  // The new item's name.
  bytes name = 1;

  // The new item's type.
  // Valid values are ``FSItem/ItemType/file`` or ``FSItem/ItemType/directory``.
  ItemType type = 2;

  // The directory in which to create the item.
  uint64 directory_id = 3;

  // Attributes to apply to the new item.
  ItemAttributes attributes = 4;
}

// Creates a new symbolic link.
//
// If an item named `name` already exists in the directory indicated by
// `directory`, complete the request with an error with a domain of
// <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
// and a code of `EEXIST`.
message CreateSymbolicLink {
  // The new item's name.
  bytes name = 1;

  // The directory in which to create the item.
  uint64 directory_id = 2;

  // Attributes to apply to the new item.
  ItemAttributes new_attributes = 3;

  // The contents of the new symbolic link.
  bytes contents = 4;
}

// Creates a new hard link.
//
// If creating the link fails, complete the request with an error with a domain
// of <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
// and the following error codes:
//
// * `EEXIST`  if there's already an item named `name` in the directory.
// * `EMLINK`  if creating the link would exceed the maximum number of hard links
//             supported on `item`.
// * `ENOTSUP` if the file system doesn't support creating hard links to the
//             type of file system object that `item` represents.
message CreateLink {
  // The existing item to which to link.
  uint64 item_id = 1;

  // The name for the new link.
  bytes name = 2;

  // The directory in which to create the link.
  uint64 directory_id = 3;
}

// Removes an existing item from a given directory.
//
// Don't actually remove the item object itself in your implementation;
// instead, only remove the given item name from the given directory.
// Remove and deallocate the item in ``reclaimItem(_:)``.
message RemoveItem {
  // The item to remove.
  uint64 item_id = 1;

  // The name of the item to remove.
  bytes name = 2;

  // The directory from which to remove the item.
  uint64 directory_id = 3;
}

// Renames an item from one path in the file system to another.
//
// Implement renaming along the lines of this algorithm:
//
// - If `item` is a file:
//   - If the destination file exists:
//     - Remove the destination file.
//   - If the source and destination directories are the same:
//     - Rewrite the name in the existing directory.
//   - Else:
//     - Write the new entry in the destination directory.
//     - Clear the old directory entry.
// - If `item` is a directory:
//   - If the destination directory exists:
//     - If the destination directory isn't empty:
//       - Fail the operation with an error of
//         <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
//         and a code of `ENOTEMPTY`.
//     - Else:
//        - Remove the destination directory.
//     - If the source and destination directories are the same:
//       - Rewrite the name in the existing directory.
//     - Else:
//       - If the destination is a child of the source directory:
//         - Fail the operation with an error.
//       - Else:
//         - Write the new entry in the destination directory.
//         - Update `"."` and `".."` in the moved directory.
//         - Clear the old directory entry.
message RenameItem {
  // The file system object being renamed.
  uint64 item_id = 1;

  // The directory that currently contains the item to rename.
  uint64 source_directory_id = 2;

  // The name of the item within the source directory.
  bytes source_name = 3;

  // The new name of the item as it appears in `destinationDirectory`.
  bytes destination_name = 4;

  // The directory to contain the renamed object, which may be the same
  // as `sourceDirectory`.
  uint64 destination_directory_id = 5;

  // The file system object if the destination exists, as discovered in a prior lookup.
  // If this parameter is non-`nil`, mark `overItem` as deleted, so the file
  // system can free its allocated space on the next call to ``reclaimItem(_:)``.
  // After doing so, ensure the operation finishes without errors.
  optional uint64 over_item_id = 6;
}

// Enumerates the contents of the given directory.
//
// This method uses the ``FSDirectoryEntryPacker/packEntry(name:itemType:itemID:
// nextCookie:attributes:)`` method of the `packer` parameter to deliver
// the enumerated items to the caller.
// The general flow of an enumeration implementation follows these steps:
//
// 1. Enumeration starts with a call to `enumerateDirectory` using the initial
//    next-cookie and verifier values ``FSDirectoryCookieInitial`` and
//    ``FSDirectoryVerifierInitial``, respectively.
// 2. The implementation uses `packer` to pack the initial set of directory entries.
//    Packing also sets a `nextCookie` to use on the next call.
// 3. The implementation replies with a new verifier value, a nonzero value that
//    reflects the directory's current version.
// 4. On the next call the implementation packs the next set of entries, starting
//    with the item indicated by `cookie`.
//    If `cookie` doesn't resolve to a valid directory entry, complete the request
//    with an error of domain
//    <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
//    and code``FSError/Code/invalidDirectoryCookie``.
//
// When packing, make sure to use acceptable directory entry names and
// unambiguous input to all file operations that take names without additional
// normalization, such as`lookupName`.
//
// > Tip: If the `attributes` parameter is `nil`, include at least two entries
// in a directory: `"."` and `".."`, which represent the current and
// parent directories, respectively.
// Both of these items have type ``FSItem/ItemType/directory``.
// For the root directory, `"."` and `".."` have identical contents.
// Don't pack  `"."` and `".."` if `attributes` isn't `nil`.
message EnumerateDirectory {
  // The item to enumerate.
  // FSKit guarantees this item is of type ``FSItem/ItemType/directory``.
  uint64 directory_id = 1;

  // A value that indicates the location within the directory from which
  // to enumerate.
  // Your implementation defines the semantics of the cookie values; they're
  // opaque to FSKit.
  // The first call to the enumerate method passes ``FSDirectoryCookieInitial``
  // for this parameter.
  // Subsequent calls pass whatever cookie value you previously passed to the
  // packer's `nextCookie` parameter.
  uint64 cookie = 2;

  // A tool to detect whether the directory contents changed since the last call
  // to `enumerateDirectory`.
  // Your implementation defines the semantics of the verifier values; they're
  // opaque to FSKit.
  // The first call to the enumerate method passes ``FSDirectoryVerifierInitial``
  // for this parameter.
  // Subsequent calls pass whatever cookie value you previously passed to the
  // packer's `currentVerifier` parameter.
  uint64 verifier = 3;
}

// Activates the volume using the specified options.
//
// When FSKit calls this method, allocate any in-memory state required to
// represent the file system.
// Also allocate an ``FSItem`` for the root directory of the file system, and
// pass it to the reply block.
// FSKit caches this root item for the lifetime of the volume, and uses it as a
// starting point for all file look-ups.
//
// Volume activation occurs prior to any call to mount the volume.
message Activate {
  // Options to apply to the activation.
  // These can include security-scoped file paths.
  // There are no defined options currently.
  TaskOptions options = 1;
}

// Tears down a previously initialized volume instance.
//
// Set up your implementation to release any resources allocated for
// the volume instance.
// By the time you receive this callback, FSKit has already performed a reclaim
// call to release all other file nodes associated with this file system instance.
//
// Avoid performing any I/O in this method.
// Prior to calling this method, FSKit has already issued a sync call to perform
// any cleanup-related I/O.
//
// FSKit unmounts any mounted volume with a call to ``unmount()`` prior to the
// deactivate callback.
message Deactivate {
  // Options that affect the behavior of deactivate methods.
  enum DeactivateOption {
    // An option to force deactivation.
    FORCE = 0;
  }

  // Options to apply to the deactivation.
  repeated DeactivateOption options = 1;
}

// Returns an array that specifies the extended attribute names the given
// item supports.
//
// If `item` supports no extended attributes, this method returns `nil`.
//
// Only implement this method if your volume works with "limited"
// extended attributes.
// For purposes of this protocol, "limited" support means the volume doesn't
// support extended attributes generally, but uses these APIs to expose
// specific file system data.
//
// > Note: If a file system implements this method, FSKit assumes limited
// support for extended attributes exists.
// In this mode, FSkit only calls this protocol's methods for the extended
// attribute names this method returns.
message GetSupportedXattrNames {
  // The item for which to get information.
  uint64 item_id = 1;
}

// Gets the specified extended attribute of the given item.
message GetXattr {
  // The extended attribute name.
  bytes name = 1;

  // The item for which to get the extended attribute.
  uint64 item_id = 2;
}

// Sets the specified extended attribute data on the given item.
message SetXattr {
  // Flags to specify the policy when setting extended file attributes.
  enum SetXattrPolicy {
    // Set the value, regardless of previous state.
    ALWAYS_SET = 0;

    // Set the value, but fail if the extended attribute already exists.
    MUST_CREATE = 1;

    // Set the value, but fail if the extended attribute doesn't already exist.
    MUST_REPLACE = 2;

    // Delete the value, failing if the extended attribute doesn't exist.
    DELETE = 3;
  }

  // The extended attribute name.
  bytes name = 1;

  // The extended attribute value to set.
  // This can't be `nil`, unless the policy is ``SetXattrPolicy/delete``.
  optional bytes value = 2;

  // The item on which to set the extended attribute.
  uint64 item_id = 3;

  // The policy to apply when setting the attribute.
  // See ``SetXattrPolicy`` for possible values.
  SetXattrPolicy policy = 4;
}

// Gets the list of extended attributes currently set on the given item.
message GetXattrs {
  // The item from which to get extended attributes.
  uint64 item_id = 1;
}

// Defined modes for opening a file.
enum OpenMode {
  // The read mode.
  //
  // This mode is equivalent to POSIX `FREAD`.
  READ = 0;

  // The write mode.
  //
  // This mode is equivalent to POSIX `FRWITE`.
  WRITE = 1;
}

// Opens a file for access.
message OpenItem {
  // The item to open.
  uint64 item_id = 1;

  // The set of mode flags to open the item with.
  repeated OpenMode modes = 2;
}

// Closes a file from further access.
message CloseItem {
  // The item to close.
  uint64 item_id = 1;

  // The set of mode flags to keep after this close.
  repeated OpenMode modes = 2;
}

// Reads the contents of the given file item.
//
// If the number of bytes requested exceeds the number of bytes available before
// the end of the file, then the call copies only those bytes to `buffer`.
// If `offset` points past the last valid byte of the file, don't reply with an
// error but set `actuallyRead` to `0`.
message Read {
  // The item from which to read.
  // FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
  uint64 item_id = 1;

  // The offset in the file from which to start reading.
  int64 offset = 2;

  // The number of bytes to read.
  int64 length = 3;
}

// Writes contents to the given file item.
//
// FSKit expects this routine to allocate space in the file system to extend the
// file as necessary.
//
// If the volume experiences an out-of-space condition, reply with an error of
// domain <doc://com.apple.documentation/documentation/Foundation/NSPOSIXErrorDomain>
// and code `ENOSPC`.
message Write {
  // A buffer containing the data to write to the file.
  bytes contents = 1;

  // The item to which to write.
  // FSKit guarantees this item will be of type ``FSItem/ItemType/file``.
  uint64 item_id = 2;

  // The offset in the file from which to start writing.
  int64 offset = 3;
}

// Checks whether the file system allows access to the given item.
message CheckAccess {
  // Options of access rights.
  enum AccessMask {
    // The file system allows reading data.
    READ_DATA = 0;

    // The file system allows listing directory contents.
    LIST_DIRECTORY = 1;

    // The file system allows writing data.
    WRITE_DATA = 2;

    // The file system allows adding files.
    ADD_FILE = 3;

    // The file system allows file execution.
    EXECUTE = 4;

    // The file system allows searching files.
    SEARCH = 5;

    // The file system allows deleting a file.
    DELETE = 6;

    // The file system allows appending data to a file.
    APPEND_DATA = 7;

    // The file system allows adding subdirectories.
    ADD_SUBDIRECTORY = 8;

    // The file system allows deleting subdirectories.
    DELETE_CHILD = 9;

    // The file system allows reading file attributes.
    READ_ATTRIBUTES = 10;

    // The file system allows writing file attributes.
    WRITE_ATTRIBUTES = 11;

    // The file system allows reading extended file attributes.
    READ_XATTR = 12;

    // The file system allows writing extended file attributes.
    WRITE_XATTR = 13;

    // The file system allows reading a file's security descriptors.
    READ_SECURITY = 14;

    // The file system allows writing a file's security descriptors.
    WRITE_SECURITY = 15;

    // The file system allows taking ownership of a file.
    TAKE_OWNERSHIP = 16;
  }

  // The item for which to check access.
  uint64 item_id = 1;

  // A mask indicating a set of access types for which to check.
  repeated AccessMask access = 2;
}

// Sets a new name for the volume.
message SetVolumeName {
  // The new volume name.
  bytes name = 1;
}

// Preallocate disk space for the given item.
message PreallocateSpace {
  // Behavior flags for preallocation operations.
  enum PreallocateFlag {
    // Allocates contiguous space.
    CONTIGUOUS = 0;

    // Allocates all requested space or no space at all.
    ALL = 1;

    // Allocates space that isn't freed when deleting the descriptor.
    //
    // This space remains allocated even after calling `close(2)`.
    PERSIST = 2;

    // Allocates space from the physical end of file.
    //
    // When implementing this behavior, ignore any offset in the preallocate call.
    // This flag is currently set for all
    // ``FSVolume/PreallocateOperations/preallocateSpace(for:at:length:flags:)``
    // calls.
    FROM_EOF = 3;
  }

  // The item for which to preallocate space.
  uint64 item_id = 1;

  // The offset from which to allocate.
  int64 offset = 2;

  // The length of the space in bytes.
  int64 length = 3;

  // Flags that affect the preallocation behavior.
  repeated PreallocateFlag flags = 4;
}

// Notifies the file system that the kernel is no longer making immediate use of
// the given item.
//
// This method gives a file system a chance to release resources associated
// with an item.
// However, this method prescribes no specific action; it's acceptable to defer
// all reclamation until ``FSVolume/Operations/reclaimItem(_:)``.
// This method is the equivalent of VFS's `VNOP_INACTIVE`.
//
// FSKit restricts calls to this method based on the current value of
// ``FSVolume/ItemDeactivation/itemDeactivationPolicy``.
message DeactivateItem {
  // The item to deactivate.
  uint64 item_id = 1;
}

// Request envelope for communication over the local socket.
message Request {
  // Correlation identifier used to match responses to requests.
  uint64 id = 1;

  // The concrete operation this request carries.
  oneof content {
    // Configurations
    GetResourceIdentifier get_resource_identifier = 10;
    GetVolumeIdentifier get_volume_identifier = 11;
    GetVolumeBehavior get_volume_behavior = 12;
    GetPathConfOperations get_path_conf_operations = 13;

    // Operations protocol.
    //
    // Methods that all volumes implement to provide required capabilities.
    //
    // Conform to this protocol in your subclass of ``FSVolume``.
    // To provide additional capabilities, conform to the other `FSVolume`
    // operations protocols, like ``FSVolumeOpenCloseOperations`` and
    // ``FSVolumeReadWriteOperations``.
    //
    // > Note: This protocol extends ``FSVolumePathConfOperations``, so your volume
    // implementation must also conform to that protocol.
    GetVolumeCapabilities get_volume_capabilities = 14;
    GetVolumeStatistics get_volume_statistics = 15;
    Mount mount = 16;
    Unmount unmount = 17;
    Synchronize synchronize = 18;
    GetAttributes get_attributes = 19;
    SetAttributes set_attributes = 20;
    LookupItem lookup_item = 21;
    ReclaimItem reclaim_item = 22;
    ReadSymbolicLink read_symbolic_link = 23;
    CreateItem create_item = 24;
    CreateSymbolicLink create_symbolic_link = 25;
    CreateLink create_link = 26;
    RemoveItem remove_item = 27;
    RenameItem rename_item = 28;
    EnumerateDirectory enumerate_directory = 29;
    Activate activate = 30;
    Deactivate deactivate = 31;

    // XattrOperations protocol.
    //
    // Methods and properties implemented by volumes that natively or partially
    // support extended attributes.
    GetSupportedXattrNames get_supported_xattr_names = 32;
    GetXattr get_xattr = 33;
    SetXattr set_xattr = 34;
    GetXattrs get_xattrs = 35;

    // OpenCloseOperations protocol.
    //
    // Methods and properties implemented by volumes that want to receive open and
    // close calls for each item.
    //
    // When a file system volume conforms to this protocol, the kernel layer issues
    // an open call to indicate desired access, and a close call to indicate
    // what access to retain.
    // A file is fully closed when the kernel layer issues a close call with no
    // retained open nodes.
    // When a file system receives the close call, it removes all access to the item.
    // When all memory mappings to the item release, the kernel layer issues
    // a final close.
    //
    // If a file system volume doesn't conform to this protocol, the kernel layer
    // can skip making such calls to the volume.
    OpenItem open_item = 36;
    CloseItem close_item = 37;

    // ReadWriteOperations protocol.
    //
    // Methods implemented for read and write operations that deliver data to and
    // from the extension.
    //
    // Most volumes conform to either this protocol or
    // ``FSVolumeKernelOffloadedIOOperations``.
    // You can conform to both if you need to provide kernel-offloaded I/O only for
    // certain files.
    // In that case, files with the ``FSItem/Attribute/inhibitKernelOffloadedIO``
    // attribute set use this protocol, and those without it use
    // ``FSVolumeKernelOffloadedIOOperations``.
    // A volume that doesn't conform to either protocol can't support
    // any I/O operation.
    Read read = 38;
    Write write = 39;

    // AccessCheckOperations protocol.
    //
    // Methods and properties implemented by volumes that want to enforce access
    // check operations.
    CheckAccess check_access = 40;

    // RenameOperations protocol.
    //
    // Methods and properties implemented by volumes that support renaming
    // the volume.
    SetVolumeName set_volume_name = 41;

    // ``PreallocateFlags`` protocol.
    //
    // Methods and properties implemented by volumes that want to offer
    // preallocation functions.
    //
    // A preallocation operation allocates space for a file without writing to it
    // yet.
    // A file system may use reallocation to avoid performing space allocation while
    // in the midst of I/O; this strategy improves performance.
    // Also, if the expected I/O pattern is many small writes,
    // preallocating contiguous chunks may prevent fragmenting the file system.
    // This process can improve performance later.
    //
    // In a kernel-based file system, you typically preallocate space with the
    // `VNOP_ALLOCATE` operation, called from `fcntl(F_PREALLOCATE)`.
    PreallocateSpace preallocate_space = 42;

    // ItemDeactivation protocol.
    //
    // Methods and properties implemented by volumes that support
    // deactivating items.
    DeactivateItem deactivate_item = 43;
  }
}

// A resource identifier and name.
message ResourceIdentifier {
  // A resource name, as found during the probe operation.
  // If the file system doesn't support names, or is awaiting naming,
  // use an empty string.
  optional string name = 1;

  // A container identifier, as found during the probe operation.
  // If the file system doesn't support durable identifiers, use a random UUID.
  optional string container_id = 2;
}

// A volume identifier and name.
message VolumeIdentifier {
  // An ``FSVolumeIdentifier`` to uniquely identify the volume.
  // For a network file system that supports multiple authenticated users,
  // disambiguate the users by using qualifying data in the identifier.
  optional string id = 1;

  // A name for the volume.
  optional string name = 2;
}

// Per-mount behavior settings for an FSKit volume.
// These options let the host file system extension declare behaviors and
// selectively inhibit operation protocols.
//
// FSKit reads these after the file system replies to the `loadResource`
// message.
// Changing the returned value during the runtime of the volume has no effect.
message VolumeBehavior {
  // Options to specify the item deactivation policy.
  //
  // Callers may want to set a deactivation policy because
  // ``FSVolume/ItemDeactivation/deactivateItem(_:)``
  // processing blocks the kernel.
  // Setting a deactivation policy allows the file system to take action at a
  // definitive point in the item's life cycle.
  // These options allow the file system to instruct the FSKit kernel of which
  // circumstances require the expense of a round-trip call to the module.
  //
  // > Note: To avoid performing deactivation calls, use an empty option set (`[]`).
  enum ItemDeactivationOption {
    // An option to always perform deactivation calls.
    //
    // Use this option if the file system needs `deactivateItem` calls in
    // circumstances beyond those covered
    // by ``forRemovedItems`` and ``forPreallocatedItems``.
    ALWAYS = 0;

    // An option to process deactivation for open-unlinked items at the moment of
    // last close.
    FOR_REMOVED_ITEMS = 1;

    // An option to process deactivation for for files with preallocated space.
    //
    // This option facilitates a sort of trim-on-close behavior.
    // It is only meaningful for volumes that conform to ``FSVolume/PreallocateOperations``.
    FOR_PREALLOCATED_ITEMS = 2;
  }

  // A property that allows the file system to use open-unlink emulation.
  //
  // _Open-unlink_ functionality refers to a file system's ability to support
  // an open file being fully unlinked from the file system namespace.
  // If a file system doesn't support this functionality, FSKit can emulate
  // it instead; this is called "open-unlink emulation".
  //
  // Set this property to `true` to allow FSKit to perform open-unlink emulation.
  // Otherwise, FSKit doesn't perform open-unlink emulation for this volume.
  optional bool enable_open_unlink_emulation = 1;

  // A Boolean value that instructs FSKit not to call ``XattrOperations``
  // protocol's methods.
  optional bool xattr_operations_inhibited = 2;

  // A Boolean value that instructs FSKit not to call ``OpenCloseOperations``
  // protocol's methods.
  optional bool is_open_close_inhibited = 3;

  // A Boolean value that instructs FSKit not to call ``AccessCheckOperations``
  // protocol's methods.
  optional bool is_access_check_inhibited = 4;

  // A Boolean value that instructs FSKit not to call ``RenameOperations``
  // protocol's methods.
  optional bool is_volume_rename_inhibited = 5;

  // A Boolean value that instructs FSKit not to call ``PreallocateOperations``
  // protocol's methods.
  optional bool is_preallocate_inhibited = 6;

  // A property that tells FSKit to which types of items the deactivation applies,
  // if any.
  repeated ItemDeactivationOption item_deactivation_options = 7;
}

// Properties implemented by volumes that support providing the values of system
// limits or options.
//
// This protocol gathers properties related to the `pathconf` and `fpathconf`
// system calls.
//
// For a file, the value of a property applies to just that file; for a
// directory, the value applies to all items in the directory.
//
// Properties that represent limits and have a numeric type use `-1` to
// represent no limit.
message PathConfOperations {
  // A property that represents the maximum number of hard links to the object.
  int64 maximum_link_count = 1;

  // A property that represents the maximum length of a component of a filename.
  int64 maximum_name_length = 2;

  // A Boolean property that indicates whether the volume restricts ownership
  // changes based on authorization.
  //
  // If this value is true, the volume rejects a `chown(2)` from anyone other than
  // the superuser.
  bool restricts_ownership_changes = 3;

  // A property that indicates whether the volume truncates files longer than its
  // maximum supported length.
  //
  // If this value is `true`, the volume truncates the filename to
  // ``maximumNameLength`` if the filename is longer than that.
  // If this value is false, the file system responds with the error code
  // `ENAMETOOLONG` if the filename is longer than ``maximumNameLength``.
  bool truncates_long_names = 4;

  // The maximum extended attribute size in bytes.
  //
  // Implement at least one of `maximumXattrSize` or ``maximumXattrSizeInBits``.
  // FSKit automatically converts from one to another if needed.
  // If you implement both, FSKit uses only the `maximumXattrSizeInBits`
  // implementation.
  optional int64 maximum_xattr_size = 5;

  // The maximum extended attribute size in bits.
  //
  // Implement at least one of ``maximumXattrSize`` or `maximumXattrSizeInBits`.
  // FSKit automatically converts from one to another if needed.
  // If you implement both, FSKit uses only the `maximumXattrSizeInBits`
  // implementation.
  optional int64 maximum_xattr_size_in_bits = 6;

  // The maximum size of a regular file allowed in the volume.
  //
  // Implement at least one of `maximumFileSize` or ``maximumFileSizeInBits``.
  // FSKit automatically converts from one to another if needed.
  // If you implement both, FSKit uses only the `maximumFileSizeInBits`
  // implementation.
  optional uint64 maximum_file_size = 7;

  // The minimum number of bits needed to represent, as a signed integer value,
  // the maximum size of a regular file
  // allowed in the volume.
  //
  // The maximum file size is `2^(maximumFileSizeInBits - 1)`.
  //
  // | Maximum file size (bytes)  | Maximum (in hex)     | Unsigned bits | Signed bits |
  // | -------------------------: | -------------------: | ------------: | ----------: |
  // |                     65,535 |             `0xFFFF` |            16 |          17 |
  // |              2,147,483,647 |         `0x7FFFFFFF` |            31 |          32 |
  // |              4,294,967,295 |         `0xFFFFFFFF` |            32 |          33 |
  // | 18,446,744,073,709,551,615 | `0xFFFFFFFFFFFFFFFF` |            64 |          65 |
  //
  // Implement at least one of ``maximumFileSize`` or `maximumFileSizeInBits`.
  // FSKit automatically converts from one to another if needed.
  // If you implement both, FSKit uses only the `maximumFileSizeInBits`
  // implementation.
  optional int64 maximum_file_size_in_bits = 8;
}

// Properties that represent capabilities supported by a volume, such as hard
// and symbolic links, journaling, and large file sizes.
message SupportedCapabilities {
  // An enumeration of case-sensitivity support types.
  //
  // A case-sensitive volume is a volume that treats upper and lower case
  // characters in file and directory names as being distinct from each other.
  // For example, `FILE.TXT` and `file.TXT` are different names in
  // a case-sensitive volume, and the same name in a case-insensitive volume.
  enum CaseFormat {
    // The volume is case sensitive.
    SENSITIVE = 0;

    // The volume isn't case sensitive.
    INSENSITIVE = 1;

    // The volume isn't case sensitive, but supports preserving the case of file and
    // directory names.
    INSENSITIVE_CASE_PRESERVING = 2;
  }

  // A Boolean property that indicates whether the volume supports persistent
  // object identifiers and can look up file system objects by their IDs.
  optional bool supports_persistent_object_ids = 1;

  // A Boolean property that indicates whether the volume supports symbolic links.
  optional bool supports_symbolic_links = 2;

  // A Boolean property that indicates whether the volume supports hard links.
  optional bool supports_hard_links = 3;

  // A Boolean property that indicates whether the volume supports a journal used
  // to speed recovery in case of unplanned restart, such as a power outage or crash.
  //
  // This property doesn't necessarily mean the volume is actively using
  // a journal.
  optional bool supports_journal = 4;

  // A Boolean property that indicates whether the volume currently uses a journal
  // for speeding recovery after an unplanned shutdown.
  optional bool supports_active_journal = 5;

  // A Boolean property that indicates the volume doesn't store reliable times for
  // the root directory.
  //
  // If this value is `true`, the volume doesn't store reliable times for the root
  // directory.
  optional bool does_not_support_root_times = 6;

  // A Boolean property that indicates whether the volume supports sparse files.
  //
  // A sparse file is a file that can have "holes" that the file system has never
  // written to, and as a result don't consume space on disk.
  optional bool supports_sparse_files = 7;

  // A Boolean property that indicates whether the volume supports zero runs
  //
  // If this value is true, the volume keeps track of allocated but unwritten runs
  // of a file so that it can substitute zeroes without actually writing
  // zeroes to the media.
  optional bool supports_zero_runs = 8;

  // A Boolean property that indicates whether the volume supports fast results
  // when fetching file system statistics.
  //
  // A true value means this volume hints to upper layers to indicate that
  // `statfs(2)` is fast enough that its results need not be cached by the caller.
  optional bool supports_fast_statfs = 9;

  // A Boolean property that indicates whether the volume supports file sizes
  // larger than 4GB, and potentially up to 2TB.
  optional bool supports_2tb_files = 10;

  // A Boolean property that indicates whether the volume supports open
  // deny modes.
  //
  // These are modes such as "open for read write, deny write".
  optional bool supports_open_deny_modes = 11;

  // A Boolean property that indicates whether the volume supports hidden files.
  //
  // A `true` value means the volume supports the `UF_HIDDEN` file flag.
  optional bool supports_hidden_files = 12;

  // A Boolean property that indicates the volume doesn't support certain volume
  // size reports.
  //
  // A true value means the volume doesn't support determining values for total
  // data blocks, available blocks, or free blocks, as in `f_blocks`, `f_bavail`,
  // and `f_bfree` in the struct `statFS` returned by `statfs(2)`.
  optional bool does_not_support_volume_sizes = 13;

  // A Boolean property that indicates whether the volume supports 64-bit
  // object IDs.
  optional bool supports_64bit_object_ids = 14;

  // A Boolean property that indicates whether the volume supports document IDs
  // for document revisions.
  //
  // A document ID is an identifier that persists across object ID changes.
  optional bool supports_document_id = 15;

  // A Boolean property that indicates the volume doesn't support immutable files.
  //
  // A `true` value means this volume doesn't support setting
  // the `UF_IMMUTABLE` flag.
  optional bool does_not_support_immutable_files = 16;

  // A Boolean property that indicates the volume doesn't set file permissions.
  //
  // If this value is `true`, the volume doesn't support setting file permissions.
  optional bool does_not_support_setting_file_permissions = 17;

  // A Boolean property that indicates whether the volume supports multiple
  // logical file systems that share space in a single "partition".
  optional bool supports_shared_space = 18;

  // A Boolean property that indicates whether the volume supports volume groups.
  //
  // Volume groups involve multiple logical file systems that the system can mount
  // and unmount together, and for which the system can present common file system
  // identifier information.
  optional bool supports_volume_groups = 19;

  // A value that indicates the volume's support for case sensitivity.
  optional CaseFormat case_format = 20;
}

// Properties used to report a volume's statistics.
//
// The names of this properties match those in the `statfs` structure in
// `statfs(2)`, which reports these values for an FSKit file system.
// All numeric properties default to `0`.
// Override these values, unless a given property has no meaningful value
// to provide.
//
// > Note: Available space, free space, total space, and used space have
// properties to express their values either as a number of blocks or
// a number of bytes.
// Your module may supply both of these values by setting both the relevant
// block or byte property.
// Alternatively, a module may set only one of the two properties.
// When you do this, FSKit calculates the matching value based on ``blockSize``.
//
// For the read-only ``fileSystemTypeName``, set this value with the designated
// initializer.
message StatFSResult {
  // A property for the volume's block size, in bytes.
  //
  // This value defaults to `4096`.
  // Zero isn't a valid block size.
  int64 block_size = 1;

  // A property for the optimal block size with which to perform I/O.
  //
  // For best performance, specify an `ioSize` that's an even multiple
  // of ``blockSize``.
  int64 io_size = 2;

  // A property for the volume's total data block count.
  uint64 total_blocks = 3;

  // A property for the number of free blocks available to a non-superuser
  // on the volume.
  uint64 available_blocks = 4;

  // A property for the number of free blocks in the volume.
  uint64 free_blocks = 5;

  // A property for the number of used blocks in the volume.
  uint64 used_blocks = 6;

  // A property for the total size, in bytes, of the volume.
  uint64 total_bytes = 7;

  // A property for the amount of space available to users, in bytes,
  // in the volume.
  uint64 available_bytes = 8;

  // A property for the amount of free space, in bytes, in the volume.
  uint64 free_bytes = 9;

  // A property for the amount of used space, in bytes, in the volume.
  uint64 used_bytes = 10;

  // A property for the total number of file slots in the volume,
  uint64 total_files = 11;

  // A property for the total number of free file slots in the volume.
  uint64 free_files = 12;
}

// Attributes of an item, such as size, creation and modification times,
// and user and group identifiers.
message ItemAttributes {
  // The user identifier.
  optional uint32 uid = 1;

  // The group identifier.
  optional uint32 gid = 2;

  // The mode of the item.
  //
  // The mode is often used for `setuid`, `setgid`, and `sticky` bits.
  optional uint32 mode = 3;

  // The item type, such as a regular file, directory, or symbolic link.
  optional ItemType type = 4;

  // The number of hard links to the item.
  optional uint32 link_count = 5;

  // The item's behavior flags.
  //
  // See `st_flags` in `stat.h` for flag definitions.
  optional uint32 flags = 6;

  // The item's size.
  optional uint64 size = 7;

  // The item's allocated size.
  optional uint64 alloc_size = 8;

  // The item's file identifier.
  // Reserved values: invalid = 0, parentOfRoot = 1, and rootDirectory = 2.
  optional uint64 file_id = 9;

  // The identifier of the item's parent.
  // Reserved values: invalid = 0, parentOfRoot = 1, and rootDirectory = 2.
  optional uint64 parent_id = 10;

  // A Boolean value that indicates whether the item supports a limited set
  // of extended attributes.
  optional bool supports_limited_xattrs = 11;

  // A Boolean value that indicates whether the file system overrides
  // the per-volume settings for kernel offloaded I/O for a specific file.
  //
  // This property has no meaning if the volume doesn't conform to
  // ``FSVolumeKernelOffloadedIOOperations``.
  optional bool inhibit_kernel_offloaded_io = 12;

  // The item's last-modified time.
  //
  // This property represents `mtime`, the last time the item's contents changed.
  optional google.protobuf.Timestamp modify_time = 13;

  // The item's added time.
  //
  // This property represents the time the file system added the item to its
  // parent directory.
  optional google.protobuf.Timestamp added_time = 14;

  // The item's last-changed time.
  //
  // This property represents `ctime`, the last time the item's metadata changed.
  optional google.protobuf.Timestamp change_time = 15;

  // The item's last-accessed time.
  optional google.protobuf.Timestamp access_time = 16;

  // The item's creation time.
  optional google.protobuf.Timestamp birth_time = 17;

  // The item's last-backup time.
  optional google.protobuf.Timestamp backup_time = 18;
}

// A distinct object in a file hierarchy, such as a file, directory, symlink,
// socket, and more.
message Item {
  // Attributes of an item, such as size, creation and modification times,
  // and user and group identifiers.
  ItemAttributes attributes = 1;

  // The name of a file, expressed as a data buffer.
  bytes name = 2;
}

// An object used to provide items during a directory enumeration.
message DirectoryEntries {
  // An object used to provide item during a directory enumeration.
  message Entry {
    // A distinct object in a file hierarchy, such as a file, directory, symlink,
    // socket, and more.
    Item item = 1;

    // A value to indicate the next entry in the directory to enumerate.
    uint64 next_cookie = 2;
  }

  // List of entries.
  repeated Entry entries = 1;

  // A tool to detect whether the directory contents changed since the last call
  // to `enumerateDirectory`.
  uint64 verifier = 2;
}

// Extended attributes.
message Xattrs {
  // The list of extended attribute names.
  repeated bytes names = 1;
}

// Successful result.
message Success {}

// Response envelope for communication.
message Response {
  // Correlates this response with the original request.
  uint64 request_id = 1;

  // The concrete result payload for the handled request.
  oneof content {
    ResourceIdentifier resource_identifier = 10;
    VolumeIdentifier volume_identifier = 11;
    VolumeBehavior volume_behavior = 12;
    PathConfOperations path_conf_operations = 13;
    SupportedCapabilities supported_capabilities = 14;
    StatFSResult stat_fs_result = 15;
    ItemAttributes item_attributes = 16;
    Item item = 17;
    DirectoryEntries directory_entries = 18;
    Xattrs xattrs = 19;
    bytes data = 20;
    int64 byte_count = 21;
    bool allow = 22;
    Success success = 23;
    int32 posix_error = 24;
  }
}