NAME

PAGI::App::File - Serve static files

SYNOPSIS

use PAGI::App::File;

my $app = PAGI::App::File->new(
    root => '/var/www/static',
)->to_app;

DESCRIPTION

PAGI::App::File serves static files from a configured root directory.

Features

• Efficient streaming (no memory bloat for large files)

• ETag caching with If-None-Match support (304 Not Modified)

• Range requests (HTTP 206 Partial Content)

• Automatic MIME type detection for common file types

• Index file resolution (index.html, index.htm)

Security

This module implements multiple layers of path traversal protection:

• Null byte injection blocking

• Double-dot and triple-dot component blocking

• Backslash normalization (Windows path separator)

• Hidden file blocking (dotfiles like .htaccess, .env)

• Symlink escape detection via realpath verification

CONFIGURATION

• root - Root directory for files

• default_type - Default MIME type (default: application/octet-stream)

• index - Index file names (default: [index.html, index.htm])