| 1 | package PAGI::Middleware::WebSocket::RateLimit; | ||||||||||||||||||||||||
| 2 | 3 | $PAGI::Middleware::WebSocket::RateLimit::VERSION = '0.002002'; | |||||||||||||||||||||||
| 3 | 3 | ▶ | use strict; | ||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||
| 4 | 3 | ▶ | use warnings; | ||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||
| 5 | 3 | ▶ | use parent 'PAGI::Middleware'; | ||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||
| 6 | 3 | ▶ | use Future::AsyncAwait; | ||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||
| 7 | 3 | ▶ | use Time::HiRes qw(time); | ||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||
| 8 | |||||||||||||||||||||||||
| 9 | =head1 NAME | ||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||
| 11 | PAGI::Middleware::WebSocket::RateLimit - Rate limiting for WebSocket connections | ||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||
| 13 | =head1 SYNOPSIS | ||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||
| 15 | use PAGI::Middleware::Builder; | ||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||
| 17 | my $app = builder { | ||||||||||||||||||||||||
| 18 | enable 'WebSocket::RateLimit', | ||||||||||||||||||||||||
| 19 | messages_per_second => 10, | ||||||||||||||||||||||||
| 20 | bytes_per_second => 65536, | ||||||||||||||||||||||||
| 21 | burst_multiplier => 2; | ||||||||||||||||||||||||
| 22 | $my_app; | ||||||||||||||||||||||||
| 23 | }; | ||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||
| 25 | =head1 DESCRIPTION | ||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||
| 27 | PAGI::Middleware::WebSocket::RateLimit enforces rate limits on incoming | ||||||||||||||||||||||||
| 28 | WebSocket messages. Connections exceeding limits can be throttled or | ||||||||||||||||||||||||
| 29 | closed. | ||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||
| 31 | =head1 CONFIGURATION | ||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||
| 33 | =over 4 | ||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||
| 35 | =item * messages_per_second (default: 100) | ||||||||||||||||||||||||
| 36 | |||||||||||||||||||||||||
| 37 | Maximum incoming messages per second. | ||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||
| 39 | =item * bytes_per_second (default: 1048576) | ||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||
| 41 | Maximum incoming bytes per second (1MB default). | ||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||
| 43 | =item * burst_multiplier (default: 2) | ||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||
| 45 | Allow bursts up to N times the limit before enforcing. | ||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||
| 47 | =item * on_limit_exceeded (optional) | ||||||||||||||||||||||||
| 48 | |||||||||||||||||||||||||
| 49 | Callback when limit exceeded. Receives ($scope, $type, $current, $limit). | ||||||||||||||||||||||||
| 50 | Return true to close connection, false to just drop the message. | ||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||
| 52 | =item * close_code (default: 1008) | ||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||
| 54 | WebSocket close code when closing due to rate limit (Policy Violation). | ||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||
| 56 | =item * close_reason (default: 'Rate limit exceeded') | ||||||||||||||||||||||||
| 57 | |||||||||||||||||||||||||
| 58 | Close reason message. | ||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||
| 60 | =item * on_error (optional) | ||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||
| 62 | Callback invoked when a send operation fails. Receives C<($error, $event)> | ||||||||||||||||||||||||
| 63 | where C<$event> is the event hash that failed to send. Default behavior | ||||||||||||||||||||||||
| 64 | is to warn to STDERR. | ||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||
| 66 | on_error => sub { | ||||||||||||||||||||||||
| 67 | my ($error, $event) = @_; | ||||||||||||||||||||||||
| 68 | $logger->warn("RateLimit close send failed: $error"); | ||||||||||||||||||||||||
| 69 | } | ||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||
| 71 | =back | ||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||
| 73 | =cut | ||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||
| 75 | 6 | ▶ | sub _init { | ||||||||||||||||||||||
|
Subroutine
_init: called CC=7 SCAR=20.2
| |||||||||||||||||||||||||
| 76 | 6 | my ($self, $config) = @_; | |||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||
| 78 | 6 | ▶ | $self->{messages_per_second} = $config->{messages_per_second} // 100; | ||||||||||||||||||||||
|
Condition100%2/2
$config->{"messages_per_second"} // 100
MC/DC100%1/1
$config->{"messages_per_second"} // 100
$config->{"messages_per_second"}
Truth table100%2/2
A
A= $config->{"messages_per_second"}
| |||||||||||||||||||||||||
| 79 | 6 | ▶ | $self->{bytes_per_second} = $config->{bytes_per_second} // 1048576; | ||||||||||||||||||||||
|
Condition100%2/2
$config->{"bytes_per_second"} // 1048576
MC/DC100%1/1
$config->{"bytes_per_second"} // 1048576
$config->{"bytes_per_second"}
Truth table100%2/2
A
A= $config->{"bytes_per_second"}
| |||||||||||||||||||||||||
| 80 | 6 | ▶ | $self->{burst_multiplier} = $config->{burst_multiplier} // 2; | ||||||||||||||||||||||
|
Condition100%2/2
$config->{"burst_multiplier"} // 2
MC/DC100%1/1
$config->{"burst_multiplier"} // 2
$config->{"burst_multiplier"}
Truth table100%2/2
A
A= $config->{"burst_multiplier"}
| |||||||||||||||||||||||||
| 81 | 6 | $self->{on_limit_exceeded} = $config->{on_limit_exceeded}; | |||||||||||||||||||||||
| 82 | 6 | ▶ | $self->{close_code} = $config->{close_code} // 1008; | ||||||||||||||||||||||
|
Condition50%1/2
$config->{"close_code"} // 1008
MC/DC0%0/1
$config->{"close_code"} // 1008
$config->{"close_code"}
Truth table50%1/2
A
A= $config->{"close_code"}
| |||||||||||||||||||||||||
| 83 | 6 | ▶ | $self->{close_reason} = $config->{close_reason} // 'Rate limit exceeded'; | ||||||||||||||||||||||
|
Condition50%1/2
$config->{"close_reason"} // "Rate limit exceeded"
MC/DC0%0/1
$config->{"close_reason"} // "Rate limit exceeded"
$config->{"close_reason"}
Truth table50%1/2
A
A= $config->{"close_reason"}
| |||||||||||||||||||||||||
| 84 | 0 | ▶ | $self->{on_error} = $config->{on_error} // sub { | ||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||
| 85 | 0 | my ($error, $event) = @_; | |||||||||||||||||||||||
| 86 | 0 | warn "WebSocket::RateLimit send failed: $error\n"; | |||||||||||||||||||||||
| 87 | 6 | ▶ | }; | ||||||||||||||||||||||
|
Condition66%2/3
$config->{"on_error"} // sub {
my($error, $event) = @_;
warn "WebSocket::RateLimit send failed: $error\n";
}
MC/DC0%0/2
$config->{"on_error"} // sub {
my($error, $event) = @_;
warn "WebSocket::RateLimit send failed: $error\n";
}
$config->{"on_error"}
sub {
my($error, $event) = @_;
warn "WebSocket::RateLimit send failed: $error\n";
}
Truth table66%2/3
A // B
A= $config->{"on_error"}B= sub {
my($error, $event) = @_;
warn "WebSocket::RateLimit send failed: $error\n";
}
| |||||||||||||||||||||||||
| 88 | } | ||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||
| 90 | 4 | ▶ | sub wrap { | ||||||||||||||||||||||
|
Subroutine
wrap: called CC=1 SCAR=0.1
Pod
documented
| |||||||||||||||||||||||||
| 91 | 4 | my ($self, $app) = @_; | |||||||||||||||||||||||
| 92 | |||||||||||||||||||||||||
| 93 | 4 | ▶ | return async sub { | ||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=7.2
| |||||||||||||||||||||||||
| 94 | 4 | my ($scope, $receive, $send) = @_; | |||||||||||||||||||||||
| 95 | # Only apply to WebSocket connections | ||||||||||||||||||||||||
| 96 | 4 | ▶ | if ($scope->{type} ne 'websocket') { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 97 | 1 | await $app->($scope, $receive, $send); | |||||||||||||||||||||||
| 98 | 1 | return; | |||||||||||||||||||||||
| 99 | } | ||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||
| 101 | 3 | my $msg_limit = $self->{messages_per_second}; | |||||||||||||||||||||||
| 102 | 3 | my $byte_limit = $self->{bytes_per_second}; | |||||||||||||||||||||||
| 103 | 3 | my $burst = $self->{burst_multiplier}; | |||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||
| 105 | # Token bucket state | ||||||||||||||||||||||||
| 106 | 3 | my $msg_tokens = $msg_limit * $burst; | |||||||||||||||||||||||
| 107 | 3 | my $byte_tokens = $byte_limit * $burst; | |||||||||||||||||||||||
| 108 | 3 | my $last_update = time(); | |||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||
| 110 | 3 | my $closed = 0; | |||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||
| 112 | # Refill tokens based on elapsed time | ||||||||||||||||||||||||
| 113 | 5 | ▶ | my $refill_tokens = sub { | ||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||
| 114 | 5 | my $now = time(); | |||||||||||||||||||||||
| 115 | 5 | my $elapsed = $now - $last_update; | |||||||||||||||||||||||
| 116 | 5 | $last_update = $now; | |||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||
| 118 | 5 | $msg_tokens += $elapsed * $msg_limit; | |||||||||||||||||||||||
| 119 | 5 | ▶ | $msg_tokens = $msg_limit * $burst if $msg_tokens > $msg_limit * $burst; | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||
| 121 | 5 | $byte_tokens += $elapsed * $byte_limit; | |||||||||||||||||||||||
| 122 | 5 | ▶ | $byte_tokens = $byte_limit * $burst if $byte_tokens > $byte_limit * $burst; | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 123 | 3 | }; | |||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||
| 125 | # Wrap receive to apply rate limiting | ||||||||||||||||||||||||
| 126 | 5 | ▶ | my $wrapped_receive = async sub { | ||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=10 SCAR=27.2
| |||||||||||||||||||||||||
| 127 | 5 | ▶ | return { type => 'websocket.disconnect' } if $closed; | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||
| 129 | 5 | RECV: while (1) { | |||||||||||||||||||||||
| 130 | 6 | my $event = await $receive->(); | |||||||||||||||||||||||
| 131 | |||||||||||||||||||||||||
| 132 | 6 | ▶ | return $event if $closed; | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 133 | 6 | ▶ | return $event if $event->{type} ne 'websocket.receive'; | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 134 | |||||||||||||||||||||||||
| 135 | 5 | $refill_tokens->(); | |||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||
| 137 | # Calculate message size | ||||||||||||||||||||||||
| 138 | 5 | ▶ | my $data = $event->{text} // $event->{bytes} // ''; | ||||||||||||||||||||||
|
Condition40%2/5
($event->{"text"} // $event->{"bytes"}) // ""
$event->{"text"} // $event->{"bytes"}
MC/DC0%0/2
($event->{"text"} // $event->{"bytes"}) // ""
$event->{"text"}
$event->{"bytes"}
Truth table33%1/3
A // B
A= $event->{"text"}B= $event->{"bytes"}
| |||||||||||||||||||||||||
| 139 | 5 | my $size = length($data); | |||||||||||||||||||||||
| 140 | |||||||||||||||||||||||||
| 141 | # Check message rate | ||||||||||||||||||||||||
| 142 | 5 | ▶ | if ($msg_tokens < 1) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 143 | 1 | my $should_close = $self->_handle_limit_exceeded( | |||||||||||||||||||||||
| 144 | $scope, $send, 'messages', 0, $msg_limit | ||||||||||||||||||||||||
| 145 | ); | ||||||||||||||||||||||||
| 146 | 1 | ▶ | if ($should_close) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 147 | 0 | $closed = 1; | |||||||||||||||||||||||
| 148 | 0 | return { type => 'websocket.disconnect' }; | |||||||||||||||||||||||
| 149 | } | ||||||||||||||||||||||||
| 150 | # Drop message but continue | ||||||||||||||||||||||||
| 151 | 1 | next RECV; | |||||||||||||||||||||||
| 152 | } | ||||||||||||||||||||||||
| 153 | |||||||||||||||||||||||||
| 154 | # Check byte rate | ||||||||||||||||||||||||
| 155 | 4 | ▶ | if ($byte_tokens < $size) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 156 | 0 | my $should_close = $self->_handle_limit_exceeded( | |||||||||||||||||||||||
| 157 | $scope, $send, 'bytes', $byte_tokens, $byte_limit | ||||||||||||||||||||||||
| 158 | ); | ||||||||||||||||||||||||
| 159 | 0 | ▶ | if ($should_close) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 160 | 0 | $closed = 1; | |||||||||||||||||||||||
| 161 | 0 | return { type => 'websocket.disconnect' }; | |||||||||||||||||||||||
| 162 | } | ||||||||||||||||||||||||
| 163 | # Drop message but continue | ||||||||||||||||||||||||
| 164 | 0 | next RECV; | |||||||||||||||||||||||
| 165 | } | ||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||
| 167 | # Consume tokens | ||||||||||||||||||||||||
| 168 | 4 | $msg_tokens -= 1; | |||||||||||||||||||||||
| 169 | 4 | $byte_tokens -= $size; | |||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||
| 171 | 4 | return $event; | |||||||||||||||||||||||
| 172 | } | ||||||||||||||||||||||||
| 173 | 3 | }; | |||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||
| 175 | # Add rate limit info to scope | ||||||||||||||||||||||||
| 176 | 3 | my $new_scope = { | |||||||||||||||||||||||
| 177 | %$scope, | ||||||||||||||||||||||||
| 178 | 'pagi.websocket.rate_limit' => { | ||||||||||||||||||||||||
| 179 | messages_per_second => $msg_limit, | ||||||||||||||||||||||||
| 180 | bytes_per_second => $byte_limit, | ||||||||||||||||||||||||
| 181 | burst_multiplier => $burst, | ||||||||||||||||||||||||
| 182 | }, | ||||||||||||||||||||||||
| 183 | }; | ||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||
| 185 | 3 | await $app->($new_scope, $wrapped_receive, $send); | |||||||||||||||||||||||
| 186 | 4 | }; | |||||||||||||||||||||||
| 187 | } | ||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||
| 189 | 1 | ▶ | sub _handle_limit_exceeded { | ||||||||||||||||||||||
|
Subroutine
_handle_limit_exceeded: called CC=3 SCAR=13.6
| |||||||||||||||||||||||||
| 190 | 1 | my ($self, $scope, $send, $type, $current, $limit) = @_; | |||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||
| 192 | 1 | my $should_close = 1; # Default to closing | |||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||
| 194 | 1 | ▶ | if ($self->{on_limit_exceeded}) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 195 | 1 | $should_close = $self->{on_limit_exceeded}->($scope, $type, $current, $limit); | |||||||||||||||||||||||
| 196 | } | ||||||||||||||||||||||||
| 197 | |||||||||||||||||||||||||
| 198 | 1 | ▶ | if ($should_close) { | ||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||
| 199 | # Send close frame | ||||||||||||||||||||||||
| 200 | my $close_event = { | ||||||||||||||||||||||||
| 201 | type => 'websocket.close', | ||||||||||||||||||||||||
| 202 | code => $self->{close_code}, | ||||||||||||||||||||||||
| 203 | reason => $self->{close_reason}, | ||||||||||||||||||||||||
| 204 | 0 | }; | |||||||||||||||||||||||
| 205 | 0 | my $on_error = $self->{on_error}; | |||||||||||||||||||||||
| 206 | 0 | ▶ | $send->($close_event)->on_fail(sub { | ||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||
| 207 | 0 | my ($error) = @_; | |||||||||||||||||||||||
| 208 | 0 | $on_error->($error, $close_event); | |||||||||||||||||||||||
| 209 | 0 | })->retain; | |||||||||||||||||||||||
| 210 | } | ||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||
| 212 | 1 | return $should_close; | |||||||||||||||||||||||
| 213 | } | ||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||
| 215 | 3 | 1; | |||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||
| 217 | __END__ | ||||||||||||||||||||||||