NAME

PAGI::Middleware::WebSocket::RateLimit - Rate limiting for WebSocket connections

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'WebSocket::RateLimit',
        messages_per_second => 10,
        bytes_per_second    => 65536,
        burst_multiplier    => 2;
    $my_app;
};

DESCRIPTION

PAGI::Middleware::WebSocket::RateLimit enforces rate limits on incoming WebSocket messages. Connections exceeding limits can be throttled or closed.

CONFIGURATION

• messages_per_second (default: 100)

  Maximum incoming messages per second.

• bytes_per_second (default: 1048576)

  Maximum incoming bytes per second (1MB default).

• burst_multiplier (default: 2)

  Allow bursts up to N times the limit before enforcing.

• on_limit_exceeded (optional)

  Callback when limit exceeded. Receives ($scope, $type, $current, $limit). Return true to close connection, false to just drop the message.

• close_code (default: 1008)

  WebSocket close code when closing due to rate limit (Policy Violation).

• close_reason (default: 'Rate limit exceeded')

  Close reason message.

ALGORITHM

This middleware uses a token bucket algorithm:

• Each connection has message and byte token buckets

• Tokens refill at the configured rate

• Burst capacity allows temporary spikes

• When tokens depleted, messages are dropped or connection closed

SCOPE EXTENSIONS

• pagi.websocket.rate_limit

  Hashref containing rate limit configuration.

CALLBACK EXAMPLE

enable 'WebSocket::RateLimit',
    messages_per_second => 10,
    on_limit_exceeded => sub  {
    my ($scope, $type, $current, $limit) = @_;
        warn "Rate limit exceeded for $scope->{client}[0]: $type\n";
        return 1;  # Close connection
    };

SEE ALSO

PAGI::Middleware - Base class for middleware

PAGI::Middleware::RateLimit - HTTP rate limiting

PAGI::Middleware::WebSocket::Heartbeat - WebSocket keepalive