// Copyright 2021 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package buildbucket.v2;

import "google/protobuf/struct.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/field_option.proto";

option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb";

// A backend task.
// Next id: 9.
message Task {
  TaskID id = 1;

  // (optional) Human-clickable link to the status page for this task.
  // This should be populated as part of the Task response in RunTaskResponse.
  // Any update to this via the Task field in BuildTaskUpdate will override the
  // existing link that was provided in RunTaskResponse.
  string link = 2;

  // The backend's status for handling this task.
  Status status = 3;

  // The 'status_details' around handling this task.
  StatusDetails status_details = 4;

  // Deprecated. Use summary_markdown instead.
  string summary_html = 5;

  // Additional backend-specific details about the task.
  //
  // This could be used to indicate things like named-cache status, task
  // startup/end time, etc.
  //
  // This is limited to 10KB (binary PB + gzip(5))
  //
  // This should be populated as part of the Task response in RunTaskResponse.
  // Any update to this via the Task field in BuildTaskUpdate will override the
  // existing details that were provided in RunTaskResponse.
  google.protobuf.Struct details = 6;

  // A monotonically increasing integer set by the backend to track
  // which task is the most up to date when calling UpdateBuildTask.
  // When the build is first created, this will be set to 0.
  // When RunTask is called and returns a task, this should not be 0 or nil.
  // Each UpdateBuildTask call will check this to ensure the latest task is
  // being stored in datastore.
  int64 update_id = 7;

  // Human-readable commentary around the handling of this task.
  string summary_markdown = 8;
}

// A unique identifier for tasks.
message TaskID {
  // Target backend. e.g. "swarming://chromium-swarm".
  string target = 1 [
    (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED
  ];

  // An ID unique to the target used to identify this task. e.g. Swarming task
  // ID.
  string id = 2;
}

// A message sent by task backends as part of the payload to a
// pubsub topic corresponding with that backend. Buildbucket handles these
// pubsub messages with the UpdateBuildTask cloud task.
// Backends must use this proto when sending pubsub updates to buildbucket.
//
// NOTE: If the task has not been registered with buildbucket yet (by means of
// RunTask returning or StartBuild doing an initial associaton of the task to
// the build), then the message will be dropped and lost forever.
// Use with caution.
message BuildTaskUpdate {
  // A build ID.
  string build_id = 1;

  // Task
  Task task = 2;
}