| 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 |