fuchsia.pkg

PROTOCOLS

PackageResolverAdmin

Defined in fuchsia.pkg/admin.fidl

Configures a package resolver.

SetExperimentState

Sets an experiment toggle to a specific state (on or off).

Experiment states are not persisted and apply only while the resolver is running.

  • request experiment_id the experiment to enable or disable.
  • request state the state the experimnet should be set to.
  • error a zx.status value indicating success or failure. Fails with `ZX_ERR_INVALID_ARGS if the experiment is unknown to the resolver.

Request

NameType
experiment_id ExperimentToggle
state bool

Response

NameType

PackageCache

Defined in fuchsia.pkg/cache.fidl

Manages the system package cache.

This interface is intended to be implemented by the package manager component and used by package resolver components.

Get

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.

Request

NameType
meta_far_blob BlobInfo
selectors vector<string>
needed_blobs request<NeededBlobs>
dir request<fuchsia.io/Directory>?

Response

NameType
status int32

Open

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.

Request

NameType
meta_far_blob_id BlobId
selectors vector<string>
dir request<fuchsia.io/Directory>

Response

NameType
status int32

NeededBlobs

Defined in fuchsia.pkg/cache.fidl

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.

GetMissingBlobs

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.

Request

NameType

Response

NameType
blobs vector<BlobInfo>

Open

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.

Request

NameType
blob_id BlobId
file request<fuchsia.io/File>

Response

NameType
status int32

FontResolver

Defined in fuchsia.pkg/font_resolver.fidl

Resolves font packages from a registry.

This interface is intended to be implemented by package resolver components, and used exclusively by fuchsia.fonts.Provider.

DEPRECATED. This is an interim solution, and will be revisited when Component Framework v2 becomes available and allows non-component packages and easier directory routing.

Resolve

Populates or updates the cache of a font package, fetching it if it is not present on the local system.

  • request package_url The package URL of a font package.
  • request directory_request Request for a directory that will be resolved when the package has been successfully cached. The directory should contain a single file, corresponding to the asset filename. The client should retain the directory handle for as long as needed to prevent the package from being evicted from cache.

  • response status Outcome of the request.

    • 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 font package or a package blob does not exist, or is not known to be a font package.
    • 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.

Request

NameType
package_url string
directory_request request<fuchsia.io/Directory>

Response

NameType
status int32

RepositoryManager

Defined in fuchsia.pkg/repo.fidl

Manages package repositories.

This interface is intended to be implemented by package resolver components, and used by repository administration tools.

Add

Add a repository. This will overwrite the repository if it already exists.

Arguments: * repo is repository to add to the resolver.

Return Values: * ZX_OK if the repository was added. * ZX_ERR_ALREADY_EXISTS if the repository already exists. * ZX_ERR_INVALID_ARGS if the repository is malformed.

Request

NameType
repo RepositoryConfig

Response

NameType
status int32

Remove

Remove a repository.

Removing a repository will prevent future packages from being cached from this repository, but in-flight downloads may not be interrupted.

Arguments: * repo_url is the URL of the repository we want to remove.

Return Values: * Returns ZX_OK if the repository was removed. * Returns ZX_ERR_INVALID_ARGS if the repo_url is malformed. * Returns ZX_ERR_NOT_FOUND if the repository does not exist.

Request

NameType
repo_url string

Response

NameType
status int32

AddMirror

Add a mirror to a repository. This will overwrite the mirror if it already exists.

Arguments: * repo_url is repository that corresponds with this mirror. * mirror_url is mirror URL to add to the resolver.

Return Values: * ZX_OK if the mirror was removed. * ZX_ERR_ALREADY_EXISTS if the mirror for this repository already exists. * ZX_ERR_INVALID_ARGS if the repo_url or the mirror is malformed. * ZX_ERR_NOT_FOUND if the repository does not exist.

Request

NameType
repo_url string
mirror MirrorConfig

Response

NameType
status int32

RemoveMirror

Remove a mirror from a repository.

Removing a mirror will prevent future packages from being cached from that mirror, but in-flight downloads may not be interrupted.

Arguments: * repo_url the URL of the mirror's repository. * mirror_url the URL of the mirror we want to remove.

Return Values: * ZX_OK if the mirror was removed. * ZX_ERR_INVALID_ARGS if the repo_url or the mirror_url is malformed. * ZX_ERR_NOT_FOUND if the repository or mirror does not exist.

Request

NameType
repo_url string
mirror_url string

Response

NameType
status int32

List

Return an iterator over all repositories.

Arguments: iterator is a request for an iterator.

Request

NameType
iterator request<RepositoryIterator>

RepositoryIterator

Defined in fuchsia.pkg/repo.fidl

The iterator over all the repositories defined in a PackageResolver.

Next

Advance the iterator and return the next batch of repositories.

Return Values: * a vector of RepositoryConfig repositories. Will return an empty vector when there are no more repositories.

Request

NameType

Response

NameType
repos vector<RepositoryConfig>

PackageResolver

Defined in fuchsia.pkg/resolver.fidl

Resolves packages from a registry.

This interface is intended to be implemented by package resolver components, and used by repository administration tools.

Resolve

Populates or updates 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_url The package URL for a package (TODO: link to docs). * 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_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.

Request

NameType
package_url string
selectors vector<string>
update_policy UpdatePolicy
dir request<fuchsia.io/Directory>

Response

NameType
status int32

SystemBlobAdmin

Defined in fuchsia.pkg/system_blob_admin.fidl

Administrates the critical system blobs on the system.

ReleaseRetainedBlobs

Allows blobs from old system versions to be garbage collected. The current system blobs will not be collected.

Request

NameType

RetainBlobs

Adds the blobs listed in the retention_index blob to the retention list. This should be called during a system upgrade with the new system blob in order to make sure they are not garbage collected before the upgrade completes.

Arguments: * retention_index is the blob id for a list of blobs to retain.

Return Values: * ZX_OK if the blobs were successfully retained. * ZX_ERR_IO if there is some other unspecified error during I/O. * ZX_ERR_NOT_FOUND if the retention_index could not be found on the local system.

Request

NameType
retention_index BlobId

Response

NameType
status int32

STRUCTS

BlobId

Defined in fuchsia.pkg/common.fidl

BlobId is a content-addressed merkle root that describes an artifact that is tracked by the packaging system.

NameTypeDescriptionDefault
merkle_root uint8[32] No default

BlobInfo

Defined in fuchsia.pkg/common.fidl

BlobInfo is a tuple of the content-addressed merkle root for an artifact, along with that artifact's length in bytes.

NameTypeDescriptionDefault
blob_id BlobId No default
length uint64 No default

UpdatePolicy

Defined in fuchsia.pkg/resolver.fidl

The UpdatePolicy provides different policies to be used when the PackageResolver is fetching packages.

NameTypeDescriptionDefault
fetch_if_absent bool Should the resolver fetch the package if it is not present on the local system. No default
allow_old_versions bool Should the resolver allow old versions of the package to be used. No default

ENUMS

ExperimentToggle

Type: uint64

Defined in fuchsia.pkg/admin.fidl

List of known experiment toggles

NameValueDescription
LIGHTBULB 0 Does nothing, but visible in inspect.
DOWNLOAD_BLOB 1 Perform blob downloading in the package resolver instead of amber.

TABLES

RepositoryConfig

Defined in fuchsia.pkg/repo.fidl

Describes the configuration necessary to connect to a repository and it's mirrors.

OrdinalNameTypeDescription
1 repo_url string A fuchsia-pkg URL identifying the repository. Required. Example: fuchsia-pkg://example.com/
2 root_keys vector<RepositoryKeyConfig> A vector of public keys. Required. These keys must match one of the trusted keys known to the system.
3 mirrors vector<MirrorConfig> The repository mirrors that serve the package contents. Required.
4 update_package_url string The package URL of the system update package. Optional. Only used for the fuchsia-pkg://fuchsia.com/ repo.

MirrorConfig

Defined in fuchsia.pkg/repo.fidl

Describes the configuration necessary to connect to a mirror.

OrdinalNameTypeDescription
1 mirror_url string The base URL of the TUF metadata on this mirror. Required.
2 subscribe bool Whether or not to automatically monitor the mirror for updates. Required.
3 blob_key RepositoryBlobKey The private (or symmetric) key used to decrypt blobs fetched from this mirror. Optional.
4 blob_mirror_url string The URL where blobs from this mirror should be fetched. Optional. Defaults to `mirror_url + "/blobs"`.

XUNIONS

RepositoryKeyConfig

Defined in fuchsia.pkg/repo.fidl

Describes the keys used by the repository to authenticate it's packages.

The only supported algorithm at the moment is ed25519.

NameTypeDescription
ed25519_key vector<uint8> The raw ed25519 public key as binary data.

RepositoryBlobKey

Defined in fuchsia.pkg/repo.fidl

Describes a key used to decrypt blobs.

The only supported algorithm at the moment is aes.

NameTypeDescription
aes_key vector<uint8> A raw aes key as binary data.