scheduler: add GetJobInvocations api.

scheduler/api/scheduler/v1/scheduler.proto

 // Copyright 2016 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.
 
 syntax = "proto3";
 
 package scheduler;
 
 
 // Scheduler exposes the public API of the Scheduler service.
 service Scheduler {
   // TODO: still in progress.
 
   // GetJobs fetches all jobs satisfying JobsRequest and visibility ACLs.
+  // If JobsRequest.project is specified but the project doesn't exist, empty
+  // list of Jobs is returned.
   rpc GetJobs(JobsRequest) returns (JobsReply);
+
+  // GetInvocations fetches invocations of a given job, most recent first.
+  rpc GetInvocations(InvocationsRequest) returns (InvocationsReply);
 }
 
 message JobsRequest {
   // If not specified or "", all projects' jobs are returned.
   string project = 1;
 }
 
 message JobsReply {
   repeated Job jobs = 1;
 }
 
 message Job {
   string name = 1;
   string project = 2;
   string schedule = 3;
 
   JobState state = 4;
 }
 
 message JobState {
   string ui_status = 1;
 }
+
+
+message InvocationsRequest{
+  string project = 1;
+  string job = 2;
+  string cursor = 3;
+  int32 page_size = 4;
+}
+
+message InvocationsReply{
+  repeated Invocation invocations = 1;
+  string next_cursor = 2;
+  // now_ts is a unix timestamp in microseconds pointing to **approximately** when
+  // the results were computed. It is useful to compute approximate durations of
+  // invocations that are not yet final.
+  int64 now_ts = 3;

[Vadim Sh., 2017/06/21 23:46:41]

why is this needed? We generally assume clocks and in sync everywhere, so
clients can just use their own clock.

[tandrii(chromium), 2017/06/22 15:47:42]

tl;dr ok, let's remove complexity from here.

I copied this from buildbucket API for search, which returns among other
properties of a build 'utcnow_ts', cq then carefully uses that field instead of
local CQ2.golo time. I don't know why.

+}
+
+message Invocation {
+  int64 id = 1;
+  string job = 2;
+  string project = 3;
+
+  // TODO(tandrii): consider exposing InvocationNonce and RetryCount as these
+  // could be important to consumers of API in order to combine multiple
+  // attempts of what was supposed to be just one invocation.
+
+  // start_ts is unix timestamp in microseconds.
+  int64 started_ts = 4;
+  // finished_ts is unix timestamp in microseconds. Set only if final is true.
+  int64 finished_ts = 5;
+  // triggered_by is an identity ("kind:value") which is specified only if
+  // invocation was triggered by not the scheduler service itself.
+  string triggered_by = 6;
+  // Latest status of a job.
+  string status = 7;
+  // If true, the status of the job is final and won't change.
+  bool final = 8;
+
+  // config_revision pins project/job config version according to which this
+  // invocation was created.
+  string config_revision = 9;
+
+  // view_url points to human readable page for a given invocation if available.
+  string view_url = 10;
+}