NAME

PAGI::Middleware::Maintenance - Serve maintenance page when enabled

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'Maintenance',
        enabled => $ENV{MAINTENANCE_MODE},
        bypass_ips => ['10.0.0.0/8'],
        retry_after => 3600;
    $my_app;
};

DESCRIPTION

PAGI::Middleware::Maintenance serves a 503 Service Unavailable page when maintenance mode is enabled. Supports IP-based bypass for admins.

CONFIGURATION

• enabled (default: 0)

  Enable maintenance mode. Can be a coderef for dynamic checking.

• bypass_ips (default: [])

  Arrayref of IPs or CIDR ranges that bypass maintenance mode.

• bypass_paths (default: [])

  Arrayref of paths that bypass maintenance mode (e.g., health checks).

• retry_after (optional)

  Seconds until maintenance expected to end. Sets Retry-After header.

• content_type (default: 'text/html')

  Content-Type of the maintenance page.

• body (default: built-in HTML page)

  Custom maintenance page body.

DYNAMIC ENABLING

The enabled option can be a coderef for dynamic maintenance mode:

enable 'Maintenance',
    enabled => sub {
        return -e '/tmp/maintenance.flag';
    };

This allows enabling/disabling maintenance mode without restarting the server.

BYPASS EXAMPLES

enable 'Maintenance',
    enabled => 1,
    bypass_ips => [
        '127.0.0.1',      # localhost
        '10.0.0.0/8',     # internal network
    ],
    bypass_paths => [
        '/health',        # health checks
        qr{^/api/status}, # status API
    ];

SEE ALSO

PAGI::Middleware - Base class for middleware

PAGI::Middleware::Healthcheck - Health check endpoints