blib/lib/Web/VWF/Throttle.pm untested

filter: Statementstmt 0.0% 0 / 47 Branchbran 0.0% 0 / 14 Conditioncond 0.0% 0 / 17 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 0.0% 0 / 9 Podpod 0.0% 0 / 4 totaltotal 0.0% 0 / 101 CC 8 SCAR 22.4
CC
8
Cov
0%
load
20.0
backend_store_ok
12.0
_chain_is_usable
6.0
CRAP 9.4
1 package Web::VWF::Throttle;
2  
3 # A Data::Throttler backend that keeps the throttle store intact where file
4 # locks are mandatory.
5 #
6 # Data::Throttler's own YAML backend locks the store, then reads and rewrites it
7 # by file name, opening a fresh handle for each of those. Unix locks are
8 # advisory, so a second handle is unaffected and the store round-trips. Windows
9 # locks are mandatory: as the documentation for LockFileEx puts it, "if the
10 # locking process opens the file a second time, it cannot access the specified
11 # region through this second handle". Every read and every write through the
12 # new handle therefore fails there, Web::VWF::Display catches the exception and
13 # removes the store it thinks is corrupt, and throttling quietly stops working -
14 # which is a security feature turning itself off on one platform, silently.
15 #
16 # Nothing in Data::Throttler is wrong on its own terms: it uses a plain file as
17 # a lock, and the file is meant to be rewritten. The two together are what
18 # Windows cannot do, so this backend keeps the store and the YAML format, and
19 # does both the reading and the writing through the one handle that already
20 # holds the lock.
21  
22 use strict;
23 use warnings;
24  
25 use Data::Throttler (); # For Data::Throttler::Backend::YAML, which this extends
26  
27 use version; our $VERSION = version->declare('0.003.0');
28  
29 =encoding utf8
30  
31 =head1 NAME
32  
33 Web::VWF::Throttle - persistent request throttling that works on Windows too
34  
35 =head1 VERSION
36  
37 Version 0.003.0
38  
39 =head1 SYNOPSIS
40  
41 use Data::Throttler;
42 use Web::VWF::Throttle; # Defines the 'VWF' backend
43  
44 my $throttler = Data::Throttler->new(
45 max_items => 30,
46 interval => 90,
47 backend => 'VWF',
48 backend_options => { db_file => '/path/to/throttle' },
49 );
50  
51 =head1 DESCRIPTION
52  
53 C<Data::Throttler> builds its backend class name from the C<backend> option, so
54 requesting C<< backend => 'VWF' >> asks for C<Data::Throttler::Backend::VWF>.
55 This module provides that class, inheriting everything from
56 C<Data::Throttler::Backend::YAML> except the two methods that touch the store.
57  
58 The YAML backend locks the store and then opens it again by name to read it and
59 to rewrite it. That is fine where locks are advisory, which is what they are on
60 Unix. Windows locks are mandatory: a process that opens the file a second time
61 cannot read or write the locked region through that second handle, so the store
62 can be neither loaded nor saved, and a caller that treats a broken store as a
63 reason to carry on unthrottled will never throttle anyone. Both methods here
64 use the handle that holds the lock instead, which is allowed to read and write
65 its own locked region on every platform.
66  
67 The file keeps the YAML format and layout that C<Data::Throttler> writes, so an
68 existing store carries on being used, and it can still be read by the backend it
69 came from.
70  
71 =head1 WHEN THE STORE CANNOT BE USED
72  
73 A store that cannot be opened, locked or written leaves the framework unable to
74 throttle anybody. The request is then served unthrottled, which is a decision
75 rather than an accident:
76  
77 =over 4
78  
79 =item * Throttling protects capacity, not privilege
80  
81 It grants access to nothing and hides nothing. A request served while the
82 store is unusable is still subject to the country blacklist, to the intrusion
83 detection beside it in the same block, and to every check the caller makes
84 afterwards.
85  
86 =item * The failure is this machine's, not the client's
87  
88 Failing closed would answer every visitor with C<429> for a fault of the
89 server. The store normally lives in the site's temporary directory, so a
90 filesystem that is full, mounted read-only or left with the wrong ownership
91 would take the whole site down - and the throttle, whose purpose is to keep the
92 site serving, would be what brought it down.
93  
94 =item * It is not quiet
95  
96 The failure is reported at error level on each request that meets it, because a
97 site that has stopped throttling anybody is a security problem rather than a
98 warning. A store that cannot be I<parsed> is a different case and heals itself:
99 C<load()> returns an empty store, C<backend_store_ok()> says so, and the caller
100 rebuilds the bucket chain over the unusable file. A store that parses but holds
101 no bucket chain parameters is healed the same way, and just as quietly - see
102 L</_chain_is_usable>.
103  
104 =item * And nothing is deleted
105  
106 The store belongs to every client, so deleting it discards their counters, and a
107 backend that cannot be used is not repaired by removing its file.
108  
109 =back
110  
111 A site that needs a hard limit even while the store is unusable needs a check
112 that does not depend on the store: at the form or the page that has to be
113 protected, rather than here.
114  
115 =head1 METHODS
116  
117 These are the methods of C<Data::Throttler::Backend::VWF>, not of
118 C<Web::VWF::Throttle> itself, which exists only to load them.
119  
120 =head2 load
121  
122 Purpose: read the store, through the locked handle when there is one.
123  
124 A store whose chain carries no bucket chain parameters comes back without that
125 chain, so that the caller rebuilds it silently rather than after comparing two
126 undefined values with the ones it was given - see L</_chain_is_usable>.
127  
128 Returns: the throttler's data, with its bucket chain restored.
129  
130 =cut
131  
132 package Data::Throttler::Backend::VWF;
133  
134 use base 'Data::Throttler::Backend::YAML';
135  
136 sub load
137 {
138 my $self = shift;
139  
140 # Nothing is locked while the store is being created, so the parent's
141 # by-name read is both correct and the only thing that can work
142 return $self->SUPER::load() unless $self->{'fh'};
143  
144 my $fh = $self->{'fh'};
145  
146 # A seek flushes anything written by the previous save and puts the
147 # read position back at the start of the file
148 seek($fh, 0, 0) or return $self->SUPER::load();
149  
150 my $yaml = do {
151 local $/;
152 <$fh>;
153 };
154  
155 # A store that cannot be parsed is no longer deleted by the caller, which
156 # now leaves it alone and reports the failure, so it has to be rebuilt
157 # here instead. Reporting nothing is what asks for that: backend_store_ok()
158 # below sees no bucket chain, Data::Throttler creates a fresh one and saves
159 # it over the unusable file.
160 # YAML warns its way through garbage before it dies; the store is about to
161 # be rebuilt, so that noise would only fill the error log
162 my $data = eval { local $SIG{__WARN__} = sub { }; YAML::Load($yaml) };
163 $data = {} if($@ || ref($data) ne 'HASH');
164 $self->native_classes_restore($data);
165  
166 # A store that parses but holds no bucket chain parameters is the one case
167 # Data::Throttler cannot rebuild quietly. native_classes_restore() has
168 # just blessed its chain into a bucket chain, so backend_store_ok() would
169 # call the store usable, and Data::Throttler then compares that chain's
170 # max_items and interval - both undef - with the ones it was given. That
171 # comparison warns once per value and then reports the parameters as
172 # changed, discarding a chain that was never usable to begin with.
173 #
174 # A store handed back without that chain never reaches the comparison: the
175 # `if($data->{chain} and ...)` in Data::Throttler's new() is false, and
176 # backend_store_ok() below says the chain cannot be reused, which is what
177 # makes it build a chain - with the parameters it was given - and save the
178 # store. The repair is the one that happened before, minus the warnings.
179 delete $data->{'chain'} unless($self->_chain_is_usable($data->{'chain'}));
180  
181 return $data;
182 }
183  
184 =head2 backend_store_ok
185  
186 Purpose: whether the store holds a bucket chain that can be reused.
187  
188 An unreadable or unparsable store used to be deleted by C<Web::VWF::Display>
189 so that the next request would write a fresh one. That deletion is gone, so the
190 rebuild happens here: a false return makes C<Data::Throttler> create the chain
191 again and save it over the unusable file, without a moment in which another
192 request can find no store at all.
193  
194 Returns: true if the store can be reused.
195  
196 =cut
197  
198 sub backend_store_ok
199 {
200 my $self = shift;
201  
202 return 1 unless(-f $self->{'db_file'});
203  
204 my $data = eval { $self->load() };
205 return 0 if($@ || ref($data) ne 'HASH');
206  
207 return $self->_chain_is_usable($data->{'chain'});
208 }
209  
210 =head2 _chain_is_usable
211  
212 Purpose: whether a chain loaded from the store carries the parameters
213 C<Data::Throttler> compares a store against.
214  
215 A chain is usable when it is a bucket chain that knows the C<max_items> and
216 C<interval> it was built with. C<chain: {}> in a store is the case this
217 catches: it parses, it restores to a bucket chain, and it has neither parameter
218 on it - so C<Data::Throttler> would compare two undefined values against the
219 configured ones, and rebuild the chain after reporting the change.
220  
221 Returns: true if the chain can be reused as it stands.
222  
223 =cut
224  
225 sub _chain_is_usable
226 {
227 # No invocant to use: the only thing this reads is the chain it is handed
228 my(undef, $chain) = @_;
229  
230 return 0 unless(ref($chain) eq 'Data::Throttler::BucketChain');
231  
232 return defined($chain->{'max_items'}) && defined($chain->{'interval'});
233 }
234  
235 =head2 save
236  
237 Purpose: write the store, through the locked handle when there is one.
238  
239 Returns: true.
240  
241 =cut
242  
243 sub save
244 {
245 my($self, $data) = @_;
246  
247 # Before the first lock the store is being created - see load() above
248 return $self->SUPER::save($data) unless $self->{'fh'};
249  
250 my $fh = $self->{'fh'};
251  
252 # Rewrite in place through the handle that owns the lock, rather than
253 # opening a second one: that is the whole point of this module
254 seek($fh, 0, 0) or die "Can't rewind $self->{'db_file'}: $!";
255 truncate($fh, 0) or die "Can't truncate $self->{'db_file'}: $!";
256 print {$fh} YAML::Dump($data) or die "Can't write $self->{'db_file'}: $!";
257  
258 return 1;
259 }
260  
261 1;
262  
263 =head1 AUTHOR
264  
265 Nigel Horne, C<< <njh at nigelhorne.com> >>
266  
267 =head1 LICENCE AND COPYRIGHT
268  
269 Copyright 2010-2026 Nigel Horne.
270  
271 Usage is subject to the GPL2 licence terms.
272 If you use it,
273 please let me know.
274  
275 =cut