Something went wrong. Try again.
A user-space CRDT filesystem
Something went wrong. Try again.
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319/* 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; }}