Documentation
¶
Overview ¶
Package swarming contains the Swarming client.
It is a "fat" client that does extra things on top of just wrapping the server API.
Index ¶
- Constants
- Variables
- func GetMany(ctx context.Context, client Client, taskIDs []string, fields *TaskResultFields, ...)
- func GetOne(ctx context.Context, client Client, taskID string, fields *TaskResultFields, ...) (*swarmingv2.TaskResultResponse, error)
- type Client
- type ClientOptions
- type ResultOrErr
- type TaskResultFields
- type WaitMode
Constants ¶
const ( // ServerEnvVar is Swarming server host to which a client connects. ServerEnvVar = "SWARMING_SERVER" // TaskIDEnvVar is a Swarming task ID in which this task is running. // // The `swarming` command line tool uses this to populate `ParentTaskId` // when being used to trigger new tasks from within a swarming task. TaskIDEnvVar = "SWARMING_TASK_ID" // UserEnvVar is the OS user name (not Swarming specific). // // The `swarming` command line tool uses this to populate `User` // when being used to trigger new tasks. UserEnvVar = "USER" )
Variables ¶
var UserAgent = "swarming 0.5.0"
UserAgent identifies the version of the client.
It is sent in all RPCs.
Functions ¶
func GetMany ¶
func GetMany(ctx context.Context, client Client, taskIDs []string, fields *TaskResultFields, mode WaitMode, sink func(taskID string, res *swarmingv2.TaskResultResponse, err error))
GetMany queries status of all given tasks, optionally waiting for them to complete.
This is a variant of GetOne which uses batch RPCs to reduce overhead. It calls the callback with result of each task as soon as it is available. See GetOne doc for the semantics of values passed to the callback.
If `mode` NoWait, will fetch the current state of all tasks and pass them to the callback. If `mode` is WaitAny, will block until at least one task completes, and then pass states of all tasks to the callback. If `mode` is WaitAll, will block until all tasks complete, calling the callback whenever it detects any new completions.
The callback will always be called exactly `len(taskIDs)` times, once per each task, in undefined order. The callback should not block. If it needs to do further processing, it should do it asynchronously.
Retries on transient errors until the context expires.
Panics if `taskIDs` is empty or any of given task IDs is an empty string.
func GetOne ¶
func GetOne(ctx context.Context, client Client, taskID string, fields *TaskResultFields, mode WaitMode) (*swarmingv2.TaskResultResponse, error)
GetOne returns the status of a single task, optionally waiting for it to complete first.
If `mode` is NoWait, will just query the task status once, otherwise (if `mode` is WaitAny or WaitAll), will block until the task completes (successfully or not) or the context expires.
On success returns task's status and a nil error. If `mode` is NoWait, it might be a non-final status (i.e. PENDING or RUNNING). In other modes this will always be a final status.
Exits early if the context expires or if RPCs to Swarming fail with a fatal error code. Returns a non-nil error in this case. It will either be a gRPC error or a context error. If an error happened after the function fetched task's state at least once, returns the latest fetched state (which will be either PENDING or RUNNING) as well.
Retries on transient errors until the context expires.
Panics if `taskID` is an empty string.
Types ¶
type Client ¶
type Client interface {
Close(ctx context.Context)
NewTask(ctx context.Context, req *swarmingv2.NewTaskRequest) (*swarmingv2.TaskRequestMetadataResponse, error)
CountTasks(ctx context.Context, start float64, state swarmingv2.StateQuery, tags []string) (*swarmingv2.TasksCount, error)
ListTasks(ctx context.Context, limit int32, start float64, state swarmingv2.StateQuery, tags []string) ([]*swarmingv2.TaskResultResponse, error)
CancelTask(ctx context.Context, taskID string, killRunning bool) (*swarmingv2.CancelResponse, error)
CancelTasks(ctx context.Context, limit int32, tags []string, killRunning bool, start, end time.Time) (*swarmingv2.TasksCancelResponse, error)
TaskRequest(ctx context.Context, taskID string) (*swarmingv2.TaskRequestResponse, error)
TaskOutput(ctx context.Context, taskID string, out io.Writer) (swarmingv2.TaskState, error)
TaskResult(ctx context.Context, taskID string, fields *TaskResultFields) (*swarmingv2.TaskResultResponse, error)
TaskResults(ctx context.Context, taskIDs []string, fields *TaskResultFields) ([]ResultOrErr, error)
CountBots(ctx context.Context, dimensions []*swarmingv2.StringPair) (*swarmingv2.BotsCount, error)
ListBots(ctx context.Context, dimensions []*swarmingv2.StringPair) ([]*swarmingv2.BotInfo, error)
DeleteBot(ctx context.Context, botID string) (*swarmingv2.DeleteResponse, error)
TerminateBot(ctx context.Context, botID string, reason string) (*swarmingv2.TerminateResponse, error)
ListBotTasks(ctx context.Context, botID string, limit int32, start float64, state swarmingv2.StateQuery) ([]*swarmingv2.TaskResultResponse, error)
FilesFromCAS(ctx context.Context, outdir string, casRef *swarmingv2.CASReference) ([]string, error)
}
Client can make requests to Swarming, in particular launch tasks and wait for their execution to finish.
A client must be closed with Close when done working with it to avoid leaking goroutines.
type ClientOptions ¶
type ClientOptions struct {
// ServiceURL is root URL of the Swarming service.
//
// Required.
ServiceURL string
// RBEAddr is "host:port" of the RBE-CAS service to use.
//
// Default is the prod service.
RBEAddr string
// UserAgent is put into User-Agent HTTP header with each request.
//
// Default is UserAgent const.
UserAgent string
// Auth contains options for constructing authenticating clients.
//
// It is used only when AuthenticatedClient or RBEClientFactory are omitted.
Auth auth.Options
// AuthenticatedClient is http.Client that attaches authentication headers.
//
// Will be used when talking to the Swarming backend.
//
// Default is a client constructed using go.chromium.org/luci/auth based on
// the given Auth options.
AuthenticatedClient *http.Client
// RBEClientFactory can create RBE clients on demand.
//
// Will be used to fetch files from RBE-CAS.
//
// Default constructs a client using go.chromium.org/luci/auth based on
// the given Auth options. It calls LUCI Token Server to get per-instance RBE
// authentication tokens. This works only with LUCI RBE instances.
RBEClientFactory func(ctx context.Context, addr, instance string) (*rbeclient.Client, error)
}
ClientOptions is passed to NewClient.
type ResultOrErr ¶
type ResultOrErr struct {
Result *swarmingv2.TaskResultResponse
Err error
}
ResultOrErr is returned by TaskResults. It either carries a task result or an error if it could not be obtained.
type TaskResultFields ¶
type TaskResultFields struct {
WithPerf bool // if true, fetch internal performance stats
}
TaskResultFields defines what optional parts of TaskResultResponse to get.
Swarming doesn't support generic field masks yet, so this struct is kind of ad-hoc right now.
A nil value means to fetch the default set of fields.
type WaitMode ¶
type WaitMode int
WaitMode is passed to Get* functions and indicates how they should block.
const ( // NoWait means to fetch the current task status, do not wait for completion. NoWait WaitMode = 0 // WaitAny means to wait until at least one task completes and then return // the current state of all tasks: at least one of them will be completed, but // possibly more (if multiple tasks complete at the same time). WaitAny WaitMode = 1 // WaitAll means to wait until all tasks complete. WaitAll WaitMode = 2 )
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package swarmingtest contains Swarming client test helpers.
|
Package swarmingtest contains Swarming client test helpers. |