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

/// Manages the system package cache.
///
/// This interface is intended to be implemented by the package manager component and used by
/// package resolver components.
[Discoverable]
protocol PackageCache {
    /// Gets the package directory if it is present on the local system. If it is not, the
    /// `missing_blobs` iterator will provide all the blobs in the package that are missing from
    /// the system, and the ability to write those blobs to blobfs. If all the missing blobs are
    /// downloaded and written to by the client, the `dir` directory will be resolved. This method
    /// will return `ZX_OK` when the package has been fully resolved, or an error if the client
    /// closes `needed_blobs` or `dir` handle before the package has been resolved.
    ///
    /// Arguments:
    /// * `meta_far_blob` is the blob info for the package's meta.far.
    /// * `selectors` are the package selectors (TODO: link to docs).
    /// * `needed_blobs` is an iterator over all the blobs in the package that
    ///   are not present on the system.
    /// * `dir` is an optional request for a directory that will be resolved when the package has
    ///   been successfully cached.
    ///
    /// Return Values:
    /// * `ZX_OK` if the package was successfully cached.
    /// * `ZX_ERR_UNAVAILABLE` if the client closed `needed_blobs` or `dir` handles before the
    ///   all the missing blobs were downloaded to the system.
    Get(
        BlobInfo meta_far_blob,
        vector<string> selectors,
        request<NeededBlobs> needed_blobs,
        request<fuchsia.io.Directory>? dir
        ) -> (zx.status status);

    /// Opens the package, or error out if it is not present on the local system.
    ///
    /// Arguments:
    /// * `meta_far_blob_id` is the blob id for the package's meta.far.
    /// * `selectors` are 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_NOT_FOUND` if the package does not exist.
    Open(
        BlobId meta_far_blob_id,
        vector<string> selectors,
        request<fuchsia.io.Directory> dir
        ) -> (zx.status status);
};

/// The `NeededBlobs` is an abstract interface that is provided by a `PackageCache` to the
/// `PackageResolver` to fetch one or more blobs that are not present on the local system for a
/// given package.
protocol NeededBlobs {
    /// Returns a vector of blobs that are not present on the system that must be downloaded and
    /// written to blobfs with the `Open` method before a package can be resolved. This method
    /// should continue to be called until it returns an empty vector. This signifies all the
    /// missing blobs have been successfully downloaded.
    GetMissingBlobs() -> (vector<BlobInfo> blobs);

    /// Open a blob for writing.
    ///
    /// Arguments:
    /// * `blob_id` is the blob id describing this blob.
    /// * `file` resolves to an opened writable file must be truncated to the correct size by the
    ///   caller.
    ///
    /// Return Values:
    /// * `ZX_OK` if successful.
    /// * `ZX_ERR_ACCESS_DENIED` if the package does not contain this blob.
    /// * `ZX_ERR_IO` if there is some other unspecified error during I/O.
    /// * `ZX_ERR_NO_SPACE` if there is no space available to store the package.
    Open(BlobId blob_id, request<fuchsia.io.File> file) -> (zx.status status);
};