Blossom/Client.pm

filter: Statementstmt 90.4% 19 / 21 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 92.8% 26 / 28 CC 1 SCAR 0.4
CC
1
Cov
90%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Blossom/ServerList.pm ↑ Summary
1 package Net::Blossom::Client;
2  
3 12 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 12 ▶use Net::Blossom::_ConstructorArgs ();
Subroutine BEGIN: called CC=1 SCAR=0.0
6 12 ▶use Net::Blossom::BlobDescriptor;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 12 ▶use Net::Blossom::Error;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 12 ▶use Net::Blossom::PaymentRequired;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 12 ▶use Net::Blossom::Response;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 0 ▶use Net::Blossom::ServerList;
Subroutine BEGIN: called CC=1 SCAR=2.6
11 use Net::Blossom::_Bech32 ();
12 use Net::Blossom::_CashuPaymentRequest ();
13 use Net::Blossom::_URL ();
14  
15 use Carp qw(croak);
16 use Class::Tiny qw(server auth), {
17 ua => sub { HTTP::Tiny->new },
18 };
19 use Digest::SHA qw(sha256_hex);
20 use HTTP::Tiny;
21 use JSON ();
22 use Net::Nostr::Zap qw(bolt11_amount);
23 use Scalar::Util qw(blessed);
24  
25 my $HEX64 = qr/\A[0-9a-f]{64}\z/;
26 my $HEX128 = qr/\A[0-9a-f]{128}\z/;
27 my $JSON = JSON->new->utf8;
28 my $CANONICAL_JSON = JSON->new->utf8->canonical;
29 my %RESERVED_PAYMENT_METHOD = map { $_ => 1 } qw(reason sha-256 content-type content-length);
30  
31 sub BUILDARGS {
32 my $class = shift;
33 my %args = Net::Blossom::_ConstructorArgs::normalize(@_);
34 my %known = map { $_ => 1 } qw(server ua auth);
35 my @unknown = grep { !exists $known{$_} } keys %args;
36 croak "unknown argument(s): " . join(', ', sort @unknown) if @unknown;
37 return \%args;
38 }
39  
40 sub BUILD {
41 my ($self) = @_;
42 croak "server is required" unless defined $self->server && length $self->server;
43 croak "server must be an http(s) base URL" if ref($self->server);
44 croak "server must be an http(s) base URL" unless _valid_server_url($self->server);
45  
46 (my $server = $self->server) =~ s{/+\z}{};
47 $self->server($server);
48 $self->ua(HTTP::Tiny->new) unless defined $self->ua;
49 return;
50 }
51  
52 sub get_blob {
53 my $self = shift;
54 my ($sha256, %opts) = @_;
55 _validate_options(\%opts, qw(extension range payment));
56 _validate_sha256($sha256);
57  
58 my %headers;
59 $headers{Range} = $opts{range} if defined $opts{range};
60  
61 return $self->_request(
62 method => 'GET',
63 path => $self->_blob_path($sha256, $opts{extension}),
64 headers => \%headers,
65 action => 'get',
66 sha256 => $sha256,
67 payment => $opts{payment},
68 ok => { map { $_ => 1 } qw(200 206 307 308) },
69 );
70 }
71  
72 sub head_blob {
73 my $self = shift;
74 my ($sha256, %opts) = @_;
75 _validate_options(\%opts, qw(extension payment));
76 _validate_sha256($sha256);
77  
78 return $self->_request(
79 method => 'HEAD',
80 path => $self->_blob_path($sha256, $opts{extension}),
81 action => 'get',
82 sha256 => $sha256,
83 payment => $opts{payment},
84 ok => { map { $_ => 1 } qw(200 307 308) },
85 );
86 }
87  
88 sub upload_blob {
89 my $self = shift;
90 my ($content, %opts) = @_;
91 _validate_options(\%opts, qw(type payment));
92 croak "content is required" unless defined $content;
93  
94 my $sha256 = sha256_hex($content);
95 my %headers = (
96 'Content-Type' => $opts{type} || 'application/octet-stream',
97 'Content-Length' => length($content),
98 'X-SHA-256' => $sha256,
99 );
100  
101 my $response = $self->_request(
102 method => 'PUT',
103 path => '/upload',
104 headers => \%headers,
105 content => $content,
106 action => 'upload',
107 sha256 => $sha256,
108 payment => $opts{payment},
109 ok => { 200 => 1, 201 => 1 },
110 );
111  
112 return Net::Blossom::BlobDescriptor->from_hash(_decode_json_hash($response->content));
113 }
114  
115 sub head_upload {
116 my $self = shift;
117 my ($content, %opts) = @_;
118 _validate_options(\%opts, qw(type payment));
119 croak "content is required" unless defined $content;
120  
121 my $sha256 = sha256_hex($content);
122 my %headers = (
123 'X-SHA-256' => $sha256,
124 'X-Content-Type' => $opts{type} || 'application/octet-stream',
125 'X-Content-Length' => length($content),
126 );
127  
128 return $self->_request(
129 method => 'HEAD',
130 path => '/upload',
131 headers => \%headers,
132 action => 'upload',
133 sha256 => $sha256,
134 payment => $opts{payment},
135 ok => { 200 => 1 },
136 );
137 }
138  
139 sub process_media {
140 my $self = shift;
141 my ($content, %opts) = @_;
142 _validate_options(\%opts, qw(type payment));
143 croak "content is required" unless defined $content;
144  
145 my $sha256 = sha256_hex($content);
146 my %headers = (
147 'Content-Type' => $opts{type} || 'application/octet-stream',
148 'Content-Length' => length($content),
149 'X-SHA-256' => $sha256,
150 );
151  
152 my $response = $self->_request(
153 method => 'PUT',
154 path => '/media',
155 headers => \%headers,
156 content => $content,
157 action => 'media',
158 sha256 => $sha256,
159 payment => $opts{payment},
160 ok => { 200 => 1, 201 => 1 },
161 );
162  
163 return Net::Blossom::BlobDescriptor->from_hash(_decode_json_hash($response->content));
164 }
165  
166 sub head_media {
167 my $self = shift;
168 my ($content, %opts) = @_;
169 _validate_options(\%opts, qw(type payment));
170 croak "content is required" unless defined $content;
171  
172 my $sha256 = sha256_hex($content);
173 my %headers = (
174 'X-SHA-256' => $sha256,
175 'X-Content-Type' => $opts{type} || 'application/octet-stream',
176 'X-Content-Length' => length($content),
177 );
178  
179 return $self->_request(
180 method => 'HEAD',
181 path => '/media',
182 headers => \%headers,
183 action => 'media',
184 sha256 => $sha256,
185 payment => $opts{payment},
186 ok => { 200 => 1 },
187 );
188 }
189  
190 sub upload_blob_to_servers {
191 my $self = shift;
192 my ($content, $servers, %opts) = @_;
193 _validate_options(\%opts, qw(type payment));
194 my @servers = _server_values($servers);
195  
196 return $self->_client_for_server($servers[0])->upload_blob($content, %opts);
197 }
198  
199 sub mirror_blob {
200 my $self = shift;
201 my ($url, %opts) = @_;
202 _validate_options(\%opts, qw(payment));
203 croak "url is required" unless defined $url && length $url;
204 croak "url must be a string" if ref($url);
205  
206 my $content = $CANONICAL_JSON->encode({ url => $url });
207 my %headers = (
208 'Content-Type' => 'application/json',
209 'Content-Length' => length($content),
210 );
211 my ($sha256) = Net::Blossom::ServerList->extract_blob_reference($url);
212  
213 my $response = $self->_request(
214 method => 'PUT',
215 path => '/mirror',
216 headers => \%headers,
217 content => $content,
218 action => 'upload',
219 sha256 => $sha256,
220 payment => $opts{payment},
221 ok => { 200 => 1, 201 => 1 },
222 );
223  
224 return Net::Blossom::BlobDescriptor->from_hash(_decode_json_hash($response->content));
225 }
226  
227 sub report_blob {
228 my $self = shift;
229 my ($event, %opts) = @_;
230 _validate_options(\%opts, qw(payment));
231 _validate_report_event($event);
232  
233 my $content = $CANONICAL_JSON->encode(_report_event_wire_form($event));
234 my %headers = (
235 'Content-Type' => 'application/json',
236 'Content-Length' => length($content),
237 );
238  
239 return $self->_request(
240 method => 'PUT',
241 path => '/report',
242 headers => \%headers,
243 content => $content,
244 action => 'report',
245 payment => $opts{payment},
246 ok => { map { $_ => 1 } 200 .. 299 },
247 );
248 }
249  
250 sub list_blobs {
251 my $self = shift;
252 my ($pubkey, %opts) = @_;
253 _validate_options(\%opts, qw(cursor limit since until payment));
254 croak "pubkey must be 64-char lowercase hex" unless defined $pubkey && $pubkey =~ $HEX64;
255  
256 my @query;
257 for my $field (qw(cursor limit since until)) {
258 next unless defined $opts{$field};
259 push @query, _uri_escape($field) . '=' . _uri_escape($opts{$field});
260 }
261  
262 my $path = "/list/$pubkey";
263 $path .= '?' . join('&', @query) if @query;
264  
265 my $response = $self->_request(
266 method => 'GET',
267 path => $path,
268 action => 'list',
269 payment => $opts{payment},
270 ok => { 200 => 1 },
271 );
272  
273 my $data = _decode_json($response->content);
274 croak "list response must be a JSON array" unless ref($data) eq 'ARRAY';
275 return [map { Net::Blossom::BlobDescriptor->from_hash($_) } @$data];
276 }
277  
278 sub delete_blob {
279 my $self = shift;
280 my ($sha256, %opts) = @_;
281 _validate_options(\%opts, qw(payment));
282 _validate_sha256($sha256);
283  
284 return $self->_request(
285 method => 'DELETE',
286 path => "/$sha256",
287 action => 'delete',
288 sha256 => $sha256,
289 payment => $opts{payment},
290 ok => { 200 => 1, 204 => 1 },
291 );
292 }
293  
294 sub get_blob_from_servers {
295 my $self = shift;
296 my ($url, $servers, %opts) = @_;
297 _validate_options(\%opts, qw(extension range payment));
298 my ($sha256, $extension) = Net::Blossom::ServerList->extract_blob_reference($url);
299 croak "URL does not contain a sha256 hash" unless defined $sha256;
300  
301 my @servers = _server_values($servers);
302 my $last_error;
303  
304 for my $server (@servers) {
305 my %get_opts = %opts;
306 $get_opts{extension} = $extension
307 if defined $extension && !defined $get_opts{extension};
308  
309 my $response = eval {
310 $self->_client_for_server($server)->get_blob($sha256, %get_opts);
311 };
312 return $response unless $@;
313  
314 my $error = $@;
315 die $error unless ref($error) && eval { $error->isa('Net::Blossom::Error') };
316 $last_error = $error;
317 }
318  
319 die $last_error if defined $last_error;
320 croak "server list must contain at least one server";
321 }
322  
323 sub _request {
324 my $self = shift;
325 my %args = @_;
326 my $method = $args{method};
327 my $url = $self->server . $args{path};
328 my %headers = %{ $args{headers} || {} };
329  
330 if (defined $args{payment}) {
331 croak "payment proof headers are not allowed on HEAD requests"
332 if $method eq 'HEAD';
333 my %payment_headers = _payment_headers($args{payment});
334 @headers{keys %payment_headers} = values %payment_headers;
335 }
336  
337 if (my $authorization = $self->_authorization_header(%args, url => $url)) {
338 $headers{Authorization} = $authorization;
339 }
340  
341 my %request = (headers => \%headers);
342 $request{content} = $args{content} if exists $args{content};
343  
344 my $raw = $self->ua->request($method, $url, \%request);
345 my $response = Net::Blossom::Response->new(
346 method => $method,
347 url => $url,
348 status => $raw->{status},
349 reason => $raw->{reason},
350 headers => $raw->{headers} || {},
351 content => $raw->{content},
352 );
353  
354 my $ok = $args{ok} || {};
355 return $response if $ok->{$response->status};
356  
357 if ($response->status == 402) {
358 die Net::Blossom::PaymentRequired->new(
359 method => $method,
360 url => $url,
361 status => $response->status,
362 reason => $response->reason,
363 x_reason => $response->header('x-reason'),
364 headers => $response->headers,
365 body => $response->content,
366 payment_challenges => _payment_challenges($response->headers),
367 );
368 }
369  
370 die Net::Blossom::Error->new(
371 method => $method,
372 url => $url,
373 status => $response->status,
374 reason => $response->reason,
375 x_reason => $response->header('x-reason'),
376 headers => $response->headers,
377 body => $response->content,
378 );
379 }
380  
381 sub _client_for_server {
382 my ($self, $server) = @_;
383 return ref($self)->new(
384 server => $server,
385 ua => $self->ua,
386 auth => $self->auth,
387 );
388 }
389  
390 sub _authorization_header {
391 my $self = shift;
392 my %args = @_;
393 return undef unless defined $self->auth;
394 return $self->auth unless ref $self->auth;
395 my %context = (
396 method => $args{method},
397 url => $args{url},
398 action => $args{action},
399 sha256 => $args{sha256},
400 );
401  
402 return $self->auth->(%context) if ref($self->auth) eq 'CODE';
403  
404 if (blessed($self->auth) && $self->auth->can('authorization_header')) {
405 # A fixed-action token (e.g. Net::Blossom::AuthToken) carries a single
406 # BUD-11 't' verb. Sending it on an endpoint with a different action
407 # produces an authorization event every conformant server rejects, and
408 # leaks the token's capability onto that request, so refuse the mismatch.
409 if ($self->auth->can('action')) {
410 my $token_action = $self->auth->action;
411 if (defined $token_action
412 && defined $context{action}
413 && $token_action ne $context{action}) {
414 croak "auth token action '$token_action' does not match "
415 . "request action '$context{action}'";
416 }
417 }
418 return $self->auth->authorization_header(%context);
419 }
420  
421 croak "auth must be a string, code reference, or object with authorization_header";
422 }
423  
424 sub _server_values {
425 my ($servers) = @_;
426 croak "servers are required" unless defined $servers;
427  
428 return @{$servers->servers}
429 if ref($servers) && eval { $servers->isa('Net::Blossom::ServerList') };
430  
431 croak "servers must be a Net::Blossom::ServerList or array reference"
432 unless ref($servers) eq 'ARRAY';
433  
434 return @{Net::Blossom::ServerList->new(servers => $servers)->servers};
435 }
436  
437 sub _payment_headers {
438 my ($payment) = @_;
439 croak "payment must be a hash reference" unless ref($payment) eq 'HASH';
440  
441 my %headers;
442 for my $method (sort keys %$payment) {
443 my $normalized = _normalize_payment_method($method);
444 my $proof = $payment->{$method};
445 croak "payment proof for $normalized is required"
446 unless defined $proof && length $proof;
447 croak "payment proof for $normalized must be a scalar" if ref($proof);
448 $headers{_payment_header_name($normalized)} = $proof;
449 }
450  
451 croak "payment requires at least one proof" unless %headers;
452 return %headers;
453 }
454  
455 sub _validate_options {
456 my ($opts, @known) = @_;
457 my %known = map { $_ => 1 } @known;
458 my @unknown = grep { !exists $known{$_} } keys %$opts;
459 croak "unknown option(s): " . join(', ', sort @unknown) if @unknown;
460 }
461  
462 sub _payment_challenges {
463 my ($headers) = @_;
464 my %challenges;
465  
466 for my $header (sort keys %{$headers || {}}) {
467 next unless $header =~ /\AX-/i;
468 my $method = _payment_challenge_method($header);
469 next unless defined $method;
470 my $payload = $headers->{$header};
471 next if ref($payload);
472 next unless defined $payload && length $payload;
473 next unless _valid_payment_challenge($method, $payload);
474 $challenges{$method} = $payload;
475 }
476  
477 return \%challenges;
478 }
479  
480 sub _valid_payment_challenge {
481 my ($method, $payload) = @_;
482 return Net::Blossom::_CashuPaymentRequest::valid($payload) if $method eq 'cashu';
483 return _valid_lightning_challenge($payload) if $method eq 'lightning';
484 return 1;
485 }
486  
487 sub _valid_lightning_challenge {
488 my ($payload) = @_;
489 my ($hrp) = Net::Blossom::_Bech32::decode($payload, 1);
490 return 0 unless defined $hrp && $hrp =~ /\Aln(?:bc|tb|bcrt|sb)(?:\d+[munp]?)?\z/;
491 return eval { bolt11_amount(lc $payload); 1 } ? 1 : 0;
492 }
493  
494 sub _payment_challenge_method {
495 my ($method) = @_;
496 return undef unless defined $method && length $method;
497 $method =~ s/\AX-//i;
498 return undef unless $method =~ /\A[A-Za-z0-9][A-Za-z0-9-]*\z/;
499  
500 my $normalized = lc $method;
501 return undef if $RESERVED_PAYMENT_METHOD{$normalized};
502 return $normalized;
503 }
504  
505 sub _normalize_payment_method {
506 my ($method) = @_;
507 croak "payment method is required" unless defined $method && length $method;
508 $method =~ s/\AX-//i;
509 croak "payment method must be an X- header token"
510 unless $method =~ /\A[A-Za-z0-9][A-Za-z0-9-]*\z/;
511  
512 my $normalized = lc $method;
513 croak "payment method $normalized is reserved"
514 if $RESERVED_PAYMENT_METHOD{$normalized};
515 return $normalized;
516 }
517  
518 sub _payment_header_name {
519 my ($method) = @_;
520 return 'X-' . join '-', map { ucfirst lc $_ } split /-/, $method;
521 }
522  
523 sub _blob_path {
524 my ($self, $sha256, $extension) = @_;
525 return "/$sha256" unless defined $extension && length $extension;
526 croak "extension must contain only letters and digits"
527 unless $extension =~ /\A[A-Za-z0-9]+\z/;
528 return "/$sha256.$extension";
529 }
530  
531 sub _validate_sha256 {
532 my ($sha256) = @_;
533 croak "sha256 must be 64-char lowercase hex"
534 unless defined $sha256 && $sha256 =~ $HEX64;
535 }
536  
537 sub _report_event_wire_form {
538 my ($event) = @_;
539  
540 # The event is already signed, so it must go on the wire with the JSON
541 # types NIP-01/NIP-56 define regardless of how the caller typed the fields
542 # in memory: kind and created_at are numbers, tag values are strings.
543 # Re-encoding a numeric field as a string (or vice versa) changes the
544 # serialization the signature was computed over and breaks verification.
545 my %wire = %$event;
546 $wire{kind} = 0 + $wire{kind};
547 $wire{created_at} = 0 + $wire{created_at};
548 $wire{content} = "$wire{content}" if defined $wire{content};
549 $wire{tags} = [map { [map { "$_" } @$_] } @{$wire{tags}}];
550  
551 return \%wire;
552 }
553  
554 sub _validate_report_event {
555 my ($event) = @_;
556 croak "report event must be a hash reference" unless ref($event) eq 'HASH';
557  
558 _validate_report_hex_field($event, 'id', $HEX64, '64-char lowercase hex');
559 _validate_report_hex_field($event, 'pubkey', $HEX64, '64-char lowercase hex');
560 _validate_report_hex_field($event, 'sig', $HEX128, '128-char lowercase hex');
561  
562 croak "report event created_at must be a non-negative integer"
563 unless defined $event->{created_at} && !ref($event->{created_at})
564 && $event->{created_at} =~ /\A\d+\z/;
565 croak "report event kind must be 1984"
566 unless defined $event->{kind} && !ref($event->{kind})
567 && $event->{kind} =~ /\A1984\z/;
568 croak "report event content must be a scalar"
569 unless defined $event->{content} && !ref($event->{content});
570 croak "report event tags must be an array reference"
571 unless ref($event->{tags}) eq 'ARRAY';
572  
573 my $has_x;
574 for my $tag (@{$event->{tags}}) {
575 croak "report event tags must be array references" unless ref($tag) eq 'ARRAY';
576 croak "report event tag values must be defined" if grep { !defined $_ } @$tag;
577 croak "report event tag values must be scalars" if grep { ref($_) } @$tag;
578  
579 next unless @$tag && $tag->[0] eq 'x';
580 croak "report x tags must contain a sha256 hash" unless @$tag >= 2;
581 croak "report x tag hash must be 64-char lowercase hex"
582 unless $tag->[1] =~ $HEX64;
583 $has_x = 1;
584 }
585  
586 croak "report event must contain at least one x tag" unless $has_x;
587 }
588  
589 sub _validate_report_hex_field {
590 my ($event, $field, $regex, $description) = @_;
591 croak "report event $field must be $description"
592 unless defined $event->{$field} && !ref($event->{$field})
593 && $event->{$field} =~ $regex;
594 }
595  
596 sub _decode_json_hash {
597 my ($content) = @_;
598 my $data = _decode_json($content);
599 croak "response body must be a JSON object" unless ref($data) eq 'HASH';
600 return $data;
601 }
602  
603 sub _decode_json {
604 my ($content) = @_;
605 my $data = eval { $JSON->decode($content) };
606 croak "invalid JSON response: $@" if $@;
607 return $data;
608 }
609  
610 sub _uri_escape {
611 my ($value) = @_;
612 $value = "$value";
613 $value =~ s/([^A-Za-z0-9_.~-])/sprintf("%%%02X", ord($1))/ge;
614 return $value;
615 }
616  
617 sub _valid_server_url {
618 my ($server) = @_;
619 return Net::Blossom::_URL::http_base_url($server);
620 }
621  
622 1;
623  
624 =pod
625  
626 =head1 NAME
627  
628 Net::Blossom::Client - HTTP client for Blossom servers
629  
630 =head1 SYNOPSIS
631  
632 use Net::Blossom::Client;
633  
634 my $client = Net::Blossom::Client->new(
635 server => 'https://cdn.example.com',
636 auth => sub {
637 my %ctx = @_;
638 return build_authorization_header(%ctx);
639 },
640 );
641  
642 my $response = $client->get_blob($sha256);
643 my $blob = $client->upload_blob($bytes, type => 'image/png');
644 my $blobs = $client->list_blobs($pubkey, limit => 20);
645  
646 =head1 DESCRIPTION
647  
648 C<Net::Blossom::Client> sends HTTP requests to one Blossom server. It implements
649 client support for the currently supported Blossom BUDs in this distribution,
650 including blob get/head/upload/delete, mirror requests, media processing,
651 upload/media preflights, blob reports, payment challenge handling, server-list
652 fallback helpers, and list pagination.
653  
654 Methods croak for invalid local arguments and unknown options. Non-success HTTP
655 responses die with C<Net::Blossom::Error>. C<402 Payment Required> responses die
656 with C<Net::Blossom::PaymentRequired>.
657  
658 =head1 CONSTRUCTOR
659  
660 =head2 new
661  
662 my $client = Net::Blossom::Client->new(%args);
663  
664 Required arguments:
665  
666 =over 4
667  
668 =item * C<server>
669  
670 The Blossom server HTTP or HTTPS base URL. Query strings, fragments, and userinfo
671 are rejected. A path prefix is allowed. Trailing slashes are removed.
672  
673 =back
674  
675 Optional arguments:
676  
677 =over 4
678  
679 =item * C<ua>
680  
681 HTTP user agent object. Defaults to C<HTTP::Tiny-E<gt>new>. The object must
682 provide C<request($method, $url, \%opts)> and return a hash reference with
683 C<status>, C<reason>, C<headers>, and C<content>.
684  
685 =item * C<auth>
686  
687 Authorization provider. It may be a static C<Authorization> header string, a
688 code reference, or an object with C<authorization_header(%context)>.
689  
690 Code references and objects receive C<method>, C<url>, C<action>, and C<sha256>.
691 They must return the header value or C<undef> to omit authorization.
692  
693 When the provider object exposes an C<action> accessor (as
694 C<Net::Blossom::AuthToken> does), its action must match the request's action.
695 A single fixed-action token cannot be reused across endpoints: a mismatch
696 croaks rather than send a token whose BUD-11 C<t> verb the server would reject.
697  
698 =back
699  
700 Unknown arguments or a missing C<server> croak.
701  
702 =head1 ACCESSORS
703  
704 =head2 server
705  
706 Returns the normalized server base URL.
707  
708 =head2 ua
709  
710 Returns the user agent object.
711  
712 =head2 auth
713  
714 Returns the configured authorization provider.
715  
716 =head1 METHODS
717  
718 =head2 get_blob
719  
720 my $response = $client->get_blob($sha256, %opts);
721  
722 Sends C<GET /<sha256>> and returns a C<Net::Blossom::Response>. Success statuses
723 are C<200>, C<206>, C<307>, and C<308>.
724  
725 Options:
726  
727 =over 4
728  
729 =item * C<extension>
730  
731 Appends C<.$extension> to the request path. The extension must contain only
732 letters and digits.
733  
734 =item * C<range>
735  
736 Sends a C<Range> header.
737  
738 =item * C<payment>
739  
740 Hash reference of payment proof headers. See L</PAYMENT PROOFS>.
741  
742 =back
743  
744 =head2 head_blob
745  
746 my $response = $client->head_blob($sha256, %opts);
747  
748 Sends C<HEAD /<sha256>> and returns a C<Net::Blossom::Response>. Success
749 statuses are C<200>, C<307>, and C<308>. Accepts the C<extension> option.
750 C<payment> is rejected because proof headers are not allowed on C<HEAD>
751 requests.
752  
753 =head2 upload_blob
754  
755 my $descriptor = $client->upload_blob($content, %opts);
756  
757 Sends C<PUT /upload> with the exact byte string in C<$content>. Returns a
758 C<Net::Blossom::BlobDescriptor> parsed from the JSON response. Success statuses
759 are C<200> and C<201>.
760  
761 Options:
762  
763 =over 4
764  
765 =item * C<type>
766  
767 Media type for C<Content-Type>. Defaults to C<application/octet-stream>.
768  
769 =item * C<payment>
770  
771 Hash reference of payment proof headers. See L</PAYMENT PROOFS>.
772  
773 =back
774  
775 =head2 head_upload
776  
777 my $response = $client->head_upload($content, %opts);
778  
779 Sends C<HEAD /upload> preflight headers for the given content and returns a
780 C<Net::Blossom::Response>. Success status is C<200>. C<payment> is not allowed
781 on C<HEAD> requests.
782  
783 The C<type> option sets C<X-Content-Type> and defaults to
784 C<application/octet-stream>.
785  
786 =head2 process_media
787  
788 my $descriptor = $client->process_media($content, %opts);
789  
790 Sends C<PUT /media> and returns a C<Net::Blossom::BlobDescriptor>. Success
791 statuses are C<200> and C<201>. Options match C<upload_blob>.
792  
793 =head2 head_media
794  
795 my $response = $client->head_media($content, %opts);
796  
797 Sends C<HEAD /media> preflight headers and returns a
798 C<Net::Blossom::Response>. Success status is C<200>. C<payment> is not allowed
799 on C<HEAD> requests.
800  
801 The C<type> option sets C<X-Content-Type> and defaults to
802 C<application/octet-stream>.
803  
804 =head2 upload_blob_to_servers
805  
806 my $descriptor = $client->upload_blob_to_servers($content, $servers, %opts);
807  
808 Uploads to the first server in C<$servers>. C<$servers> may be a
809 C<Net::Blossom::ServerList> or an array reference of server base URLs. Options
810 are passed to C<upload_blob>.
811  
812 =head2 mirror_blob
813  
814 my $descriptor = $client->mirror_blob($url, %opts);
815  
816 Sends C<PUT /mirror> with a canonical JSON body containing C<url>. Returns a
817 C<Net::Blossom::BlobDescriptor>. Success statuses are C<200> and C<201>.
818  
819 If the source URL contains a SHA-256 hash, that hash is passed to the auth
820 provider as request context.
821  
822 =head2 report_blob
823  
824 my $response = $client->report_blob($event, %opts);
825  
826 Sends C<PUT /report> with a NIP-56 report event hash reference. Returns a
827 C<Net::Blossom::Response>. Any C<2xx> status is treated as success.
828  
829 The report event is validated locally. It must be kind C<1984>, include
830 lowercase hex C<id>, C<pubkey>, and C<sig> fields, include scalar C<content>,
831 include a non-negative integer C<created_at>, and contain at least one C<x> tag
832 with a lowercase SHA-256 hash.
833  
834 =head2 list_blobs
835  
836 my $descriptors = $client->list_blobs($pubkey, %opts);
837  
838 Sends C<GET /list/<pubkey>> and returns an array reference of
839 C<Net::Blossom::BlobDescriptor> objects. C<$pubkey> must be lowercase
840 64-character hex.
841  
842 Options C<cursor>, C<limit>, C<since>, and C<until> are sent as query
843 parameters when defined.
844  
845 =head2 delete_blob
846  
847 my $response = $client->delete_blob($sha256, %opts);
848  
849 Sends C<DELETE /<sha256>> and returns a C<Net::Blossom::Response>. Success
850 statuses are C<200> and C<204>. Accepts the C<payment> option.
851  
852 =head2 get_blob_from_servers
853  
854 my $response = $client->get_blob_from_servers($url, $servers, %opts);
855  
856 Extracts the last SHA-256 hash from C<$url> and tries C<get_blob> against each
857 server in order until one succeeds. C<$servers> may be a
858 C<Net::Blossom::ServerList> or an array reference of server base URLs.
859  
860 If all servers return Blossom HTTP errors, the last C<Net::Blossom::Error> is
861 re-thrown. Non-Blossom exceptions are re-thrown immediately.
862  
863 =head1 PAYMENT PROOFS
864  
865 C<GET>, C<PUT>, and C<DELETE> methods accept C<payment =E<gt> \%proofs>. Keys
866 are payment method names such as C<cashu> or C<lightning>, optionally with an
867 C<X-> prefix. Values are scalar proof strings. The client sends them as
868 C<X-Cashu>, C<X-Lightning>, or the matching C<X-*> header.
869  
870 Reserved payment method names C<reason>, C<sha-256>, C<content-type>, and
871 C<content-length> are rejected.
872  
873 =head1 ERRORS
874  
875 Invalid local arguments and unknown method options croak. Failed HTTP responses
876 die with C<Net::Blossom::Error>. Payment challenges die with
877 C<Net::Blossom::PaymentRequired>.
878  
879 Malformed JSON success bodies also croak.
880  
881 =head1 SEE ALSO
882  
883 L<Net::Blossom::AuthToken>, L<Net::Blossom::BlobDescriptor>,
884 L<Net::Blossom::Error>, L<Net::Blossom::PaymentRequired>,
885 L<Net::Blossom::Response>, L<Net::Blossom::ServerList>
886  
887 =head1 INTERNAL METHODS
888  
889 =head2 BUILDARGS
890  
891 Normalizes constructor arguments for Class::Tiny.
892  
893 =head2 BUILD
894  
895 Validates the constructed object for Class::Tiny.
896  
897 =cut
« Blossom/ServerList.pm ↑ Summary