Google is committed to advancing racial equity for Black communities. See how.

fuchsia.pkg

PROTOCOLS

FontResolver

Defined in fuchsia.pkg/font_resolver.fidl

This resolves font packages from a registry.

This 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 update_policy the freshness and caching policies to be used when the FontResolver is fetching packages.
  • request directory_request a 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.
  • error a zx_status value indicating failure. One of the following:
    • 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
update_policy UpdatePolicy
directory_request request<fuchsia.io/Directory>

Response

NameType
result FontResolver_Resolve_Result

LocalMirror

Defined in fuchsia.pkg/local_mirror.fidl

A collection of TUF repositories contained in an attached storage device.

GetBlob

Obtains and returns a blob from an attached storage device.

  • request blob_id the id of the blob to return.
  • request blob a server end for a blob file to be opened with OPEN_RIGHT_READABLE | OPEN_FLAG_DESCRIBE. If the blobs directory exists but the requested file does not, the client end will receive an OnOpen with Status::NOT_FOUND.
  • error a GetBlobError value

Request

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

Response

NameType
result LocalMirror_GetBlob_Result

GetMetadata

Obtains and returns a named TUF metadata file from an attached storage device.

  • request repo_url the URL of the TUF repository for which to return metadata.
  • request path the path of the metadata file, relative to the repository_metadata directory for the specific TUF repository.
  • request metadata a server end for a TUF metadata file to be opened with OPEN_RIGHT_READABLE | OPEN_FLAG_DESCRIBE. If the metadata directory exists but the requested file does not, the client end will receive an OnOpen with Status::NOT_FOUND.
  • error a GetMetadataError value

Request

NameType
repo_url RepositoryUrl
path string[4096]
metadata request<fuchsia.io/File>

Response

NameType
result LocalMirror_GetMetadata_Result

NeededBlobs

Defined in fuchsia.pkg/cache.fidl

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.

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.

  • response blobs the vector of missing blobs.

Request

NameType

Response

NameType
blobs vector<BlobInfo>

Open

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.

Request

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

Response

NameType
result NeededBlobs_Open_Result

PackageCache

Defined in fuchsia.pkg/cache.fidl

This manages the system package cache.

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

BasePackageIndex

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.

Request

NameType
iterator request<PackageIndexIterator>

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 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.

Request

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

Response

NameType
result PackageCache_Get_Result

Open

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.

Request

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

Response

NameType
result PackageCache_Open_Result

Sync

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.

Request

NameType

Response

NameType
result PackageCache_Sync_Result

PackageIndexIterator

Defined in fuchsia.pkg/cache.fidl

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).

Next

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.

Request

NameType

Response

NameType
entries vector<PackageIndexEntry>[32]

PackageResolver

Defined in fuchsia.pkg/resolver.fidl

This resolves packages from a repository.

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

GetHash

Determines the hash of a package.

  • request package_url the package URL for a package.
  • response meta_far_blob_id the hash of the package.
  • error a zx_status value indicating failure. One of the following:
    • ZX_ERR_INTERNAL if the resolver encountered an otherwise unspecified error while handling the request
    • ZX_ERR_NOT_FOUND if the package does not exist.
    • ZX_ERR_ADDRESS_UNREACHABLE if the resolver does not know about the repo.

Request

NameType
package_url PackageUrl

Response

NameType
result PackageResolver_GetHash_Result

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.

  • request package_url the package URL for a package (TODO: link to docs).
  • request selectors the package selectors (TODO: link to docs).
  • request update_policy the policy to use when fetching packages.
  • 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_ACCESS_DENIED if the resolver does not have permission to fetch a package blob.
    • ZX_ERR_INTERNAL if the resolver encountered an otherwise unspecified error while handling the request
    • 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_ADDRESS_UNREACHABLE if the resolver does not know about the repo.
    • 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
result PackageResolver_Resolve_Result

PackageResolverAdmin

Defined in fuchsia.pkg/admin.fidl

This 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 experiment should be set to.

Request

NameType
experiment_id ExperimentToggle
state bool

Response

NameType

RepositoryIterator

Defined in fuchsia.pkg/repo.fidl

The iterator over all the repositories defined in a PackageResolver.

Next

Advances the iterator and returns the next batch of repositories.

  • response repos a vector of RepositoryConfig repositories. Will return an empty vector when there are no more repositories.

Request

NameType

Response

NameType
repos vector<RepositoryConfig>

RepositoryManager

Defined in fuchsia.pkg/repo.fidl

This manages package repositories.

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

Add

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

  • request repo a repository to add to the resolver.
  • error a zx_status value indicating failure. One of the following:
    • ZX_ERR_ACCESS_DENIED if editing repositories is permanently disabled.
    • ZX_ERR_ALREADY_EXISTS if the repository already exists.
    • ZX_ERR_INVALID_ARGS if the repository is malformed.

Request

NameType
repo RepositoryConfig

Response

NameType
result RepositoryManager_Add_Result

AddMirror

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

  • request repo_url the URL of the repository to add the mirror to.
  • request mirror the mirror config used to add the mirror.
  • error a zx_status value indicating failure. One of the following:
    • 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
result RepositoryManager_AddMirror_Result

List

Returns an iterator over all repositories.

  • request iterator a request for an iterator.

Request

NameType
iterator request<RepositoryIterator>

Remove

Removes a repository.

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

  • request repo_url the URL of the repository we want to remove.
  • error a zx_status value indicating failure. One of the following:
    • ZX_ERR_ACCESS_DENIED if editing repositories is permanently disabled or the repo_url matches a static repository.
    • ZX_ERR_INVALID_ARGS if the repo_url is malformed.
    • ZX_ERR_NOT_FOUND if the repository does not exist.

Request

NameType
repo_url string

Response

NameType
result RepositoryManager_Remove_Result

RemoveMirror

Removes 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.

  • request repo_url the URL of the mirror's repository.
  • request mirror_url the URL of the mirror we want to remove.
  • error a zx_status value indicating failure. One of the following:
    • 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
result RepositoryManager_RemoveMirror_Result

STRUCTS

BlobId

Defined in fuchsia.pkg/common.fidl

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

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

FontResolver_Resolve_Response

Defined in fuchsia.pkg/font_resolver.fidl

NameTypeDescriptionDefault

LocalMirror_GetBlob_Response

Defined in fuchsia.pkg/local_mirror.fidl

NameTypeDescriptionDefault

LocalMirror_GetMetadata_Response

Defined in fuchsia.pkg/local_mirror.fidl

NameTypeDescriptionDefault

NeededBlobs_Open_Response

Defined in fuchsia.pkg/cache.fidl

NameTypeDescriptionDefault

PackageCache_Get_Response

Defined in fuchsia.pkg/cache.fidl

NameTypeDescriptionDefault

PackageCache_Open_Response

Defined in fuchsia.pkg/cache.fidl

NameTypeDescriptionDefault

PackageCache_Sync_Response

Defined in fuchsia.pkg/cache.fidl

NameTypeDescriptionDefault

PackageIndexEntry

Defined in fuchsia.pkg/common.fidl

A single entry in the package index.

NameTypeDescriptionDefault
package_url PackageUrl No default
meta_far_blob_id BlobId No default

PackageResolver_GetHash_Response

Defined in fuchsia.pkg/resolver.fidl

NameTypeDescriptionDefault
meta_far_blob_id BlobId No default

PackageResolver_Resolve_Response

Defined in fuchsia.pkg/resolver.fidl

NameTypeDescriptionDefault

PackageUrl

Defined in fuchsia.pkg/common.fidl

A fuchsia-pkg:// URL indicating a package. https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#package_identity

NameTypeDescriptionDefault
url string[2048] No default

RepositoryManager_AddMirror_Response

Defined in fuchsia.pkg/repo.fidl

NameTypeDescriptionDefault

RepositoryManager_Add_Response

Defined in fuchsia.pkg/repo.fidl

NameTypeDescriptionDefault

RepositoryManager_RemoveMirror_Response

Defined in fuchsia.pkg/repo.fidl

NameTypeDescriptionDefault

RepositoryManager_Remove_Response

Defined in fuchsia.pkg/repo.fidl

NameTypeDescriptionDefault

RepositoryUrl

Defined in fuchsia.pkg/common.fidl

A fuchsia-pkg:// URL indicating a repository. https://fuchsia.dev/fuchsia-src/concepts/packages/package_url#repository_identity

NameTypeDescriptionDefault
url string[2048] No default

UpdatePolicy

Defined in fuchsia.pkg/resolver.fidl

The policy to use when resolving packages.

NameTypeDescriptionDefault
fetch_if_absent bool

Whether the resolver should fetch the package if it is not present on the local system.

No default
allow_old_versions bool

Whether the resolver should 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

This does nothing, but is visible in inspect.

GetBlobError

Type: uint32

Defined in fuchsia.pkg/local_mirror.fidl

Error type for LocalMirror.GetBlob.

NameValueDescription
ERROR_OPENING_BLOB 1

An error occurred when opening the requested blob. This may (though does not necessarily) indicate the blobs directory does not exist.

GetMetadataError

Type: uint32

Defined in fuchsia.pkg/local_mirror.fidl

Error type for LocalMirror.GetMetadata.

NameValueDescription
ERROR_OPENING_METADATA 1

An error occurred when opening the requested metadata file. This may (though does not necessarily) indicate the metadata directory does not exist.

TABLES

MirrorConfig

Defined in fuchsia.pkg/repo.fidl

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
4 blob_mirror_url string

The URL where blobs from this mirror should be fetched. Optional. Defaults to mirror_url + "/blobs".

RepositoryConfig

Defined in fuchsia.pkg/repo.fidl

The configuration necessary to connect to a repository and its 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 that have signed the initial trusted root metadata. 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.

5 root_version uint32

The initial trusted root metadata version. Optional, defaulting to 1.

This value describes the initial root metadata version the resolver will fetch to initialize trust, once it's signatures has been verified by the root_keys. It will then walk the chain of N+1, N+2, and etc to the latest version before the resolver fetches any targets.

It is recommended that this root_version number and root_keys are kept reasonably in sync with the most recent published version of the root metadata, as that avoids the risk of an old and unused root key being used to compromise resolvers during the trust initialization.

6 root_threshold uint32

The number of root_keys that need to have signed the root metadata for it to be considered trusted. This value must be greater than or equal to 1. Optional, defaulting to 1.

7 use_local_mirror bool

Whether the package resolver should check attached storage for blobs and repository metadata.

UNIONS

FontResolver_Resolve_Result

Defined in fuchsia.pkg/font_resolver.fidl

NameTypeDescription
response FontResolver_Resolve_Response
err zx/status

LocalMirror_GetBlob_Result

Defined in fuchsia.pkg/local_mirror.fidl

NameTypeDescription
response LocalMirror_GetBlob_Response
err GetBlobError

LocalMirror_GetMetadata_Result

Defined in fuchsia.pkg/local_mirror.fidl

NameTypeDescription
response LocalMirror_GetMetadata_Response
err GetMetadataError

NeededBlobs_Open_Result

Defined in fuchsia.pkg/cache.fidl

NameTypeDescription
response NeededBlobs_Open_Response
err zx/status

PackageCache_Get_Result

Defined in fuchsia.pkg/cache.fidl

NameTypeDescription
response PackageCache_Get_Response
err zx/status

PackageCache_Open_Result

Defined in fuchsia.pkg/cache.fidl

NameTypeDescription
response PackageCache_Open_Response
err zx/status

PackageCache_Sync_Result

Defined in fuchsia.pkg/cache.fidl

NameTypeDescription
response PackageCache_Sync_Response
err zx/status

PackageResolver_GetHash_Result

Defined in fuchsia.pkg/resolver.fidl

NameTypeDescription
response PackageResolver_GetHash_Response
err zx/status

PackageResolver_Resolve_Result

Defined in fuchsia.pkg/resolver.fidl

NameTypeDescription
response PackageResolver_Resolve_Response
err zx/status

RepositoryKeyConfig

Defined in fuchsia.pkg/repo.fidl

The keys used by the repository to authenticate its packages.

The only supported algorithm at the moment is ed25519.

NameTypeDescription
ed25519_key vector<uint8>

The raw ed25519 public key as binary data.

RepositoryManager_AddMirror_Result

Defined in fuchsia.pkg/repo.fidl

NameTypeDescription
response RepositoryManager_AddMirror_Response
err zx/status

RepositoryManager_Add_Result

Defined in fuchsia.pkg/repo.fidl

NameTypeDescription
response RepositoryManager_Add_Response
err zx/status

RepositoryManager_RemoveMirror_Result

Defined in fuchsia.pkg/repo.fidl

NameTypeDescription
response RepositoryManager_RemoveMirror_Response
err zx/status

RepositoryManager_Remove_Result

Defined in fuchsia.pkg/repo.fidl

NameTypeDescription
response RepositoryManager_Remove_Response
err zx/status

CONSTANTS

NameValueTypeDescription
PACKAGE_INDEX_CHUNK_SIZE 32 uint32