feat(tvix/proto): Add evaluator communication proto r/2574

This adds the proto messages and service definition used for
communicating with our evaluator.

Please refer to the `Tvix - Component interaction` document for a
detailed description of the interactions that this service is used
for.

Change-Id: If44cdbff66c6cfe88c22a748fe29c0bbd8510b0d
Co-Authored-By: Florian Klink <flokli@flokli.de>
Co-Authored-By: Adam Höse <adisbladis@gmail.com>
Reviewed-on: https://cl.tvl.fyi/c/depot/+/2685
Tested-by: BuildkiteCI
Reviewed-by: flokli <flokli@flokli.de>
Reviewed-by: grfn <grfn@gws.fyi>

1 files changed, 144 insertions, 0 deletions

diff --git a/tvix/proto/evaluator.proto b/tvix/proto/evaluator.proto
new file mode 100644
index 0000000000..710a28fb9d
--- /dev/null
+++ b/tvix/proto/evaluator.proto
@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: MIT
+// Copyright © 2021 The Tvix Authors
+syntax = "proto3";
+
+package tvix.proto.evaluator.v1;
+
+service EvaluatorService {
+  rpc Evaluate(stream EvaluateRequest) returns (stream EvaluateResponse) {}
+}
+
+//
+// Message types for EvaluateRequest
+//
+
+message EvaluateFile {
+  // Absolute path at which the evaluator can find the file to be
+  // evaluated.
+  string file_path = 1;
+
+  // Optional attribute that should be evaluated within the file,
+  // assuming that the value it evaluates to is an attribute set.
+  optional string attribute = 2;
+
+  // Additional arguments to pass into the evaluation, with which the
+  // file's top-level function will be auto-called.
+  map<string, NixValue> arguments = 3;
+}
+
+message EvaluateExpression {
+  // Literal Nix expression to evaluate.
+  string expression = 1;
+
+  // Working directory in which the expression should be evaluated.
+  string working_directory = 2;
+}
+
+message BuildResultChunk {
+  string drv_hash = 1;
+  string output = 2;
+  bytes data = 3;
+
+  // This field may be set on the first build result chunk returned
+  // to the evaluator, indicating the total size of the output that
+  // is going to be streamed in bytes.
+  //
+  // If set, the evaluator can use this to appropriately allocate a
+  // buffer for the output.
+  optional int64 output_size = 4;
+}
+
+// Indicates that a single build has completed successfully. In case
+// that the build outputs were required by the evaluator this also
+// indicates that the output has been returned completely.
+message BuildSuccess {
+  string drv_hash = 1;
+  string output = 2;
+}
+
+// Describes an error that occured during a single build.
+//
+// TODO: We might want a more sophisticated error type.
+message BuildError {
+  string drv_hash = 1;
+  string output = 2;
+  string error = 3;
+}
+
+message BuildResult {
+  oneof build_result {
+    BuildSuccess build_success = 1;
+    BuildError build_error = 2;
+  }
+}
+
+
+/// Messages sent to the evaluator by the build coordinator.
+message EvaluateRequest {
+  oneof message {
+    // Ask the evaluator to evaluate the specified file, and
+    // optionally attribute within that file. Must be the first
+    // message.
+    EvaluateFile evaluate_file = 1;
+
+    // Ask the evaluator to evaluate the specified Nix expression.
+    // Must be the first message.
+    EvaluateExpression evaluate_expression = 2;
+
+    // Send the chunks of a build result, in response to a
+    // BuildRequest.
+    //
+    // Note: This message might change as the store protocol is
+    // designed, as it is possible that mechanisms for transferring
+    // files might be reused between the protocols.
+    BuildResultChunk build_result_chunk = 3;
+
+    // Indicate the result of a single build. See the documentation
+    // for the message types defined above for semantic details.
+    BuildResult build_result = 4;
+  }
+}
+
+//
+// Message types for EvaluateResponse
+//
+
+// TODO: Placeholder type.
+message Derivation {
+  string drv = 1;
+}
+
+// TODO: Placeholder type.
+message NixValue {
+  string value = 1;
+}
+
+// TODO: Placeholder type.
+message NixError {
+  string value = 1;
+}
+
+message BuildRequest {
+  Derivation drv = 1;
+  string output = 2;
+}
+
+// Messages returned to the coordinator by the evaluator.
+message EvaluateResponse {
+  oneof message {
+    // A derivation that was instantiated while reducing the graph,
+    // and whose output is not required by the evaluator.
+    Derivation derivation = 1;
+
+    // A derivation that was instantiated while reducing the graph,
+    // and whose output is required by the evaluator (IFD).
+    BuildRequest build_request = 2;
+
+    // The final value yielded by the evaluation. Stream is closed
+    // after this.
+    NixValue done = 3;
+
+    // Evaluation error. Stream is closed after this.
+    NixError error = 4;
+  }
+}