/ 
PAGI-0.001008
/ 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).

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