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