blib/lib/EV/Nats/ObjectStore.pm

filter: Statementstmt 89.8% 238 / 265 Branchbran 66.6% 76 / 114 Conditioncond 59.0% 39 / 66 MC/DCmcdc 27.0% 10 / 37 Subroutinesub 91.1% 41 / 45 Podpod 100% 9 / 9 totaltotal 77.0% 413 / 536 CC 84 SCAR 19.5
CC
84
Cov
79%
create_bucket
30.0
__ANON__
12.5
__ANON__
12.2
CRAP 7.1
« blib/lib/EV/Nats/KV.pm ↑ Summary blib/lib/EV/Nats.pm »
1 package EV::Nats::ObjectStore;
2 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 our $VERSION = '0.06';
5 3 ▶use Digest::SHA qw(sha256 sha256_hex);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 ▶use EV::Nats::JetStream;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 3 my $CHUNK_SIZE = 128 * 1024; # 128KB default
9  
10 3 my $NUID_PID = $$;
11 3 srand();
12  
13 21 ▶sub new {
Subroutine new: called CC=9 SCAR=23.0
Pod documented
14 21 my ($class, %opts) = @_;
15 21 ▶ my $js = delete $opts{js} || die "js (JetStream) required";
Condition50%1/2
delete $opts{'js'} || die('js (JetStream) required')
l!l
210
MC/DC0%0/1
delete $opts{'js'} || die('js (JetStream) required')
delete $opts{'js'}
Truth table50%1/2
A
A= delete $opts{'js'}
Aresult
11
00
16 21 ▶ my $bucket = delete $opts{bucket} || die "bucket name required";
Condition50%1/2
delete $opts{'bucket'} || die('bucket name required')
l!l
210
MC/DC0%0/1
delete $opts{'bucket'} || die('bucket name required')
delete $opts{'bucket'}
Truth table50%1/2
A
A= delete $opts{'bucket'}
Aresult
11
00
17 21 ▶ die "invalid ObjectStore bucket name '$bucket'"
Branch: 1 branch
BranchTrueFalseTotal
unless $bucket =~ /\A[a-zA-Z0-9_-]+\z/ 1 20 21
18 unless $bucket =~ /\A[a-zA-Z0-9_-]+\z/;
19 20 ▶ my $timeout = delete $opts{timeout} || $js->{timeout};
Condition33%1/3
delete $opts{'timeout'} || $js->{'timeout'}
l!l&&r!l&&!r
0200
MC/DC0%0/2
delete $opts{'timeout'} || $js->{'timeout'}
delete $opts{'timeout'} $js->{'timeout'}
Truth table33%1/3
A || B
A= delete $opts{'timeout'}B= $js->{'timeout'}
ABresult
1X1
011
000
20 20 ▶ my $chunk_size = delete $opts{chunk_size} || $CHUNK_SIZE;
Condition66%2/3
delete $opts{'chunk_size'} || $CHUNK_SIZE
l!l&&r!l&&!r
5150
MC/DC0%0/2
delete $opts{'chunk_size'} || $CHUNK_SIZE
delete $opts{'chunk_size'} $CHUNK_SIZE
Truth table66%2/3
A || B
A= delete $opts{'chunk_size'}B= $CHUNK_SIZE
ABresult
1X1
011
000
21 20 ▶ die "invalid chunk_size '$chunk_size'"
Branch: 1 branch
BranchTrueFalseTotal
unless $chunk_size =~ /\A\d+\z/ and $chunk_size > 0 1 19 20
Condition66%2/3
$chunk_size =~ /\A\d+\z/ and $chunk_size > 0
!ll&&!rl&&r
1019
MC/DC50%1/2
$chunk_size =~ /\A\d+\z/ and $chunk_size > 0
$chunk_size =~ /\A\d+\z/ $chunk_size > 0
Truth table66%2/3
A and B
A= $chunk_size =~ /\A\d+\z/B= $chunk_size > 0
ABresult
0X0
100
111
22 unless $chunk_size =~ /\A\d+\z/ && $chunk_size > 0;
23 19 warn "EV::Nats::ObjectStore::new: unknown option '$_'" for keys %opts;
24 19 bless {
25 js => $js,
26 bucket => $bucket,
27 stream => "OBJ_$bucket",
28 chunk_size => $chunk_size,
29 timeout => $timeout,
30 }, $class;
31 }
32  
33 0 ▶sub create_bucket {
Subroutine create_bucket: not called CC=5 SCAR=34.0
Pod documented
34 0 my ($self, $opts, $cb) = @_;
35 0 ▶ $opts //= {};
Condition0%0/2
$opts //= {}
l!l
00
MC/DC0%0/1
$opts //= {}
$opts
Truth table0%0/2
A
A= $opts
Aresult
11
00
36 0 require JSON::PP;
37 my $config = {
38 name => $self->{stream},
39 subjects => [
40 '$O.' . $self->{bucket} . '.C.>', # chunks
41 '$O.' . $self->{bucket} . '.M.>', # metadata
42 ],
43 retention => 'limits',
44 ($opts->{max_bytes} ? (max_bytes => $opts->{max_bytes}) : ()),
45 ($opts->{max_age} ? (max_age => $opts->{max_age}) : ()),
46 0 ▶ ($opts->{replicas} ? (num_replicas => $opts->{replicas}) : ()),
Branch: 3 branches
BranchTrueFalseTotal
$opts->{'max_bytes'} ? : 0 0 0
$opts->{'max_age'} ? : 0 0 0
$opts->{'replicas'} ? : 0 0 0
47 discard => 'new',
48 allow_rollup_hdrs => JSON::PP::true(),
49 };
50 0 $self->{js}->stream_create($config, $cb);
51 }
52  
53 0 ▶sub delete_bucket {
Subroutine delete_bucket: not called CC=1 SCAR=6.9
Pod documented
54 0 my ($self, $cb) = @_;
55 0 $self->{js}->stream_delete($self->{stream}, $cb);
56 }
57  
58 # Best-effort purge that survives a dead connection: a sync croak
59 # (not connected, nothing queued) skips the purge and runs $cb now.
60 10 ▶sub _purge_best_effort {
Subroutine _purge_best_effort: called CC=2 SCAR=6.9
61 10 my ($self, $filter, $cb) = @_;
62 10 my $ok = eval {
63 $self->{js}->_json_api('STREAM.PURGE.' . $self->{stream},
64 10 { filter => $filter }, $cb);
65 9 1;
66 };
67 10 ▶ $cb->() unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 1 9 10
68 }
69  
70 14 ▶sub put {
Subroutine put: called CC=4 SCAR=13.9
Pod documented
71 14 my ($self, $name, $data, $cb) = @_;
72 # Fail fast on a chunk_size the server cannot take, instead of dying
73 # async in a chunk publish. Skipped pre-connect: max_payload is only
74 # the default until the first INFO arrives.
75 14 ▶ if ($self->{js}{nats}->is_connected) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"js"}{"nats"}->is_connected) 2 12 14
76 2 my $max = $self->{js}{nats}->max_payload;
77 2 ▶ if ($max > 0 && $self->{chunk_size} > $max) {
Branch: 1 branch
BranchTrueFalseTotal
if ($max > 0 and $self->{"chunk_size"} > $max) 1 1 2
Condition66%2/3
$max > 0 and $self->{"chunk_size"} > $max
!ll&&!rl&&r
011
MC/DC50%1/2
$max > 0 and $self->{"chunk_size"} > $max
$max > 0 $self->{"chunk_size"} > $max
Truth table66%2/3
A and B
A= $max > 0B= $self->{"chunk_size"} > $max
ABresult
0X0
100
111
78 1 die "chunk_size ($self->{chunk_size}) exceeds max_payload ($max)";
79 }
80 }
81 # Look up any existing object first so its old chunks / legacy %XX meta
82 # can be purged after the new meta is rolled up. A real error aborts.
83 13 ▶ $self->_raw_meta($name, sub {
Subroutine __ANON__: called CC=5 SCAR=16.2
84 13 my ($old_meta, $old_subj, $old_gone, $err) = @_;
85 13 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 13 13
86  
87 13 my $nuid = _nuid();
88 # ADR-20 digest: padded base64url of the raw SHA-256 (nats.go form).
89 13 my $sha = _b64url(sha256($data));
90 13 my $size = length $data;
91 13 my $chunks = 0;
92 13 my $offset = 0;
93 13 my $chunk_subj = '$O.' . $self->{bucket} . '.C.' . $nuid;
94  
95 # Publish chunks via JetStream (with ack for durability)
96 13 my $chunk_errors = 0;
97 13 my $chunks_acked = 0;
98  
99 # Define completion handler before starting any publishes
100 13 ▶ my $on_all_chunks = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
101 13 ▶ if ($chunk_errors) {
Branch: 1 branch
BranchTrueFalseTotal
if ($chunk_errors) 3 10 13
102 # Best-effort: purge this put's already-stored chunks so a
103 # failed put leaves no debris no meta points at.
104 $self->_purge_best_effort($chunk_subj,
105 3 ▶ sub { $cb->(undef, "$chunk_errors chunk(s) failed to publish") });
Subroutine __ANON__: called CC=1 SCAR=0.0
106 3 return;
107 }
108 10 require JSON::PP;
109 my $meta = JSON::PP::encode_json({
110 name => $name,
111 size => $size,
112 chunks => $chunks,
113 nuid => $nuid,
114 digest => "SHA-256=$sha",
115 bucket => $self->{bucket},
116 10 });
117 10 my $meta_subj = '$O.' . $self->{bucket} . '.M.' . _encode_name($name);
118 # Nats-Rollup: sub keeps exactly one message on the meta subject.
119 10 my $headers = "NATS/1.0\r\nNats-Rollup: sub\r\n\r\n";
120 9 ▶ my $on_meta = sub {
Subroutine __ANON__: called CC=9 SCAR=22.4
121 9 my ($ack, $err) = @_;
122 9 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 1 8 9
123 $self->_purge_best_effort($chunk_subj,
124 1 ▶ sub { $cb->(undef, $err) });
Subroutine __ANON__: called CC=1 SCAR=0.0
125 1 return;
126 }
127  
128 # Purge the previous object's chunks, and its legacy %XX
129 # meta subject when found there (migrate to base64url).
130 8 my @purges;
131 8 ▶ if ($old_meta && !$old_gone
Branch: 1 branch
BranchTrueFalseTotal
if ($old_meta and not $old_gone and length($old_meta->{"nuid"} // "") and $old_meta->{"nuid"} ne $nuid) 1 7 8
Condition63%7/11
$old_meta and not $old_gone and length($old_meta->{"nuid"} // "") and $old_meta->{"nuid"} ne $nuid
!ll&&!rl&&r
701
$old_meta and not $old_gone and length($old_meta->{"nuid"} // "")
!ll&&!rl&&r
701
$old_meta and not $old_gone
!ll&&!rl&&r
701
$old_meta->{"nuid"} // ""
l!l
10
MC/DC25%1/4
$old_meta and not $old_gone and length($old_meta->{"nuid"} // "") and $old_meta->{"nuid"} ne $nuid
$old_meta not $old_gone $old_meta->{"nuid"} $old_meta->{"nuid"} ne $nuid
Truth table40%2/5
A and not(B) and C and D
A= $old_metaB= not $old_goneC= $old_meta->{"nuid"}D= $old_meta->{"nuid"} ne $nuid
ABCDresult
0XXX0
10XX0
110X0
11100
11111
132 && length($old_meta->{nuid} // '')
133 && $old_meta->{nuid} ne $nuid) {
134 1 push @purges, '$O.' . $self->{bucket} . '.C.' . $old_meta->{nuid};
135 }
136 8 my $legacy_subj = '$O.' . $self->{bucket} . '.M.' . _encode_name_legacy($name);
137 8 ▶ if ($old_subj && $old_subj eq $legacy_subj) {
Branch: 1 branch
BranchTrueFalseTotal
if ($old_subj and $old_subj eq $legacy_subj) 0 8 8
Condition66%2/3
$old_subj and $old_subj eq $legacy_subj
!ll&&!rl&&r
710
MC/DC0%0/2
$old_subj and $old_subj eq $legacy_subj
$old_subj $old_subj eq $legacy_subj
Truth table66%2/3
A and B
A= $old_subjB= $old_subj eq $legacy_subj
ABresult
0X0
100
111
138 0 push @purges, $legacy_subj;
139 }
140 # The put already succeeded (meta rolled up); old-chunk
141 # cleanup is best-effort.
142 8 my $run_purge;
143 9 ▶ $run_purge = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
144 9 my $filter = shift @purges;
145 9 ▶ if (!defined $filter) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $filter) 8 1 9
146 # Break the $run_purge self-cycle before firing $cb.
147 8 undef $run_purge;
148 8 return $cb->({ name => $name, size => $size, chunks => $chunks, seq => $ack->{seq} }, undef);
149 }
150 $self->_purge_best_effort($filter,
151 1 ▶ sub { $run_purge->() }); # ignore purge errors
Subroutine __ANON__: called CC=1 SCAR=0.0
152 8 };
153 8 $run_purge->();
154 10 };
155 10 ▶ if (!eval { $self->{js}->js_publish_h($meta_subj, $headers, $meta, $on_meta); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (not eval { do { $self->{"js"}->js_publish_h($meta_subj, $headers, $meta, $on_meta); 1 } }) 1 9 10
156 1 my $err = $@;
157 1 ▶ $self->_purge_best_effort($chunk_subj, sub { $cb->(undef, $err) });
Subroutine __ANON__: called CC=1 SCAR=0.0
158 }
159 13 };
160  
161 30 ▶ my $publish_chunk = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
162 30 my $chunk = shift;
163 30 ▶ my $on_ack = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
164 30 my ($ack, $err) = @_;
165 30 ▶ $chunk_errors++ if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 15 15 30
166 30 $chunks_acked++;
167 30 ▶ $on_all_chunks->() if $chunks_acked >= $chunks;
Branch: 1 branch
BranchTrueFalseTotal
if $chunks_acked >= $chunks 13 17 30
168 30 };
169 $on_ack->(undef, $@)
170 30 ▶ unless eval { $self->{js}->js_publish($chunk_subj, $chunk, $on_ack); 1 };
Branch: 1 branch
BranchTrueFalseTotal
unless eval { do { $self->{"js"}->js_publish($chunk_subj, $chunk, $on_ack); 1 } } 4 26 30
171 13 };
172  
173 13 ▶ if ($size == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($size == 0) { } 0 13 13
174 0 $chunks = 1;
175 0 $publish_chunk->('');
176 } else {
177 # Fix the total first: an ack arriving before the loop ends would
178 # otherwise complete the object with a short count.
179 13 $chunks = int(($size + $self->{chunk_size} - 1) / $self->{chunk_size});
180 13 ▶ while ($offset < $size) {
Branch: 1 branch
BranchTrueFalseTotal
if ($offset < $size) 30 13 43
181 30 my $end = $offset + $self->{chunk_size};
182 30 ▶ $end = $size if $end > $size;
Branch: 1 branch
BranchTrueFalseTotal
if $end > $size 10 20 30
183 30 $publish_chunk->(substr($data, $offset, $end - $offset));
184 30 $offset = $end;
185 }
186 }
187 13 });
188 }
189  
190 10 ▶sub get {
Subroutine get: called CC=1 SCAR=0.1
Pod documented
191 10 my ($self, $name, $cb) = @_;
192  
193 10 ▶ $self->_raw_meta($name, sub {
Subroutine __ANON__: called CC=6 SCAR=18.8
194 10 my ($meta, $meta_subj, $gone, $err) = @_;
195 10 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 10 10
196 # Missing object or deleted marker: a clean miss, same as KV::get.
197 10 ▶ return $cb->(undef, undef) if !$meta || $gone;
Branch: 1 branch
BranchTrueFalseTotal
if not $meta or $gone 4 6 10
Condition100%3/3
not $meta or $gone
l!l&&r!l&&!r
136
MC/DC100%2/2
not $meta or $gone
not $meta $gone
Truth table100%3/3
not(A) or B
A= not $metaB= $gone
ABresult
1X1
011
000
198  
199 6 my $nuid = $meta->{nuid};
200 6 ▶ my $expected = $meta->{chunks} || 0;
Condition50%1/2
$meta->{'chunks'} || 0
l!l
60
MC/DC0%0/1
$meta->{'chunks'} || 0
$meta->{'chunks'}
Truth table50%1/2
A
A= $meta->{'chunks'}
Aresult
11
00
201 6 my $chunk_subj = '$O.' . $self->{bucket} . '.C.' . $nuid;
202  
203 6 ▶ if ($expected == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if ($expected == 0) 0 6 6
204 0 return $cb->('', undef, $meta);
205 }
206  
207 # Fetch chunks sequentially via STREAM.MSG.GET.
208 # next_by_subj returns first matching message with seq >= start_sequence,
209 # so after each hit we must advance past the returned seq.
210 6 my @chunks;
211 6 my $seq = 1;
212  
213 6 my $fetch_next;
214 6 ▶ $fetch_next = sub {
Subroutine __ANON__: called CC=1 SCAR=0.2
215 $self->{js}->_json_api(
216 'STREAM.MSG.GET.' . $self->{stream},
217 { next_by_subj => $chunk_subj, seq => $seq },
218 6 ▶ sub {
Subroutine __ANON__: called CC=10 SCAR=25.2
219 6 my ($resp, $err) = @_;
220 6 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 0 6 6
221 # Break the $fetch_next self-cycle before firing
222 # $cb, or the closure pins $self forever.
223 0 undef $fetch_next;
224 0 return $cb->(undef, "chunk fetch error: $err", $meta);
225 }
226 6 my $msg = $resp->{message};
227 6 ▶ if (!$msg) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($msg) 0 6 6
228 0 undef $fetch_next;
229 0 return $cb->(undef, "missing chunk message", $meta);
230 }
231 6 require MIME::Base64;
232 6 ▶ my $data = MIME::Base64::decode_base64($msg->{data} || '');
Condition50%1/2
$msg->{'data'} || ''
l!l
60
MC/DC0%0/1
$msg->{'data'} || ''
$msg->{'data'}
Truth table50%1/2
A
A= $msg->{'data'}
Aresult
11
00
233 6 push @chunks, $data;
234 6 ▶ $seq = ($msg->{seq} || $seq) + 1;
Condition33%1/3
$msg->{'seq'} || $seq
l!l&&r!l&&!r
600
MC/DC0%0/2
$msg->{'seq'} || $seq
$msg->{'seq'} $seq
Truth table33%1/3
A || B
A= $msg->{'seq'}B= $seq
ABresult
1X1
011
000
235  
236 6 ▶ if (scalar @chunks >= $expected) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @chunks >= $expected) { } 6 0 6
237 6 my $assembled = join('', @chunks);
238 6 ▶ if ($meta->{digest} && $meta->{digest} =~ /^SHA-256=(.+)\z/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->{"digest"} and $meta->{"digest"} =~ /^SHA-256=(.+)\z/) 6 0 6
Condition33%1/3
$meta->{"digest"} and $meta->{"digest"} =~ /^SHA-256=(.+)\z/
!ll&&!rl&&r
006
MC/DC0%0/2
$meta->{"digest"} and $meta->{"digest"} =~ /^SHA-256=(.+)\z/
$meta->{"digest"} $meta->{"digest"} =~ /^SHA-256=(.+)\z/
Truth table33%1/3
A and B
A= $meta->{"digest"}B= $meta->{"digest"} =~ /^SHA-256=(.+)\z/
ABresult
0X0
100
111
239 # Accept all three writers: 0.03/0.04 hex, 0.05
240 # unpadded base64url, and 0.06+/nats.go padded.
241 6 my $stored = $1;
242 6 my $ok;
243 6 ▶ if ($stored =~ /\A[0-9a-f]{64}\z/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stored =~ /\A[0-9a-f]{64}\z/) { } 1 5 6
244 1 $ok = sha256_hex($assembled) eq $stored;
245 } else {
246 5 (my $s = $stored) =~ s/=+\z//;
247 5 (my $g = _b64url(sha256($assembled))) =~ s/=+\z//;
248 5 $ok = $g eq $s;
249 }
250 6 ▶ unless ($ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($ok) 1 5 6
251 1 undef $fetch_next;
252 1 return $cb->(undef, "digest mismatch", $meta);
253 }
254 }
255 5 undef $fetch_next;
256 5 $cb->($assembled, undef, $meta);
257 } else {
258 0 $fetch_next->();
259 }
260 }
261 6 );
262 6 };
263 6 $fetch_next->();
264 10 });
265 }
266  
267 5 ▶sub delete {
Subroutine delete: called CC=1 SCAR=0.1
Pod documented
268 5 my ($self, $name, $cb) = @_;
269 # nats.go marks a delete with the full metadata JSON carrying
270 # "deleted":true and a rollup header, not an empty KV-Operation tombstone.
271 5 ▶ $self->_raw_meta($name, sub {
Subroutine __ANON__: called CC=8 SCAR=21.6
272 5 my ($meta, $found_subj, $gone, $err) = @_;
273 5 ▶ return $cb ? $cb->(undef, $err) : undef if $err;
Branch: 2 branches
BranchTrueFalseTotal
if $err 0 5 5
$cb ? : 0 0 0
274 # Idempotent: nothing live to delete -> success, no spurious marker.
275 5 ▶ return $cb ? $cb->(1, undef) : undef if !$meta || $gone;
Branch: 2 branches
BranchTrueFalseTotal
if not $meta or $gone 2 3 5
$cb ? : 2 0 2
Condition100%3/3
not $meta or $gone
l!l&&r!l&&!r
113
MC/DC100%2/2
not $meta or $gone
not $meta $gone
Truth table100%3/3
not(A) or B
A= not $metaB= $gone
ABresult
1X1
011
000
276  
277 3 my $prefix = '$O.' . $self->{bucket} . '.M.';
278 3 my $meta_subj = $prefix . _encode_name($name);
279 3 my $legacy_subj = $prefix . _encode_name_legacy($name);
280 3 ▶ my $nuid = length($meta->{nuid} // '') ? $meta->{nuid} : undef;
Branch: 1 branch
BranchTrueFalseTotal
length($meta->{'nuid'} // '') ? : 3 0 3
Condition50%1/2
$meta->{"nuid"} // ""
l!l
30
MC/DC0%0/1
$meta->{"nuid"} // ""
$meta->{"nuid"}
Truth table50%1/2
A
A= $meta->{"nuid"}
Aresult
11
00
281  
282 3 require JSON::PP;
283 my $marker = JSON::PP::encode_json({
284 name => $name,
285 bucket => $self->{bucket},
286 3 nuid => '',
287 size => 0,
288 chunks => 0,
289 digest => '',
290 deleted => JSON::PP::true(),
291 });
292 3 my $headers = "NATS/1.0\r\nNats-Rollup: sub\r\n\r\n";
293  
294 # Mark deleted first (nats.go order) so a best-effort cleanup purge
295 # can't leave a "deleted" object still readable.
296 3 ▶ $self->{js}->js_publish_h($meta_subj, $headers, $marker, sub {
Subroutine __ANON__: called CC=6 SCAR=18.4
297 3 my ($ack, $perr) = @_;
298 3 ▶ return $cb ? $cb->(undef, $perr) : undef if $perr;
Branch: 2 branches
BranchTrueFalseTotal
if $perr 0 3 3
$cb ? : 0 0 0
299  
300 3 my @cleanup;
301 3 ▶ push @cleanup, '$O.' . $self->{bucket} . '.C.' . $nuid if $nuid;
Branch: 1 branch
BranchTrueFalseTotal
if $nuid 3 0 3
302 # A live meta at the legacy %XX subject would resurface via the
303 # dual-read fallback / list(); purge it too.
304 3 ▶ push @cleanup, $legacy_subj if $found_subj && $found_subj eq $legacy_subj;
Branch: 1 branch
BranchTrueFalseTotal
if $found_subj and $found_subj eq $legacy_subj 1 2 3
Condition66%2/3
$found_subj and $found_subj eq $legacy_subj
!ll&&!rl&&r
021
MC/DC50%1/2
$found_subj and $found_subj eq $legacy_subj
$found_subj $found_subj eq $legacy_subj
Truth table66%2/3
A and B
A= $found_subjB= $found_subj eq $legacy_subj
ABresult
0X0
100
111
305  
306 3 ▶ my $step; $step = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
307 7 my $subj = shift @cleanup;
308 7 ▶ if (!defined $subj) { undef $step; return $cb ? $cb->(1, undef) : undef }
Branch: 2 branches
BranchTrueFalseTotal
unless (defined $subj) 3 4 7
$cb ? : 3 0 3
309 4 ▶ $self->_purge_best_effort($subj, sub { $step->() });
Subroutine __ANON__: called CC=1 SCAR=0.0
310 3 };
311 3 $step->();
312 3 });
313 5 });
314 }
315  
316 3 ▶sub info {
Subroutine info: called CC=1 SCAR=0.0
Pod documented
317 3 my ($self, $name, $cb) = @_;
318 3 ▶ $self->_raw_meta($name, sub {
Subroutine __ANON__: called CC=4 SCAR=14.1
319 3 my ($meta, $meta_subj, $gone, $err) = @_;
320 3 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 3 3
321 # Missing or deleted (tombstone or "deleted":true): a clean miss.
322 3 ▶ return $cb->(undef, undef) if !$meta || $gone;
Branch: 1 branch
BranchTrueFalseTotal
if not $meta or $gone 2 1 3
Condition66%2/3
not $meta or $gone
l!l&&r!l&&!r
021
MC/DC50%1/2
not $meta or $gone
not $meta $gone
Truth table66%2/3
not(A) or B
A= not $metaB= $gone
ABresult
1X1
011
000
323 1 $cb->($meta, undef);
324 3 });
325 }
326  
327 1 ▶sub list {
Subroutine list: called CC=1 SCAR=0.0
Pod documented
328 1 my ($self, $cb) = @_;
329 1 my $prefix = '$O.' . $self->{bucket} . '.M.';
330 $self->{js}->stream_info(
331 $self->{stream},
332 { subjects_filter => $prefix . '>' },
333 1 ▶ sub {
Subroutine __ANON__: called CC=3 SCAR=11.1
334 1 my ($info, $err) = @_;
335 1 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 1 1
336 1 ▶ my $subjects = $info->{state}{subjects} || {};
Condition50%1/2
$info->{'state'}{'subjects'} || {}
l!l
10
MC/DC0%0/1
$info->{'state'}{'subjects'} || {}
$info->{'state'}{'subjects'}
Truth table50%1/2
A
A= $info->{'state'}{'subjects'}
Aresult
11
00
337 1 my $plen = length $prefix;
338 # Best-effort decode: base64url names (0.06+/nats.go) and
339 # legacy %XX names (0.03-0.05) can share a bucket.
340 2 my @names = map { _decode_name_best(substr($_, $plen)) }
341 1 grep { substr($_, 0, $plen) eq $prefix }
342 keys %$subjects;
343 1 $cb->(\@names, undef);
344 },
345 1 );
346 }
347  
348 0 ▶sub status {
Subroutine status: not called CC=1 SCAR=6.9
Pod documented
349 0 my ($self, $cb) = @_;
350 0 ▶ $self->{js}->stream_info($self->{stream}, sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
351 0 my ($info, $err) = @_;
352 0 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
353 $cb->({
354 bucket => $self->{bucket},
355 bytes => $info->{state}{bytes},
356 0 ▶ sealed => $info->{config}{sealed} ? 1 : 0,
Branch: 1 branch
BranchTrueFalseTotal
$info->{'config'}{'sealed'} ? : 0 0 0
357 }, undef);
358 0 });
359 }
360  
361 # ($meta, $found_subject, $is_gone, $err) -> $cb. Dual-read: base64url meta
362 # subject first, then legacy %XX (0.03-0.05 buckets stay readable). $is_gone
363 # covers a KV-Operation tombstone and a "deleted":true meta; $meta is still
364 # returned when gone so delete() can read its nuid.
365 31 ▶sub _raw_meta {
Subroutine _raw_meta: called CC=2 SCAR=7.1
366 31 my ($self, $name, $cb) = @_;
367 31 my $prefix = '$O.' . $self->{bucket} . '.M.';
368 31 my @try = $prefix . _encode_name($name);
369 31 my $legacy = $prefix . _encode_name_legacy($name);
370 31 ▶ push @try, $legacy if $legacy ne $try[0];
Branch: 1 branch
BranchTrueFalseTotal
if $legacy ne $try[0] 31 0 31
371  
372 31 my $attempt;
373 62 ▶ $attempt = sub {
Subroutine __ANON__: called CC=2 SCAR=7.2
374 62 my $meta_subj = shift @try;
375 62 ▶ if (!defined $meta_subj) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $meta_subj) 14 48 62
376 # Break the $attempt self-cycle before firing $cb.
377 14 undef $attempt;
378 14 return $cb->(undef, undef, 0, undef);
379 }
380 $self->{js}->_json_api(
381 'STREAM.MSG.GET.' . $self->{stream},
382 { last_by_subj => $meta_subj },
383 48 ▶ sub {
Subroutine __ANON__: called CC=10 SCAR=25.1
384 48 my ($resp, $err) = @_;
385 48 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 31 17 48
386 # Clean miss on this subject -> try the fallback form.
387 31 ▶ return $attempt->() if $err =~ /no message found|\(code 10037\)/;
Branch: 1 branch
BranchTrueFalseTotal
if $err =~ /no message found|\(code 10037\)/ 31 0 31
388 0 undef $attempt;
389 0 return $cb->(undef, undef, 0, $err);
390 }
391 17 my $msg = $resp->{message};
392 17 ▶ return $attempt->() if !$msg;
Branch: 1 branch
BranchTrueFalseTotal
unless $msg 0 17 17
393 17 my $tombstone = EV::Nats::JetStream::msg_is_tombstone($msg);
394 17 require MIME::Base64;
395 17 ▶ my $meta_json = MIME::Base64::decode_base64($msg->{data} || '');
Condition50%1/2
$msg->{'data'} || ''
l!l
170
MC/DC0%0/1
$msg->{'data'} || ''
$msg->{'data'}
Truth table50%1/2
A
A= $msg->{'data'}
Aresult
11
00
396 17 my ($meta, $derr);
397 # A tombstone's payload is empty; only parse real data.
398 17 ▶ if (length $meta_json) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $meta_json) 17 0 17
399 17 ($meta, $derr) = EV::Nats::JetStream::decode_json_or_error($meta_json);
400 17 ▶ if ($derr) {
Branch: 1 branch
BranchTrueFalseTotal
if ($derr) 0 17 17
401 0 undef $attempt;
402 0 return $cb->(undef, $meta_subj, 0, "invalid metadata: $derr");
403 }
404 }
405 17 ▶ my $gone = ($tombstone || ($meta && $meta->{deleted})) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$tombstone || $meta && $meta->{'deleted'} ? : 6 11 17
Condition66%4/6
$tombstone or $meta and $meta->{"deleted"}
l!l&&r!l&&!r
0611
$meta and $meta->{"deleted"}
!ll&&!rl&&r
0116
MC/DC33%1/3
$tombstone or $meta and $meta->{"deleted"}
$tombstone $meta $meta->{"deleted"}
Truth table50%2/4
A or B and C
A= $tombstoneB= $metaC= $meta->{"deleted"}
ABCresult
1XX1
0111
00X0
0100
406 17 undef $attempt;
407 17 $cb->($meta, $meta_subj, $gone, undef);
408 }
409 48 );
410 31 };
411 31 $attempt->();
412 }
413  
414 13 ▶sub _nuid {
Subroutine _nuid: called CC=2 SCAR=7.9
415 13 ▶ if ($NUID_PID != $$) {
Branch: 1 branch
BranchTrueFalseTotal
if ($NUID_PID != $$) 0 13 13
416 0 srand();
417 0 $NUID_PID = $$;
418 }
419 13 my @chars = ('A'..'Z', 'a'..'z', '0'..'9');
420 13 join '', map { $chars[rand @chars] } 1..22;
421 }
422  
423 # padded base64url of a byte/most-strings value, matching Go URLEncoding
424 67 ▶sub _b64url {
Subroutine _b64url: called CC=2 SCAR=7.0
425 67 my $bytes = shift;
426 67 ▶ utf8::encode($bytes) if utf8::is_utf8($bytes); # names may be wide
Branch: 1 branch
BranchTrueFalseTotal
if utf8::is_utf8($bytes) 0 67 67
427 67 require MIME::Base64;
428 67 (my $e = MIME::Base64::encode_base64($bytes, '')) =~ tr{+/}{-_};
429 67 return $e; # keeps '=' padding
430 }
431 # inverse: padded-or-unpadded base64url -> UTF-8-decoded string
432 4 ▶sub _b64url_dec {
Subroutine _b64url_dec: called CC=1 SCAR=0.0
433 4 my $s = shift;
434 4 $s =~ tr{-_}{+/};
435 4 require MIME::Base64;
436 4 my $b = MIME::Base64::decode_base64($s); # tolerant of padding
437 4 utf8::decode($b);
438 4 return $b;
439 }
440  
441 # ADR-20 name encoding: padded base64url (nats.go). The 0.03-0.05 %XX
442 # percent form is kept as *_legacy for the dual-read fallback.
443 49 ▶sub _encode_name { _b64url($_[0]) }
Subroutine _encode_name: called CC=1 SCAR=0.0
444 2 ▶sub _decode_name { _b64url_dec($_[0]) }
Subroutine _decode_name: called CC=1 SCAR=0.0
445 43 ▶sub _encode_name_legacy { my $n = $_[0]; $n =~ s/([^A-Za-z0-9._-])/sprintf("%%%02X", ord($1))/ge; $n }
Subroutine _encode_name_legacy: called CC=1 SCAR=0.0
446 2 ▶sub _decode_name_legacy { my $n = $_[0]; $n =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/ge; $n }
Subroutine _decode_name_legacy: called CC=1 SCAR=0.0
447  
448 # Best-effort name decode for list(): the base64url form wins when
449 # re-encoding round-trips, otherwise fall back to the legacy %XX form.
450 2 ▶sub _decode_name_best {
Subroutine _decode_name_best: called CC=2 SCAR=6.9
451 2 my $tok = shift;
452 2 my $dec = _b64url_dec($tok);
453 2 ▶ return $dec if _encode_name($dec) eq $tok;
Branch: 1 branch
BranchTrueFalseTotal
if _encode_name($dec) eq $tok 1 1 2
454 1 return _decode_name_legacy($tok);
455 }
456  
457 3 1;
458  
459 =head1 NAME
460  
461 EV::Nats::ObjectStore - Chunked object store on top of NATS JetStream
462  
463 =head1 SYNOPSIS
464  
465 use EV;
466 use EV::Nats;
467 use EV::Nats::JetStream;
468 use EV::Nats::ObjectStore;
469  
470 my $nats = EV::Nats->new(host => '127.0.0.1');
471 my $js = EV::Nats::JetStream->new(nats => $nats);
472 my $os = EV::Nats::ObjectStore->new(js => $js, bucket => 'files');
473 my $pdf_data = '...'; # your file bytes here
474  
475 $os->create_bucket({}, sub {
476 $os->put('report.pdf', $pdf_data, sub {
477 my ($info, $err) = @_;
478 print "stored: $info->{size} bytes in $info->{chunks} chunks\n";
479 $os->get('report.pdf', sub {
480 my ($data, $err, $meta) = @_;
481 print "got $meta->{size} bytes back\n";
482 });
483 });
484 });
485  
486 EV::run;
487  
488 =head1 DESCRIPTION
489  
490 An object-store bucket is a JetStream stream named C<OBJ_E<lt>bucketE<gt>>
491 with two subject groups:
492  
493 =over
494  
495 =item * C<$O.E<lt>bucketE<gt>.C.E<lt>nuidE<gt>> - opaque chunks for one
496 object (one chunk per stream message; the nuid is generated per object).
497  
498 =item * C<$O.E<lt>bucketE<gt>.M.E<lt>encoded-nameE<gt>> - last-write-wins
499 metadata describing an object (name, size, chunk count, SHA-256 digest).
500  
501 =back
502  
503 C<put> chunks the input, publishes each chunk via C<js_publish> for
504 durability, then writes a metadata entry. C<get> fetches the metadata,
505 walks the chunks back via C<STREAM.MSG.GET>, and verifies the digest.
506  
507 =head1 METHODS
508  
509 All callbacks fire on the L<EV> loop, not synchronously.
510  
511 =head2 new
512  
513 new(js => $js, bucket => $name, [chunk_size => $bytes])
514  
515 Default C<chunk_size> is 128 KiB. C<timeout> defaults to the timeout
516 of C<$js>. The bucket name must match C<[a-zA-Z0-9_-]+> and
517 C<chunk_size> must be a positive integer; both are validated up
518 front. C<chunk_size> must also not exceed the server's
519 C<max_payload> (checked on L</put> once connected).
520  
521 =head2 create_bucket
522  
523 create_bucket(\%opts, $cb)
524  
525 Provision the underlying stream. Recognised C<\%opts>:
526  
527 =over
528  
529 =item * C<max_bytes> - bucket-wide storage cap.
530  
531 =item * C<max_age> - per-message TTL in nanoseconds.
532  
533 =item * C<replicas> - cluster replication factor.
534  
535 =back
536  
537 Callback: C<($info, $err)>.
538  
539 =head2 delete_bucket
540  
541 delete_bucket($cb)
542  
543 Tear down the underlying stream. Callback: C<($info, $err)>.
544  
545 =head2 put
546  
547 put($name, $data, $cb)
548  
549 Store C<$data> under C<$name>, automatically chunked. Each chunk is
550 published with JetStream ack; the metadata entry is written last
551 (with a C<Nats-Rollup: sub> header, so the meta subject holds exactly
552 one message) so a partial upload doesn't surface a half-stored object.
553 Overwriting an existing name purges the previous object's chunks after
554 the new metadata is acknowledged. Callback: C<($info, $err)> where
555 C<$info> is C<{ name, size, chunks, seq }>.
556  
557 =head2 get
558  
559 get($name, $cb)
560  
561 Retrieve a previously-stored object. Callback: C<($data, $err, $meta)>.
562 C<$data> is C<undef> if the object does not exist or has been deleted
563 (both the old C<KV-Operation> tombstone and the nats.go
564 C<"deleted":true> marker are recognised). On digest mismatch, C<$data>
565 is C<undef> and C<$err> is C<"digest mismatch">. Digests written by
566 0.03/0.04 (hex), 0.05 (unpadded base64url) and 0.06+/nats.go (padded
567 base64url) all verify.
568  
569 =head2 delete
570  
571 delete($name, [$cb])
572  
573 Publishes a C<"deleted":true> metadata marker with a C<Nats-Rollup:
574 sub> header (the nats.go form; the PubAck doubles as the flush fence),
575 then best-effort purges the object's chunks under
576 C<$O.E<lt>bucketE<gt>.C.E<lt>nuidE<gt>>. Marking is done first, so a
577 purge hiccup cannot leave a "deleted" object still readable. Idempotent:
578 deleting a missing or already-deleted object is a no-op success and
579 writes no marker. Callback: C<($ok, $err)>.
580  
581 =head2 info
582  
583 info($name, $cb)
584  
585 Fetch only the metadata entry for an object, without downloading
586 chunks. Callback: C<(\%meta, $err)>; C<\%meta> is C<undef> if the
587 object does not exist or was deleted (the deletion marker is
588 recognised). This is the recommended way to filter live objects out
589 of a L</list> result.
590  
591 =head2 list
592  
593 list($cb)
594  
595 List object names in the bucket. Callback: C<(\@names, $err)>.
596 Names written by 0.03-0.05 (legacy %XX encoding) and by 0.06+/nats.go
597 (base64url) are both decoded. Deleted entries still appear in the
598 listing -- filtering them would cost a per-name metadata round-trip,
599 so call C<info> to filter.
600  
601 =head2 status
602  
603 status($cb)
604  
605 Returns a snapshot hashref:
606  
607 { bucket => $name, bytes => $n, sealed => 0|1 }
608  
609 C<sealed> reflects the underlying stream's C<config.sealed> flag;
610 this client never seals on its own, so unless someone manually
611 sealed the stream out-of-band the value is always 0.
612  
613 Callback: C<(\%status, $err)>.
614  
615 =head1 SEE ALSO
616  
617 L<EV::Nats>, L<EV::Nats::JetStream>, L<EV::Nats::KV>,
618 L<NATS Object Store|https://docs.nats.io/using-nats/developer/develop_jetstream/object>.
619  
620 =cut
« blib/lib/EV/Nats/KV.pm ↑ Summary blib/lib/EV/Nats.pm »