Enum NeededBlobsRequest

pub enum NeededBlobsRequest {
    OpenMetaBlob {
        responder: NeededBlobsOpenMetaBlobResponder,
    },
    GetMissingBlobs {
        iterator: ServerEnd<BlobInfoIteratorMarker>,
        control_handle: NeededBlobsControlHandle,
    },
    OpenBlob {
        blob_id: BlobId,
        responder: NeededBlobsOpenBlobResponder,
    },
    BlobWritten {
        blob_id: BlobId,
        responder: NeededBlobsBlobWrittenResponder,
    },
    Abort {
        responder: NeededBlobsAbortResponder,
    },
}

Represents the transaction for caching a particular package.

Server expects client to follow the normal operation sequence defined below. Violating the protocol (e.g. calling wrong methods at the wrong time) will result in the channel being closed by the package cache with a ZX_ERR_BAD_STATE epitaph and aborting the package cache operation. If a fatal error occurs at any step, server will close the channel, and client should not proceed with the sequence. Non-fatal errors could be retried, as long as the channel remains open.

Normal operation sequence:

1. Clients should start by requesting to OpenMetaBlob(), and fetch and write the metadata blob if needed, calling BlobWritten() when done to indicate the write is complete.
2. GetMissingBlobs() should be used to determine which blobs need to be fetched and written.
3. Each of the missing blobs needs to be written using OpenBlob() and BlobWritten() should be called after each blob is written.

Clients are responsible for avoiding concurrent creation of the same blob if the underlying blobstore does not support it. This manifests as the following constraints (applied per BlobId):

1. If the BlobWriter returned by calls to Open[Meta]Blob is the file variant, once Clients call Resize on a file, they must close all file connections obtained from Open[Meta]Blob before calling Open[Meta]Blob again.
2. If the BlobWriter returned by calls to Open[Meta]Blob is the writer variant, Clients must not write all the bytes to more than one of the writers. This applies per BlobId to all BlobWriters returned by all calls to Open[Meta]Blob across all NeededBlobs connections across all PackageCache connections. Once c++blobfs support is removed and fxblob is changed to support duplicate concurrent creation requests (https://fxbug.dev/335870456#comment9), this requirement can be dropped.

Once all needed blobs are written by the client, the package cache will complete the pending [PackageCache.Get] request and close this channel with a ZX_OK epitaph.

Variants

OpenMetaBlob

Opens the package’s metadata blob for writing. GetMissingBlobs() should not be called until writing the meta blob or this request responds with false.

If the package was already cached, server will close the channel with a ZX_OK epitaph.

• response writer is used to write the blob. If writer is absent, the blob is already cached and so does not need to be written.

• error an OpenBlobError indicating failure. Clients may retry this request, though the server end may abort this cache operation on errors it considers to be fatal.

Fields

responder: NeededBlobsOpenMetaBlobResponder

GetMissingBlobs

Returns an iterator of blobs that are not present on the system that must be written using the OpenBlob request before the package will be fully cached.

Client should call OpenMetaBlob, and write it if needed, before calling GetMissingBlobs.

A client should make this request no more than once per NeededBlobs connection. Once all blobs yielded by this iterator are written, the package open request will complete.

New items may be added to the obtained BlobInfoIterator as the client calls OpenBlob, so, to guaranatee termination of the iterator, clients should call OpenBlob concurrently with reading the iterator.

• request iterator a request for an iterator of BlobInfo of blobs that the client should try to write.

Fields

iterator: ServerEnd<BlobInfoIteratorMarker>

control_handle: NeededBlobsControlHandle

OpenBlob

Opens a blob for writing.

• request blob_id the blob id describing this blob.

• response writer is used to write the blob. If writer is absent, the blob is already cached and so does not need to be written.

• error an OpenBlobError indicating failure. Clients may retry this request, though the server end may abort this cache operation on errors it considers to be fatal.

Fields

blob_id: BlobId

responder: NeededBlobsOpenBlobResponder

BlobWritten

Indicates that a blob opened by Open[Meta]Blob has been successfully written.

A client should call this once the blob has been fully written using the writer returned by Open[Meta]Blob.

• request blob_id the blob id describing this blob.

• error a BlobWrittenError indicating failure. Clients may retry the Open[Meta]Blob request that prompted this call, though the server end may abort this cache operation on errors it considers to be fatal.

Fields

blob_id: BlobId

responder: NeededBlobsBlobWrittenResponder

Abort

Aborts this caching operation for the package.

Any open blobs and any missing blobs iterator will be closed. Any dir provided to the associated [PackageCache.Get] request will also be closed. Once this request is acknowledged, this channel will be closed.

Note, dropping this NeededBlobs channel without writing all needed blobs will also abort the package cache operation. However, this API provides the ability to wait for the operation to be torn down.

Fields

responder: NeededBlobsAbortResponder

Implementations

impl NeededBlobsRequest

pub fn into_open_meta_blob(self) -> Option<NeededBlobsOpenMetaBlobResponder>

pub fn into_get_missing_blobs( self, ) -> Option<(ServerEnd<BlobInfoIteratorMarker>, NeededBlobsControlHandle)>

pub fn into_open_blob(self) -> Option<(BlobId, NeededBlobsOpenBlobResponder)>

pub fn into_blob_written( self, ) -> Option<(BlobId, NeededBlobsBlobWrittenResponder)>

pub fn into_abort(self) -> Option<NeededBlobsAbortResponder>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for NeededBlobsRequest

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.