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