// Copyright 2017 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 ensure contains methods and types for interacting with the 'ensure
// file format'.
//
// The format is used by the CIPD client to describe the desired state of a CIPD
// installation. This states can be asserted with the CIPD client 'ensure'
// command. The state is essentially a list of packages, their versions and
// their installation subdirectories ("subdirs").
//
// Format Description
//
// The file is line-oriented. All statements fit on a single line.
//
// A line can be blank, a comment, a setting, a package, or a directive.
//
//
// Comments
//
// A comment begins with a # and goes to the end of the line. It is ignored.
// Example:
//   # This is a comment. It has no effect.
//
//
// Settings
//
// A setting looks like `$name value`. Settings are global and can only be set
// once per file. The following settings are allowed:
//   - `$ServiceURL <url>` is the url for the CIPD service. It can be used in
//     lieu of the -service-url command line parameter.
//   - `$VerifiedPlatform <platform> [ <platform>]*` allows the manifest to
//     specify a list of ${platform} expansions to use for verification.
//     Multiple $VerifiedPlatform directives can be specified, and will
//     accumulate.
//   - `$ParanoidMode NotParanoid|CheckPresence|CheckIntegrity` controls how
//     paranoid CIPD should be when checking the state of already installed
//     packages. `NotParanoid` (default) indicates that CIPD should trust that
//     no one is messing with the installation root directory. `CheckPresence`
//     indicates CIPD should verify all files that are supposed to be already
//     installed are indeed present (this incurs additional overhead). And
//     finally `CheckIntegrity` will verify that files weren't modified since
//     they were installed (this incurs even more overhead).
//   - `$ResolvedVersions <filename>` is a path (either relative to the ensure
//     file or absolute) to a file that contains "frozen" instance IDs (hashes)
//     of all packages for all verified platforms, resolved at the time the
//     "frozen" file was generated by `cipd ensure-file-resolve`. The CIPD
//     client will use these instance IDs (instead of contacting the backend)
//     when installing packages in `cipd ensure`. Using this file allows to
//     cryptographically bind the intended state of the deployment to a git
//     commit, since all hashes of all packages become part of the git commit
//     object. Use this if you want to reduce trust in the CIPD backend and root
//     in the git server instead.
//
//
// Package Definitions
//
// A package line looks like `<package_template> <version>`. Package templates
// are CIPD package names, with optional expansion parameters `${os}`,
// `${arch}`, and `${platform}`. These placeholders can appear anywhere in the
// package template except for the first letter.  All other characters in the
// template are taken verbatim.
//
// ${os} will expand to one of the following, based on the value of this
// client's runtime.GOOS value:
//   * windows
//   * mac
//   * linux
//
// ${arch} will expand to one of the following, based on the value of this
// client's runtime.GOARCH value:
//   * 386
//   * amd64
//   * armv6l
//
// Since these two often appear together, the convenience placeholder
// `${platform}` expands to the equivalent of `${os}-${arch}`.
//
// All of these parameters also support the syntax ${var=possible,values}.
// What this means is that the package line will be expanded if, and only if,
// var equals one of the possible values. If that var does not match
// a possible value, the line is ignored. This allows you to do, e.g.:
//   path/to/package/${os=windows}  windows_release
//   path/to/package/${os=linux}    linux_release
//   # no version for mac
//
//   path/to/posix/tool/${os=mac,linux}  some_tag:value
//   # no version for windows
//
//
// Directives
//
// A directive looks like `@name value`. Directives are 'sticky' and apply until
// the next same-name directive. The following directive names are allowed:
//   - `@Subdir` allows you to change the subdirectory that subsequent packages
//     are installed to.
//     * The subdir value is always relative to the root of the CIPD
//       installation (the directory containing the .cipd folder).
//     * The value of Subdir before any @Subdir directives is "", or the root
//       of the CIPD installation.
//     * You can reset the directory back to root by doing `@Subdir` by itself,
//       without a value.
//     * @Subdir directives also support expansion parameters `${os}`, `${arch}`
//       and `${platform}`. Using a subdir expansion like `${param=val}` will
//       cause that subdirectory, and any packages in it, to only exist if the
//       param matches one of the values.
//
//
// Example
//
// Here is an example ensure file which demonstrates all the various features.
//
//   # This is an ensure file!
//   $ServiceURL https://chrome-infra-packages.appspot.com/
//   $ParanoidMode CheckPresence
//   $ResolvedVersions cipd_lock.versions
//
//   # This is the CIPD client itself
//   infra/tools/cipd/${os}-${arch}  latest
//
//   @Subdir python
//   python/wheels/pip                     version:8.1.2
//   # use the convenience placeholder
//   python/wheels/coverage/${platform}    version:4.1
//
//   @Subdir infra/support
//   infra/some/other/package deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
//
//   # only exists on windows machines
//   @Subdir support/${os=windows}-${arch}
//   some/support/package  latest
//   some/other/support/package  latest
//
//   # Always exists, but the directory changes based on the os
//   @Subdir platform/${os}
//   a/platform/package latest
package ensure