Static File Processor

Static file processor in a nutshell

The static file processor is highly efficient, as it can quickly serve files without the need for additional processing or interpretation. This makes it ideal for serving static content that does not require dynamic generation.

This is the most common and classic type of processor: static files (HTML, CSS, JavaScript, images, and other assets) are served directly from the filesystem.

The processor maps a specific URL path to a directory on the server, allowing clients to access files by requesting the corresponding URL. The directory is typically the web root or a subdirectory within it.

The default URL match is * (match all requests), because the processor only serves files that exist on the file system. If a file does not exist, the request is passed to the next processor in line.

You can make this more specific by using URL matching rules to only serve files from a specific path (for example, /static/*) or specific file types (for example, *.js).

If you are serving a static HTML site, you will normally want to configure an index file such as index.html to be served when a directory is requested.

Static file serving in short

• Serves static files directly from the file system
• Streaming support of large files for optimal performance
• Highly efficient and fast
• Supports URL path mapping to directories
• Can be customized with URL matching rules
• Commonly used for HTML, CSS, JavaScript, images, and other assets
• Uses file blacklisting to prevent some files from being downloaded

Configuration fields

The PHP Processor has these configuration fields in the admin portal:

Name

Name is just a label for the processor and can be set to anything you like and only uses for your reference in the admin portal.

URL Match Patterns

The static file processor will only handle requests that match the URL patterns you specify, and it will pass other requests to the next processor in line. Default is * (match all requests), but you can make this more specific by using URL matching rules to only proxy requests from one or more specific paths (for example, /static/*).

Web Root

The web root is the directory on your server where your static files are located. This is the root directory that Gruxi will use when serving static files. For example, if your static files are located in C:\my-static-files on Windows or /var/www/html/my-static-files on Linux, you would set the web root to that path.

Index Files

The index files are the default files that Gruxi will serve when a directory is requested. For example, if you set index.html as an index file, a request to /my-subdir/ will serve the index.html file in /my-subdir/index.html. You can specify multiple index files, and Gruxi will serve the first one it finds in the order they are listed.

Blacklisted file extensions and URL paths

Gruxi configuration contains a list of blocked file extensions that the static file processor will never allow to be downloaded. These can be edited by the user in the configuration and include a default set of extensions. Changes require a configuration reload to take effect. Requests that match blocked extensions return HTTP 404 Not Found. Examples include PHP files (.php) and configuration files (for example, .ini).

In addition to configurable blocked extensions, Gruxi employs a path normalizer that cleans up URLs that are deemed unsafe. This path normalizer prevents path traversal attempts (with .. in the URL) and blocks all dotfiles and dot-paths (for example, /.git or /.env). This is not configurable and is a core safety feature in Gruxi to mitigate attacks that rely on unusual paths.