internal/gomote/protos/gomote.proto

// Copyright 2021 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

syntax = "proto3";

package protos;

option go_package = "golang.org/x/build/internal/gomote/protos";

// GomoteService can manage the lifecycle of gomote instances and interact with them.
service GomoteService {
  // Authenticate provides authentication information without any additional action.
  rpc Authenticate (AuthenticateRequest) returns (AuthenticateResponse) {}
  // AddBootstrap adds the bootstrap version of Go to the work directory.
  rpc AddBootstrap (AddBootstrapRequest) returns (AddBootstrapResponse) {}
  // CreateInstance creates a gomote instance.
  rpc CreateInstance (CreateInstanceRequest) returns (stream CreateInstanceResponse) {}
  // DestroyInstance destroys a gomote instance.
  rpc DestroyInstance (DestroyInstanceRequest) returns (DestroyInstanceResponse) {}
  // ExecuteCommand executes a command on the gomote instance.
  rpc ExecuteCommand (ExecuteCommandRequest) returns (stream ExecuteCommandResponse) {}
  // InstanceAlive gives the liveness state of a gomote instance.
  rpc InstanceAlive (InstanceAliveRequest) returns (InstanceAliveResponse) {}
  // ListDirectory lists the contents of a directory on an gomote instance.
  rpc ListDirectory (ListDirectoryRequest) returns (ListDirectoryResponse) {}
  // ListDirectoryStreaming lists the contents of a directory on an gomote instance.
  rpc ListDirectoryStreaming (ListDirectoryRequest) returns (stream ListDirectoryResponse) {}
  // ListInstances lists all of the live gomote instances owned by the caller.
  rpc ListInstances (ListInstancesRequest) returns (ListInstancesResponse) {}
  // ListSwarmingBuilders lists all of the swarming builders for the project.
  rpc ListSwarmingBuilders (ListSwarmingBuildersRequest) returns (ListSwarmingBuildersResponse) {}
  // ReadTGZToURL tars and zips a directory which exists on the gomote instance and returns a URL where it can be
  // downloaded from.
  rpc ReadTGZToURL (ReadTGZToURLRequest) returns (ReadTGZToURLResponse) {}
  // RemoveFiles removes files or directories from the gomote instance.
  rpc RemoveFiles (RemoveFilesRequest) returns (RemoveFilesResponse) {}
  // SignSSHKey signs an SSH public key which can be used to SSH into instances owned by the caller.
  rpc SignSSHKey (SignSSHKeyRequest) returns (SignSSHKeyResponse) {}
  // UploadFile generates a signed URL and associated fields to be used when uploading the object to GCS. Once uploaded
  // the corresponding Write endpoint can be used to send the file to the gomote instance.
  rpc UploadFile (UploadFileRequest) returns (UploadFileResponse) {}
  // WriteFileFromURL
  rpc WriteFileFromURL (WriteFileFromURLRequest) returns (WriteFileFromURLResponse) {}
  // WriteTGZFromURL retrieves a tar and zipped file from a URL and expands it onto the file system of a gomote instance.
  rpc WriteTGZFromURL (WriteTGZFromURLRequest) returns (WriteTGZFromURLResponse) {}
}

// AuthenticateRequest specifies the data needed for an authentication request.
message AuthenticateRequest {}

// AuthenticateResponse contains authenticated user data.
message AuthenticateResponse {}

// AddBootstrapRequest specifies the data needed for a request to add the bootstrap version of Go
// to the instance.
message AddBootstrapRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
}

// AddBootstrapResponse contains the information about the add bootstrap request.
message AddBootstrapResponse {
  // The URL for the Go version added to the work directory.
  // If empty, the bootstrap version is undefined and has probably been included in
  // the instance image.
  string bootstrap_go_url = 1;
}

// CreateInstanceRequest specifies the data needed to create a gomote instance.
message CreateInstanceRequest {
  string builder_type = 1;
  repeated string experiment_option = 2;
}

// CreateInstanceResponse contains data about a created gomote instance.
message CreateInstanceResponse {
  // Instance information for the requested instance.
  Instance instance = 1;
  enum Status {
    UNKNOWN = 0;
    WAITING = 1;
    COMPLETE = 2;
  }
  // The status for the requested create.
  Status status = 2;
  // Waiters ahead is the count of how many instances are being scheduled for
  // creation before the current instance creation request.
  int64 waiters_ahead = 3;
}

// DestroyInstanceRequest specifies the data needed to destroy a gomote instance.
message DestroyInstanceRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
}

// DestroyInstanceResponse contains data about a destroyed gomote instance.
message DestroyInstanceResponse {}

// ExecuteCommandRequest specifies the data needed to execute a command on a gomote instance.
message ExecuteCommandRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // The command to be executed on the buildlet.
  string command = 2;
  // Controls whether the command is run outside of the buildlet's environment.
  bool system_level = 3;
  // Debug will instruct the buildlet to include extra debugging information in the output.
  bool debug = 4;
  // These are additional environmental variables to include in the buildlet's process's
  // environment.
  repeated string append_environment = 5;
  // Path specifies the PATH variable of the executed procesess's environment.
  // A non-nil entry will clear the existing PATH value.
  // The string "$PATH" expands to any existing PATH element(s).
  // The substring "$WORKDIR" expands to buildlet's temp workdir.
  repeated string path = 6;
  // The directory from which to execute the command.
  // If not specified, it defaults to the directory of the command or the
  // work directory if system level is set.
  string directory = 7;
  // The arguments to pass to the command.
  repeated string args = 8;
  // Optional alternate builder to act like. It must be a compatible builder.
  string imitate_host_type = 9;
}

// ExecuteCommandResponse contains data about the executed command.
message ExecuteCommandResponse {
  // The output from the executed command.
  bytes output = 1;
}

// Instance contains descriptive information about a gomote instance.
message Instance {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // Builder type for the gomote instance.
  string builder_type = 2;
  // Host type for the gomote instance.
  string host_type = 3;
  // The timestamp for when the builder instance will expire. It is
  // represented in Unix epoch time format.
  int64 expires = 4;
  // The working directory of the instance.
  string working_dir = 5;
}

// InstanceAliveRequest specifies the data needed to check the liveness of a gomote instance.
message InstanceAliveRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
}

// InstanceAliveResponse contains instance liveness state.
message InstanceAliveResponse {}

// ListDirectoryRequest specifies the data needed to list contents of a directory from a gomote instance.
message ListDirectoryRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // The directory to list the contents of. The directory dir itself is not included.
  string directory = 2;
  // Controls whether the directory is listed recursively.
  bool recursive = 3;
  // The directories to skip, relative to the main directory.
  // Each item should contain only forward slashes and not start or end in slashes.
  repeated string skip_files = 4;
  // Controls whether the SHA-1 of regular files are returned.
  bool digest = 5;
}

// ListDirectoryResponse contains the directory listing of a gomote instance.
message ListDirectoryResponse {
  // The directory entries.
  repeated string entries = 1;
}

// ListInstancesRequest specifies the data needed to list the live gomote instances owned by the caller.
message ListInstancesRequest {}

// ListInstancesResponse contains the list of live gomote instances owned by the caller.
message ListInstancesResponse {
  repeated Instance instances = 1;
}

// ListSwarmingBuildersRequest specifies the data needed to list all swarming builders.
message ListSwarmingBuildersRequest {}

// ListSwarmingBuildersResponse contains a list of swarming builders.
message ListSwarmingBuildersResponse {
  repeated string builders = 1;
}

// ReadTGZToURLRequest specifies the data needed to retrieve a tar and zipped directory from a gomote instance.
message ReadTGZToURLRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // The relative directory from the gomote's work directory to tar up.
  string directory = 2;
}

// ReadTGZToURLResponse contains a URL where the tar and zipped directory from a gomote instance can be downloaded from.
message ReadTGZToURLResponse {
  // URL to retrieve the tarball from.
  string url = 1;
}

// RemoveFilesRequest specifies the data needed to remove files or directories from a gomote instance.
message RemoveFilesRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // The list of paths for files or directories to remove from the file system.
  // When everything should be deleted, "." should be used.
  // The paths are relative to the work directory.
  repeated string paths = 2;
}

// RemoveFilesResponse contains the results from removing files or directories from a gomote instance.
message RemoveFilesResponse {}

// SignSSHKeyRequest specifies the data needed to sign a public SSH key which attaches a certificate to the key.
message SignSSHKeyRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // A user provided public SSH key which the user intends to initiate an SSH session with.
  bytes public_ssh_key = 2;
}

// SignSSHKeyResponse contains the results from a request to sign a public SSH key.
message SignSSHKeyResponse {
  // A signed SSH key can be used in conjunction with the associated private key to initiate an SSH session to a gomote instance.
  // The certificate attached to the key will contain principles which restrict the instance that can be logged into.
  bytes signed_public_ssh_key = 1;
}

// UploadFileRequest specifies the data needed to create a request to upload an object to GCS.
message UploadFileRequest {}

// UploadFileResponse contains the results from a request to upload an object to GCS.
message UploadFileResponse {
  // URL to post file to.
  string url = 1;
  // Form fields used when http posting files to GCS.
  map<string, string> fields = 2;
  // Name used to reference the object.
  string object_name = 3;
}

// WriteFileFromURLRequest specifies the data needed to request that a gomote download the contents of a URL and place
// the contents in a file.
message WriteFileFromURLRequest {
  // The unique identifier for a gomote instance.
  string gomote_id = 1;
  // URL to post get file from.
  string url = 2;
  // The filename as it should appear at the destination.
  string filename = 3;
  // The file mode.
  fixed32 mode = 4;
}

// WriteFileFromURLResponse contains the results from requesting that a file be downloaded onto a gomote instance.
message WriteFileFromURLResponse {}

// WriteTGZFromURLRequest specifies the data needed to retrieve a file and expand it onto the file system of a gomote instance.
// It instructs the buildlet to download the tar.gz file from the url and write it to a directory, a relative directory from the workdir.
// If the directory is empty, they're placed at the root of the buildlet's work directory.
// The directory is created if necessary.
// The url must be of a tar.gz file.
message WriteTGZFromURLRequest {
  string gomote_id = 1;
  string url = 2;
  string directory = 3;
}

// WriteTGZFromURLResponse contains the results from retrieving a file and expanding it onto the file system of a gomote instance.
message WriteTGZFromURLResponse {}