/ 
PAGI-0.001010
/ PAGI::Middleware::Static

NAME

PAGI::Middleware::Static - Static file serving middleware

SYNOPSIS

use PAGI::Middleware::Builder;

my $app = builder {
    enable 'Static',
        root        => '/var/www/static',
        path        => qr{^/static/},
        pass_through => 1;
    $my_app;
};

DESCRIPTION

PAGI::Middleware::Static serves static files from a specified directory. It includes path traversal protection, MIME type detection, ETag support for caching, and Range request support for partial content.

CONFIGURATION

  • root (required)

    The root directory to serve files from.

  • path (default: qr{^/})

    A regex or coderef to match request paths. Only matching paths are handled.

  • pass_through (default: 0)

    If true, pass requests to inner app when file not found instead of returning 404.

  • index (default: ['index.html', 'index.htm'])

    Array of index file names to try for directory requests.

  • encoding (default: undef)

    If set, look for pre-compressed files with this extension (e.g., 'gz' for .gz files).

  • handle_ranges (default: 1)

    When enabled (default), the middleware processes Range request headers and returns 206 Partial Content responses. Set to 0 to ignore Range headers and always return the full file.

    When to disable Range handling:

    When using PAGI::Middleware::XSendfile with a reverse proxy (Nginx, Apache), you should disable range handling. The proxy will handle Range requests more efficiently using its native sendfile implementation:

    my $app = builder {
    enable 'XSendfile',
        type    => 'X-Accel-Redirect',
        mapping => { '/var/www/files/' => '/protected/' };
    enable 'Static',
        root          => '/var/www/files',
        handle_ranges => 0;  # Let proxy handle Range requests
    $my_app;
};

SECURITY

This middleware includes path traversal protection to prevent access to files outside the configured root directory. Requests containing ".." sequences that would escape the root are rejected with 403 Forbidden.

CACHING

The middleware generates ETags based on file path, size, and modification time. Clients can use If-None-Match to receive 304 Not Modified responses when the file hasn't changed.

RANGE REQUESTS

The middleware supports HTTP Range requests for partial content, useful for resumable downloads and media streaming. Only single byte ranges are supported (not multi-range requests).

SEE ALSO

PAGI::Middleware - Base class for middleware