streaming results from the CPAN

Net-Blossom-Server
Handles a normalized C<GET /E<lt>sha256E<gt>> request and returns a
C<Net::Blossom::Server::Response>. The request path must contain one lowercase
64-character SHA-256 hash segment and may include a file extension.

The method calls C<< $server->storage->get_blob($sha256) >>. It returns C<404>
when storage returns C<undef>. Otherwise, storage must return a
C<Net::Blossom::Server::BlobResult> whose descriptor C<sha256> matches the
request path. The response status is C<200>, the response body is the blob body,
and C<Content-Type> and C<Content-Length> come from the descriptor.

=head2 handle_head_blob

    my $response = $server->handle_head_blob($request);

Handles a normalized C<HEAD /E<lt>sha256E<gt>> request and returns the same
C<Content-Type> and C<Content-Length> headers as C<GET /E<lt>sha256E<gt>>
without returning the blob body. The request path may include a file extension.

If storage provides an optional C<head_blob($sha256)> method, that method is
used and may return either a L<Net::Blossom::BlobDescriptor> or a
L<Net::Blossom::Server::BlobResult>. Otherwise C<get_blob> is used and the body
is discarded.

=head2 handle_media

    my $response = $server->handle_media($request, %opts);

Handles a normalized C<PUT /media> request. The current implementation uses the
same identity byte path as C<PUT /upload>: it stores the received bytes without
media transformation and returns a blob descriptor JSON response with C<201> or
C<200>. When C<X-SHA-256> is present, a hash mismatch throws a typed C<409>
error before storage commit. C<Content-Length> mismatches throw a typed C<400>
error before storage commit.

Options:

=over 4

=item * C<pubkey>

Optional already-verified uploader public key as lowercase 64-character hex.

=back

=head2 handle_head_media

    my $response = $server->handle_head_media($request);

Handles a normalized C<HEAD /media> BUD-05 preflight request. It validates the
C<X-SHA-256>, C<X-Content-Type>, and C<X-Content-Length> headers and returns the
same status behavior as C<handle_head_upload>.

=head2 handle_mirror

    my $response = $server->handle_mirror($request, %opts);

Handles a normalized C<PUT /mirror> request. The request body must be a JSON
object with a C<url> field. The URL must use C<http> or C<https>, have a host,
must not include userinfo, and must not include a fragment.

The server calls the configured C<mirror_fetcher> with a streaming sink and stores
origin bytes as the fetcher writes them. SHA-256 calculation and storage commit
remain owned by the server core. A missing C<mirror_fetcher> returns C<503>.
Malformed mirror requests return C<400>. Origin fetch failures, unusable fetch
results, or origin content-length mismatches return C<502>.

The fetcher may be a code reference called with C<$url> and C<< sink => $sink >>,
or an object called as C<< $fetcher->fetch_blob($url, sink => $sink) >>. It must
call C<< $sink->start(%metadata) >> before writing bytes, then call
C<< $sink->write($chunk) >> for each scalar byte chunk. C<%metadata> may include
C<type> and C<content_length>; missing C<type> defaults to
C<application/octet-stream>. For empty origin bodies, the fetcher may instead
return a metadata hash reference and let the server start the sink. Returning a
C<body> value is not supported.

Options:

=over 4

=item * C<pubkey>

Optional already-verified uploader public key.

=item * C<authorization>

Optional L<Net::Blossom::Server::AuthorizationResult>. When provided, the
downloaded blob hash must match one of the authorized C<x> tag hashes before
storage commit, otherwise a typed C<409> error is thrown.

=back

=head2 handle_delete_blob

    my $response = $server->handle_delete_blob($request, pubkey => $pubkey);

Handles a normalized C<DELETE /E<lt>sha256E<gt>> request and returns a
C<Net::Blossom::Server::Response>. The request path must contain one lowercase
64-character SHA-256 hash segment.

C<pubkey> is required and must be the already-verified owner public key as
lowercase 64-character hex. Authorization event verification is deliberately
outside this method.

The method calls C<< $server->storage->delete_blob($sha256, pubkey => $pubkey) >>.
It returns C<204> when storage deletes an owner relationship and C<404> when
storage returns false.

=head2 handle_list_blobs

    my $response = $server->handle_list_blobs($request);

Handles a normalized C<GET /list/E<lt>pubkeyE<gt>> request and returns a
C<Net::Blossom::Server::Response>. The request path must contain one lowercase
64-character public key segment.

The method reads optional C<cursor> and C<limit> query parameters. C<cursor>
must be a lowercase 64-character SHA-256 hash. C<limit> must be a positive
integer no larger than C<max_list_limit>. Requests without C<limit> use
C<max_list_limit> as the default page size. Storage receives a bounded C<limit>
for every list request.
( run in 0.579 second using v1.01-cache-2.11-cpan-6aa56a78535 )