/ 
Net-Blossom-Server-0.001003
/ Net::Blossom::Server::BlobStore

NAME

Net::Blossom::Server::BlobStore - Byte storage contract for Blossom backends

DESCRIPTION

Net::Blossom::Server::BlobStore documents and validates the component that stores blob bytes. Metadata stores refer to bytes through opaque storage keys.

Uploads use a two-phase lifecycle. prepare stages bytes and returns a storage key while the coordinating metadata transaction is open. After that transaction succeeds, commit finalizes local upload resources. abort discards an unfinished or rolled-back upload.

STORE METHODS

deploy_schema

Creates any byte-storage tables required by the implementation. Stores without a database schema may implement this as a no-op.

begin_upload

my $upload = $blobs->begin_upload(%context);

Starts an upload and returns a blob upload writer. The context is the same as for "begin_upload" in Net::Blossom::Server::Storage.

get_blob

my $body = $blobs->get_blob($storage_key);

Returns blob bytes as a scalar or stream object, or undef when absent.

get_blob_range

my $body = $blobs->get_blob_range(
    $storage_key,
    offset => $offset,
    length => $length,
    size   => $size,
);

Optional method for efficient byte-range reads. offset is zero-based and length is positive. It returns exactly length bytes as a scalar or stream, or undef when the storage key is absent. size may be supplied as the expected full blob size.

delete_blob

my $deleted = $blobs->delete_blob($storage_key);

Deletes the bytes identified by $storage_key and reports whether they existed. A database blob store must perform deletion in the transaction that removes the corresponding metadata and reject the call when that transaction is not active.

required_methods

Returns the method names required from a blob store.

required_upload_methods

Returns the method names required from a blob upload writer.

assert_implements

Net::Blossom::Server::BlobStore->assert_implements($blobs);

Croaks unless $blobs is an object implementing the store contract.

assert_upload

Net::Blossom::Server::BlobStore->assert_upload($upload);

Croaks unless $upload is an object implementing the upload contract.

UPLOAD METHODS

write

$upload->write($bytes);

Appends one byte chunk to the staged upload.

prepare

my $storage_key = $upload->prepare(%metadata);

Stages the bytes and returns their opaque storage key. Before metadata commits, the bytes must either be durable already or be part of the same database transaction. A database blob store must reject the call when its paired metadata transaction is not active. %metadata contains sha256, size, type, uploaded, and optionally pubkey.

commit

$upload->commit;

Marks a prepared upload successful and releases staging resources. A coordinator must not report a durable upload as failed solely because this post-commit cleanup fails.

abort

$upload->abort;

Discards staging resources. It must be safe to call more than once. It must not delete pre-existing bytes that use the same storage key.