Blossom/ServerList.pm

filter: Statementstmt 86.6% 13 / 15 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 90.0% 18 / 20 CC 1 SCAR 0.6
CC
1
Cov
87%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« Blossom.pm ↑ Summary Blossom/Client.pm »
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
« Blossom.pm ↑ Summary Blossom/Client.pm »