blib/lib/EV/Nats/KV.pm

filter: Statementstmt 57.7% 86 / 149 Branchbran 27.7% 15 / 54 Conditioncond 40.4% 17 / 42 MC/DCmcdc 13.0% 3 / 23 Subroutinesub 60.0% 18 / 30 Podpod 100% 12 / 12 totaltotal 48.7% 151 / 310 CC 46 SCAR 23.6
CC
46
Cov
48%
create_bucket
42.0
__ANON__
21.2
__ANON__
20.0
CRAP 10.6
« blib/lib/EV/Nats/JetStream.pm ↑ Summary blib/lib/EV/Nats/ObjectStore.pm »
1 package EV::Nats::KV;
2 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 our $VERSION = '0.06';
5 4 ▶use EV;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 4 ▶use EV::Nats::JetStream;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 12 ▶sub new {
Subroutine new: called CC=6 SCAR=18.3
Pod documented
9 12 my ($class, %opts) = @_;
10 12 ▶ my $js = delete $opts{js} || die "js (JetStream) required";
Condition50%1/2
delete $opts{'js'} || die('js (JetStream) required')
l!l
120
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
11 12 ▶ my $bucket = delete $opts{bucket} || die "bucket name required";
Condition50%1/2
delete $opts{'bucket'} || die('bucket name required')
l!l
120
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
12 # The bucket name is interpolated into subjects verbatim; validate (nats.go rule) up front.
13 12 ▶ die "invalid KV bucket name '$bucket'" unless $bucket =~ /\A[a-zA-Z0-9_-]+\z/;
Branch: 1 branch
BranchTrueFalseTotal
unless $bucket =~ /\A[a-zA-Z0-9_-]+\z/ 1 11 12
14 11 ▶ my $timeout = delete $opts{timeout} || $js->{timeout};
Condition66%2/3
delete $opts{'timeout'} || $js->{'timeout'}
l!l&&r!l&&!r
1100
MC/DC0%0/2
delete $opts{'timeout'} || $js->{'timeout'}
delete $opts{'timeout'} $js->{'timeout'}
Truth table66%2/3
A || B
A= delete $opts{'timeout'}B= $js->{'timeout'}
ABresult
1X1
011
000
15 11 warn "EV::Nats::KV::new: unknown option '$_'" for keys %opts;
16 11 bless {
17 js => $js,
18 bucket => $bucket,
19 stream => "KV_$bucket",
20 timeout => $timeout,
21 }, $class;
22 }
23  
24 # Keys are interpolated into subjects verbatim: spaces are a fatal protocol
25 # error, * and > turn lookups into wildcards. Validate (nats.go rule) up front.
26 22 ▶sub _check_key {
Subroutine _check_key: called CC=5 SCAR=16.1
27 22 my $key = shift;
28 22 ▶ die "invalid KV key '$key'"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./ and not $key =~ /\.\z/ 6 16 22
Condition88%8/9
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./ and not $key =~ /\.\z/
!ll&&!rl&&r
5116
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./
!ll&&!rl&&r
4117
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z]
!ll&&!rl&&r
0418
MC/DC75%3/4
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./ and not $key =~ /\.\z/
defined $key $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] not $key =~ /\A\./ not $key =~ /\.\z/
Truth table80%4/5
A and B and not(C) and not(D)
A= defined $keyB= $key =~ m[\A[-/_=.a-zA-Z0-9]+\z]C= not $key =~ /\A\./D= not $key =~ /\.\z/
ABCDresult
0XXX0
10XX0
110X0
11100
11111
29 unless defined $key
30 && $key =~ /\A[-\/_=.a-zA-Z0-9]+\z/
31 && $key !~ /\A\./ && $key !~ /\.\z/;
32 }
33  
34 10 ▶sub get {
Subroutine get: called CC=1 SCAR=2.2
Pod documented
35 10 my ($self, $key, $cb) = @_;
36 10 _check_key($key);
37 4 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
38 $self->{js}->_json_api(
39 'STREAM.MSG.GET.' . $self->{stream},
40 { last_by_subj => $subj },
41 4 ▶ sub {
Subroutine __ANON__: called CC=6 SCAR=30.5
42 4 my ($resp, $err) = @_;
43 4 ▶ if ($err) {
Branch: 1 branch
BranchTrueFalseTotal
if ($err) 4 0 4
44 # 10037 = "no message found" -- treat as missing key
45 4 ▶ return $cb->(undef, undef) if $err =~ /no message found|\(code 10037\)/;
Branch: 1 branch
BranchTrueFalseTotal
if $err =~ /no message found|\(code 10037\)/ 4 0 4
46 0 return $cb->(undef, $err);
47 }
48 0 my $msg = $resp->{message};
49 0 ▶ return $cb->(undef, undef) unless $msg;
Branch: 1 branch
BranchTrueFalseTotal
unless $msg 0 0 0
50 # DEL/PURGE tombstones surface as missing
51 0 ▶ return $cb->(undef, undef)
Branch: 1 branch
BranchTrueFalseTotal
if EV::Nats::JetStream::msg_is_tombstone($msg) 0 0 0
52 if EV::Nats::JetStream::msg_is_tombstone($msg);
53  
54 0 require MIME::Base64;
55 0 ▶ my $value = MIME::Base64::decode_base64($msg->{data} || '');
Condition0%0/2
$msg->{'data'} || ''
l!l
00
MC/DC0%0/1
$msg->{'data'} || ''
$msg->{'data'}
Truth table0%0/2
A
A= $msg->{'data'}
Aresult
11
00
56 0 $cb->($value, undef);
57 },
58 4 );
59 }
60  
61 0 ▶sub put {
Subroutine put: not called CC=1 SCAR=6.9
Pod documented
62 0 my ($self, $key, $value, $cb) = @_;
63 0 _check_key($key);
64 0 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
65 0 ▶ $self->{js}->js_publish($subj, $value, sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
66 0 my ($ack, $err) = @_;
67 0 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
68 0 $cb->($ack->{seq}, undef);
69 0 });
70 }
71  
72 5 ▶sub _expect_publish {
Subroutine _expect_publish: called CC=3 SCAR=13.2
73 5 my ($self, $subj, $headers, $value, $cb, $what) = @_;
74 5 my $nats = $self->{js}{nats};
75  
76 5 ▶ if ($cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cb) { } 5 0 5
77 5 my $inbox = $nats->new_inbox;
78 5 my ($sid, $timer);
79 0 ▶ $sid = $nats->subscribe_max($inbox, sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
80 0 my ($s, $payload) = @_;
81 0 ▶ if ($timer) { $timer->stop; undef $timer; }
Branch: 1 branch
BranchTrueFalseTotal
if ($timer) 0 0 0
82 0 my ($ack, $derr) = EV::Nats::JetStream::decode_json_or_error($payload);
83 0 ▶ return $cb->(undef, $derr) if $derr;
Branch: 1 branch
BranchTrueFalseTotal
if $derr 0 0 0
84 return $cb->(undef, "$ack->{error}{description} (code $ack->{error}{code})")
85 0 ▶ if $ack->{error};
Branch: 1 branch
BranchTrueFalseTotal
if $ack->{"error"} 0 0 0
86 0 $cb->($ack->{seq}, undef);
87 5 }, 1);
88 4 ▶ $timer = $nats->_timer($self->{timeout} / 1000.0, 0, sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
89 4 eval { $nats->unsubscribe($sid) };
90 4 $cb->(undef, "$what timeout");
91 5 });
92 5 ▶ if (!eval { $nats->hpublish($subj, $headers, $value, $inbox); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (not eval { do { $nats->hpublish($subj, $headers, $value, $inbox); 1 } }) 1 4 5
93 1 my $err = $@;
94 1 $timer->stop;
95 1 eval { $nats->unsubscribe($sid) };
96 1 die $err;
97 }
98 } else {
99 0 $nats->hpublish($subj, $headers, $value);
100 }
101 }
102  
103 3 ▶sub create {
Subroutine create: called CC=2 SCAR=10.7
Pod documented
104 3 my ($self, $key, $value, $cb) = @_;
105 3 _check_key($key);
106 3 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
107 $self->_expect_publish($subj,
108 "NATS/1.0\r\nNats-Expected-Last-Subject-Sequence: 0\r\n\r\n",
109 2 ▶ $value, $cb ? sub {
Subroutine __ANON__: called CC=3 SCAR=19.5
110 2 my ($seq, $err) = @_;
111 2 ▶ return $cb->($seq, $err) unless $err && $err =~ /wrong last sequence/i;
Branch: 1 branch
BranchTrueFalseTotal
unless $err and $err =~ /wrong last sequence/i 2 0 2
Condition33%1/3
$err and $err =~ /wrong last sequence/i
!ll&&!rl&&r
020
MC/DC0%0/2
$err and $err =~ /wrong last sequence/i
$err $err =~ /wrong last sequence/i
Truth table33%1/3
A and B
A= $errB= $err =~ /wrong last sequence/i
ABresult
0X0
100
111
112 $self->{js}->_json_api('STREAM.MSG.GET.' . $self->{stream},
113 0 ▶ { last_by_subj => $subj }, sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
114 0 my ($resp, $read_err) = @_;
115 0 ▶ return $cb->(undef, $read_err) if $read_err;
Branch: 1 branch
BranchTrueFalseTotal
if $read_err 0 0 0
116 0 my $msg = $resp->{message};
117 0 ▶ return $cb->(undef, $err)
Branch: 1 branch
BranchTrueFalseTotal
unless EV::Nats::JetStream::msg_is_tombstone($msg) 0 0 0
118 unless EV::Nats::JetStream::msg_is_tombstone($msg);
119 0 $self->_expect_publish($subj,
120 "NATS/1.0\r\nNats-Expected-Last-Subject-Sequence: $msg->{seq}\r\n\r\n",
121 $value, $cb, 'create');
122 0 });
123 3 ▶ } : undef, 'create');
Branch: 1 branch
BranchTrueFalseTotal
$cb ? : 3 0 3
124 }
125  
126 2 ▶sub update {
Subroutine update: called CC=4 SCAR=16.4
Pod documented
127 2 my ($self, $key, $value, $rev, $cb) = @_;
128 2 _check_key($key);
129 2 ▶ die "invalid KV revision '" . ($rev // '') . "'"
Branch: 1 branch
BranchTrueFalseTotal
unless defined $rev and $rev =~ /\A[1-9][0-9]*\z/ 0 2 2
Condition20%1/5
defined $rev and $rev =~ /\A[1-9][0-9]*\z/
!ll&&!rl&&r
002
$rev // ""
l!l
00
MC/DC0%0/2
defined $rev and $rev =~ /\A[1-9][0-9]*\z/
defined $rev $rev =~ /\A[1-9][0-9]*\z/
MC/DC0%0/1
$rev // ""
$rev
Truth table33%1/3
A and B
A= defined $revB= $rev =~ /\A[1-9][0-9]*\z/
ABresult
0X0
100
111
Truth table0%0/2
A
A= $rev
Aresult
11
00
130 unless defined $rev && $rev =~ /\A[1-9][0-9]*\z/;
131 2 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
132 2 $self->_expect_publish($subj,
133 "NATS/1.0\r\nNats-Expected-Last-Subject-Sequence: $rev\r\n\r\n",
134 $value, $cb, 'update');
135 }
136  
137 4 ▶sub delete {
Subroutine delete: called CC=1 SCAR=0.0
Pod documented
138 4 my ($self, $key, $cb) = @_;
139 4 _check_key($key);
140 # KV delete = publish empty with KV-Operation: DEL header.
141 # flush() ensures the tombstone reaches the server before $cb fires
142 # so a subsequent get() doesn't race the publish.
143 4 my $headers = "NATS/1.0\r\nKV-Operation: DEL\r\n\r\n";
144 4 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
145 4 my $nats = $self->{js}{nats};
146 4 _fenced_publish($nats, $subj, $headers, $cb);
147 }
148  
149 3 ▶sub purge {
Subroutine purge: called CC=1 SCAR=0.0
Pod documented
150 3 my ($self, $key, $cb) = @_;
151 3 _check_key($key);
152 3 my $headers = "NATS/1.0\r\nKV-Operation: PURGE\r\nNats-Rollup: sub\r\n\r\n";
153 3 my $subj = '$KV.' . $self->{bucket} . '.' . $key;
154 3 my $nats = $self->{js}{nats};
155 3 _fenced_publish($nats, $subj, $headers, $cb);
156 }
157  
158 # Report publish and flush failures through the supplied callback.
159 7 ▶sub _fenced_publish {
Subroutine _fenced_publish: called CC=4 SCAR=15.1
160 7 my ($nats, $subj, $headers, $cb) = @_;
161 7 ▶ return $nats->hpublish($subj, $headers, '') unless $cb;
Branch: 1 branch
BranchTrueFalseTotal
unless $cb 0 7 7
162 7 my $ok = eval {
163 7 $nats->hpublish($subj, $headers, '');
164 0 ▶ $nats->flush(sub { $cb->(defined $_[0] ? undef : 1, $_[0]) });
Subroutine __ANON__: not called CC=2 SCAR=13.0
Branch: 1 branch
BranchTrueFalseTotal
defined $_[0] ? : 0 0 0
165 0 1;
166 };
167 7 ▶ return if $ok;
Branch: 1 branch
BranchTrueFalseTotal
if $ok 0 7 7
168 7 ▶ (my $err = $@ || 'not connected') =~ s/ at \S+ line \d+.*//s;
Condition50%1/2
$@ || 'not connected'
l!l
70
MC/DC0%0/1
$@ || 'not connected'
$@
Truth table50%1/2
A
A= $@
Aresult
11
00
169 7 $err =~ s/\n\z//;
170 7 ▶ my $t; $t = $nats->_timer(0, 0, sub { undef $t; $cb->(undef, $err) });
Subroutine __ANON__: called CC=1 SCAR=0.0
171 }
172  
173 0 ▶sub keys {
Subroutine keys: not called CC=1 SCAR=6.9
Pod documented
174 0 my ($self, $cb) = @_;
175 0 my $prefix = '$KV.' . $self->{bucket} . '.';
176 $self->{js}->stream_info(
177 $self->{stream},
178 { subjects_filter => $prefix . '>' },
179 0 ▶ sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
180 0 my ($info, $err) = @_;
181 0 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
182 0 ▶ my $subjects = $info->{state}{subjects} || {};
Condition0%0/2
$info->{'state'}{'subjects'} || {}
l!l
00
MC/DC0%0/1
$info->{'state'}{'subjects'} || {}
$info->{'state'}{'subjects'}
Truth table0%0/2
A
A= $info->{'state'}{'subjects'}
Aresult
11
00
183 0 my $plen = length $prefix;
184 0 my @keys = map { substr($_, $plen) }
185 0 grep { substr($_, 0, $plen) eq $prefix }
186 CORE::keys %$subjects;
187 0 $cb->(\@keys, undef);
188 },
189 0 );
190 }
191  
192 1 ▶sub watch {
Subroutine watch: called CC=4 SCAR=23.7
Pod documented
193 1 my ($self, $key_pattern, $cb) = @_;
194 1 ▶ $key_pattern //= '>';
Condition50%1/2
$key_pattern //= ">"
l!l
10
MC/DC0%0/1
$key_pattern //= ">"
$key_pattern
Truth table50%1/2
A
A= $key_pattern
Aresult
11
00
195 1 ▶ die "invalid KV watch pattern '$key_pattern'"
Branch: 1 branch
BranchTrueFalseTotal
if not length $key_pattern or $key_pattern =~ /\s/ 1 0 1
Condition33%1/3
not length $key_pattern or $key_pattern =~ /\s/
l!l&&r!l&&!r
010
MC/DC0%0/2
not length $key_pattern or $key_pattern =~ /\s/
not length $key_pattern $key_pattern =~ /\s/
Truth table33%1/3
not(A) or B
A= not length $key_patternB= $key_pattern =~ /\s/
ABresult
1X1
011
000
196 if !length $key_pattern || $key_pattern =~ /\s/;
197 0 my $subj = '$KV.' . $self->{bucket} . '.' . $key_pattern;
198 0 ▶ return $self->{js}{nats}->subscribe($subj, sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
199 0 my ($subject, $payload, $reply, $headers) = @_;
200 0 my $prefix = '$KV.' . $self->{bucket} . '.';
201 0 my $key = substr($subject, length $prefix);
202 0 my $op = 'PUT';
203 0 ▶ if ($headers && $headers =~ /KV-Operation:\s*(\S+)/i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($headers and $headers =~ /KV-Operation:\s*(\S+)/i) 0 0 0
Condition0%0/3
$headers and $headers =~ /KV-Operation:\s*(\S+)/i
!ll&&!rl&&r
000
MC/DC0%0/2
$headers and $headers =~ /KV-Operation:\s*(\S+)/i
$headers $headers =~ /KV-Operation:\s*(\S+)/i
Truth table0%0/3
A and B
A= $headersB= $headers =~ /KV-Operation:\s*(\S+)/i
ABresult
0X0
100
111
204 0 $op = uc $1;
205 }
206 0 $cb->($key, $payload, $op);
207 0 });
208 }
209  
210 0 ▶sub create_bucket {
Subroutine create_bucket: not called CC=6 SCAR=37.4
Pod documented
211 0 my ($self, $opts, $cb) = @_;
212 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
213 0 require JSON::PP;
214 my $config = {
215 name => $self->{stream},
216 subjects => ['$KV.' . $self->{bucket} . '.>'],
217 retention => 'limits',
218 max_msgs_per_subject => $opts->{max_history} || 1,
219 ($opts->{max_bytes} ? (max_bytes => $opts->{max_bytes}) : ()),
220 ($opts->{max_age} ? (max_age => $opts->{max_age}) : ()),
221 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
Condition0%0/2
$opts->{'max_history'} || 1
l!l
00
MC/DC0%0/1
$opts->{'max_history'} || 1
$opts->{'max_history'}
Truth table0%0/2
A
A= $opts->{'max_history'}
Aresult
11
00
222 discard => 'new',
223 allow_rollup_hdrs => JSON::PP::true(),
224 deny_delete => JSON::PP::true(),
225 deny_purge => JSON::PP::false(),
226 };
227 0 $self->{js}->stream_create($config, $cb);
228 }
229  
230 0 ▶sub delete_bucket {
Subroutine delete_bucket: not called CC=1 SCAR=6.9
Pod documented
231 0 my ($self, $cb) = @_;
232 0 $self->{js}->stream_delete($self->{stream}, $cb);
233 }
234  
235 0 ▶sub status {
Subroutine status: not called CC=1 SCAR=6.9
Pod documented
236 0 my ($self, $cb) = @_;
237 0 ▶ $self->{js}->stream_info($self->{stream}, sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
238 0 my ($info, $err) = @_;
239 0 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 0 0
240 $cb->({
241 bucket => $self->{bucket},
242 values => $info->{state}{messages},
243 bytes => $info->{state}{bytes},
244 history => $info->{config}{max_msgs_per_subject},
245 0 }, undef);
246 0 });
247 }
248  
249 4 1;
250  
251 =head1 NAME
252  
253 EV::Nats::KV - Key-Value store on top of NATS JetStream
254  
255 =head1 SYNOPSIS
256  
257 use EV;
258 use EV::Nats;
259 use EV::Nats::JetStream;
260 use EV::Nats::KV;
261  
262 my $nats = EV::Nats->new(host => '127.0.0.1');
263 my $js = EV::Nats::JetStream->new(nats => $nats);
264 my $kv = EV::Nats::KV->new(js => $js, bucket => 'config');
265  
266 $kv->create_bucket({}, sub {
267 $kv->put('app.setting', 'on', sub {
268 $kv->get('app.setting', sub {
269 my ($val, $err) = @_;
270 print "got: $val\n";
271 });
272 });
273 });
274  
275 # Live updates
276 $kv->watch('app.>', sub {
277 my ($key, $value, $op) = @_;
278 print "$op $key = $value\n";
279 });
280  
281 EV::run;
282  
283 =head1 DESCRIPTION
284  
285 A KV bucket is a JetStream stream named C<KV_E<lt>bucketE<gt>> with
286 subjects C<$KV.E<lt>bucketE<gt>.E<gt>>, history of 1, rollup headers
287 allowed, and deletes denied (purge tombstones are used instead).
288 This module wraps that convention: C<put>/C<get> become single calls
289 that hide the underlying C<js_publish> + C<STREAM.MSG.GET> dance.
290  
291 Keys must match C<[-/_=.a-zA-Z0-9]+> without leading or trailing
292 dots, and are validated up front.
293  
294 =head1 METHODS
295  
296 All callbacks fire on the L<EV> loop, not synchronously.
297  
298 =head2 new
299  
300 new(js => $js, bucket => $name, [timeout => $ms])
301  
302 The bucket need not exist yet; call L</create_bucket> first to
303 provision it. C<timeout> defaults to the timeout of C<$js>. The
304 bucket name must match C<[a-zA-Z0-9_-]+>.
305  
306 =head2 get
307  
308 get($key, $cb)
309  
310 Fetch the latest value for C<$key>. Callback: C<($value, $err)>.
311 C<$value> is C<undef> if the key does not exist, or has been deleted
312 or purged (the tombstone is recognised and surfaces as a clean miss).
313  
314 =head2 put
315  
316 put($key, $value, $cb)
317  
318 Set C<$key> to C<$value>. Callback: C<($seq, $err)>, where C<$seq> is
319 the JetStream sequence number assigned by the server.
320  
321 =head2 create
322  
323 create($key, $value, [$cb])
324  
325 Like C<put>, but only succeeds if C<$key> is missing. With a callback,
326 deleted/purged keys can be recreated using the tombstone's revision;
327 concurrent creators see a wrong-last-sequence error. Callback: C<($seq, $err)>.
328 Without C<$cb> the headered publish is fire-and-forget.
329  
330 =head2 update
331  
332 update($key, $value, $rev, [$cb])
333  
334 Like C<put>, but only succeeds if C<$key>'s current revision is
335 C<$rev> (compare-and-swap). Callback: C<($seq, $err)>.
336  
337 =head2 delete
338  
339 delete($key, [$cb])
340  
341 Mark C<$key> as deleted by publishing a C<KV-Operation: DEL> tombstone,
342 followed by a C<flush> fence so a subsequent C<get> won't race the
343 publish. Callback: C<($ok, $err)>; C<$err> is set if the connection
344 dropped before the PONG arrived, or if the client is not currently
345 connected.
346  
347 =head2 purge
348  
349 purge($key, [$cb])
350  
351 Like C<delete>, but emits C<Nats-Rollup: sub> too -- the prior history
352 of C<$key> is rolled up and replaced by the tombstone, freeing storage.
353 Callback: C<($ok, $err)>; C<$err> is set if the client is not
354 currently connected.
355  
356 =head2 keys
357  
358 keys($cb)
359  
360 List all keys currently stored in the bucket. Callback: C<(\@keys, $err)>.
361 Tombstoned keys are not filtered out -- check with C<get> if needed.
362  
363 =head2 watch
364  
365 watch($pattern, $cb)
366  
367 Subscribe to live changes. C<$pattern> is a NATS subject suffix relative
368 to the bucket (e.g. C<E<gt>> for all keys, C<app.E<gt>> for everything
369 under C<app.>); it must be non-empty and contain no whitespace.
370 Callback receives C<($key, $value, $op)> where C<$op>
371 is C<PUT>, C<DEL>, or C<PURGE>. Returns the underlying subscription
372 id; pass to L<EV::Nats/unsubscribe> to stop. Resubscribes on
373 reconnect; updates published while disconnected are missed.
374  
375 =head2 create_bucket
376  
377 create_bucket(\%opts, $cb)
378  
379 Provision the underlying stream. Recognised C<\%opts>:
380  
381 =over
382  
383 =item * C<max_history> - default 1; how many revisions to keep per key.
384  
385 =item * C<max_bytes> - bucket-wide storage cap.
386  
387 =item * C<max_age> - per-message TTL in nanoseconds.
388  
389 =item * C<replicas> - cluster replication factor.
390  
391 =back
392  
393 Callback: C<($info, $err)>.
394  
395 =head2 delete_bucket
396  
397 delete_bucket($cb)
398  
399 Tear down the underlying stream. Callback: C<($info, $err)>.
400  
401 =head2 status
402  
403 status($cb)
404  
405 Returns a snapshot hashref:
406  
407 { bucket => $name, values => $count, bytes => $n, history => $h }
408  
409 Callback: C<(\%status, $err)>.
410  
411 =head1 SEE ALSO
412  
413 L<EV::Nats>, L<EV::Nats::JetStream>, L<EV::Nats::ObjectStore>,
414 L<NATS KV documentation|https://docs.nats.io/nats-concepts/jetstream/key-value-store>.
415  
416 =cut
« blib/lib/EV/Nats/JetStream.pm ↑ Summary blib/lib/EV/Nats/ObjectStore.pm »