| 1 | package Net::Blossom::ServerList; | ||
| 2 | |||
| 3 | 13 | ▶ | use strictures 2; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | |||
| 5 | 13 | ▶ | use Net::Blossom::_ConstructorArgs (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | |||
| 7 | 13 | ▶ | use Carp qw(croak); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 8 | 13 | ▶ | use Class::Tiny qw(_blossom); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 0 | ▶ | use Net::Nostr::Blossom; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 10 | |||
| 11 | sub BUILDARGS { | ||
| 12 | my $class = shift; | ||
| 13 | my %args = Net::Blossom::_ConstructorArgs::normalize(@_); | ||
| 14 | my %known = map { $_ => 1 } qw(servers); | ||
| 15 | my @unknown = grep { !exists $known{$_} } keys %args; | ||
| 16 | croak "unknown argument(s): " . join(', ', sort @unknown) if @unknown; | ||
| 17 | |||
| 18 | croak "servers is required" unless exists $args{servers}; | ||
| 19 | croak "servers must be an array reference" unless ref($args{servers}) eq 'ARRAY'; | ||
| 20 | croak "server list requires at least one server" unless @{$args{servers}}; | ||
| 21 | |||
| 22 | my $blossom = Net::Nostr::Blossom->new(servers => $args{servers}); | ||
| 23 | return { _blossom => $blossom }; | ||
| 24 | } | ||
| 25 | |||
| 26 | sub from_event { | ||
| 27 | my ($class, $event) = @_; | ||
| 28 | my $blossom = Net::Nostr::Blossom->from_event($event); | ||
| 29 | my $servers = $blossom->servers; | ||
| 30 | return $class->new(servers => $servers); | ||
| 31 | } | ||
| 32 | |||
| 33 | sub servers { | ||
| 34 | my ($self) = @_; | ||
| 35 | my $servers = $self->_blossom->servers; | ||
| 36 | return $servers; | ||
| 37 | } | ||
| 38 | |||
| 39 | sub primary_server { | ||
| 40 | my ($self) = @_; | ||
| 41 | return $self->_blossom->primary_server; | ||
| 42 | } | ||
| 43 | |||
| 44 | sub to_tags { | ||
| 45 | my ($self) = @_; | ||
| 46 | return $self->_blossom->server_tags; | ||
| 47 | } | ||
| 48 | |||
| 49 | sub to_event { | ||
| 50 | my $self = shift; | ||
| 51 | my %args = Net::Blossom::_ConstructorArgs::normalize(@_); | ||
| 52 | return $self->_blossom->to_event(%args); | ||
| 53 | } | ||
| 54 | |||
| 55 | sub extract_sha256 { | ||
| 56 | my $class = shift; | ||
| 57 | my ($sha256) = $class->extract_blob_reference(@_); | ||
| 58 | return $sha256; | ||
| 59 | } | ||
| 60 | |||
| 61 | sub extract_blob_reference { | ||
| 62 | my ($class, $url) = @_; | ||
| 63 | my ($sha256, $extension) = Net::Nostr::Blossom->extract_hash($url); | ||
| 64 | return unless defined $sha256; | ||
| 65 | return ($sha256, $extension); | ||
| 66 | } | ||
| 67 | |||
| 68 | sub blob_urls_for { | ||
| 69 | my ($self, $url) = @_; | ||
| 70 | return [$self->_blossom->fallback_urls($url)]; | ||
| 71 | } | ||
| 72 | |||
| 73 | 1; | ||
| 74 | |||
| 75 | =pod | ||
| 76 | |||
| 77 | =head1 NAME | ||
| 78 | |||
| 79 | Net::Blossom::ServerList - BUD-03 Blossom server-list value object | ||
| 80 | |||
| 81 | =head1 SYNOPSIS | ||
| 82 | |||
| 83 | use Net::Blossom::ServerList; | ||
| 84 | |||
| 85 | my $list = Net::Blossom::ServerList->new( | ||
| 86 | servers => [ | ||
| 87 | 'https://cdn.example.com', | ||
| 88 | 'https://backup.example.com', | ||
| 89 | ], | ||
| 90 | ); | ||
| 91 | |||
| 92 | my $servers = $list->servers; | ||
| 93 | |||
| 94 | =head1 DESCRIPTION | ||
| 95 | |||
| 96 | C<Net::Blossom::ServerList> represents a user's BUD-03 list of Blossom servers. | ||
| 97 | Server order is preserved. The first server is treated as primary by helper | ||
| 98 | methods. This class is a Blossom-facing wrapper around | ||
| 99 | C<Net::Nostr::Blossom>. | ||
| 100 | |||
| 101 | =head1 CONSTRUCTORS | ||
| 102 | |||
| 103 | =head2 new | ||
| 104 | |||
| 105 | my $list = Net::Blossom::ServerList->new(servers => \@servers); | ||
| 106 | |||
| 107 | Creates a server list from an array reference of HTTP or HTTPS base URLs. At | ||
| 108 | least one server is required. Unknown arguments or invalid server URLs croak. | ||
| 109 | Server URL validation is provided by C<Net::Nostr::Blossom>. | ||
| 110 | |||
| 111 | =head2 from_event | ||
| 112 | |||
| 113 | my $list = Net::Blossom::ServerList->from_event($event); | ||
| 114 | |||
| 115 | Builds a server list from a kind C<10063> C<Net::Nostr::Event>. C<server> tags | ||
| 116 | are read in order. Plain hash references are not accepted; parse wire data with | ||
| 117 | C<Net::Nostr::Event> first. | ||
| 118 | |||
| 119 | =head1 METHODS | ||
| 120 | |||
| 121 | =head2 servers | ||
| 122 | |||
| 123 | my $servers = $list->servers; | ||
| 124 | |||
| 125 | Returns a copy array reference of server base URLs. Mutating the returned array | ||
| 126 | reference does not mutate the object. | ||
| 127 | |||
| 128 | =head2 primary_server | ||
| 129 | |||
| 130 | my $server = $list->primary_server; | ||
| 131 | |||
| 132 | Returns the first listed server. | ||
| 133 | |||
| 134 | =head2 to_tags | ||
| 135 | |||
| 136 | my $tags = $list->to_tags; | ||
| 137 | |||
| 138 | Returns a Nostr tag array reference containing one C<server> tag per server. | ||
| 139 | |||
| 140 | =head2 to_event | ||
| 141 | |||
| 142 | my $event = $list->to_event(%event_args); | ||
| 143 | |||
| 144 | Returns a C<Net::Nostr::Event> for kind C<10063>. Arguments are passed through | ||
| 145 | to C<Net::Nostr::Event-E<gt>new>; C<kind>, C<content>, and C<tags> are supplied | ||
| 146 | by the server list. | ||
| 147 | |||
| 148 | =head2 extract_sha256 | ||
| 149 | |||
| 150 | my $sha256 = Net::Blossom::ServerList->extract_sha256($url); | ||
| 151 | |||
| 152 | Extracts and returns the last 64-character hex SHA-256 value from C<$url>, | ||
| 153 | normalized to lowercase. Returns C<undef> when no hash is found. | ||
| 154 | |||
| 155 | =head2 extract_blob_reference | ||
| 156 | |||
| 157 | my ($sha256, $extension) = | ||
| 158 | Net::Blossom::ServerList->extract_blob_reference($url); | ||
| 159 | |||
| 160 | Extracts the last SHA-256 hash and an optional alphanumeric extension. Returns | ||
| 161 | an empty list when no hash is found. | ||
| 162 | |||
| 163 | =head2 blob_urls_for | ||
| 164 | |||
| 165 | my $urls = $list->blob_urls_for($url); | ||
| 166 | |||
| 167 | Builds fallback blob URLs for every server in the list using the hash and | ||
| 168 | optional extension extracted from C<$url>. Returns an array reference. Returns an | ||
| 169 | empty array reference when C<$url> does not contain a hash. | ||
| 170 | |||
| 171 | =head1 INTERNAL METHODS | ||
| 172 | |||
| 173 | =head2 BUILDARGS | ||
| 174 | |||
| 175 | Normalizes constructor arguments for Class::Tiny. | ||
| 176 | |||
| 177 | =cut | ||