blib/lib/EV/Nats/JetStream.pm

filter: Statementstmt 66.2% 100 / 151 Branchbran 37.0% 20 / 54 Conditioncond 36.6% 11 / 30 MC/DCmcdc 17.6% 3 / 17 Subroutinesub 56.6% 17 / 30 Podpod 100% 17 / 17 totaltotal 56.1% 168 / 299 CC 42 SCAR 24.2
CC
42
Cov
56%
__ANON__
56.0
__ANON__
20.0
consumer_create
12.0
CRAP 11.2
↑ Summary blib/lib/EV/Nats/KV.pm »
1 package EV::Nats::JetStream;
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 JSON::PP ();
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 14 ▶sub new {
Subroutine new: called CC=5 SCAR=16.3
Pod documented
9 14 my ($class, %opts) = @_;
10 14 ▶ my $nats = delete $opts{nats} || die "nats connection required";
Condition50%1/2
delete $opts{'nats'} || die('nats connection required')
l!l
140
MC/DC0%0/1
delete $opts{'nats'} || die('nats connection required')
delete $opts{'nats'}
Truth table50%1/2
A
A= delete $opts{'nats'}
Aresult
11
00
11 14 ▶ my $prefix = delete $opts{prefix} || '$JS.API';
Condition50%1/2
delete $opts{'prefix'} || '$JS.API'
l!l
014
MC/DC0%0/1
delete $opts{'prefix'} || '$JS.API'
delete $opts{'prefix'}
Truth table50%1/2
A
A= delete $opts{'prefix'}
Aresult
11
00
12 14 ▶ my $timeout = delete $opts{timeout} || 5000;
Condition100%2/2
delete $opts{'timeout'} || 5000
l!l
68
MC/DC100%1/1
delete $opts{'timeout'} || 5000
delete $opts{'timeout'}
Truth table100%2/2
A
A= delete $opts{'timeout'}
Aresult
11
00
13 14 warn "EV::Nats::JetStream::new: unknown option '$_'" for keys %opts;
14 14 bless {
15 nats => $nats,
16 prefix => $prefix,
17 timeout => $timeout,
18 }, $class;
19 }
20  
21 3 ▶sub _api {
Subroutine _api: called CC=2 SCAR=7.1
22 3 my ($self, $subj, $payload, $cb) = @_;
23 3 ▶ $payload //= '';
Condition50%1/2
$payload //= ""
l!l
30
MC/DC0%0/1
$payload //= ""
$payload
Truth table50%1/2
A
A= $payload
Aresult
11
00
24 $self->{nats}->request(
25 "$self->{prefix}.$subj",
26 $payload, $cb, $self->{timeout},
27 3 );
28 }
29  
30 ## Public to sibling modules (KV, ObjectStore, ...) -- not part of the user
31 ## API. Decode a JSON string; returns ($decoded, $error_or_undef) where
32 ## $error already includes a "JSON decode error: ..." prefix when set.
33 ## Gates on $@ so falsy-but-valid JSON (null/0/false/empty-string) doesn't
34 ## get misreported as a decode failure.
35 19 ▶sub decode_json_or_error {
Subroutine decode_json_or_error: called CC=2 SCAR=7.2
Pod documented
36 19 my ($json) = @_;
37 19 local $@;
38 19 my $r = eval { JSON::PP::decode_json($json) };
39 19 ▶ return ($r, undef) unless $@;
Branch: 1 branch
BranchTrueFalseTotal
unless $@ 19 0 19
40 0 return (undef, "JSON decode error: $@");
41 }
42  
43 ## Public to sibling modules. True if a STREAM.MSG.GET response message
44 ## carries a KV-Operation: DEL or PURGE tombstone header. $msg is the
45 ## decoded {message} hash; its {hdrs} field is base64-encoded by the server.
46 17 ▶sub msg_is_tombstone {
Subroutine msg_is_tombstone: called CC=4 SCAR=14.0
Pod documented
47 17 my ($msg) = @_;
48 17 ▶ return 0 unless $msg && $msg->{hdrs};
Branch: 1 branch
BranchTrueFalseTotal
unless $msg and $msg->{"hdrs"} 5 12 17
Condition66%2/3
$msg and $msg->{"hdrs"}
!ll&&!rl&&r
0512
MC/DC50%1/2
$msg and $msg->{"hdrs"}
$msg $msg->{"hdrs"}
Truth table66%2/3
A and B
A= $msgB= $msg->{"hdrs"}
ABresult
0X0
100
111
49 12 require MIME::Base64;
50 12 my $hdrs = MIME::Base64::decode_base64($msg->{hdrs});
51 12 ▶ return $hdrs =~ /KV-Operation:\s*(?:DEL|PURGE)/i ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$hdrs =~ /KV-Operation:\s*(?:DEL|PURGE)/i ? : 0 12 12
52 }
53  
54 3 ▶sub _json_api {
Subroutine _json_api: called CC=2 SCAR=7.4
55 3 my ($self, $subj, $data, $cb) = @_;
56 3 ▶ my $payload = defined $data ? JSON::PP::encode_json($data) : '';
Branch: 1 branch
BranchTrueFalseTotal
defined $data ? : 3 0 3
57 2 ▶ $self->_api($subj, $payload, sub {
Subroutine __ANON__: called CC=4 SCAR=15.0
58 2 my ($resp, $err) = @_;
59 2 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 0 2 2
60 2 my ($decoded, $derr) = decode_json_or_error($resp);
61 2 ▶ return $cb->(undef, $derr) if $derr;
Branch: 1 branch
BranchTrueFalseTotal
if $derr 0 2 2
62 2 ▶ if ($decoded->{error}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($decoded->{"error"}) 2 0 2
63 2 return $cb->(undef, "$decoded->{error}{description} (code $decoded->{error}{code})");
64 }
65 0 $cb->($decoded, undef);
66 3 });
67 }
68  
69 # Stream management
70  
71 0 ▶sub stream_create {
Subroutine stream_create: not called CC=2 SCAR=17.9
Pod documented
72 0 my ($self, $config, $cb) = @_;
73 0 ▶ my $name = $config->{name} || die "stream name required";
Condition0%0/2
$config->{'name'} || die('stream name required')
l!l
00
MC/DC0%0/1
$config->{'name'} || die('stream name required')
$config->{'name'}
Truth table0%0/2
A
A= $config->{'name'}
Aresult
11
00
74 0 $self->_json_api("STREAM.CREATE.$name", $config, $cb);
75 }
76  
77 0 ▶sub stream_update {
Subroutine stream_update: not called CC=2 SCAR=17.9
Pod documented
78 0 my ($self, $config, $cb) = @_;
79 0 ▶ my $name = $config->{name} || die "stream name required";
Condition0%0/2
$config->{'name'} || die('stream name required')
l!l
00
MC/DC0%0/1
$config->{'name'} || die('stream name required')
$config->{'name'}
Truth table0%0/2
A
A= $config->{'name'}
Aresult
11
00
80 0 $self->_json_api("STREAM.UPDATE.$name", $config, $cb);
81 }
82  
83 0 ▶sub stream_delete {
Subroutine stream_delete: not called CC=1 SCAR=6.9
Pod documented
84 0 my ($self, $name, $cb) = @_;
85 0 $self->_json_api("STREAM.DELETE.$name", undef, $cb);
86 }
87  
88 0 ▶sub stream_info {
Subroutine stream_info: not called CC=1 SCAR=6.9
Pod documented
89 0 my ($self, $name, @rest) = @_;
90 0 my $cb = pop @rest;
91 0 my $opts = $rest[0];
92 0 $self->_json_api("STREAM.INFO.$name", $opts, $cb);
93 }
94  
95 0 ▶sub stream_list {
Subroutine stream_list: not called CC=1 SCAR=6.9
Pod documented
96 0 my ($self, $cb) = @_;
97 0 $self->_json_api("STREAM.LIST", undef, $cb);
98 }
99  
100 0 ▶sub stream_purge {
Subroutine stream_purge: not called CC=1 SCAR=6.9
Pod documented
101 0 my ($self, $name, $cb) = @_;
102 0 $self->_json_api("STREAM.PURGE.$name", undef, $cb);
103 }
104  
105 # Fetch a single message from a stream by sequence, last-by-subject, or
106 # next-by-subject. \%opts is passed verbatim as the request body
107 # (server accepts: seq, last_by_subj, next_by_subj).
108 0 ▶sub stream_msg_get {
Subroutine stream_msg_get: not called CC=1 SCAR=6.9
Pod documented
109 0 my ($self, $stream, $opts, $cb) = @_;
110 0 $self->_json_api("STREAM.MSG.GET.$stream", $opts, $cb);
111 }
112  
113 # Consumer management
114  
115 0 ▶sub consumer_create {
Subroutine consumer_create: not called CC=3 SCAR=24.8
Pod documented
116 0 my ($self, $stream, $config, $cb) = @_;
117 0 ▶ my $name = $config->{durable_name} || $config->{name};
Condition0%0/3
$config->{'durable_name'} || $config->{'name'}
l!l&&r!l&&!r
000
MC/DC0%0/2
$config->{'durable_name'} || $config->{'name'}
$config->{'durable_name'} $config->{'name'}
Truth table0%0/3
A || B
A= $config->{'durable_name'}B= $config->{'name'}
ABresult
1X1
011
000
118 0 ▶ my $subj = $name
Branch: 1 branch
BranchTrueFalseTotal
$name ? : 0 0 0
119 ? "CONSUMER.CREATE.$stream.$name"
120 : "CONSUMER.CREATE.$stream";
121 0 $self->_json_api($subj, { stream_name => $stream, config => $config }, $cb);
122 }
123  
124 0 ▶sub consumer_delete {
Subroutine consumer_delete: not called CC=1 SCAR=6.9
Pod documented
125 0 my ($self, $stream, $consumer, $cb) = @_;
126 0 $self->_json_api("CONSUMER.DELETE.$stream.$consumer", undef, $cb);
127 }
128  
129 0 ▶sub consumer_info {
Subroutine consumer_info: not called CC=1 SCAR=6.9
Pod documented
130 0 my ($self, $stream, $consumer, $cb) = @_;
131 0 $self->_json_api("CONSUMER.INFO.$stream.$consumer", undef, $cb);
132 }
133  
134 0 ▶sub consumer_list {
Subroutine consumer_list: not called CC=1 SCAR=6.9
Pod documented
135 0 my ($self, $stream, $cb) = @_;
136 0 $self->_json_api("CONSUMER.LIST.$stream", undef, $cb);
137 }
138  
139 # Publishing with ack
140  
141 8 ▶sub js_publish {
Subroutine js_publish: called CC=1 SCAR=2.4
Pod documented
142 8 my ($self, $subject, $payload, $cb) = @_;
143 8 ▶ $self->{nats}->request($subject, $payload, sub {
Subroutine __ANON__: called CC=4 SCAR=23.7
144 8 my ($resp, $err) = @_;
145 8 ▶ return $cb->(undef, $err) if $err;
Branch: 1 branch
BranchTrueFalseTotal
if $err 8 0 8
146 0 my ($ack, $derr) = decode_json_or_error($resp);
147 0 ▶ return $cb->(undef, $derr) if $derr;
Branch: 1 branch
BranchTrueFalseTotal
if $derr 0 0 0
148 return $cb->(undef, "$ack->{error}{description} (code $ack->{error}{code})")
149 0 ▶ if $ack->{error};
Branch: 1 branch
BranchTrueFalseTotal
if $ack->{"error"} 0 0 0
150 0 $cb->($ack, undef);
151 8 }, $self->{timeout});
152 }
153  
154 # Like js_publish but carries NATS headers (e.g. Nats-Rollup) and still
155 # waits for the PubAck. Same inbox pattern as EV::Nats::KV::create.
156 3 ▶sub js_publish_h {
Subroutine js_publish_h: called CC=2 SCAR=8.4
Pod documented
157 3 my ($self, $subject, $headers, $payload, $cb) = @_;
158 3 my $nats = $self->{nats};
159 3 my $inbox = $nats->new_inbox;
160 3 my ($sid, $timer);
161 0 ▶ $sid = $nats->subscribe_max($inbox, sub {
Subroutine __ANON__: not called CC=4 SCAR=30.0
162 0 my ($s, $resp) = @_;
163 0 ▶ if ($timer) { $timer->stop; undef $timer; }
Branch: 1 branch
BranchTrueFalseTotal
if ($timer) 0 0 0
164 0 my ($ack, $derr) = decode_json_or_error($resp);
165 0 ▶ return $cb->(undef, $derr) if $derr;
Branch: 1 branch
BranchTrueFalseTotal
if $derr 0 0 0
166 return $cb->(undef, "$ack->{error}{description} (code $ack->{error}{code})")
167 0 ▶ if $ack->{error};
Branch: 1 branch
BranchTrueFalseTotal
if $ack->{"error"} 0 0 0
168 0 $cb->($ack, undef);
169 3 }, 1);
170 2 ▶ $timer = $nats->_timer($self->{timeout} / 1000.0, 0, sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
171 2 eval { $nats->unsubscribe($sid) };
172 2 $cb->(undef, "publish timeout");
173 3 });
174 3 ▶ if (!eval { $nats->hpublish($subject, $headers, $payload, $inbox); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (not eval { do { $nats->hpublish($subject, $headers, $payload, $inbox); 1 } }) 1 2 3
175 1 my $err = $@;
176 1 $timer->stop;
177 1 eval { $nats->unsubscribe($sid) };
178 1 die $err;
179 }
180 }
181  
182 # Fetch messages (pull consumer).
183 #
184 # A pull-consumer NEXT request returns up to N messages on a reply inbox,
185 # not a single JSON API response. We subscribe to a fresh inbox, publish
186 # the fetch request, and collect messages until $batch is reached, the
187 # server emits a status message (404/408/503), or the local safety timer
188 # fires.
189  
190 3 ▶sub fetch {
Subroutine fetch: called CC=8 SCAR=24.7
Pod documented
191 3 my ($self, $stream, $consumer, $opts, $cb) = @_;
192 3 ▶ $opts //= {};
Condition50%1/2
$opts //= {}
l!l
30
MC/DC0%0/1
$opts //= {}
$opts
Truth table50%1/2
A
A= $opts
Aresult
11
00
193 3 ▶ my $batch = $opts->{batch} || 1;
Condition100%2/2
$opts->{'batch'} || 1
l!l
12
MC/DC100%1/1
$opts->{'batch'} || 1
$opts->{'batch'}
Truth table100%2/2
A
A= $opts->{'batch'}
Aresult
11
00
194 3 ▶ my $expires_ns = $opts->{expires} || 5_000_000_000; # 5s default
Condition50%1/2
$opts->{'expires'} || 5000000000
l!l
30
MC/DC0%0/1
$opts->{'expires'} || 5000000000
$opts->{'expires'}
Truth table50%1/2
A
A= $opts->{'expires'}
Aresult
11
00
195 3 ▶ my $no_wait = $opts->{no_wait} ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$opts->{'no_wait'} ? : 0 3 3
196 3 my $expires_sec = $expires_ns / 1_000_000_000;
197  
198 3 my $nats = $self->{nats};
199 3 my $inbox = $nats->new_inbox;
200  
201 3 my @messages;
202 3 my ($sid, $timer);
203 3 my $finished = 0;
204  
205 2 ▶ my $finish = sub {
Subroutine __ANON__: called CC=5 SCAR=16.7
206 2 my $err = shift;
207 2 ▶ return if $finished;
Branch: 1 branch
BranchTrueFalseTotal
if $finished 0 2 2
208 2 $finished = 1;
209 2 ▶ if ($timer) { $timer->stop; undef $timer; }
Branch: 1 branch
BranchTrueFalseTotal
if ($timer) 2 0 2
210 2 ▶ eval { $nats->unsubscribe($sid) } if defined $sid;
Branch: 1 branch
BranchTrueFalseTotal
if defined $sid 2 0 2
211 2 ▶ $err ? $cb->(undef, $err) : $cb->(\@messages, undef);
Branch: 1 branch
BranchTrueFalseTotal
$err ? : 0 2 2
212 3 };
213  
214 0 ▶ $sid = $nats->subscribe($inbox, sub {
Subroutine __ANON__: not called CC=7 SCAR=40.3
215 0 my ($subject, $payload, $reply, $headers) = @_;
216 # Status lines are exactly "NATS/1.0 <3 digits>"; a loose \s+ would
217 # swallow a headered DATA message's first header as a status frame.
218 0 ▶ if ($headers && $headers =~ m{\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($headers and $headers =~ m[\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)]) 0 0 0
Condition0%0/3
$headers and $headers =~ m[\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)]
!ll&&!rl&&r
000
MC/DC0%0/2
$headers and $headers =~ m[\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)]
$headers $headers =~ m[\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)]
Truth table0%0/3
A and B
A= $headersB= $headers =~ m[\ANATS/1\.0 (\d{3})(?:[ \r\n]|\z)]
ABresult
0X0
100
111
219 0 my $code = $1;
220 # A NATS/1.0 status frame is a control message, never data, so it
221 # must not be pushed as a result. 100 = idle heartbeat / flow
222 # control: ignore and keep waiting. 404/408 (no messages, wait
223 # elapsed) end the batch cleanly. Anything else (409 consumer
224 # deleted, 503 no responders, 400 bad request, ...) is a real
225 # failure the caller must see, not an empty batch.
226 0 ▶ return if $code == 100;
Branch: 1 branch
BranchTrueFalseTotal
if $code == 100 0 0 0
227 0 ▶ return $finish->() if $code == 404 || $code == 408;
Branch: 1 branch
BranchTrueFalseTotal
if $code == 404 or $code == 408 0 0 0
Condition0%0/3
$code == 404 or $code == 408
l!l&&r!l&&!r
000
MC/DC0%0/2
$code == 404 or $code == 408
$code == 404 $code == 408
Truth table0%0/3
A or B
A= $code == 404B= $code == 408
ABresult
1X1
011
000
228 0 my ($status) = split /\r\n/, $headers;
229 0 return $finish->("fetch failed: $status");
230 }
231 0 push @messages, {
232 subject => $subject,
233 payload => $payload,
234 reply => $reply,
235 headers => $headers,
236 };
237 0 ▶ $finish->() if @messages >= $batch;
Branch: 1 branch
BranchTrueFalseTotal
if @messages >= $batch 0 0 0
238 3 });
239  
240 3 my %req = (batch => $batch);
241 # no_wait with an expires is pointless: the server waits the expires
242 # out instead of answering immediately.
243 3 ▶ $req{expires} = $expires_ns unless $no_wait;
Branch: 1 branch
BranchTrueFalseTotal
unless $no_wait 3 0 3
244 3 ▶ $req{no_wait} = JSON::PP::true() if $no_wait;
Branch: 1 branch
BranchTrueFalseTotal
if $no_wait 0 3 3
245 3 my $req_body = JSON::PP::encode_json(\%req);
246 3 my $subj = "$self->{prefix}.CONSUMER.MSG.NEXT.$stream.$consumer";
247 3 ▶ if (!eval { $nats->publish($subj, $req_body, $inbox); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (eval { do { $nats->publish($subj, $req_body, $inbox); 1 } }) 1 2 3
248 1 my $err = $@;
249 1 eval { $nats->unsubscribe($sid) };
250 1 die $err;
251 }
252  
253 2 ▶ $timer = $nats->_timer($expires_sec + 1, 0, sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
254 2 $finish->();
255 2 });
256 2 return;
257 }
258  
259 4 1;
260  
261 =head1 NAME
262  
263 EV::Nats::JetStream - JetStream API client for L<EV::Nats>
264  
265 =head1 SYNOPSIS
266  
267 use EV;
268 use EV::Nats;
269 use EV::Nats::JetStream;
270  
271 my $nats = EV::Nats->new(host => '127.0.0.1');
272 my $js = EV::Nats::JetStream->new(nats => $nats);
273  
274 $js->stream_create({ name => 'ORDERS', subjects => ['orders.>'] },
275 sub {
276 my ($info, $err) = @_;
277 die $err if $err;
278 $js->js_publish('orders.new', '{"item":"widget"}', sub {
279 my ($ack, $err) = @_;
280 print "stored at seq=$ack->{seq}\n";
281 });
282 });
283  
284 EV::run;
285  
286 =head1 DESCRIPTION
287  
288 Thin async wrapper over the JetStream C<$JS.API.*> request/reply
289 endpoints. Each method is a single request whose callback is invoked
290 with the decoded JSON response (or an error string). The C<$nats>
291 connection passed to L</new> handles all the actual I/O.
292  
293 L<EV::Nats::KV> and L<EV::Nats::ObjectStore> build on top of this
294 module -- see those for higher-level KV / blob APIs.
295  
296 =head1 METHODS
297  
298 All methods are async. Callbacks fire on the L<EV> loop.
299  
300 =head2 new
301  
302 new(%opts)
303  
304 my $js = EV::Nats::JetStream->new(
305 nats => $nats,
306 prefix => '$JS.API', # default API subject prefix
307 timeout => 5000, # ms; default 5000
308 );
309  
310 =head2 Stream management
311  
312 =head3 stream_create
313  
314 stream_create($config, $cb)
315  
316 Create a stream. C<$config> is passed verbatim as the
317 C<StreamConfig> request body. Callback: C<($info, $err)>.
318  
319 =head3 stream_update
320  
321 stream_update($config, $cb)
322  
323 Update an existing stream. Same shape as C<stream_create>.
324  
325 =head3 stream_delete
326  
327 stream_delete($name, $cb)
328  
329 Delete the stream by name.
330  
331 =head3 stream_info
332  
333 stream_info($name, [\%opts], $cb)
334  
335 Fetch stream config + state. Optional C<\%opts> may include
336 C<subjects_filter> (e.g. C<E<gt>>) to populate C<state.subjects>;
337 without it the server omits that field for performance.
338  
339 =head3 stream_list
340  
341 stream_list($cb)
342  
343 List all streams' info.
344  
345 =head3 stream_purge
346  
347 stream_purge($name, $cb)
348  
349 Purge all messages from the stream.
350  
351 =head3 stream_msg_get
352  
353 stream_msg_get($stream, \%opts, $cb)
354  
355 Fetch a single message from C<$stream>. C<\%opts> selects the message:
356  
357 { seq => $n } # by sequence number
358 { last_by_subj => $subject } # latest matching subject
359 { next_by_subj => $subject, seq => $start } # next at-or-after $start
360  
361 The message body and headers in the response are base64-encoded
362 under C<< $resp->{message}{data} >> and C<< $resp->{message}{hdrs} >>.
363  
364 =head2 Consumer management
365  
366 =head3 consumer_create
367  
368 consumer_create($stream, $config, $cb)
369  
370 Create a consumer (push or pull). C<$config> is the consumer config
371 hashref; C<durable_name> makes it durable, C<ack_policy> controls
372 ack semantics.
373  
374 =head3 consumer_delete
375  
376 consumer_delete($stream, $consumer, $cb)
377  
378 =head3 consumer_info
379  
380 consumer_info($stream, $consumer, $cb)
381  
382 =head3 consumer_list
383  
384 consumer_list($stream, $cb)
385  
386 =head2 Publishing and fetching
387  
388 =head3 js_publish
389  
390 js_publish($subject, $payload, $cb)
391  
392 Publish with JetStream acknowledgment. Callback: C<($ack, $err)>
393 where C<$ack> is C<{ stream, seq, duplicate }>.
394  
395 =head3 js_publish_h
396  
397 js_publish_h($subject, $headers, $payload, $cb)
398  
399 Like L</js_publish> but sends C<$headers> (a full C<NATS/1.0> header
400 block, e.g. C<"NATS/1.0\r\nNats-Rollup: sub\r\n\r\n">) with the
401 message, waiting for the PubAck on a one-shot reply inbox. Used for
402 rollup publishes where the acknowledged sequence still matters
403 (L<EV::Nats::ObjectStore> metadata). Callback: C<($ack, $err)>.
404  
405 =head3 fetch
406  
407 fetch($stream, $consumer, \%opts, $cb)
408  
409 Pull messages from a pull-mode consumer. Options:
410  
411 =over
412  
413 =item C<batch>
414  
415 Maximum number of messages to fetch (default 1).
416  
417 =item C<expires>
418  
419 Server-side wait time in nanoseconds (default 5_000_000_000 = 5s).
420 Ignored with C<no_wait>.
421  
422 =item C<no_wait>
423  
424 If true, return immediately if no messages are currently available.
425  
426 =back
427  
428 Callback: C<(\@messages, $err)>. Each message is a hashref:
429  
430 {
431 subject => 'orders.new',
432 payload => '...',
433 reply => '$JS.ACK....', # for explicit ack/nak/wpi
434 headers => "...", # raw NATS/1.0 header block, or undef
435 }
436  
437 To acknowledge a message:
438  
439 $nats->publish($msg->{reply}, '+ACK'); # success
440 $nats->publish($msg->{reply}, '-NAK'); # negative --redeliver after ack_wait
441 $nats->publish($msg->{reply}, '+WPI'); # work-in-progress --extend ack_wait
442  
443 An abnormal server status (e.g. 409, the consumer was deleted
444 mid-fetch) arrives as C<$err>. An unknown stream or consumer yields
445 an empty batch after C<expires>: the server answers nothing at all.
446  
447 =head1 INTERNAL
448  
449 These are exposed for sibling modules (L<EV::Nats::KV>,
450 L<EV::Nats::ObjectStore>) -- not part of the end-user API and subject
451 to change.
452  
453 =head2 decode_json_or_error
454  
455 decode_json_or_error($json)
456  
457 Decode C<$json>. Returns C<($decoded, $error_or_undef)>; the error
458 string already includes a C<"JSON decode error: "> prefix when set.
459 Gates on C<$@> so falsy-but-valid JSON (C<null>, C<0>, C<false>,
460 empty string) is reported as a clean decode rather than a failure.
461  
462 =head2 msg_is_tombstone
463  
464 msg_is_tombstone($msg)
465  
466 True if a C<STREAM.MSG.GET> response message carries a
467 C<KV-Operation: DEL> or C<KV-Operation: PURGE> header. C<$msg> is the
468 decoded C<message> hash from the response. Used by L<EV::Nats::KV>
469 and L<EV::Nats::ObjectStore> to surface deleted/purged entries as
470 clean misses rather than as malformed payloads.
471  
472 =head1 SEE ALSO
473  
474 L<EV::Nats>, L<EV::Nats::KV>, L<EV::Nats::ObjectStore>,
475 L<JetStream API reference|https://docs.nats.io/reference/reference-protocols/nats_api_reference>.
476  
477 =cut
↑ Summary blib/lib/EV/Nats/KV.pm »