about summary refs log tree commit diff
path: root/tvix/store/README.md
diff options
context:
space:
mode:
authorFlorian Klink <flokli@flokli.de>2022-11-26T21·16+0000
committerflokli <flokli@flokli.de>2022-12-26T11·38+0000
commite05e8bdd036ea0bd185a2234921f2fcfc146cd55 (patch)
tree2a5bea4e21a14b14eb9cd212b0a9af79ed3cc3d0 /tvix/store/README.md
parent2403871bed37958d4e90ad3893017ac1a2173555 (diff)
docs(tvix/store): add README, document services and store model r/5494
These are intended to help digest the protocol definitions for tvix-
store, and how they tie into the whole concept.

Co-Authored-By: Vincent Ambo <mail@tazj.in>
Change-Id: Ic1ba3ba41ef599209453f15d0ac2e07a6144bcca
Reviewed-on: https://cl.tvl.fyi/c/depot/+/7439
Tested-by: BuildkiteCI
Reviewed-by: tazjin <tazjin@tvl.su>
Diffstat (limited to 'tvix/store/README.md')
-rw-r--r--tvix/store/README.md59
1 files changed, 59 insertions, 0 deletions
diff --git a/tvix/store/README.md b/tvix/store/README.md
new file mode 100644
index 000000000000..7844264ca181
--- /dev/null
+++ b/tvix/store/README.md
@@ -0,0 +1,59 @@
+# //tvix/store
+
+This contains the code hosting the tvix-store.
+
+For the local store, Nix realizes files on the filesystem in `/nix/store` (and
+maintains some metadata in a SQLite database). For "remote stores", it
+communicates this metadata in NAR (Nix ARchive) and NARInfo format.
+
+Compared to the Nix model, `tvix-store` stores data on a much more granular
+level than that, which provides more deduplication possibilities, and more
+granular copying.
+
+However, enough information is preserved to still be able to render NAR and
+NARInfo (handled by `//tvix/nar-bridge`).
+
+## More Information
+Check the `protos/` subfolder for the definition of the exact RPC methods and
+messages.
+
+
+## Interacting with the GRPC service manually
+The shell environment in `//tvix` provides `evans`, which is an interactive
+REPL-based gPRC client.
+
+You can use it to connect to a `tvix-store` and call the various RPC methods.
+
+```shell
+$ cargo run &
+$ evans --host localhost --port 8000 -r repl
+  ______
+ |  ____|
+ | |__    __   __   __ _   _ __    ___
+ |  __|   \ \ / /  / _. | | '_ \  / __|
+ | |____   \ V /  | (_| | | | | | \__ \
+ |______|   \_/    \__,_| |_| |_| |___/
+
+ more expressive universal gRPC client
+
+
+tvix.store.v1@localhost:8000> service BlobService
+
+tvix.store.v1.BlobService@localhost:8000> call Put --bytes-from-file
+data (TYPE_BYTES) => /run/current-system/system
+{
+  "digest": "KOM3/IHEx7YfInAnlJpAElYezq0Sxn9fRz7xuClwNfA="
+}
+
+tvix.store.v1.BlobService@localhost:8000> call Get --bytes-as-base64
+digest (TYPE_BYTES) => KOM3/IHEx7YfInAnlJpAElYezq0Sxn9fRz7xuClwNfA=
+{
+  "data": "eDg2XzY0LWxpbnV4"
+}
+
+$ echo eDg2XzY0LWxpbnV4 | base64 -d
+x86_64-linux
+```
+
+Thanks to `tvix-store` providing gRPC Server Reflection (with `reflection`
+feature), you don't need to point `evans` to the `.proto` files.