tvl-depot/tvix/proto/evaluator.proto
Vincent Ambo 8c2084d0a1 feat(tvix/proto): Add evaluator communication proto
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>
2021-05-08 22:50:34 +00:00

144 lines
3.7 KiB
Protocol Buffer

// 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;
}
}