github.com/creachadair/ffs@v0.17.3/file/wiretype/wiretype.proto

// Copyright 2021 Michael J. Fromberger. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// This schema defines the encoding types for the ffs package.
syntax = "proto3";

package ffs.file;
option go_package = "github.com/creachadair/ffs/file/wiretype";

import "index/indexpb/index.proto";

// An Object is the top-level wrapper for encoded objects.
message Object {
  oneof value {
    Node node = 1;              // a structured file object
    Root root = 2;              // a root pointer
    ffs.index.Index index = 3;  // a blob index
  }

  // next id: 4

  // A version marker for the stored object.
  // Currently 0 is the only known value.
  uint64 version = 15;
}

// A Root records the location of a root node of a file tree.
message Root {
  // The storage key of the root of the tree.
  // The blob contains an Object holding a Node message.
  // This field must be non-empty for a root to be valid.
  bytes file_key = 1;

  // A human-readable descriptive label for the root.
  string description = 2;

  // The storage key of a blob index for the root.
  // The blob contains a Object holding an ffs.index.Index message.
  bytes index_key = 4;

  // The storage key of a previous version of this root.  The file_key and
  // index_key of the chained root, if any, are considered reachable from this
  // root.
  bytes chain_key = 6;

  // next id: 7

  reserved 3;  // was: owner_key
  reserved 5;  // was: predecessor
}

// A Node is the top-level encoding of a file.
message Node {
  Index index = 1;              // file contents
  Stat stat = 2;                // stat metadata (optional)
  repeated XAttr x_attrs = 3;   // extended attributes
  repeated Child children = 4;  // child file pointers

  // next id: 5
}

// Stat records POSIX style file metadata. Other than the modification time,
// these metadata are not interpreted by the file plumbing, but are preserved
// for the benefit of external tools.
message Stat {
  // The low-order 12 bits of this field hold the standard Unix permissions,
  // along with the sticky, setuid, and setgid bits. The rest are reserved and
  // must be set to zero. In binary:
  //
  //             owner group other
  //  ... +-+-+-+-----+-----+-----+   S: setuid
  //      |S|G|T|r w x|r w x|r w x|   G: setgid
  //  ... +-+-+-+-----+-----+-----+   T: sticky
  //       B A 9     6     3     0  « bit
  //
  uint32 permissions = 1;

  FileType file_type = 2;
  Timestamp mod_time = 3;
  Ident owner = 4;
  Ident group = 5;

  // An Ident represents the identity of a user or group.
  message Ident {
    uint64 id = 1;    // numeric ID
    string name = 2;  // human-readable name
  }

  // A FileType abstracts the type of a file.
  enum FileType {
    REGULAR = 0;      // a regular file
    DIRECTORY = 1;    // a directory
    SYMLINK = 2;      // a symbolic link
    SOCKET = 3;       // a Unix-domain socket
    NAMED_PIPE = 4;   // a named pipe
    DEVICE = 5;       // a (block) device file
    CHAR_DEVICE = 6;  // a (character) device file
    UNKNOWN = 404;    // nothing is known about the type of this file
  }
  // next id: 6
}

// Time is the encoding of a timestamp, in seconds and nanoseconds elapsed
// since the Unix epoch in UTC.
message Timestamp {
  uint64 seconds = 1;
  uint32 nanos = 2;
}

// An Index records the size and storage locations of file data.
message Index {
  uint64 total_bytes = 1;

  // File contents are split into blocks, which are in turn grouped into
  // contiguous extents. However, for the common case of small files that have
  // only one block, the index may instead store the key of that one block
  // without the overhead of extent metadata.
  //
  // At most one of these fields may be non-empty. We do not use a oneof here
  // because oneof does not allow repeated fields, and we don't want to spend
  // storage on a wrapper message.

  repeated Extent extents = 2;  // multiple blocks
  bytes single = 3;             // a single block

  // next id: 4
}

// An Extent describes a single contiguous span of stored data.
message Extent {
  uint64 base = 1;   // the starting offset
  uint64 bytes = 2;  // the number of bytes in this extent
  repeated Block blocks = 3;

  // next id: 4
}

// A Block describes the size and storage key of a data blob.
message Block {
  uint64 bytes = 1;  // the number of bytes in this block
  bytes key = 2;     // the storage key of the block data

  // next id: 3
}

// An XAttr records the name and value of an extended attribute.
// The contents of the value are not interpreted.
message XAttr {
  string name = 1;
  bytes value = 2;

  // next id: 3
}

// A Child records the name and storage key of a child Node.
message Child {
  string name = 1;
  bytes key = 2;

  // next id: 3
}