| 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')
MC/DC0%0/1
delete $opts{'js'} || die('js (JetStream) required')
delete $opts{'js'}
Truth table50%1/2
A
A= delete $opts{'js'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 11 | 12 | ▶ | my $bucket = delete $opts{bucket} || die "bucket name required"; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
delete $opts{'bucket'} || die('bucket name required')
MC/DC0%0/1
delete $opts{'bucket'} || die('bucket name required')
delete $opts{'bucket'}
Truth table50%1/2
A
A= delete $opts{'bucket'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 14 | 11 | ▶ | my $timeout = delete $opts{timeout} || $js->{timeout}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition66%2/3
delete $opts{'timeout'} || $js->{'timeout'}
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'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition88%8/9
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./ and not $key =~ /\.\z/
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z] and not $key =~ /\A\./
defined $key and $key =~ m[\A[-/_=.a-zA-Z0-9]+\z]
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/
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 46 | 0 | return $cb->(undef, $err); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 47 | } | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 48 | 0 | my $msg = $resp->{message}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 49 | 0 | ▶ | return $cb->(undef, undef) unless $msg; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 50 | # DEL/PURGE tombstones surface as missing | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 51 | 0 | ▶ | return $cb->(undef, undef) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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'} || ''
MC/DC0%0/1
$msg->{'data'} || ''
$msg->{'data'}
Truth table0%0/2
A
A= $msg->{'data'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 82 | 0 | my ($ack, $derr) = EV::Nats::JetStream::decode_json_or_error($payload); | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 83 | 0 | ▶ | return $cb->(undef, $derr) if $derr; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 84 | return $cb->(undef, "$ack->{error}{description} (code $ack->{error}{code})") | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 85 | 0 | ▶ | if $ack->{error}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition33%1/3
$err and $err =~ /wrong last sequence/i
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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 116 | 0 | my $msg = $resp->{message}; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 117 | 0 | ▶ | return $cb->(undef, $err) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition20%1/5
defined $rev and $rev =~ /\A[1-9][0-9]*\z/
$rev // ""
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/
Truth table0%0/2
A
A= $rev
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 165 | 0 | 1; | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 166 | }; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 167 | 7 | ▶ | return if $ok; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 168 | 7 | ▶ | (my $err = $@ || 'not connected') =~ s/ at \S+ line \d+.*//s; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition50%1/2
$@ || 'not connected'
MC/DC0%0/1
$@ || 'not connected'
$@
Truth table50%1/2
A
A= $@
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 182 | 0 | ▶ | my $subjects = $info->{state}{subjects} || {}; | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Condition0%0/2
$info->{'state'}{'subjects'} || {}
MC/DC0%0/1
$info->{'state'}{'subjects'} || {}
$info->{'state'}{'subjects'}
Truth table0%0/2
A
A= $info->{'state'}{'subjects'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 //= ">"
MC/DC0%0/1
$key_pattern //= ">"
$key_pattern
Truth table50%1/2
A
A= $key_pattern
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 195 | 1 | ▶ | die "invalid KV watch pattern '$key_pattern'" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
not length $key_pattern or $key_pattern =~ /\s/
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/
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition0%0/3
$headers and $headers =~ /KV-Operation:\s*(\S+)/i
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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 //= {}
MC/DC0%0/1
$opts //= {}
$opts
Truth table0%0/2
A
A= $opts
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
Condition0%0/2
$opts->{'max_history'} || 1
MC/DC0%0/1
$opts->{'max_history'} || 1
$opts->{'max_history'}
Truth table0%0/2
A
A= $opts->{'max_history'}
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||