// Copyright 2022 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.

// Package provenance provides API definitions and simple libraries to interface
// with the APIs.
//
// It supports all possible provenance information that are supported currently.
//
// Provenance is a metadata about an artifact that provides information to trace
// a binary back to its sources. It also provides a chain-of-custody as the
// artifact traverses through multiple systems.
//
// Summary
//
// Provenance defines APIs for reporting `provenance` metadata, in order to
// establish a traceable lineage for artifacts produced within the LUCI
// ecosystem.
// Artifact provenance is otherwise defined as "metadata which records a
// snapshot of the build-time states that correspond to an artifact."
//
// Usage
//
// Service self-report is used by local processes to insert relevant information
// into provenance. Server side implementation is beyond the scope of this
// package and is Google-internal.
//
// A local git checkout can be reported by:
//  pClient, _ := client.MakeProvenanceClient(ctx, "http://localhost:port")
//  reporter := &reporter.Report{RClient: pClient}
//  ok, err := reporter.ReportGitCheckout(ctx, "https://repo.git", "deadbeef", "refs/heads/example")
//  if err != nil & !ok {
//      ...
//  }
//
// This call will return a result back to you, user can implement it in a
// blocking way to ensure the event was recorded. Failure mode here can be
// internal error (that would include invalid input) as well as absence of local
// provenance server.
//
// Results here can be:
//  (true, nil) => report successfully exported
//  (true, ErrServiceUnavailable) => service unavailable
//  (false, err) => all other cases
//
// This allows users to determine how to interpret failure. A concrete example
// would be a workload where security policy is set to "enforce" mode, meaning
// checkout should fail loudly, in this case `ok` status can be ignored.
// For workloads where this is in "audit" mode, API will return a success ok
// status when local server isn't configured/unreachable. This is particularly
// helpful for flexible workloads.
//
// Similarly other interfaces of this API can be used to report a variety of
// interesting things.
package provenance