Resource

Introduction

The Resource module publishes static files from a local directory over HTTP. Deploy multiple module instances when files must be served from different roots or HTTP contexts.

Configuration

Note

Module name: Resource

Properties

Name	Description	Default	Mandatory
http_context	Base HTTP context for the published files.	"/resources"
context_path	Route mounted below http_context.	"/"
webroot_dir	Local directory containing the files to publish.	""
overlay_dir	One overlay directory or an ordered array of overlay directories. Overlay files take precedence over files in webroot_dir.	[]
overlay_dirs	Compatibility name for additional overlay directories. Prefer overlay_dir.	[]
public	Allows requests without an authenticated session when enabled.	false
http_auth_redirect_url	Redirect target for unauthenticated requests when public is false.	""
enable_precompression	Serves matching pre-compressed files from webroot_dir.	false
enable_precompression_overlay	Serves matching pre-compressed files from overlay directories.	false
cache_control	Ordered cache policies. See Cache control.	Directory responses are not cached
use_cache	Enables the static handler cache.	true
files_read_only	Enables file metadata caching when files do not change while the service is running.	true
cache_entry_timeout_ms	Lifetime of cached file metadata in milliseconds.	30000
max_age_secs	Browser cache lifetime for static files in seconds.	86400

Example

{
  "name": "Resource",
  "enabled": true,
  "config": {
    "http_context": "/assets",
    "context_path": "/public",
    "webroot_dir": "htdocs/public",
    "overlay_dir": [
      "htdocs/branding"
    ],
    "public": true,
    "enable_precompression": true
  }
}

This example publishes files from htdocs/public at /assets/public. A matching file in htdocs/branding is served before the file in the web root.

Pre-compressed resources

When pre-compression is enabled and the request contains an Accept-Encoding header, the module looks for a matching compressed file before serving the original file.

Encoding	File extension
Brotli	.br
Gzip	.gz

Send X-Precompressed-Content: false to disable pre-compressed content for an individual request. A pre-compressed response includes these diagnostic headers:

X-Precompressed-Content: true
X-Precompressed-Path: <path-to-precompressed-file>
X-Precompressed-Encoding: <encoding>

Cache control

Without a cache_control object, directory and index responses receive Cache-Control: no-store, no-transform, max-age=0. Static files otherwise use the static handler cache settings.

Policies are evaluated in order and the first matching glob pattern wins:

{
  "cache_control": {
    "policies": [
      {
        "pattern": "**/*.html",
        "value": "no-store, no-transform, max-age=0",
        "override": true
      },
      {
        "pattern": "**",
        "value": "public, immutable, max-age=86400",
        "override": true
      }
    ]
  }
}

Set override to false when the policy should only add the header if no earlier handler has already set it.