blib/lib/Mojolicious/Plugin/Buffer/Lock/Redis.pm

filter: Statementstmt 100% 122 / 122 Branchbran 85.2% 29 / 34 Conditioncond 72.4% 21 / 29 MC/DCmcdc 37.5% 6 / 16 Subroutinesub 100% 31 / 31 Podpod 100% 3 / 3 totaltotal 90.2% 212 / 235 CC 28 SCAR 12.6
CC
28
Cov
93%
acquire
7.3
release
6.1
_run_script
6.0
CRAP 3.5
« blib/lib/Mojolicious/Plugin/Buffer/Lock/File.pm ↑ Summary examples/hypnotoad/script/my_app »
1 package Mojolicious::Plugin::Buffer::Lock::Redis;
2  
3 10 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 10 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 10 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 10 ▶use Mojo::Base -base;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 10 ▶use Carp qw(croak);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 10 ▶use Mojo::Util qw(encode md5_sum trim);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 10 ▶use Mojolicious::Plugin::Buffer::I18N qw(i18n);
Subroutine BEGIN: called CC=1 SCAR=0.0
12 10 ▶use Params::Get qw(get_params);
Subroutine BEGIN: called CC=1 SCAR=0.0
13 10 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
14 10 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 10 ▶use Scalar::Util qw(blessed refaddr);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 10 ▶use Sub::Private { mode => 'enforce' };
Subroutine BEGIN: called CC=1 SCAR=0.0
17 10 ▶use Sub::Protected;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 10 ▶use Time::HiRes ();
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 10 ▶use version; our $VERSION = version->declare('0.002.0');
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 10 Readonly::Scalar my $DEFAULT_NAMESPACE => 'buffer:lock:';
23 10 Readonly::Scalar my $DEFAULT_TTL => 60;
24  
25 # Redis takes PX in milliseconds; a TTL that rounds below 1ms would be
26 # rejected by the server, so it is clamped to this
27 10 Readonly::Scalar my $MS_PER_SECOND => 1000;
28 10 Readonly::Scalar my $MIN_TTL_MS => 1;
29  
30 # Constructor arguments. The client is checked separately, because CPAN Redis
31 # dispatches commands through AUTOLOAD and has no eval() for can() to find.
32 Readonly::Hash my %NEW_SCHEMA => (
33 namespace => {type => 'string', min => 1},
34 22 ▶ ttl => {type => 'number', matches => qr/^\d+(?:\.\d+)?$/, callback => sub { defined($_[0]) && ($_[0] > 0) }},
Subroutine __ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
BranchTrueFalseTotal
defined $_[0] and $_[0] > 0 20 2 22
35 10 );
36  
37 10 has redis => undef;
38 10 has namespace => $DEFAULT_NAMESPACE;
39 10 has ttl => $DEFAULT_TTL;
40 10 has messages => undef;
41  
42 # Makes each token unique within a process even within one clock tick
43 10 my $TOKEN_COUNTER = 0;
44  
45 # SET NX PX is atomic, so only one worker can create the key. The token lets
46 # the owner release exactly its own lock.
47 10 Readonly::Scalar my $ACQUIRE_SCRIPT => <<'LUA';
48 if redis.call('set', KEYS[1], ARGV[1], 'NX', 'PX', ARGV[2]) then
49 return 1
50 end
51 return 0
52 LUA
53  
54 # Compare and delete in one script, so a lock that expired and was taken by
55 # another worker is never removed by the previous owner.
56 10 Readonly::Scalar my $RELEASE_SCRIPT => <<'LUA';
57 if redis.call('get', KEYS[1]) == ARGV[1] then
58 return redis.call('del', KEYS[1])
59 end
60 return 0
61 LUA
62  
63 =encoding utf8
64  
65 =head1 NAME
66  
67 Mojolicious::Plugin::Buffer::Lock::Redis - Redis-backed lock backend
68  
69 =head1 VERSION
70  
71 Version 0.002.0
72  
73 =head1 SYNOPSIS
74  
75 Workers on several machines, sharing one Redis server and one cache:
76  
77 use Mojolicious::Lite;
78 use CHI;
79 use Redis;
80 use Mojolicious::Plugin::Buffer::Lock::Redis;
81  
82 plugin 'Buffer' => {
83 cache => CHI->new(driver => 'Memcached', servers => ['cache.internal:11211']),
84 cache_lock => Mojolicious::Plugin::Buffer::Lock::Redis->new(
85 # A code reference: each worker makes its own connection
86 redis => sub {
87 Redis->new(
88 server => 'redis.internal:6379',
89 cnx_timeout => 1,
90 read_timeout => 1,
91 write_timeout => 1,
92 );
93 },
94 namespace => 'myapp:buffer:',
95 ttl => 60,
96 ),
97 };
98  
99 The same with L<Redis::Fast>, which has the same interface:
100  
101 use Redis::Fast;
102  
103 my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new(
104 redis => sub { Redis::Fast->new(server => 'redis.internal:6379') },
105 );
106  
107 Use it on its own, for example so that only one machine runs a job:
108  
109 my ($guard, $error) = $lock->acquire('nightly-report');
110 if ($guard) {
111 build_report();
112 $lock->release($guard);
113 } elsif (defined $error) {
114 warn "Redis problem: $error\n";
115 } # else another machine is already doing it
116  
117 Add a Redis Cluster hash tag by overriding the protected C<_key> method, so
118 every lock lands in one slot:
119  
120 package MyApp::Lock;
121 use Mojo::Base 'Mojolicious::Plugin::Buffer::Lock::Redis';
122 use Mojo::Util qw(encode md5_sum);
123  
124 sub _key {
125 my ($self, $key) = @_;
126 return '{' . $self->namespace . '}' . md5_sum(encode('UTF-8', $key));
127 }
128  
129 =head1 DESCRIPTION
130  
131 This is a lock backend for
132 L<cache_lock|Mojolicious::Plugin::Buffer/cache_lock>. It lets workers on
133 I<different machines> agree that only one of them builds a missing cache
134 entry. The cache itself must also be shared between those workers.
135  
136 =head2 How it works, in plain words
137  
138 =over 4
139  
140 =item 1. Each cache key is turned into a Redis key: L</namespace> followed by
141 the MD5 digest of the cache key.
142  
143 =item 2. To take the lock, the backend writes a random I<token> into that
144 Redis key, but only if the key does not exist yet (Redis C<SET ... NX PX>).
145 Redis does this in one step, so two workers can never both succeed.
146  
147 =item 3. The Redis key expires by itself after L</ttl> seconds. So if a
148 worker crashes while it holds a lock, the lock disappears later on its own.
149  
150 =item 4. To release the lock, a small Lua script deletes the Redis key, but
151 only if it still holds I<our> token. If our lock already expired and another
152 worker took it, we do not delete theirs.
153  
154 =back
155  
156 The Redis client is called I<synchronously>: the worker waits for Redis to
157 answer before the request goes on. So set short connect, read and write
158 timeouts on the client, and do not use a non-blocking client. Redis 2.6.12
159 or newer is needed for C<SET ... NX PX>.
160  
161 =head2 Words used in this document
162  
163 =over 4
164  
165 =item token
166  
167 A random 32-character string made for each successful L</acquire>. It
168 proves which worker owns a lock.
169  
170 =item TTL
171  
172 "Time to live": how long Redis keeps the lock before it deletes it by
173 itself.
174  
175 =item guard
176  
177 The value L</acquire> returns when you get the lock. It holds the Redis key
178 and the token. Give it back to L</release>.
179  
180 =back
181  
182 =head1 ATTRIBUTES
183  
184 Attributes are set with L</new>, which checks them. Each one also has an
185 accessor method with the same name, made by L<Mojo::Base>. Changing a value
186 through the accessor after L</new> skips those checks.
187  
188 =head2 redis
189  
190 Required. Either a Redis client object with the same
191 C<eval($script, $numkeys, @args)> method as L<Redis> and L<Redis::Fast>, or
192 a code reference that returns such an object.
193  
194 Prefer the code reference. It is called the first time this backend is
195 used in each process, so with a pre-forking server such as L<hypnotoad>
196 every worker gets its own connection. A client object made in C<startup>
197 is copied into every worker by C<fork>, and the workers would then share
198 one network connection, which corrupts the replies.
199  
200 =head3 API SPECIFICATION
201  
202 =head4 Input
203  
204 # An object is accepted when it can('eval') or has an AUTOLOAD, as the
205 # CPAN Redis client dispatches its commands through AUTOLOAD
206 { redis => { type => ['coderef', 'object'], optional => 1 } }
207  
208 =head4 Output
209  
210 # Return::Set schema: the value when reading, the object when writing
211 { type => ['coderef', 'object'] }
212  
213 =head2 namespace
214  
215 The prefix for every Redis key this backend makes. Defaults to
216 C<'buffer:lock:'>. Use a different namespace for each application that
217 shares a Redis database.
218  
219 =head3 API SPECIFICATION
220  
221 =head4 Input
222  
223 { namespace => { type => 'string', min => 1, optional => 1 } }
224  
225 =head4 Output
226  
227 # Return::Set schema: the value when reading, the object when writing
228 { type => 'string', min => 1 }
229  
230 =head2 ttl
231  
232 How long a lock lives, in seconds. Defaults to 60. Fractions such as
233 C<0.5> are allowed; the value is sent to Redis in whole milliseconds, and
234 never less than 1 millisecond. Choose a value longer than
235 L<cache_lock_timeout|Mojolicious::Plugin::Buffer/cache_lock_timeout> and
236 longer than your slowest cached action.
237  
238 =head3 API SPECIFICATION
239  
240 =head4 Input
241  
242 { ttl => { type => 'number', min => 0, optional => 1,
243 matches => qr/^\d+(?:\.\d+)?$/ } } # and > 0
244  
245 =head4 Output
246  
247 # Return::Set schema: the value when reading, the object when writing
248 { type => 'number' }
249  
250 =head2 messages
251  
252 An optional hash of message overrides. See
253 L<Mojolicious::Plugin::Buffer::I18N> for the keys and the text format.
254  
255 =head3 API SPECIFICATION
256  
257 =head4 Input
258  
259 { messages => { type => 'hashref', optional => 1 } }
260  
261 =head4 Output
262  
263 # Return::Set schema: the hash (or undef) when reading, the object
264 # when writing
265 { type => 'hashref', optional => 1 }
266  
267 =head1 METHODS
268  
269 =head2 new
270  
271 my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new(redis => sub { Redis->new });
272  
273 =head3 Purpose
274  
275 Create the backend and check its configuration. No connection is made.
276  
277 =head3 Arguments
278  
279 =over 4
280  
281 =item C<redis> (named, required)
282  
283 A client object or a code reference returning one.
284  
285 =item C<namespace> (named, optional)
286  
287 A non-empty string, default C<'buffer:lock:'>.
288  
289 =item C<ttl> (named, optional)
290  
291 A positive number of seconds, default 60.
292  
293 =item C<messages> (named, optional)
294  
295 A hash of message overrides.
296  
297 =back
298  
299 =head3 Returns
300  
301 The new object.
302  
303 =head3 Side effects
304  
305 None.
306  
307 =head3 Example
308  
309 my $lock = Mojolicious::Plugin::Buffer::Lock::Redis->new(
310 redis => sub { Redis->new(server => 'redis.internal:6379') },
311 namespace => 'shop:buffer:',
312 ttl => 30,
313 );
314  
315 =head3 API SPECIFICATION
316  
317 =head4 Input
318  
319 {
320 redis => { type => ['coderef', 'object'] }, # object: eval() or AUTOLOAD
321 namespace => { type => 'string', min => 1, optional => 1 },
322 ttl => { type => 'number', min => 0, optional => 1,
323 matches => qr/^\d+(?:\.\d+)?$/ }, # and > 0
324 messages => { type => 'hashref', optional => 1 },
325 }
326  
327 =head4 Output
328  
329 # Return::Set schema
330 { type => 'object', isa => 'Mojolicious::Plugin::Buffer::Lock::Redis' }
331  
332 =head3 MESSAGES
333  
334 Key Message Resolution
335 ----------------------- ---------------------------------------- -------------------------------
336 redis_client_invalid cache_lock redis must be an object with Pass a Redis/Redis::Fast object
337 an eval() method or a code reference or, better, a factory sub
338 returning one
339 redis_namespace_invalid cache_lock namespace must be a non-empty Pass e.g. 'myapp:buffer:'
340 string
341 redis_ttl_invalid cache_lock ttl must be a positive number Pass e.g. 60
342 of seconds
343  
344 All three croak.
345  
346 =cut
347  
348 26 ▶sub new {
Subroutine new: called CC=5 SCAR=16.1
Pod documented
349 26 my ($class, @args) = @_;
350  
351 26 ▶ my $self = $class->SUPER::new(get_params(undef, @args) // {});
Condition50%1/2
get_params(undef, @args) // {}
l!l
260
MC/DC0%0/1
get_params(undef, @args) // {}
get_params(undef, @args)
Truth table50%1/2
A
A= get_params(undef, @args)
Aresult
11
00
352  
353 26 ▶ croak $self->i18n('redis_client_invalid') unless _valid_client($self->redis);
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_client($self->redis) 2 24 26
354 24 ▶ croak $self->i18n('redis_namespace_invalid') unless _valid($self, 'namespace');
Branch: 1 branch
BranchTrueFalseTotal
unless _valid($self, "namespace") 2 22 24
355 22 ▶ croak $self->i18n('redis_ttl_invalid') unless _valid($self, 'ttl');
Branch: 1 branch
BranchTrueFalseTotal
unless _valid($self, "ttl") 4 18 22
356  
357 18 return $self;
358 }
359  
360 =head2 acquire
361  
362 my ($guard, $error) = $lock->acquire($key);
363  
364 =head3 Purpose
365  
366 Try, without waiting, to become the only worker building C<$key>.
367  
368 =head3 Arguments
369  
370 =over 4
371  
372 =item C<$key> (positional, required)
373  
374 The cache key: any defined string, in any language, emoji included. Only
375 its MD5 digest is sent to Redis.
376  
377 =back
378  
379 =head3 Returns
380  
381 C<($guard, undef)> when the lock was acquired, C<(undef, undef)> when
382 another worker holds it, and C<(undef, $error)> when Redis is unavailable.
383 The plugin logs an error and continues without a cross-worker lock in the
384 last case. Call it in list context; see L</COMMON PITFALLS>.
385  
386 =head3 Side effects
387  
388 Connects to Redis on first use (through the factory) and sets a key that
389 expires after L</ttl>.
390  
391 =head3 Example
392  
393 my ($guard, $error) = $lock->acquire('buffer:0123abcd');
394 $lock->release($guard) if $guard;
395  
396 =head3 API SPECIFICATION
397  
398 =head4 Input
399  
400 { key => { type => 'string', position => 0 } }
401  
402 =head4 Output
403  
404 # Return::Set schema (list of two)
405 {
406 type => 'arrayref',
407 schema => [
408 { type => 'hashref', optional => 1 }, # guard: {key, token}
409 { type => 'string', optional => 1 }, # error
410 ],
411 }
412  
413 =head3 MESSAGES
414  
415 Key Message Resolution
416 ------------------ ---------------------------------------- ---------------------------
417 lock_key_undefined cache key is not defined Pass a defined key
418 redis_lock_failed Redis lock failed: ERROR Check the server and client
419 redis_no_client Redis client factory returned no client Make the factory return one
420 redis_no_result Redis lock command returned no result Check the client library
421  
422 These are returned, not thrown.
423  
424 =head3 PSEUDOCODE
425  
426 reject an undefined key
427 derive the Redis key and a fresh token
428 convert the TTL to milliseconds, at least 1
429 run SET NX PX through the Lua script
430 if the call failed, return the error
431 if it returned nothing, return "no result"
432 if it returned 1, return the guard
433 otherwise return (undef, undef): someone else holds it
434  
435 =cut
436  
437 32 ▶sub acquire {
Subroutine acquire: called CC=7 SCAR=19.8
Pod documented
438 32 my ($self, @args) = @_;
439  
440 # get_params() confesses on an empty list; no key is a returned error
441 32 ▶ my $key = @args ? get_params('key', @args)->{key} : undef;
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 32 0 32
442 32 ▶ return (undef, $self->i18n('lock_key_undefined')) unless defined($key);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 0 32 32
443  
444 32 my $lock_key = $self->_key($key);
445 32 my $token = $self->_token;
446 32 my $ttl = int($self->ttl * $MS_PER_SECOND);
447 32 ▶ $ttl = $MIN_TTL_MS if $ttl < $MIN_TTL_MS;
Branch: 1 branch
BranchTrueFalseTotal
if $ttl < $MIN_TTL_MS 0 32 32
448  
449 32 my $outcome = $self->_run_script($ACQUIRE_SCRIPT, $lock_key, $token, $ttl);
450 32 ▶ return (undef, $self->i18n('redis_lock_failed', {error => $outcome->{error}})) if defined($outcome->{error});
Branch: 1 branch
BranchTrueFalseTotal
if defined $outcome->{"error"} 4 28 32
451 28 ▶ return (undef, $self->i18n('redis_no_result')) unless defined($outcome->{result});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $outcome->{"result"} 0 28 28
452  
453 28 ▶ return $outcome->{result} ? ({key => $lock_key, token => $token}, undef) : (undef, undef);
Branch: 1 branch
BranchTrueFalseTotal
$outcome->{'result'} ? : 20 8 28
454 }
455  
456 =head2 release
457  
458 my ($ok, $error) = $lock->release($guard);
459  
460 =head3 Purpose
461  
462 Delete the lock, but only if it still holds this guard's token.
463  
464 =head3 Arguments
465  
466 =over 4
467  
468 =item C<$guard> (positional, required)
469  
470 A guard returned by L</acquire>.
471  
472 =back
473  
474 =head3 Returns
475  
476 C<(1, undef)> on success, including when the lock had already expired, and
477 C<(0, $error)> on failure. A failed release is not fatal because the lock
478 expires after L</ttl>.
479  
480 =head3 Side effects
481  
482 Deletes the Redis key if it still holds the token.
483  
484 =head3 Example
485  
486 my ($ok, $error) = $lock->release($guard);
487 warn $error unless $ok;
488  
489 =head3 API SPECIFICATION
490  
491 =head4 Input
492  
493 { guard => { type => 'hashref', position => 0 } } # {key, token}
494  
495 =head4 Output
496  
497 # Return::Set schema (list of two)
498 {
499 type => 'arrayref',
500 schema => [
501 { type => 'boolean' },
502 { type => 'string', optional => 1 },
503 ],
504 }
505  
506 =head3 MESSAGES
507  
508 Key Message Resolution
509 ------------------- ---------------------------- ------------------------------
510 redis_invalid_guard invalid lock guard Pass the guard acquire returned
511 redis_unlock_failed Redis unlock failed: ERROR None needed; the TTL expires it
512  
513 =cut
514  
515 24 ▶sub release {
Subroutine release: called CC=6 SCAR=18.0
Pod documented
516 24 my ($self, $guard) = @_;
517  
518 24 ▶ my $valid = (ref($guard) eq 'HASH') && defined($guard->{key}) && defined($guard->{token});
Condition66%4/6
ref $guard eq 'HASH' && defined $guard->{'key'} && defined $guard->{'token'}
!ll&&!rl&&r
2022
ref $guard eq "HASH" and defined $guard->{"key"}
!ll&&!rl&&r
0222
MC/DC33%1/3
ref $guard eq 'HASH' && defined $guard->{'key'} && defined $guard->{'token'}
ref $guard eq "HASH" defined $guard->{"key"} defined $guard->{'token'}
Truth table50%2/4
A and B && C
A= ref $guard eq "HASH"B= defined $guard->{"key"}C= defined $guard->{'token'}
ABCresult
0XX0
10X0
1100
1111
519 24 ▶ my $outcome = $valid ? $self->_run_script($RELEASE_SCRIPT, $guard->{key}, $guard->{token}) : {};
Branch: 1 branch
BranchTrueFalseTotal
$valid ? : 22 2 24
520  
521 # An expired lock (script result 0) is still a successful release
522 return !$valid ? (0, $self->i18n('redis_invalid_guard'))
523 24 ▶ : defined($outcome->{error}) ? (0, $self->i18n('redis_unlock_failed', {error => $outcome->{error}}))
Branch: 2 branches
BranchTrueFalseTotal
!$valid ? : 2 22 24
defined $outcome->{'error'} ? : 2 20 22
524 : (1, undef);
525 }
526  
527 # Purpose: Run one of the Lua scripts against a single key.
528 # Entry criteria: $script is Lua; $key and @argv are strings.
529 # Exit status: {result => $value} on success, {error => $text} when the
530 # factory returned nothing or the client died.
531 # Side effects: Network round trip; may create the per-worker client.
532 54 ▶sub _run_script :Private {
Subroutine _run_script: called CC=6 SCAR=18.0
533 54 my ($self, $script, $key, @argv) = @_;
534  
535 54 my $redis = eval { $self->_client };
536 54 my $error = $@;
537 54 ▶ $error = $self->i18n('redis_no_client') if !$error && !$redis;
Branch: 1 branch
BranchTrueFalseTotal
unless $error or $redis 0 54 54
Condition66%2/3
$error or $redis
l!l&&r!l&&!r
2520
MC/DC0%0/2
$error or $redis
$error $redis
Truth table66%2/3
A or B
A= $errorB= $redis
ABresult
1X1
011
000
538  
539 54 ▶ my $result = $error ? undef : eval { $redis->eval($script, 1, $key, @argv) };
Branch: 1 branch
BranchTrueFalseTotal
$error ? : 2 52 54
540 54 ▶ $error ||= $@;
Condition100%3/3
$error ||= $@
l!l&&r!l&&!r
2448
MC/DC100%2/2
$error ||= $@
$error $@
Truth table100%3/3
A ||= B
A= $errorB= $@
ABresult
1X1
011
000
541  
542 54 ▶ return $error ? {error => trim("$error")} : {result => $result};
Branch: 1 branch
BranchTrueFalseTotal
$error ? : 6 48 54
543 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
544  
545 # Purpose: Return the Redis client, calling the factory once.
546 # Entry criteria: redis is an object or a code reference.
547 # Exit status: The client, or whatever the factory returned.
548 # Side effects: Caches the factory result for this object; may die if
549 # the factory dies. Protected so a subclass can supply a
550 # pooled or sentinel-aware client.
551 54 ▶sub _client :Protected {
Subroutine _client: called CC=3 SCAR=11.0
552 54 my $self = shift;
553  
554 54 my $redis = $self->redis;
555  
556 # Called lazily, so a pre-forking server gets one connection per worker
557 54 ▶ return ref($redis) eq 'CODE' ? ($self->{client} //= $redis->()) : $redis;
Branch: 1 branch
BranchTrueFalseTotal
ref $redis eq 'CODE' ? : 10 44 54
Condition66%2/3
$self->{"client"} //= &$redis()
l!l&&r!l&&!r
640
MC/DC0%0/2
$self->{"client"} //= &$redis()
$self->{"client"} &$redis()
Truth table66%2/3
A //= B
A= $self->{"client"}B= &$redis()
ABresult
1X1
011
000
558 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
559  
560 # Purpose: Map a cache key to its Redis key.
561 # Entry criteria: $key is a defined string.
562 # Exit status: namespace followed by the MD5 of the key.
563 # Side effects: None. Protected so a subclass can add e.g. a hash tag
564 # for Redis Cluster slot placement.
565 32 ▶sub _key :Protected {
Subroutine _key: called CC=1 SCAR=0.0
566 32 my ($self, $key) = @_;
567  
568 # md5_sum dies on characters above 255, so hash the UTF-8 bytes
569 32 return $self->namespace . md5_sum(encode('UTF-8', $key));
570 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
571  
572 # Purpose: Produce a token that no other acquisition will share.
573 # Entry criteria: None.
574 # Exit status: A 32-character hex string.
575 # Side effects: Increments the per-process counter.
576 32 ▶sub _token :Protected {
Subroutine _token: called CC=1 SCAR=0.0
577 32 my $self = shift;
578  
579 32 return md5_sum(join "\0", $$, Time::HiRes::time(), ++$TOKEN_COUNTER, rand(), refaddr($self));
580 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
581  
582 # Purpose: Check a client value without connecting.
583 # Entry criteria: Any scalar.
584 # Exit status: True for a code reference, or an object with eval() or an
585 # AUTOLOAD that will provide it.
586 # Side effects: None.
587 26 ▶sub _valid_client :Private {
Subroutine _valid_client: called CC=4 SCAR=14.1
588 26 my $redis = shift;
589  
590 26 ▶ return (ref($redis) eq 'CODE')
Condition77%7/9
ref $redis eq 'CODE' || builtin::blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD'))
l!l&&r!l&&!r
4202
builtin::blessed($redis) and $redis->can("eval") || $redis->can("AUTOLOAD")
!ll&&!rl&&r
2020
$redis->can("eval") or $redis->can("AUTOLOAD")
l!l&&r!l&&!r
1820
MC/DC50%2/4
ref $redis eq 'CODE' || builtin::blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD'))
ref $redis eq 'CODE' builtin::blessed($redis) $redis->can("eval") $redis->can("AUTOLOAD")
Truth table80%4/5
A || B and C or D
A= ref $redis eq 'CODE'B= builtin::blessed($redis)C= $redis->can("eval")D= $redis->can("AUTOLOAD")
ABCDresult
1XXX1
011X1
01011
00XX0
01000
591 || (blessed($redis) && ($redis->can('eval') || $redis->can('AUTOLOAD')));
592 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
593  
594 # Purpose: Validate one attribute against %NEW_SCHEMA.
595 # Entry criteria: $self is constructed; $name is a key of %NEW_SCHEMA.
596 # Exit status: True if the attribute's value is acceptable.
597 # Side effects: None.
598 46 ▶sub _valid :Private {
Subroutine _valid: called CC=2 SCAR=7.0
599 46 my ($self, $name) = @_;
600  
601 46 my $value = $self->$name;
602 46 ▶ return !ref($value) && eval { validate_strict(schema => {$name => $NEW_SCHEMA{$name}}, input => {$name => $value}); 1 };
Condition66%2/3
!ref($value) && eval { do { validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value}); 1 } }
!ll&&!rl&&r
0640
MC/DC50%1/2
!ref($value) && eval { do { validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value}); 1 } }
!ref($value) eval { do { validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value}); 1 } }
Truth table66%2/3
not(A) && B
A= !ref($value)B= eval { do { validate_strict('schema', {$name, $NEW_SCHEMA{$name}}, 'input', {$name, $value}); 1 } }
ABresult
0X0
100
111
603 10 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
604  
605 10 1;
606  
607 =head1 COMMON PITFALLS
608  
609 =over 4
610  
611 =item * B<Always take both return values.> L</acquire> returns a list of
612 two values. In scalar context Perl gives you only the I<last> one, the
613 error slot:
614  
615 my $guard = $lock->acquire($key); # WRONG: $guard is undef
616 my ($guard, $error) = $lock->acquire($key); # right
617  
618 Here the mistake is costly. The lock I<was> taken in Redis, but you have
619 lost the token, so you cannot release it. Every worker then sees "busy" for
620 that key until the L</ttl> runs out.
621  
622 =item * B<The TTL is too short.> If the builder is still working when the
623 lock expires, a second worker can take the lock and build the same entry.
624 Make L</ttl> longer than the slowest action that uses the cache.
625  
626 =item * B<A client object made before the fork.> Pass a code reference as
627 L</redis>, not an object made in C<startup>. Also, do not call L</acquire>
628 in C<startup>: the first call stores the client, and C<fork> would then copy
629 it into every worker.
630  
631 =item * B<A slow Redis server slows every cached request.> The call waits
632 for Redis. Set C<cnx_timeout>, C<read_timeout> and C<write_timeout> on the
633 client.
634  
635 =item * B<Changing attributes after C<new>.> C<< $lock->ttl(0) >> is not
636 checked; Redis is then sent the smallest TTL, 1 millisecond, and the lock
637 protects nothing. Set attributes with L</new> only.
638  
639 =item * B<The lock is not re-entrant.> A second C<acquire> for a key this
640 worker already holds returns "busy" C<(undef, undef)>.
641  
642 =item * B<undef values.> C<acquire(undef)> returns
643 C<(undef, 'cache key is not defined')>. C<release(undef)> returns
644 C<(0, 'invalid lock guard')>. A factory that returns C<undef> gives
645 C<(undef, 'Redis lock failed: Redis client factory returned no client')>,
646 and is asked again on the next call. C<< new(ttl =E<gt> undef) >> and
647 C<< new(namespace =E<gt> undef) >> croak.
648  
649 =back
650  
651 =head1 ENCODING
652  
653 =over 4
654  
655 =item Keys
656  
657 Any Perl string is safe, including accented letters, other non-ASCII text
658 and emoji. The key is encoded as UTF-8 bytes and hashed, so only an ASCII
659 digest is sent to Redis. A subclass that overrides C<_key> must encode
660 before calling C<md5_sum>, which dies on a character above U+00FF.
661  
662 =item namespace
663  
664 Sent to Redis as part of the key. Keep it ASCII. Redis keys are bytes, so
665 a non-ASCII namespace must be encoded to bytes by you first.
666  
667 =item messages
668  
669 Override texts may hold any characters, including emoji. The messages this
670 module returns are Perl character strings; print them through an encoding
671 layer such as C<:encoding(UTF-8)>, or Perl warns "Wide character".
672 L<Mojo::Log> encodes to UTF-8 by itself. The text after C<ERROR> comes from
673 the Redis client and is passed on unchanged.
674  
675 =back
676  
677 =head1 LIMITATIONS
678  
679 =over 4
680  
681 =item * The client is called synchronously inside a request. A slow or
682 partitioned Redis server stalls that worker for as long as the client's own
683 timeouts allow; there is no circuit breaker.
684  
685 =item * This is a single-instance lock, not Redlock. With Redis replication,
686 a fail-over can lose a lock that was just set, and two builders may run. For
687 a cache that is acceptable: the cost is one duplicated build, not corrupted
688 data.
689  
690 =item * A lock that outlives L</ttl> is silently lost, and a second builder
691 can start. Choose a TTL longer than the slowest cached action.
692  
693 =back
694  
695 =head1 SEE ALSO
696  
697 L<Mojolicious::Plugin::Buffer>,
698 L<Mojolicious::Plugin::Buffer::Lock::File>,
699 L<Mojolicious::Plugin::Buffer::I18N>.
700  
701 =head1 AUTHOR
702  
703 Nigel Horne, C<< <njh at bandsman.co.uk> >>
704  
705 =head1 FORMAL SPECIFICATION
706  
707 This section describes the backend in the Z notation, for readers who want
708 an exact model. You do not need it to use the module. C<store> is the part
709 of the Redis database that this backend uses, C<expiry> says when each of
710 its keys disappears, and C<now> is the current time.
711  
712 [KEY, TEXT, TOKEN, Client]
713  
714 rkey : KEY → TEXT
715 ∀ k : KEY • rkey k = namespace ⁀ md5(utf8(k))
716  
717 Guard == TEXT × TOKEN
718  
719 ┌─ Redis ─────────────────────────────────────
720 │ namespace : seq₁ CHAR
721 │ ttl : ℝ
722 │ client : Client ∪ {⊥}
723 │ store : TEXT ⇸ TOKEN
724 │ expiry : TEXT ⇸ ℝ
725 ├─────────────────────────────────────────────
726 │ ttl > 0
727 │ dom expiry = dom store
728 └─────────────────────────────────────────────
729  
730 ┌─ Expire ────────────────────────────────────
731 │ ΔRedis
732 ├─────────────────────────────────────────────
733 │ store′ = { r : dom store | expiry r ≤ now } ⩤ store
734 │ expiry′ = { r : dom store | expiry r ≤ now } ⩤ expiry
735 └─────────────────────────────────────────────
736  
737 =head2 new
738  
739 ┌─ NewRedisLock ──────────────────────────────
740 │ Redis′
741 │ redis? : Client ∪ (seq ARG → Client)
742 │ namespace? : seq₁ CHAR ; ttl? : ℝ
743 │ result! : Redis
744 ├─────────────────────────────────────────────
745 │ ttl? > 0
746 │ namespace′ = namespace? ∧ ttl′ = ttl?
747 │ client′ = ⊥ ⇐ redis? is a code reference
748 │ result! = θRedis′
749 └─────────────────────────────────────────────
750 -- No connection is made. Any violated predicate: croak.
751  
752 =head2 acquire
753  
754 C<reachable> means the client could be made and answered. C<token> is
755 fresh: it differs from every token issued before.
756  
757 ┌─ AcquireRedis ──────────────────────────────
758 │ ΔRedis
759 │ key? : KEY ; token : TOKEN
760 │ guard! : Guard ∪ {⊥} ; error! : TEXT ∪ {⊥}
761 ├─────────────────────────────────────────────
762 │ let r == rkey key? •
763 │ reachable ∧ r ∉ dom store ⇒
764 │ store′ = store ⊕ {r ↦ token}
765 │ ∧ expiry′ = expiry ⊕ {r ↦ now + max(ttl, 0.001)}
766 │ ∧ guard! = (r, token) ∧ error! = ⊥
767 │ reachable ∧ r ∈ dom store ⇒
768 │ store′ = store ∧ guard! = ⊥ ∧ error! = ⊥
769 │ ¬reachable ⇒
770 │ store′ = store ∧ guard! = ⊥ ∧ error! ≠ ⊥
771 └─────────────────────────────────────────────
772  
773 =head2 release
774  
775 ┌─ ReleaseRedis ──────────────────────────────
776 │ ΔRedis
777 │ guard? : Guard ∪ {⊥} ; ok! : 𝔹 ; error! : TEXT ∪ {⊥}
778 ├─────────────────────────────────────────────
779 │ guard? = ⊥ ⇒ store′ = store ∧ ok! = false ∧ error! ≠ ⊥
780 │ guard? = (r, t) ∧ store r = t ⇒
781 │ store′ = {r} ⩤ store ∧ ok! = true
782 │ guard? = (r, t) ∧ (r ∉ dom store ∨ store r ≠ t) ⇒
783 │ store′ = store ∧ ok! = true
784 │ ¬reachable ⇒ store′ = store ∧ ok! = false ∧ error! ≠ ⊥
785 └─────────────────────────────────────────────
786  
787 =head1 STATE DIAGRAM
788  
789 Each cache key's lock, as Redis sees it. The numbers on the arrows are
790 explained below the picture.
791  
792 +-----------+ (1) +----------------+
793 | FREE | --------------------------> | HELD (token) |
794 | (key k) | <-------------------------- | |
795 +-----------+ (2) or (3) +----------------+
796 | ^ | ^
797 +-----+ (4) +-----+ (5), (6)
798  
799 (1) acquire(k) [Redis answers and the key is absent]
800 / SET key token NX PX ttl; returns ({key, token}, undef)
801 (2) release(guard) [the stored token matches the guard]
802 / the Lua script deletes the key; returns (1, undef)
803 (3) the TTL runs out
804 / Redis deletes the key by itself. If the holder is still
805 building, a second worker can now start building as well.
806 (4) acquire(k) [Redis is unreachable, or the factory gave no client]
807 / returns (undef, error); nothing changes
808 (5) acquire(k) [the key is present], from any worker, the holder too
809 / returns (undef, undef); nothing changes
810 (6) release(old guard) [the token differs: this lock expired and
811 another worker took the key]
812 / nothing is deleted; returns (1, undef)
813  
814 The backend object itself has one more state, for its client:
815  
816 +----------------+ first acquire() or release() in this process
817 | NO CLIENT YET | [redis is a code reference] +---------+
818 | (after new) | -------------------------------------> | CLIENT |
819 +----------------+ / call the factory once; keep result | READY |
820 | ^ +---------+
821 +---+ the factory returned undef or died
822 / the call returns (undef, error); try again next time
823  
824 When L</redis> is an object rather than a code reference, the backend
825 starts in CLIENT READY.
826  
827 The plugin's own use of these states is drawn in
828 L<Mojolicious::Plugin::Buffer/STATE DIAGRAM>.
829  
830 =head1 LICENSE AND COPYRIGHT
831  
832 Copyright 2026 Nigel Horne.
833  
834 This program is free software; you can redistribute it and/or modify it
835 under the terms of the GNU General Public License as published by the Free
836 Software Foundation; either version 2 of the License, or (at your option)
837 any later version.
838  
839 =cut
« blib/lib/Mojolicious/Plugin/Buffer/Lock/File.pm ↑ Summary examples/hypnotoad/script/my_app »