scheduler/appengine/internal/triggers.proto

// Copyright 2017 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 internal.triggers;

option go_package = "go.chromium.org/luci/scheduler/appengine/internal";

import "google/protobuf/timestamp.proto";
import "go.chromium.org/luci/scheduler/api/scheduler/v1/triggers.proto";


// Trigger can be emitted by the engine itself (e.g. on a schedule) or by
// triggering tasks (such as Gitiles tasks).
//
// One or multiple triggers are consumed to initiate a new invocation which has
// access to the properties of consumed triggers. For example, Buildbucket task
// knows about triggers produced by Gitiles tasks.
//
// This message is an internal representation of the trigger, as stored in
// the datastore. See also triggers.Trigger for public representation used in
// API calls.
message Trigger {
  // Unique in time identifier of the trigger.
  //
  // It is used to deduplicate and hence provide idempotency for adding
  // a trigger. Must be provided by whoever emits the trigger.
  string id = 1;

  // ID of a job that emitted this trigger or "" if emitted by the engine.
  //
  // Set by the engine, can't be overridden.
  string job_id = 2;

  // ID of an invocation that emitted this trigger or 0 if emitted by the
  // engine.
  //
  // Set by the engine, can't be overridden.
  int64 invocation_id = 3;

  // Timestamp when the trigger was created.
  //
  // Can be set by whoever emits the trigger if the trigger is based on some
  // external event. If not provided, the engine will set it to the current
  // time.
  //
  // Together with 'order_in_batch' used for weak ordering of triggers that
  // aren't directly comparable (e.g. git commits from different repositories).
  // This ordering shouldn't be considered reliable.
  google.protobuf.Timestamp created = 4;

  // If a bunch of triggers were emitted at the same moment in time (for example
  // through a single RPC or by a single invocation in a tight loop), a trigger
  // with smaller 'order_in_batch' is considered to be older. Value of
  // 'order_in_batch' for triggers with different 'created' timestamps are not
  // comparable.
  //
  // Should be set by whoever emits the trigger if 'created' timestamp was
  // supplied explicitly. Otherwise will be set by the engine based on the order
  // of EmitTrigger calls done by the invocation.
  //
  // Together with 'order_in_batch' used for weak ordering of triggers that
  // aren't directly comparable (e.g. git commits from different repositories).
  // This ordering shouldn't be considered reliable.
  int64 order_in_batch = 7;

  // User friendly name for this trigger that shows up in UI.
  //
  // Can be provided by whoever emits the trigger. Doesn't have to be unique.
  string title = 5;

  // Optional HTTP link to display in UI.
  //
  // Can be provided by whoever emits the trigger. Doesn't have to be unique.
  string url = 6;

  // For triggers emitted through public API or "Trigger" button, contains
  // identity of a user who submitted this trigger.
  //
  // Empty for triggers emitted by the service itself.
  string emitted_by_user = 8;

  // Actual trigger data that depends on type of the trigger.
  oneof payload {
    scheduler.CronTrigger cron = 40;
    scheduler.WebUITrigger webui = 41;
    scheduler.NoopTrigger noop = 50;
    scheduler.GitilesTrigger gitiles = 51;
    scheduler.BuildbucketTrigger buildbucket = 52;
  }
}


// TriggerList is what we store in datastore entities.
message TriggerList {
  repeated Trigger triggers = 1;
}