S3.pm

filter: Statementstmt 36.9% 68 / 184 Branchbran 21.6% 16 / 74 Conditioncond 25.0% 6 / 24 MC/DCmcdc 6.2% 1 / 16 Subroutinesub 41.6% 15 / 36 Podpod 100% 8 / 8 totaltotal 33.3% 114 / 342 CC 46 SCAR 24.2
CC
46
Cov
32%
__ANON__
42.0
__ANON__
20.0
_report_cleanup_error
20.0
CRAP 11.3
« S3/_Client.pm ↑ Summary S3/BlobStore.pm »
1 package Net::Blossom::Server::Backend::S3;
2  
3 5 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 5 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 5 ▶use Class::Tiny qw(metadata_store blob_store base_url cleanup_error_handler);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 5 ▶use Net::Blossom::BlobDescriptor;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 5 ▶use Net::Blossom::_URL;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 5 ▶use Net::Blossom::Server::Backend::S3::BlobStore;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 5 ▶use Net::Blossom::Server::BlobResult;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 5 ▶use Net::Blossom::Server::BlobStore;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 5 ▶use Net::Blossom::Server::MetadataStore;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 5 our $VERSION = '0.001001';
15  
16 5 my @BLOB_STORE_ARGS = qw(
17 bucket endpoint region access_key_id secret_access_key session_token
18 path_style s3 timeout retry temp_dir prefix range_size
19 multipart_threshold multipart_part_size generation client
20 );
21  
22 7 ▶sub BUILDARGS {
Subroutine BUILDARGS: called CC=11 SCAR=25.2
Pod documented
23 7 my $class = shift;
24 7 my %args = _constructor_args(@_);
25 7 my %known = map { $_ => 1 } (
26 qw(metadata_store blob_store base_url cleanup_error_handler),
27 @BLOB_STORE_ARGS,
28 );
29 7 my @unknown = grep { !$known{$_} } keys %args;
30 7 ▶ croak "unknown argument(s): " . join(', ', sort @unknown) if @unknown;
Branch: 1 branch
BranchTrueFalseTotal
if @unknown 1 6 7
31  
32 6 ▶ croak "metadata_store is required" unless defined $args{metadata_store};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args{"metadata_store"} 1 5 6
33 5 ▶ croak "base_url is required" unless defined $args{base_url};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args{"base_url"} 1 4 5
34 croak "cleanup_error_handler must be a code reference"
35 if defined $args{cleanup_error_handler}
36 4 ▶ && ref($args{cleanup_error_handler}) ne 'CODE';
Branch: 1 branch
BranchTrueFalseTotal
if defined $args{"cleanup_error_handler"} and ref $args{"cleanup_error_handler"} ne "CODE" 1 3 4
Condition66%2/3
defined $args{"cleanup_error_handler"} and ref $args{"cleanup_error_handler"} ne "CODE"
!ll&&!rl&&r
301
MC/DC50%1/2
defined $args{"cleanup_error_handler"} and ref $args{"cleanup_error_handler"} ne "CODE"
defined $args{"cleanup_error_handler"} ref $args{"cleanup_error_handler"} ne "CODE"
Truth table66%2/3
A and B
A= defined $args{"cleanup_error_handler"}B= ref $args{"cleanup_error_handler"} ne "CODE"
ABresult
0X0
100
111
37  
38 3 Net::Blossom::Server::MetadataStore->assert_implements($args{metadata_store});
39 2 my $base_url = _normalize_base_url($args{base_url});
40 1 my $blob_store = delete $args{blob_store};
41 my %blob_args = map {
42 1 ▶ exists $args{$_} ? ($_ => delete $args{$_}) : ()
Branch: 1 branch
BranchTrueFalseTotal
exists $args{$_} ? : 0 17 17
43 } @BLOB_STORE_ARGS;
44 1 ▶ croak "blob_store cannot be combined with S3 client arguments"
Branch: 1 branch
BranchTrueFalseTotal
if defined $blob_store and keys %blob_args 0 1 1
Condition33%1/3
defined $blob_store and keys %blob_args
!ll&&!rl&&r
010
MC/DC0%0/2
defined $blob_store and keys %blob_args
defined $blob_store keys %blob_args
Truth table33%1/3
A and B
A= defined $blob_storeB= keys %blob_args
ABresult
0X0
100
111
45 if defined $blob_store && keys %blob_args;
46 1 ▶ $blob_store ||= Net::Blossom::Server::Backend::S3::BlobStore->new(%blob_args);
Condition33%1/3
$blob_store ||= "Net::Blossom::Server::Backend::S3::BlobStore"->new(%blob_args)
l!l&&r!l&&!r
100
MC/DC0%0/2
$blob_store ||= "Net::Blossom::Server::Backend::S3::BlobStore"->new(%blob_args)
$blob_store "Net::Blossom::Server::Backend::S3::BlobStore"->new(%blob_args)
Truth table33%1/3
A ||= B
A= $blob_storeB= "Net::Blossom::Server::Backend::S3::BlobStore"->new(%blob_args)
ABresult
1X1
011
000
47 1 Net::Blossom::Server::BlobStore->assert_implements($blob_store);
48  
49 return {
50 metadata_store => $args{metadata_store},
51 blob_store => $blob_store,
52 base_url => $base_url,
53 0 ▶ cleanup_error_handler => $args{cleanup_error_handler} || sub { warn $_[0] },
Subroutine __ANON__: not called CC=1 SCAR=6.9
54 1 ▶ };
Condition33%1/3
$args{'cleanup_error_handler'} || sub { warn $_[0]; }
l!l&&r!l&&!r
010
MC/DC0%0/2
$args{'cleanup_error_handler'} || sub { warn $_[0]; }
$args{'cleanup_error_handler'} sub { warn $_[0]; }
Truth table33%1/3
A || B
A= $args{'cleanup_error_handler'}B= sub { warn $_[0]; }
ABresult
1X1
011
000
55 }
56  
57 0 ▶sub deploy_schema {
Subroutine deploy_schema: not called CC=1 SCAR=6.9
Pod documented
58 0 my ($self) = @_;
59 0 $self->blob_store->deploy_schema;
60 0 $self->metadata_store->deploy_schema;
61 0 return 1;
62 }
63  
64 0 ▶sub begin_upload {
Subroutine begin_upload: not called CC=1 SCAR=6.9
Pod documented
65 0 my ($self, %context) = @_;
66 0 my $blob_upload = $self->blob_store->begin_upload(%context);
67 0 Net::Blossom::Server::BlobStore->assert_upload($blob_upload);
68  
69 0 return Net::Blossom::Server::Backend::S3::_Upload->new(
70 storage => $self,
71 blob_upload => $blob_upload,
72 );
73 }
74  
75 0 ▶sub get_blob {
Subroutine get_blob: not called CC=3 SCAR=24.8
Pod documented
76 0 my ($self, $sha256) = @_;
77 0 my $row = $self->metadata_store->find_blob($sha256);
78 0 ▶ return unless defined $row;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $row 0 0 0
79 my $body = $self->blob_store->get_blob(
80 $row->{storage_key},
81 size => $row->{size},
82 0 );
83 0 ▶ return unless defined $body;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $body 0 0 0
84  
85 0 return Net::Blossom::Server::BlobResult->new(
86 descriptor => $self->_descriptor($row),
87 body => $body,
88 );
89 }
90  
91 0 ▶sub get_blob_range {
Subroutine get_blob_range: not called CC=2 SCAR=17.9
Pod documented
92 0 my ($self, $sha256, %opts) = @_;
93 0 my $row = $self->metadata_store->find_blob($sha256);
94 0 ▶ return unless defined $row;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $row 0 0 0
95 return $self->blob_store->get_blob_range(
96 $row->{storage_key},
97 %opts,
98 size => $row->{size},
99 0 );
100 }
101  
102 0 ▶sub head_blob {
Subroutine head_blob: not called CC=2 SCAR=17.9
Pod documented
103 0 my ($self, $sha256) = @_;
104 0 my $row = $self->metadata_store->find_blob($sha256);
105 0 ▶ return unless defined $row;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $row 0 0 0
106 0 return $self->_descriptor($row);
107 }
108  
109 0 ▶sub delete_blob {
Subroutine delete_blob: not called CC=3 SCAR=24.8
Pod documented
110 0 my ($self, $sha256, %opts) = @_;
111 0 my $metadata = $self->metadata_store;
112 0 my $storage_key;
113  
114 0 ▶ my $deleted = $metadata->with_transaction(sub {
Subroutine __ANON__: not called CC=6 SCAR=37.4
115 0 $metadata->lock_blob($sha256);
116  
117 0 ▶ if (defined $opts{pubkey}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $opts{"pubkey"}) 0 0 0
118 0 ▶ return 0 unless $metadata->delete_owner($sha256, $opts{pubkey});
Branch: 1 branch
BranchTrueFalseTotal
unless $metadata->delete_owner($sha256, $opts{"pubkey"}) 0 0 0
119 0 ▶ if (!$metadata->owner_count($sha256)) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($metadata->owner_count($sha256)) 0 0 0
120 0 my $record = $metadata->find_blob($sha256);
121 0 ▶ if (defined $record) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $record) 0 0 0
122 0 $storage_key = $record->{storage_key};
123 0 $metadata->delete_blob($sha256);
124 }
125 }
126 0 return 1;
127 }
128  
129 0 my $record = $metadata->find_blob($sha256);
130 0 ▶ return 0 unless defined $record;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $record 0 0 0
131 0 $storage_key = $record->{storage_key};
132 0 $metadata->delete_owners($sha256);
133 0 $metadata->delete_blob($sha256);
134 0 return 1;
135 0 });
136  
137 0 ▶ $self->_delete_object($storage_key) if defined $storage_key;
Branch: 1 branch
BranchTrueFalseTotal
if defined $storage_key 0 0 0
138 0 ▶ return $deleted ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$deleted ? : 0 0 0
139 }
140  
141 0 ▶sub list_blobs {
Subroutine list_blobs: not called CC=1 SCAR=6.9
Pod documented
142 0 my ($self, $pubkey, %opts) = @_;
143 0 my $rows = $self->metadata_store->list_blobs($pubkey, %opts);
144 0 return [map { $self->_descriptor($_) } @$rows];
145 }
146  
147 0 ▶sub _commit_upload {
Subroutine _commit_upload: not called CC=3 SCAR=24.8
148 0 my ($self, $upload, %metadata) = @_;
149 0 my $store = $self->metadata_store;
150 0 my $created;
151 my $storage_key;
152  
153 0 my $ok = eval {
154 0 ▶ $store->with_transaction(sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
155 0 $store->lock_blob($metadata{sha256});
156 0 my $record = $store->find_blob($metadata{sha256});
157  
158 0 ▶ if (defined $record) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $record) { } 0 0 0
159 0 $created = 0;
160 0 $storage_key = $record->{storage_key};
161 }
162 else {
163 0 $storage_key = $upload->_prepare(%metadata);
164 0 ▶ $created = $store->insert_blob(
Branch: 1 branch
BranchTrueFalseTotal
$store->insert_blob(%metadata, 'storage_key', $storage_key) ? : 0 0 0
165 %metadata,
166 storage_key => $storage_key,
167 ) ? 1 : 0;
168 }
169  
170 0 ▶ $store->upsert_owner(%metadata) if defined $metadata{pubkey};
Branch: 1 branch
BranchTrueFalseTotal
if defined $metadata{"pubkey"} 0 0 0
171 0 return 1;
172 0 });
173 0 1;
174 };
175 0 my $error = $@;
176  
177 0 ▶ if (!$ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 0 0 0
178 0 eval { $upload->_cleanup(0) };
179 0 die $error;
180 }
181  
182 0 my $cleanup_ok = eval { $upload->_cleanup($created); 1 };
183 0 ▶ $self->_report_cleanup_error($@, $storage_key) unless $cleanup_ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $cleanup_ok 0 0 0
184  
185 return {
186 0 descriptor => $self->_descriptor(\%metadata),
187 created => $created,
188 };
189 }
190  
191 0 ▶sub _delete_object {
Subroutine _delete_object: not called CC=2 SCAR=17.9
192 0 my ($self, $storage_key) = @_;
193 0 my $ok = eval { $self->blob_store->delete_blob($storage_key); 1 };
194 0 ▶ $self->_report_cleanup_error($@, $storage_key) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 0 0 0
195 0 return;
196 }
197  
198 0 ▶sub _report_cleanup_error {
Subroutine _report_cleanup_error: not called CC=4 SCAR=30.0
199 0 my ($self, $error, $storage_key) = @_;
200 0 ▶ return unless defined $error && length $error;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $error and length $error 0 0 0
Condition0%0/3
defined $error and length $error
!ll&&!rl&&r
000
MC/DC0%0/2
defined $error and length $error
defined $error length $error
Truth table0%0/3
A and B
A= defined $errorB= length $error
ABresult
0X0
100
111
201 0 my $ok = eval { $self->cleanup_error_handler->($error, $storage_key); 1 };
202 0 ▶ warn $@ unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 0 0 0
203 0 return;
204 }
205  
206 0 ▶sub _descriptor {
Subroutine _descriptor: not called CC=1 SCAR=6.9
207 0 my ($self, $row) = @_;
208 return Net::Blossom::BlobDescriptor->new(
209 url => $self->base_url . '/' . $row->{sha256},
210 sha256 => $row->{sha256},
211 size => 0 + $row->{size},
212 type => $row->{type},
213 uploaded => 0 + $row->{uploaded},
214 0 );
215 }
216  
217 2 ▶sub _normalize_base_url {
Subroutine _normalize_base_url: called CC=4 SCAR=14.0
218 2 my ($base_url) = @_;
219 2 ▶ croak "base_url must be a scalar" if ref($base_url);
Branch: 1 branch
BranchTrueFalseTotal
if ref $base_url 0 2 2
220 2 ▶ croak "base_url is required" unless length $base_url;
Branch: 1 branch
BranchTrueFalseTotal
unless length $base_url 0 2 2
221 2 ▶ croak "base_url must be a valid HTTP base URL"
Branch: 1 branch
BranchTrueFalseTotal
unless Net::Blossom::_URL::http_base_url($base_url) 1 1 2
222 unless Net::Blossom::_URL::http_base_url($base_url);
223 1 $base_url =~ s{/+\z}{};
224 1 return $base_url;
225 }
226  
227 7 ▶sub _constructor_args {
Subroutine _constructor_args: called CC=4 SCAR=17.1
228 0 ▶ return %{$_[0]} if @_ == 1 && ref($_[0]) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 1 and ref $_[0] eq "HASH" 0 7 7
Condition33%1/3
@_ == 1 and ref $_[0] eq "HASH"
!ll&&!rl&&r
700
MC/DC0%0/2
@_ == 1 and ref $_[0] eq "HASH"
@_ == 1 ref $_[0] eq "HASH"
Truth table33%1/3
A and B
A= @_ == 1B= ref $_[0] eq "HASH"
ABresult
0X0
100
111
229 7 ▶ croak "constructor arguments must be name/value pairs" if @_ % 2;
Branch: 1 branch
BranchTrueFalseTotal
if @_ % 2 0 7 7
230 7 return @_;
231 }
232  
233 {
234 package Net::Blossom::Server::Backend::S3::_Upload;
235  
236 5 ▶ use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
237  
238 5 ▶ use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
239 5 ▶ use Class::Tiny qw(storage blob_upload), {
Subroutine BEGIN: called CC=1 SCAR=0.0
240 committed => 0,
241 aborted => 0,
242 5 };
243  
244 0 ▶ sub BUILD {
Subroutine BUILD: not called CC=1 SCAR=6.9
245 0 my ($self) = @_;
246 0 $self->committed;
247 0 $self->aborted;
248 0 return;
249 }
250  
251 0 ▶ sub write {
Subroutine write: not called CC=3 SCAR=24.8
252 0 my ($self, $chunk) = @_;
253 0 ▶ croak "upload is already committed" if $self->{committed};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"committed"} 0 0 0
254 0 ▶ croak "upload is aborted" if $self->{aborted};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"aborted"} 0 0 0
255 0 return $self->{blob_upload}->write($chunk);
256 }
257  
258 0 ▶ sub commit {
Subroutine commit: not called CC=3 SCAR=24.8
259 0 my ($self, %metadata) = @_;
260 0 ▶ croak "upload is already committed" if $self->{committed};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"committed"} 0 0 0
261 0 ▶ croak "upload is aborted" if $self->{aborted};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"aborted"} 0 0 0
262 0 my $result = $self->{storage}->_commit_upload($self, %metadata);
263 0 $self->{committed} = 1;
264 0 return $result;
265 }
266  
267 0 ▶ sub abort {
Subroutine abort: not called CC=3 SCAR=24.8
268 0 my ($self) = @_;
269 0 ▶ return 1 if $self->{aborted} || $self->{committed};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"aborted"} or $self->{"committed"} 0 0 0
Condition0%0/3
$self->{"aborted"} or $self->{"committed"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{"aborted"} or $self->{"committed"}
$self->{"aborted"} $self->{"committed"}
Truth table0%0/3
A or B
A= $self->{"aborted"}B= $self->{"committed"}
ABresult
1X1
011
000
270 0 $self->{aborted} = 1;
271 0 return $self->{blob_upload}->abort;
272 }
273  
274 0 ▶ sub _prepare {
Subroutine _prepare: not called CC=1 SCAR=6.9
275 0 my ($self, %metadata) = @_;
276 0 return $self->{blob_upload}->prepare(%metadata);
277 }
278  
279 0 ▶ sub _cleanup {
Subroutine _cleanup: not called CC=2 SCAR=17.9
280 0 my ($self, $created) = @_;
281 return $created
282 ? $self->{blob_upload}->commit
283 0 ▶ : $self->{blob_upload}->abort;
Branch: 1 branch
BranchTrueFalseTotal
$created ? : 0 0 0
284 }
285  
286 0 ▶ sub DEMOLISH {
Subroutine DEMOLISH: not called CC=3 SCAR=24.8
287 0 my ($self) = @_;
288 0 ▶ return if $self->{committed} || $self->{aborted};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"committed"} or $self->{"aborted"} 0 0 0
Condition0%0/3
$self->{"committed"} or $self->{"aborted"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{"committed"} or $self->{"aborted"}
$self->{"committed"} $self->{"aborted"}
Truth table0%0/3
A or B
A= $self->{"committed"}B= $self->{"aborted"}
ABresult
1X1
011
000
289 0 eval { $self->abort };
290 0 return;
291 }
292 }
293  
294 5 1;
295  
296 =pod
297  
298 =head1 NAME
299  
300 Net::Blossom::Server::Backend::S3 - S3-compatible storage for Blossom servers
301  
302 =head1 SYNOPSIS
303  
304 use DBI;
305 use Net::Blossom::Server;
306 use Net::Blossom::Server::Backend::S3;
307 use Net::Blossom::Server::Backend::SQLite::MetadataStore;
308  
309 my $sqlite_dbh = DBI->connect('dbi:SQLite:dbname=blossom.sqlite', '', '', {
310 AutoCommit => 1,
311 RaiseError => 1,
312 PrintError => 0,
313 });
314 my $metadata = Net::Blossom::Server::Backend::SQLite::MetadataStore->new(
315 dbh => $sqlite_dbh,
316 );
317 my $storage = Net::Blossom::Server::Backend::S3->new(
318 metadata_store => $metadata,
319 base_url => 'https://cdn.example.com',
320 bucket => 'blossom',
321 endpoint => 'https://s3.example.com',
322 region => 'us-east-1',
323 access_key_id => $ENV{AWS_ACCESS_KEY_ID},
324 secret_access_key => $ENV{AWS_SECRET_ACCESS_KEY},
325 );
326 $storage->deploy_schema;
327  
328 my $server = Net::Blossom::Server->new(storage => $storage);
329  
330 =head1 DESCRIPTION
331  
332 This module implements L<Net::Blossom::Server::Storage> with S3-compatible
333 object storage. It works with Amazon S3 and independent implementations such
334 as Ceph and Garage.
335  
336 Descriptor and owner metadata are supplied separately through any
337 L<Net::Blossom::Server::MetadataStore> implementation. The S3 backend has no
338 runtime dependency on a particular database backend.
339  
340 The default blob store stages uploads in a temporary file. Files below
341 C<multipart_threshold> use one PUT unless they exceed S3's single-PUT limit.
342 Other files use multipart upload. Downloads use bounded range requests and may
343 return short reads, so blob bodies are not held in memory in full.
344  
345 =head1 CONSTRUCTOR
346  
347 =head2 new
348  
349 my $storage = Net::Blossom::Server::Backend::S3->new(%args);
350  
351 Requires C<metadata_store> and C<base_url>. The default S3 client also requires
352 C<bucket>. Credentials may be passed as C<access_key_id>,
353 C<secret_access_key>, and C<session_token>, or read from
354 C<AWS_ACCESS_KEY_ID>, C<AWS_SECRET_ACCESS_KEY>, and C<AWS_SESSION_TOKEN>.
355  
356 C<region> defaults to C<us-east-1>. C<endpoint> selects a compatible service;
357 when omitted, Amazon S3 is used. Custom endpoints use path-style bucket URLs by
358 default. Set C<path_style> explicitly when the service requires another style.
359  
360 C<timeout> defaults to 30 seconds and C<retry> is enabled by default. An
361 existing C<Net::Amazon::S3> object may be passed as C<s3> for advanced client
362 configuration. It cannot be combined with other connection arguments.
363  
364 C<temp_dir> selects the upload staging directory. C<prefix> defaults to
365 C<blossom>. C<multipart_threshold>, C<multipart_part_size>, and C<range_size>
366 default to 100 MiB, 16 MiB, and 8 MiB. Multipart parts are enlarged when needed
367 to remain within S3's 10,000-part limit. The configured part size must be
368 between 5 MiB and 5 GiB; the final part may be smaller. Objects above 5 GB
369 always use multipart upload. The client follows
370 L<Amazon S3's multipart limits|https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html>:
371 10,000 5-GiB parts, or about 48.8 TiB. Compatible services may impose lower
372 limits.
373  
374 C<generation> may supply an object-key callback for testing. Each result must
375 be unique for a given hash. The default uses 128 random bits.
376  
377 C<client> may supply an object client that implements C<upload_file>, C<head>,
378 C<get_range>, and C<delete>. It cannot be combined with S3 connection options.
379  
380 C<cleanup_error_handler> may be a code reference. It receives a post-commit
381 cleanup error and the storage key, when available. The default warns.
382  
383 C<blob_store> may be supplied for custom composition or tests. It cannot be
384 combined with any option used to construct the default blob store.
385  
386 =head1 CONSISTENCY
387  
388 The default blob store uses a new generation-specific object key for each newly
389 stored object. Object bytes are durable before metadata commits, so the metadata
390 transaction remains open during a new object upload. Database-backed metadata
391 stores also keep their connection occupied. Deletion commits the metadata change
392 before deleting that exact object key, so delayed cleanup cannot erase a later
393 upload of the same hash.
394  
395 S3 and the metadata store cannot commit atomically. A metadata failure or failed
396 object deletion can therefore leave an unreachable object.
397 The object remains invisible because metadata is authoritative. Operators
398 should monitor cleanup errors and may remove unreachable objects separately.
399  
400 The bucket must already exist and have the required access policy. This module
401 does not create buckets or configure encryption, lifecycle, or replication.
402 Only an HTTP 404 response is treated as a missing object. Other service errors
403 propagate. On Amazon S3, grant C<s3:ListBucket> so a missing object returns 404
404 rather than an indistinguishable 403 permission error.
405  
406 =head1 LIVE TESTING
407  
408 C<t/20-LiveS3.t> runs the same storage contract against any S3-compatible
409 endpoint. Set C<NET_BLOSSOM_S3_ENDPOINT>, C<NET_BLOSSOM_S3_BUCKET>,
410 C<NET_BLOSSOM_S3_REGION>, C<NET_BLOSSOM_S3_ACCESS_KEY_ID>, and
411 C<NET_BLOSSOM_S3_SECRET_ACCESS_KEY>. Set C<NET_BLOSSOM_POSTGRES_DSN>,
412 C<NET_BLOSSOM_POSTGRES_USER>, and C<NET_BLOSSOM_POSTGRES_PASSWORD> to also run
413 the contract with Postgres metadata.
414  
415 C<t/21-LiveMultiNode.t> repeats cross-node operations through two independent
416 backend instances. Set C<NET_BLOSSOM_S3_PEER_ENDPOINT> to route the second
417 instance through another S3 gateway; otherwise it uses the primary endpoint.
418  
419 When live S3 testing is required, CI runs both tests against three-node Garage
420 and Ceph clusters.
421  
422 =head1 METHODS
423  
424 =head2 BUILDARGS
425  
426 Normalizes and validates constructor arguments for C<Class::Tiny>.
427  
428 =head2 metadata_store
429  
430 Returns the configured metadata store.
431  
432 =head2 blob_store
433  
434 Returns the configured byte store.
435  
436 =head2 base_url
437  
438 Returns the normalized public blob URL prefix.
439  
440 =head2 cleanup_error_handler
441  
442 Returns the post-commit cleanup error callback.
443  
444 =head2 deploy_schema
445  
446 Deploys both store schemas. The default S3 byte store has no schema.
447  
448 =head2 begin_upload
449  
450 Starts a blob upload.
451  
452 =head2 get_blob
453  
454 Returns a L<Net::Blossom::Server::BlobResult>, or C<undef> when metadata or
455 object bytes are absent. The default byte store returns a ranged-read stream
456 for nonempty objects.
457  
458 =head2 get_blob_range
459  
460 Returns one requested byte range as a bounded ranged-read stream, or C<undef>
461 when metadata or object bytes are absent.
462  
463 =head2 head_blob
464  
465 Returns the blob descriptor from metadata, or C<undef> when absent.
466  
467 =head2 delete_blob
468  
469 With C<pubkey>, removes that owner and deletes the object after its final owner
470 is removed. Without C<pubkey>, deletes the whole blob.
471  
472 =head2 list_blobs
473  
474 Returns an array reference of L<Net::Blossom::BlobDescriptor> objects for one
475 pubkey. C<cursor> and C<limit> follow L<Net::Blossom::Server::Storage>.
476  
477 =cut
« S3/_Client.pm ↑ Summary S3/BlobStore.pm »