/*
* Copyright (C) 2022 The Android Open Source Project
*
* 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/protobuf/timestamp.proto";
import public "tools/tradefederation/core/proto/resultdb/common.proto";

option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";
option java_package = "com.android.resultdb.proto";
option java_multiple_files = true;

// A message notifying that an invocation has been finalized,
// i.e. that an invocation's test results are now immutable and are
// safe to be exported.
//
// The message is sent over the `v1.invocation_finalized` Cloud Pub/Sub
// topic in JSON-serialized form.
//
// Next id: 6.
message InvocationFinalizedNotification {
    // The name of the invocation that was finalized.
    // Format: invocations/{INVOCATION_ID}.
    string invocation = 1;

    // The LUCI realm that owns the invocation.
    // E.g. "chromium:ci".
    string realm = 2;

    // Whether this invocation is a root of the invocation graph for export purposes.
    //
    // To help downstream systems (like LUCI Analysis) make sense of test results,
    // and gather overall context for a result, ResultDB data export is centered
    // around export roots.
    //
    // See more in invocation.proto.
    bool is_export_root = 3;

    // The hostname of the luci.resultdb.v1.ResultDB service which
    // can be used to query more information about the invocation(s)
    // notified in this message.
    string resultdb_host = 4;

    // When the invocation was created.
    google.protobuf.Timestamp create_time = 5;
}

// InvocationReadyForExportNotification notifies that the properties, test results
// and artifacts directly inside invocation `invocation`, within the context of
// export root `root_invocation`, are now immutable and ready for consumption
// by downstream systems.
//
// If a given invocation is included by multiple export roots, a message will
// be sent for each such root.
//
// When sent over v1.invocation_ready_for_export Cloud Pub/Sub, an attribute
// "luci_project" will be attached to the message, which will contain the
// LUCI Project of the `root_invocation_realm`.
//
// Next ID: 8.
message InvocationReadyForExportNotification {
    // The hostname of the luci.resultdb.v1.ResultDB service which
    // can be used to query more information about the invocation(s)
    // notified in this message.
    string resultdb_host = 6;

    // The export root with respect to which the export is occurring.
    //
    // Format: invocations/{ROOT_INVOCATION_ID}.
    string root_invocation = 1;

    // The LUCI realm that owns the root invocation.
    string root_invocation_realm = 2;

    // When the root invocation was created.
    google.protobuf.Timestamp root_create_time = 7;

    // The name of the ResultDB invocation included by root_invocation whose
    // immediate properties, test results and artifacts are now immutable
    // (in FINALIZING OR FINALIZED state). Note that child invocations included
    // by `invocation` may not yet be immutable.
    //
    // This may be equal to root_invocation, to indicate test results, artifacts
    // and properties immediately inside root_invocation are immutable and ready
    // for ingestion.
    //
    // Format: invocations/{INVOCATION_ID}.
    string invocation = 3;

    // The LUCI realm that owns `invocation`.
    string invocation_realm = 4;

    // The resolved sources for `invocation`, if any.
    //
    // As sources may be inherited, the sources resolved for the same
    // invocation may vary between export roots. This typically occurs when
    // a project uses testing task deduplication, and the different sources
    // deduplicate to the same testing task as they compile to
    // byte-for-byte-identical testing artifacts.
    luci.resultdb.v1.Sources sources = 5;
}