| // 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); |
| |
| /// Retrieves a chunk iterator to the base package index. |
| /// |
| /// Arguments: |
| /// * `packages` is 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); |
| }; |
| |
| /// 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); |
| }; |
| |
| const uint32 PACKAGE_INDEX_CHUNK_SIZE = 32; |
| |
| /// The `PackageIndexIterator` is 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 an empty vector when the iterator is exhausted. |
| Next() -> (vector<PackageIndexEntry>:PACKAGE_INDEX_CHUNK_SIZE entries); |
| }; |