// 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;

/// Resolves packages from a registry.
///
/// This interface is intended to be implemented by package resolver components, and used by
/// repository administration tools.
[Discoverable]
interface PackageResolver {
    /// Populates or updates the the cache of a package with the given selectors as specified by the
    /// update policy.
    ///
    /// Ensures that a package is on the local filesystem.
    ///
    /// Arguments:
    /// * |package_uri| The package URI for a package (TODO: link to docs).
    /// * |selectors| are the the package selectors (TODO: link to docs).
    /// * |dir| is a request for a directory that will be resolved when the package has been
    ///   successfully cached.
    ///
    /// Return Values:
    /// * |ZX_OK| if the package was successfully opened.
    /// * |ZX_ERR_ACCESS_DENIED| if the resolver does not have permission to fetch a package blob.
    /// * |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_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.
    Resolve(
        string package_uri,
        vector<string> selectors,
        UpdatePolicy update_policy,
        request<fuchsia.io.Directory> dir
        ) -> (zx.status status);
};

/// The |UpdatePolicy| provides different policies to be used when the |PackageResolver| is
/// fetching packages.
struct UpdatePolicy {
    /// Should the resolver fetch the package if it is not present on the local system.
    bool fetch_if_absent;

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