blob: 36763a6573ac99b10cf68253fb7ce37b322393fa [file] [log] [blame]
// 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 manages the system package cache.
///
/// This 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 successfully when the package has been fully resolved, or return an error if
/// the client closes `needed_blobs` or `dir` handle before the package has been resolved.
///
/// This method does not guarantee the missing blobs have been persisted. In order to guarantee
/// missing blobs are persisted, clients should call ['Sync'].
///
/// + request `meta_far_blob` the blob info for the package's meta.far.
/// + request `selectors` the package selectors (TODO: link to docs).
/// + request `needed_blobs` an iterator over all the blobs in the package that
/// are not present on the system.
/// + request `dir` an optional 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_UNAVAILABLE` if the client closed `needed_blobs` or `dir` handles before
/// 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
) -> () error zx.status;
/// Opens the package, or errors out if it is not present on the local system.
///
/// + request `meta_far_blob_id` the blob id for the package's meta.far.
/// + request `selectors` the package selectors (TODO: link to docs).
/// + 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_NOT_FOUND` if the package does not exist.
Open(
BlobId meta_far_blob_id,
vector<string> selectors,
request<fuchsia.io.Directory> dir
) -> () error zx.status;
/// Retrieves a chunk iterator to the base package index.
///
/// + request `iterator` a request for the `PackageIndexIterator` that will return sets of
/// `PackageIndexEntry` objects until all packages in the base index have been iterated.
BasePackageIndex(request<PackageIndexIterator> iterator);
/// Synchronizes updates to the cached packages to the underlying persistent storage.
///
/// * error a zx_status value indicating failure. One of the following:
/// * `ZX_ERR_INTERNAL` if the sync fails.
Sync() -> () error zx.status;
};
/// This is used to fetch blobs that are not present on the local system for a
/// given package. This is provided by a [`PackageCache`] to the [`PackageResolver`].
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.
///
/// - response `blobs` the vector of missing blobs.
GetMissingBlobs() -> (vector<BlobInfo> blobs);
/// Opens a blob for writing.
///
/// + request `blob_id` the blob id describing this blob.
/// + request `file` resolves to an opened writable file must be truncated to the correct size
/// by the caller.
/// * error a zx_status value indicating failure. One of the following:
/// * `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) -> () error zx.status;
};
const uint32 PACKAGE_INDEX_CHUNK_SIZE = 32;
/// A chunk iterator for the package index. This is required because it is possible for the
/// package index to be too large to send over in a single request (over 64KiB).
protocol PackageIndexIterator {
/// Returns the next chunk of package index entries. When the iterator is exhausted,
/// this returns an empty vector.
///
/// - response `entries` the next chunk of entries in the package index.
Next() -> (vector<PackageIndexEntry>:PACKAGE_INDEX_CHUNK_SIZE entries);
};