scheduler: add GetJobInvocations api.

scheduler/api/scheduler/v1/scheduler.proto

Index: scheduler/api/scheduler/v1/scheduler.proto
diff --git a/scheduler/api/scheduler/v1/scheduler.proto b/scheduler/api/scheduler/v1/scheduler.proto
index 87acb32489f274e9068319f49609b312ba0c2f43..2080cfce612b0c7fe18a1fd891515c331048e8c8 100644
--- a/scheduler/api/scheduler/v1/scheduler.proto
+++ b/scheduler/api/scheduler/v1/scheduler.proto
@@ -12,7 +12,12 @@ 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 {
@@ -35,3 +40,49 @@ message Job {
 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;
+}