// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.pkg;

using fuchsia.io;
using zx;

/// This resolves packages from a repository.
///
/// This is intended to be implemented by package resolver components, and used by
/// repository administration tools.
[Discoverable]
protocol PackageResolver {
    /// Populates or updates the cache of a package with the given selectors as specified by the
    /// update policy.
    ///
    /// Ensures that a package is on the local filesystem.
    ///
    /// + request `package_url` the package URL for a package (TODO: link to docs).
    /// + request `selectors` the package selectors (TODO: link to docs).
    /// + request `update_policy` the policy to use when fetching packages.
    /// + request `dir` a request for a directory that will be resolved when the package has
    ///   been successfully cached.
    /// * error a zx_status value indicating failure. One of the following:
    ///     * `ZX_ERR_ACCESS_DENIED` if the resolver does not have permission to fetch a
    ///       package blob.
    ///     * `ZX_ERR_INTERNAL` if the resolver encountered an otherwise unspecified error while
    ///       handling the request
    ///     * `ZX_ERR_IO` if there is some other unspecified error during I/O.
    ///     * `ZX_ERR_NOT_FOUND` if the package or a package blob does not exist.
    ///     * `ZX_ERR_ADDRESS_UNREACHABLE` if the resolver does not know about the repo.
    ///     * `ZX_ERR_NO_SPACE` if there is no space available to store the package.
    ///     * `ZX_ERR_UNAVAILABLE` if the resolver is currently unable to fetch a package blob.
    // TODO(fxbug.dev/45811) change `package_url` from string to PackageUrl
    Resolve(
        string package_url,
        vector<string> selectors,
        UpdatePolicy update_policy,
        request<fuchsia.io.Directory> dir
        ) -> () error zx.status;

    /// Determines the hash of a package.
    ///
    /// + request `package_url` the package URL for a package.
    /// - response `meta_far_blob_id` the hash of the package.
    /// * error a zx_status value indicating failure. One of the following:
    ///     * `ZX_ERR_INTERNAL` if the resolver encountered an otherwise unspecified error
    ///       while handling the request
    ///     * `ZX_ERR_NOT_FOUND` if the package does not exist.
    ///     * `ZX_ERR_ADDRESS_UNREACHABLE` if the resolver does not know about the repo.
    GetHash(
        PackageUrl package_url
        ) -> (BlobId meta_far_blob_id) error zx.status;
};

/// The policy to use when resolving packages.
struct UpdatePolicy {
    /// Whether the resolver should fetch the package if it is not present on the local system.
    bool fetch_if_absent;

    /// Whether the resolver should allow old versions of the package to be used.
    bool allow_old_versions;
};