about summary refs log tree commit diff
path: root/tvix/proto
diff options
context:
space:
mode:
authorFlorian Klink <flokli@flokli.de>2022-10-28T14·26+0200
committerflokli <flokli@flokli.de>2022-11-08T17·57+0000
commit442384f6e52abd454733068c945e06a16b97a655 (patch)
treebdc5cceecc23dd0be68e17fd6838c64e6feac1fa /tvix/proto
parent76d7671c8a7fa624947e3523d635f0608aae2d07 (diff)
docs(tvix/proto/castore.proto): add comments r/5270
Change-Id: Ie5438cc6b6d4c63fc05236a2f0f900c92b5a4a7d
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7128
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>
Diffstat (limited to 'tvix/proto')
-rw-r--r--tvix/proto/castore.proto25
1 files changed, 25 insertions, 0 deletions
diff --git a/tvix/proto/castore.proto b/tvix/proto/castore.proto
index f9cffc3ebed9..b479595820fb 100644
--- a/tvix/proto/castore.proto
+++ b/tvix/proto/castore.proto
@@ -5,26 +5,51 @@ syntax = "proto3";
 
 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 {
     repeated DirectoryNode directories = 1;
     repeated FileNode files = 2;
     repeated LinkNode links = 3;
 }
 
+// A DirectoryNode represents a directory in a Directory.
 message DirectoryNode {
+    // The (base)name of the directory
     string name = 1;
+    // The blake3 hash of a Directory message, serialized in protobuf canonical form.
     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;
 }
 
+// A FileNode represents a regular or executable file in a Directory.
 message FileNode {
+    // The (base)name of the file
     string name = 1;
+    // The blake3 hash of the file contents
     bytes ref = 2;
+    // The file content size
     uint32 size = 3;
+    // Whether the file is executable
     bool executable = 4;
 }
 
+// A LinkNode represents a symbolic link in a Directory.
 message LinkNode {
+    // The (base)name of the symlink
     string name = 1;
+    // The target of the symlink.
     string target = 2;
 }