docs(tvix/proto/castore.proto): add comments

Change-Id: Ie5438cc6b6d4c63fc05236a2f0f900c92b5a4a7d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7128
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>
This commit is contained in:
Florian Klink 2022-10-28 16:26:21 +02:00 committed by flokli
parent 76d7671c8a
commit 442384f6e5

View file

@ -5,26 +5,51 @@ syntax = "proto3";
package fossil.store; package fossil.store;
// A Directory can contain Directory, File or Link nodes.
// Each of these nodes have a name attribute, which is the basename in that directory
// and node type specific attributes.
// The name attribute:
// - may not contain slashes or null bytes
// - needs to be unique across all three lists
// Elements in each list need to be lexicographically ordered by the name
// attribute.
message Directory { message Directory {
repeated DirectoryNode directories = 1; repeated DirectoryNode directories = 1;
repeated FileNode files = 2; repeated FileNode files = 2;
repeated LinkNode links = 3; repeated LinkNode links = 3;
} }
// A DirectoryNode represents a directory in a Directory.
message DirectoryNode { message DirectoryNode {
// The (base)name of the directory
string name = 1; string name = 1;
// The blake3 hash of a Directory message, serialized in protobuf canonical form.
bytes ref = 2; bytes ref = 2;
// Number of child elements in the Directory referred to by ref.
// Calculated by summing up the numbers of `directories`, `files` and `links`,
// and for each directory, its size field. Used for inode number calculation
// TODO(flokli): These numbers can't really be verified until you know the whole graph.
// Is this a problem? Should we instead only have this field
// in our local representation?
uint32 size = 3; uint32 size = 3;
} }
// A FileNode represents a regular or executable file in a Directory.
message FileNode { message FileNode {
// The (base)name of the file
string name = 1; string name = 1;
// The blake3 hash of the file contents
bytes ref = 2; bytes ref = 2;
// The file content size
uint32 size = 3; uint32 size = 3;
// Whether the file is executable
bool executable = 4; bool executable = 4;
} }
// A LinkNode represents a symbolic link in a Directory.
message LinkNode { message LinkNode {
// The (base)name of the symlink
string name = 1; string name = 1;
// The target of the symlink.
string target = 2; string target = 2;
} }