blob: ffe24d3bb32ba7e28a97b81b9abea20744c1063d [file] [log] [blame]
// 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) {}
// ListInstances lists all of the live gomote instances owned by the caller.
rpc ListInstances (ListInstancesRequest) returns (ListInstancesResponse) {}
// 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 {}
// CreateInstanceRequest specifies the data needed to create a gomote instance.
message CreateInstanceRequest {
string builder_type = 1;
}
// 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;
}
// 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;
}
// 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 {}