blob: 1de9c708a511e6c79e6d62eb585f9a1bb567d94b [file] [log] [blame]
// Copyright 2018 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.
// This proto file describes the external scheduler plugin API.
syntax = "proto3";
package swarming.v1;
option go_package = ";pluginpb";
import "google/protobuf/timestamp.proto";
// TaskSpec describes a task request and its state, for the purposes of the
// external scheduler API.
// It intentionally elides aspects of a task request that are irrelevant
// to scheduling decisions, to keep this proto small for performance reasons.
// This message format is in its early stages, and may be subject to frequent
// or even breaking changes as the external scheduler API is rolled out.
message TaskSpec {
// Represents the 5 different categories of task state.
enum StateCategory {
// Invalid value.
// Bit mask for the State inside each category.
// The task is enqueued and pending bot availability.
// The task is running.
// Transient done states are uncertain states.
// The task ran, and it is done.
// The task did not run, and won't.
// Represents the different possible states for a TaskSpec.
enum State {
// Invalid task state.
// The task is currently pending.
PENDING = 0x10;
// Unused.
// The task is currently running.
RUNNING = 0x20;
// Unused.
// Unused.
// Unused.
// Unused.
// The task ran but the bot had an internal failure.
// Unused.
// Unused.
// Unused.
// The task ran and completed normally.
// The task ran for longer than the allowed time.
TIMED_OUT = 0x41;
// Unused.
// The task ran but was manually killed via the 'cancel' API.
KILLED = 0x43;
// Unused.
// The task didn't have to run, because a previous task had results.
DEDUPED = 0x50;
// The task is not pending anymore; it never ran due to lack of capacity.
EXPIRED = 0x51;
// The task never ran, and was manually cancelled via the 'cancel' API.
CANCELED = 0x52;
// The task was never set to PENDING and was immediately refused.
// Unused.
LOAD_SHED = 0x54;
// Unused.
// Unused.
// The task encountered an error caused by the client.
// Id is the swarming task request ID.
// Other than being a unique string to track the lifecycle of this request,
// it is opaque to external scheduler. By convention, swarming uses a task's
// summary ID (trailing '0') here, not the run ID.
string id = 1;
// Tags is the list of tags applied to this task request.
repeated string tags = 2;
// Slices is the set of task slices for this spec. A TaskSpec must contain
// at least 1 slice.
repeated SliceSpec slices = 3;
// State is the current state of this task.
State state = 4;
// BotID is the id of the bot that this task is running on. It is only
// valid if state=RUNNING.
string bot_id = 5;
// EnqueuedTime is the time at which a task was enqueued. It is only valid
// if state=PENDING.
google.protobuf.Timestamp enqueued_time = 6;
// SliceSpec describes a task request slice, for the purposes of TaskSpec.
message SliceSpec {
// Dimensions is set dimension strings for this slice.
repeated string dimensions = 1;
message IdleBot {
// BotId is the id of the bot that is idle.
string bot_id = 1;
// Dimensions is the dimension set of the idle bot.
repeated string dimensions = 2;
// API Request/Response types.
message AssignTasksRequest {
// SchedulerID is the id of the scheduler that this request should be run on.
string scheduler_id = 1;
// IdleBots is the set of idle bots that are trying to get tasks assigned.
repeated IdleBot idle_bots = 2;
// Time is the current time (according to swarming) at which these bots
// are attempting to have tasks assigned to them.
google.protobuf.Timestamp time = 3;
message AssignTasksResponse {
// Assignments is the set of (bot, task) assignments that the scheduler
// determined should be made.
repeated TaskAssignment assignments = 1;
message TaskAssignment {
// BotID is the bot that should be assigned a task.
string bot_id = 1;
// TaskID is the task that should be assigned to the bot.
string task_id = 2;
// SliceNumber is the slice within the task that should be assigned to the bot.
// If absent, slice 0 will be assumed.
int32 slice_number = 3;
message GetCancellationsRequest {
// SchedulerID is the id of the scheduler that this request should be run on.
string scheduler_id = 1;
message GetCancellationsResponse {
message Cancellation {
// BotID is the bot that a task should be cancelled on.
string bot_id = 1;
// TaskID is the task that should be cancelled on the bot.
string task_id = 2;
enum Reason {
// Invalid reason, do not use.
// Task was running on a worker, but was interrupted by another task.
// Task may be retried by swarming.
// Task had invalid or erroneous properties that make it not handleable
// by scheduler. Task should not be retried.
ERROR = 2;
// Reason is the reason the task was cancelled.
Reason reason = 3;
// ExtraInfo is optional, human readable extra information about why the
// task was cancelled.
string extra_info = 4;
// Cancellations is the set of (bot, task) pairs for tasks that should be
// cancelled on bots.
repeated Cancellation cancellations = 1;
message NotifyTasksItem {
// Time is the time at which the given task was in the given state.
google.protobuf.Timestamp time = 1;
// Task describes a task request and its current state.
TaskSpec task = 2;
message NotifyTasksRequest {
// SchedulerID is the id of the scheduler that this request should be run on.
string scheduler_id = 1;
// Notifications is the set of task notifications to send to the scheduler.
repeated NotifyTasksItem notifications = 2;
// IsCallback specifies whether these notifications are in response to
// updates that were requested by a previous GetCallbacks call.
// This is for diagnostic purposes only.
bool is_callback = 3;
message NotifyTasksResponse {}
message GetCallbacksRequest {
// SchedulerID is the id of the scheduler that this request should be run on.
string scheduler_id = 1;
message GetCallbacksResponse {
// TaskIds is the list of tasks that the external scheduler would like
// callback notifications about.
repeated string task_ids = 1;
// Service definition.
// ExternalScheduler is the API by which swarming can delegate the assigning of
// individuals task requests to individual bots to an external service.
service ExternalScheduler {
// Swarming-scheduler plugin endpoints.
// AssignTasks determines which tasks should be run on which of the supplied
// idle bots.
rpc AssignTasks(AssignTasksRequest) returns (AssignTasksResponse);
// GetCancellations determines which tasks should be cancelled on which bots.
rpc GetCancellations(GetCancellationsRequest) returns (GetCancellationsResponse);
// NotifyTasks informs the scheduler about the state of tasks (either new
// tasks, or states of existing tasks).
rpc NotifyTasks(NotifyTasksRequest) returns (NotifyTasksResponse);
// GetCallbacks asks the scheduler for a set of request ids that the
// external scheduler wants to receive callback NotifyTasks calls about.
rpc GetCallbacks(GetCallbacksRequest) returns (GetCallbacksResponse);