path: root/third_party/nix/src/proto/worker.proto

syntax = "proto3";

import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

package nix.proto;

// Service representing a worker used for building and interfacing
// with the Nix store.
service Worker {
  // Validates whether the supplied path is a valid store path.
  rpc IsValidPath(StorePath) returns (IsValidPathResponse);

  // Checks whether any substitutes exist for the given path.
  rpc HasSubstitutes(StorePath) returns (HasSubstitutesResponse);

  // Query referrers for a given path.
  rpc QueryReferrers(StorePath) returns (StorePaths);

  // Add a NAR (I think?) to the store. The first stream request
  // should be a message indicating metadata, the rest should be file
  // chunks.
  rpc AddToStore(stream AddToStoreRequest) returns (StorePath);

  // Adds the supplied string to the store, as a text file.
  rpc AddTextToStore(AddTextToStoreRequest) returns (StorePath);

  // Build the specified derivations in one of the specified build
  // modes, defaulting to a normal build.
  rpc BuildPaths(BuildPathsRequest) returns (google.protobuf.Empty);

  // TODO: What does this do?
  rpc EnsurePath(StorePath) returns (google.protobuf.Empty);

  // TODO: What does this do?
  rpc AddTempRoot(StorePath) returns (google.protobuf.Empty);

  // TODO: What does this do?
  rpc AddIndirectRoot(StorePath) returns (google.protobuf.Empty);

  // TODO: What does this do?
  rpc SyncWithGC(google.protobuf.Empty) returns (google.protobuf.Empty);

  // TODO: What does this do?
  rpc FindRoots(google.protobuf.Empty) returns (FindRootsResponse);

  // TODO: What does this do?
  rpc SetOptions(SetOptionsRequest) returns (google.protobuf.Empty);

  // Ask the store to perform a garbage collection, based on the
  // specified parameters. See `GCAction` for the possible actions.
  rpc CollectGarbage(CollectGarbageRequest) returns (CollectGarbageResponse);

  // TODO: What does this do?
  rpc QuerySubstitutablePathInfos(StorePaths) returns (SubstitutablePathInfos);

  // TODO: What does this do?
  rpc QueryDerivationOutputs(StorePath) returns (StorePaths);

  // Query all valid paths in the store
  rpc QueryAllValidPaths(google.protobuf.Empty) returns (StorePaths);

  // TODO: What does this do?
  rpc QueryPathInfo(StorePath) returns (QueryPathInfoResponse);

  // Query the output names of the given derivation
  rpc QueryDerivationOutputNames(StorePath) returns (DerivationOutputNames);

  // TODO: What is a HashPart?
  rpc QueryPathFromHashPart(HashPart) returns (StorePath);

  // Query which of the given paths is valid.
  rpc QueryValidPaths(StorePaths) returns (StorePaths);

  // Query which of the given paths have substitutes.
  rpc QuerySubstitutablePaths(StorePaths) returns (StorePaths);

  // Return all currently valid derivations that have the given store path as an
  // output.
  rpc QueryValidDerivers(StorePath) returns (StorePaths);
}

enum HashType {
  UNKNOWN = 0;
  MD5 = 1;  // TODO(tazjin): still needed?
  SHA1 = 2;
  SHA256 = 3;
  SHA512 = 4;
}

enum BuildMode {
  Normal = 0;
  Repair = 1;
  Check = 2;
}

enum GCAction {
  // Return the set of paths reachable from (i.e. in the closure of)
  // the roots.
  ReturnLive = 0;

  // Return the set of paths not reachable from the roots.
  ReturnDead = 1;

  // Actually delete the latter set.
  DeleteDead = 2;

  // Delete the paths listed in `pathsToDelete', insofar as they are
  // not reachable.
  DeleteSpecific = 3;
}

// Generic type for any RPC call that just reads or returns a single
// store path.
message StorePath {
  string path = 1;
}

// Generic type for any RPC call that just reads or returns a list of
// store paths.
message StorePaths {
  repeated string paths = 1;
}

message IsValidPathResponse {
  bool is_valid = 1;
}

message HasSubstitutesResponse {
  bool has_substitutes = 1;
}

message AddToStoreRequest {
  message Metadata {
    bool fixed = 1;
    bool recursive = 2;  // TODO(tazjin): what is this? "obsolete" comment?
    HashType hash_type = 3;
    string base_name = 4;
  }

  message Chunk {
    bytes content = 1;
    bool final = 2;
  }

  oneof add_oneof {
    Metadata meta = 1;
    Chunk chunk = 2;
  }
}

message AddTextToStoreRequest {
  string name = 1;
  string content = 2;
  repeated string references = 3;
}

message BuildPathsRequest {
  repeated string drvs = 1;
  BuildMode mode = 2;
}

message FindRootsResponse {
  map<string, string> roots = 1;
}

message SetOptionsRequest {
  bool keep_failed = 1;
  bool keep_going = 2;
  bool try_fallback = 3;
  uint32 max_build_jobs = 4;
  uint32 verbose_build =
      5;                   // TODO(tazjin): Maybe this should be bool, unclear.
  uint32 build_cores = 6;  // TODO(tazjin): Difference from max_build_jobs?
  bool use_substitutes = 7;
  map<string, string> overrides = 8;  // TODO(tazjin): better name?
}

message CollectGarbageRequest {
  // GC action that should be performed.
  GCAction action = 1;

  // For `DeleteSpecific', the paths to delete.
  repeated string paths_to_delete = 2;

  // If `ignore_liveness' is set, then reachability from the roots is
  // ignored (dangerous!). However, the paths must still be
  // unreferenced *within* the store (i.e., there can be no other
  // store paths that depend on them).
  bool ignore_liveness = 3;

  // Stop after at least `max_freed' bytes have been freed.
  uint64 max_freed = 4;
}

message CollectGarbageResponse {
  // Depending on the action, the GC roots, or the paths that would be
  // or have been deleted.
  repeated string deleted_paths = 1;

  // For `ReturnDead', `DeleteDead' and `DeleteSpecific', the number
  // of bytes that would be or was freed.
  uint64 bytes_freed = 2;
}

message SubstitutablePathInfos {
  message PathInfo {
    string path = 1;
    string deriver = 2;
    uint64 download_size = 3;
    uint64 nar_size = 4;
    repeated string references = 5;
  }

  repeated PathInfo path_infos = 1;
}

message QueryPathInfoResponse {
  StorePath deriver = 1;
  string nar_hash = 2;
  repeated string references = 3;
  google.protobuf.Timestamp registration_time = 4;
  uint64 nar_size = 5;
  // Whether the path is ultimately trusted, that is, it's a derivation
  // output that was built locally.
  bool ultimate = 6;
  repeated string sigs = 7;
  // If non-empty, an assertion that the path is content-addressed
  string ca = 8;
};

message DerivationOutputNames {
  repeated string names = 1;
}

message HashPart {
  string hash_part = 1;
}