resultdb/proto/v1/recorder.proto - infra/luci/luci-go - Git at Google

 // Copyright 2019 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 luci.resultdb.v1;

 import "google/api/field_behavior.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 import "go.chromium.org/luci/resultdb/proto/v1/invocation.proto";
 import "go.chromium.org/luci/resultdb/proto/v1/test_result.proto";

 option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";

 // Service to record test results.
 //
 // CreateInvocation response includes a metadata key "update-token".
 // It MUST be passed to all other mutation RPCs, such as CreateTestResult.
 // Otherwise the request will fail with UNAUTHENTICATED error code.
 //
 // RPCs that mutate an invocation return FAILED_PRECONDITION error code if the
 // invocation is finalized.
 service Recorder {

   // == Invocations ============================================================

   // Creates a new invocation.
   // The request specifies the invocation id and its contents.
   //
   // The response header metadata contains "update-token" required for future
   // updates, including finalization.
   //
   // If invocation with the given ID already exists, returns ALREADY_EXISTS
   // error code.
   rpc CreateInvocation(CreateInvocationRequest) returns (Invocation) {};

   // Creates multiple invocations in a single rpc.
   //
   // The response header metadata contains a multi-valued "update-token"
   // required for future updates, including finalization. The tokens will be
   // given in the same order as BatchCreateInvocationRequest.requests.
   rpc BatchCreateInvocations(BatchCreateInvocationsRequest)
       returns (BatchCreateInvocationsResponse) {};

   // Updates an existing non-finalized invocation.
   rpc UpdateInvocation(UpdateInvocationRequest) returns (Invocation) {};

   // Transitions the given invocation to the state FINALIZED.
   rpc FinalizeInvocation(FinalizeInvocationRequest) returns (Invocation) {};

   // Updates inclusions for a non-finalized invocation.
   rpc UpdateIncludedInvocations(UpdateIncludedInvocationsRequest)
       returns (google.protobuf.Empty) {};

   // == Test results ===========================================================

   // Appends a test result to a non-finalized invocation.
   rpc CreateTestResult(CreateTestResultRequest) returns (TestResult) {};
   // Atomically appends a batch of test results to a non-finalized invocation.
   rpc BatchCreateTestResults(BatchCreateTestResultsRequest)
       returns (BatchCreateTestResultsResponse) {};

   // Appends a test exoneration to a non-finalized invocation.
   rpc CreateTestExoneration(CreateTestExonerationRequest)
       returns (TestExoneration) {};
   // Atomically appends a batch of test exonerations to a non-finalized
   // invocation.
   rpc BatchCreateTestExonerations(BatchCreateTestExonerationsRequest)
       returns (BatchCreateTestExonerationsResponse) {};
 }

 // == Invocations ==============================================================

 // A request message for CreateInvocation.
 message CreateInvocationRequest {
   // Invocation identifier, becomes a part of the invocation.name.
   // LUCI systems MAY create invocations with nicely formatted IDs, such as
   // "build-1234567890". All other clients MUST use GUIDs.
   //
   // Regex: ^[a-z][a-z0-9_\-]*$.
   string invocation_id = 1 [ (google.api.field_behavior) = REQUIRED ];

   // Invocation data to insert.
   Invocation invocation = 2;

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided.
   string request_id = 3;
 }

 // A request message for BatchCreateInvocations
 message BatchCreateInvocationsRequest {
   // requests[i].request_id MUST be either empty or equal to request_id in
   // this message.
   //
   // Up to 500 requests.
   repeated CreateInvocationRequest requests = 1;

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided, so it is
   // strongly recommended to populate this field.
   string request_id = 2;
 }


 // A response message for BatchCreateInvocations RPC.
 message BatchCreateInvocationsResponse {
   // Invocations created.
   repeated Invocation invocations = 1;

   // One token per each created invocation.
   // These are passed in the response instead of as metadata, because large
   // batches increase the size of the response headers beyond allowed limits and
   // cause failures like crbug.com/1064496
   // update_tokens[i] corresponds to invocations[i].
   // *Do not log these values*.
   repeated string update_tokens = 2;
 }


 // A request message for UpdateInvocation RPC.
 message UpdateInvocationRequest {
   // Invocation to update.
   Invocation invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // The list of fields to be updated.
   google.protobuf.FieldMask update_mask = 2;
 }

 // A request message for FinalizeInvocation RPC.
 message FinalizeInvocationRequest {
   // Name of the invocation to finalize.
   string name = 1 [ (google.api.field_behavior) = REQUIRED ];
 }

 // A request message for UpdateIncludedInvocations RPC.
 message UpdateIncludedInvocationsRequest {
   // Name of the invocation to add/remove inclusions to/from,
   // see Invocation.name.
   // For example, name of the buildbucket build invocation that should include
   // a swarming task invocation.
   string including_invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // Names of the invocations to include, see Invocation.name.
   // If any of these invocations are already included, they will be silently
   // ignored for idempotency.
   repeated string add_invocations = 2;

   // Names of the previously included invocations to remove, see
   // Invocation.name.
   // If any of these invocations are not included already, they will be silently
   // ignored for idempotency.
   repeated string remove_invocations = 3;
 }

 // A request message for CreateTestResult RPC.
 message CreateTestResultRequest {
   // Name of the parent invocation, see Invocation.name.
   string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // The test result to create.
   // Test id and result id are used to dedupe requests, i.e.
   // if a test result with the same test id and result id already exists in
   // the invocation, then the requests succeeds as opposed to returns with
   // ALREADY_EXISTS error.
   TestResult test_result = 2 [ (google.api.field_behavior) = REQUIRED ];

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided, so it is
   // strongly recommended to populate this field.
   //
   // Impl note: this field is used to compute the spanner-level result id, which
   // will encode tuple (request_id, index_of_request)", where
   // - request_id is a random GUID if not provided by the user
   // - index_of_request is 0 in CreateTestResult RPC, or index of the request
   //   in BatchCreateTestResultsRequest in the batch RPC.
   // TODO(jchinlee): remove this impl note when it is converted into code.
   string request_id = 3;
 }

 // == Test results =============================================================

 // A request message for BatchCreateTestResults RPC.
 message BatchCreateTestResultsRequest {
   // Name of the parent invocation, see Invocation.name.
   string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // Requests to create test results.
   // requests[i].invocation MUST be either empty or equal to invocation in this
   // message.
   // requests[i].request_id MUST be either empty or equal to request_id in
   // this message.
   //
   // Up to 500 requests.
   repeated CreateTestResultRequest requests = 2;

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided, so it is
   // strongly recommended to populate this field.
   //
   string request_id = 3;
 }

 // A response message for BatchCreateTestResults RPC.
 message BatchCreateTestResultsResponse {
   // Test results created.
   repeated TestResult test_results = 1;
 }

 // A request message for CreateTestExoneration RPC.
 message CreateTestExonerationRequest {
   // Name of the parent invocation, see Invocation.name.
   string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // The TestExoneration to create.
   TestExoneration test_exoneration = 2
       [ (google.api.field_behavior) = REQUIRED ];

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided.
   string request_id = 3;
 }

 // A request message for BatchCreateTestExonerations RPC.
 message BatchCreateTestExonerationsRequest {
   // Name of the parent invocation, see Invocation.name.
   string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

   // Requests to create TestExonerations.
   // requests[i].invocation MUST be either empty or equal to invocation in this
   // message.
   // requests[i].request_id MUST be either empty or equal to request_id in
   // this message.
   //
   // Up to 500 requests.
   repeated CreateTestExonerationRequest requests = 2;

   // A unique identifier for this request. Restricted to 36 ASCII characters.
   // A random UUID is recommended.
   // This request is only idempotent if a `request_id` is provided, so it is
   // strongly recommended to populate this field.
   string request_id = 3;
 }

 // A response message for BatchCreateTestExonerations RPC.
 message BatchCreateTestExonerationsResponse {
   // Test exonerations created.
   repeated TestExoneration test_exonerations = 1;
 }
	// Copyright 2019 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 luci.resultdb.v1;

	import "google/api/field_behavior.proto";
	import "google/protobuf/empty.proto";
	import "google/protobuf/field_mask.proto";
	import "go.chromium.org/luci/resultdb/proto/v1/invocation.proto";
	import "go.chromium.org/luci/resultdb/proto/v1/test_result.proto";

	option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";

	// Service to record test results.
	//
	// CreateInvocation response includes a metadata key "update-token".
	// It MUST be passed to all other mutation RPCs, such as CreateTestResult.
	// Otherwise the request will fail with UNAUTHENTICATED error code.
	//
	// RPCs that mutate an invocation return FAILED_PRECONDITION error code if the
	// invocation is finalized.
	service Recorder {

	// == Invocations ============================================================

	// Creates a new invocation.
	// The request specifies the invocation id and its contents.
	//
	// The response header metadata contains "update-token" required for future
	// updates, including finalization.
	//
	// If invocation with the given ID already exists, returns ALREADY_EXISTS
	// error code.
	rpc CreateInvocation(CreateInvocationRequest) returns (Invocation) {};

	// Creates multiple invocations in a single rpc.
	//
	// The response header metadata contains a multi-valued "update-token"
	// required for future updates, including finalization. The tokens will be
	// given in the same order as BatchCreateInvocationRequest.requests.
	rpc BatchCreateInvocations(BatchCreateInvocationsRequest)
	returns (BatchCreateInvocationsResponse) {};

	// Updates an existing non-finalized invocation.
	rpc UpdateInvocation(UpdateInvocationRequest) returns (Invocation) {};

	// Transitions the given invocation to the state FINALIZED.
	rpc FinalizeInvocation(FinalizeInvocationRequest) returns (Invocation) {};

	// Updates inclusions for a non-finalized invocation.
	rpc UpdateIncludedInvocations(UpdateIncludedInvocationsRequest)
	returns (google.protobuf.Empty) {};

	// == Test results ===========================================================

	// Appends a test result to a non-finalized invocation.
	rpc CreateTestResult(CreateTestResultRequest) returns (TestResult) {};
	// Atomically appends a batch of test results to a non-finalized invocation.
	rpc BatchCreateTestResults(BatchCreateTestResultsRequest)
	returns (BatchCreateTestResultsResponse) {};

	// Appends a test exoneration to a non-finalized invocation.
	rpc CreateTestExoneration(CreateTestExonerationRequest)
	returns (TestExoneration) {};
	// Atomically appends a batch of test exonerations to a non-finalized
	// invocation.
	rpc BatchCreateTestExonerations(BatchCreateTestExonerationsRequest)
	returns (BatchCreateTestExonerationsResponse) {};
	}

	// == Invocations ==============================================================

	// A request message for CreateInvocation.
	message CreateInvocationRequest {
	// Invocation identifier, becomes a part of the invocation.name.
	// LUCI systems MAY create invocations with nicely formatted IDs, such as
	// "build-1234567890". All other clients MUST use GUIDs.
	//
	// Regex: ^[a-z][a-z0-9_\-]*$.
	string invocation_id = 1 [ (google.api.field_behavior) = REQUIRED ];

	// Invocation data to insert.
	Invocation invocation = 2;

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided.
	string request_id = 3;
	}

	// A request message for BatchCreateInvocations
	message BatchCreateInvocationsRequest {
	// requests[i].request_id MUST be either empty or equal to request_id in
	// this message.
	//
	// Up to 500 requests.
	repeated CreateInvocationRequest requests = 1;

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided, so it is
	// strongly recommended to populate this field.
	string request_id = 2;
	}


	// A response message for BatchCreateInvocations RPC.
	message BatchCreateInvocationsResponse {
	// Invocations created.
	repeated Invocation invocations = 1;

	// One token per each created invocation.
	// These are passed in the response instead of as metadata, because large
	// batches increase the size of the response headers beyond allowed limits and
	// cause failures like crbug.com/1064496
	// update_tokens[i] corresponds to invocations[i].
	// Do not log these values.
	repeated string update_tokens = 2;
	}


	// A request message for UpdateInvocation RPC.
	message UpdateInvocationRequest {
	// Invocation to update.
	Invocation invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// The list of fields to be updated.
	google.protobuf.FieldMask update_mask = 2;
	}

	// A request message for FinalizeInvocation RPC.
	message FinalizeInvocationRequest {
	// Name of the invocation to finalize.
	string name = 1 [ (google.api.field_behavior) = REQUIRED ];
	}

	// A request message for UpdateIncludedInvocations RPC.
	message UpdateIncludedInvocationsRequest {
	// Name of the invocation to add/remove inclusions to/from,
	// see Invocation.name.
	// For example, name of the buildbucket build invocation that should include
	// a swarming task invocation.
	string including_invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// Names of the invocations to include, see Invocation.name.
	// If any of these invocations are already included, they will be silently
	// ignored for idempotency.
	repeated string add_invocations = 2;

	// Names of the previously included invocations to remove, see
	// Invocation.name.
	// If any of these invocations are not included already, they will be silently
	// ignored for idempotency.
	repeated string remove_invocations = 3;
	}

	// A request message for CreateTestResult RPC.
	message CreateTestResultRequest {
	// Name of the parent invocation, see Invocation.name.
	string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// The test result to create.
	// Test id and result id are used to dedupe requests, i.e.
	// if a test result with the same test id and result id already exists in
	// the invocation, then the requests succeeds as opposed to returns with
	// ALREADY_EXISTS error.
	TestResult test_result = 2 [ (google.api.field_behavior) = REQUIRED ];

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided, so it is
	// strongly recommended to populate this field.
	//
	// Impl note: this field is used to compute the spanner-level result id, which
	// will encode tuple (request_id, index_of_request)", where
	// - request_id is a random GUID if not provided by the user
	// - index_of_request is 0 in CreateTestResult RPC, or index of the request
	// in BatchCreateTestResultsRequest in the batch RPC.
	// TODO(jchinlee): remove this impl note when it is converted into code.
	string request_id = 3;
	}

	// == Test results =============================================================

	// A request message for BatchCreateTestResults RPC.
	message BatchCreateTestResultsRequest {
	// Name of the parent invocation, see Invocation.name.
	string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// Requests to create test results.
	// requests[i].invocation MUST be either empty or equal to invocation in this
	// message.
	// requests[i].request_id MUST be either empty or equal to request_id in
	// this message.
	//
	// Up to 500 requests.
	repeated CreateTestResultRequest requests = 2;

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided, so it is
	// strongly recommended to populate this field.
	//
	string request_id = 3;
	}

	// A response message for BatchCreateTestResults RPC.
	message BatchCreateTestResultsResponse {
	// Test results created.
	repeated TestResult test_results = 1;
	}

	// A request message for CreateTestExoneration RPC.
	message CreateTestExonerationRequest {
	// Name of the parent invocation, see Invocation.name.
	string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// The TestExoneration to create.
	TestExoneration test_exoneration = 2
	[ (google.api.field_behavior) = REQUIRED ];

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided.
	string request_id = 3;
	}

	// A request message for BatchCreateTestExonerations RPC.
	message BatchCreateTestExonerationsRequest {
	// Name of the parent invocation, see Invocation.name.
	string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

	// Requests to create TestExonerations.
	// requests[i].invocation MUST be either empty or equal to invocation in this
	// message.
	// requests[i].request_id MUST be either empty or equal to request_id in
	// this message.
	//
	// Up to 500 requests.
	repeated CreateTestExonerationRequest requests = 2;

	// A unique identifier for this request. Restricted to 36 ASCII characters.
	// A random UUID is recommended.
	// This request is only idempotent if a `request_id` is provided, so it is
	// strongly recommended to populate this field.
	string request_id = 3;
	}

	// A response message for BatchCreateTestExonerations RPC.
	message BatchCreateTestExonerationsResponse {
	// Test exonerations created.
	repeated TestExoneration test_exonerations = 1;
	}