NAME

Web::VWF::Throttle - persistent request throttling that works on Windows too

VERSION

Version 0.003.0

SYNOPSIS

use Data::Throttler;
use Web::VWF::Throttle;	# Defines the 'VWF' backend

my $throttler = Data::Throttler->new(
	max_items => 30,
	interval => 90,
	backend => 'VWF',
	backend_options => { db_file => '/path/to/throttle' },
);

DESCRIPTION

Data::Throttler builds its backend class name from the backend option, so requesting backend => 'VWF' asks for Data::Throttler::Backend::VWF. This module provides that class, inheriting everything from Data::Throttler::Backend::YAML except the two methods that touch the store.

The YAML backend locks the store and then opens it again by name to read it and to rewrite it. That is fine where locks are advisory, which is what they are on Unix. Windows locks are mandatory: a process that opens the file a second time cannot read or write the locked region through that second handle, so the store can be neither loaded nor saved, and a caller that treats a broken store as a reason to carry on unthrottled will never throttle anyone. Both methods here use the handle that holds the lock instead, which is allowed to read and write its own locked region on every platform.

The file keeps the YAML format and layout that Data::Throttler writes, so an existing store carries on being used, and it can still be read by the backend it came from.

WHEN THE STORE CANNOT BE USED

A store that cannot be opened, locked or written leaves the framework unable to throttle anybody. The request is then served unthrottled, which is a decision rather than an accident:

  • Throttling protects capacity, not privilege

    It grants access to nothing and hides nothing. A request served while the store is unusable is still subject to the country blacklist, to the intrusion detection beside it in the same block, and to every check the caller makes afterwards.

  • The failure is this machine's, not the client's

    Failing closed would answer every visitor with 429 for a fault of the server. The store normally lives in the site's temporary directory, so a filesystem that is full, mounted read-only or left with the wrong ownership would take the whole site down - and the throttle, whose purpose is to keep the site serving, would be what brought it down.

  • It is not quiet

    The failure is reported at error level on each request that meets it, because a site that has stopped throttling anybody is a security problem rather than a warning. A store that cannot be parsed is a different case and heals itself: load() returns an empty store, backend_store_ok() says so, and the caller rebuilds the bucket chain over the unusable file. A store that parses but holds no bucket chain parameters is healed the same way, and just as quietly - see "_chain_is_usable".

  • And nothing is deleted

    The store belongs to every client, so deleting it discards their counters, and a backend that cannot be used is not repaired by removing its file.

A site that needs a hard limit even while the store is unusable needs a check that does not depend on the store: at the form or the page that has to be protected, rather than here.

METHODS

These are the methods of Data::Throttler::Backend::VWF, not of Web::VWF::Throttle itself, which exists only to load them.

load

Purpose: read the store, through the locked handle when there is one.

A store whose chain carries no bucket chain parameters comes back without that chain, so that the caller rebuilds it silently rather than after comparing two undefined values with the ones it was given - see "_chain_is_usable".

Returns: the throttler's data, with its bucket chain restored.

backend_store_ok

Purpose: whether the store holds a bucket chain that can be reused.

An unreadable or unparsable store used to be deleted by Web::VWF::Display so that the next request would write a fresh one. That deletion is gone, so the rebuild happens here: a false return makes Data::Throttler create the chain again and save it over the unusable file, without a moment in which another request can find no store at all.

Returns: true if the store can be reused.

_chain_is_usable

Purpose: whether a chain loaded from the store carries the parameters Data::Throttler compares a store against.

A chain is usable when it is a bucket chain that knows the max_items and interval it was built with. chain: {} in a store is the case this catches: it parses, it restores to a bucket chain, and it has neither parameter on it - so Data::Throttler would compare two undefined values against the configured ones, and rebuild the chain after reporting the change.

Returns: true if the chain can be reused as it stands.

save

Purpose: write the store, through the locked handle when there is one.

Returns: true.

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENCE AND COPYRIGHT

Copyright 2010-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms. If you use it, please let me know.