StaticHandler class

A HandlerObject that serves static files from a directory or a single file.

When serving from a directory, files are served with appropriate headers including ETag, Last-Modified, and Cache-Control. The handler supports:

  • Conditional requests (If-None-Match, If-Modified-Since, If-Range (for range request))
  • Range requests for partial content (multi-range is supported, but ranges are not coalesced)
  • Proper MIME type detection (from magic-bytes prefixes, or file extension)

When serving a directory:

  • If the requested path doesn't correspond to a file, the defaultHandler is called.
  • If no defaultHandler is provided, a 404 Not Found response is returned.
  • Directory listings are not supported for security reasons.

The handler requires the request method to be either GET, or HEAD. Otherwise, a 405 Method Not Allowed response is returned with an appropriate Allow header.

The mimeResolver can be provided to customize MIME type detection. The cacheControl header can be customized using cacheControl callback.

If cacheBustingConfig is provided, the handler will strip cache-busting hashes from the URL path before looking up the file. See CacheBustingConfig for details.

Examples

  // Basic directory, 1 day cache
  StaticHandler.directory(
    Directory('static'),
    cacheControl: (_, __) => CacheControlHeader(maxAge: 86400),
  );

  // Long term/immutable + cache busting
  final staticDir = Directory('static');
  final buster = CacheBustingConfig(
    mountPrefix: '/static',
    fileSystemRoot: staticDir,
  );
  StaticHandler.directory(
    staticDir,
    cacheControl: (_, __) => CacheControlHeader(
      maxAge: 31536000,
      publicCache: true,
      immutable: true,
    ),
    cacheBustingConfig: buster,
  );

  // Single file, 1 day cache
  StaticHandler.file(
    File('assets/favicon.ico'),
    cacheControl: (_, __) => CacheControlHeader(maxAge: 86400),
  );

Security Features

The handler includes built-in security protections:

  • Path traversal protection: Prevents access to files outside the directory
  • Hidden file protection: Blocks access to files starting with .
  • Symbolic link handling: Safely resolves symlinks within the allowed directory

These protections are automatically applied and cannot be disabled.

Inheritance

Constructors

StaticHandler.directory(Directory directory, {Handler? defaultHandler, MimeTypeResolver? mimeResolver, required CacheControlFactory cacheControl, CacheBustingConfig? cacheBustingConfig})
Creates a StaticHandler for serving files from a Directory.
factory
StaticHandler.file(File file, {MimeTypeResolver? mimeResolver, required CacheControlFactory cacheControl})
Creates a StaticHandler for serving a single File.
factory

Properties

asHandler → Handler
Returns this HandlerObject as a Handler.
no setterinherited
cacheBustingConfig → CacheBustingConfig?
final
cacheControl → CacheControlFactory
final
defaultHandler → Handler?
final
entity → FileSystemEntity
final
hashCode → int
The hash code for this object.
no setterinherited
mimeResolver → MimeTypeResolver?
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

call(Request req) → FutureOr<Result>
The implementation of this HandlerObject
override
injectIn(RelicRouter router) → void
Adds this handler to the given router with Method.get and path '/' Override to add differently.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited