static

README

Static

Static file server middleware for Hanzo Ingress (Traefik v3).

Serves static files, SPAs, directory listings, and custom error pages directly from the ingress layer — no backend required.

Features

• Static file serving from any directory
• SPA mode (fallback to index for client-side routing)
• Custom index files per directory
• Directory listing with sortable HTML output
• Custom 404 error pages
• Cache-Control headers by file extension
• Zero dependencies (pure Go stdlib)

Weight

~360 lines of Go. No external dependencies. Loaded via Yaegi interpreter at runtime — adds negligible overhead to ingress startup.

Configuration

Option	Type	Default	Description
root	String	.	Root directory to serve files from
enableDirectoryListing	Boolean	false	Enable directory browsing
indexFiles	Array	["index.html", "index.htm"]	Index filenames to try for directories
spaMode	Boolean	false	Redirect all 404s to SPA index
spaIndex	String	index.html	File to serve in SPA mode
errorPage404	String	""	Custom 404 page (relative to root)
cacheControl	Map	{}	File extension to Cache-Control value map

Usage

Embedded in Hanzo Ingress (local plugin)

Add to ingress static config:

experimental:
  localPlugins:
    static:
      moduleName: github.com/hanzoai/static

Place the plugin source in plugins-local/src/github.com/hanzoai/static/.

Then use in dynamic config:

http:
  routers:
    site:
      rule: Host(`example.com`)
      service: noop@internal
      middlewares:
        - static-files

  middlewares:
    static-files:
      plugin:
        static:
          root: /var/www/html

Remote plugin

experimental:
  plugins:
    static:
      moduleName: github.com/hanzoai/static
      version: v0.1.0

SPA mode (React/Vue/Angular)

http:
  middlewares:
    spa:
      plugin:
        static:
          root: /var/www/app
          spaMode: true
          spaIndex: index.html
          cacheControl:
            ".html": "no-cache"
            ".js": "max-age=31536000"
            ".css": "max-age=31536000"
            "*": "max-age=86400"

Development

make lint    # golangci-lint
make test    # go test -v -cover

License

Apache 2.0 — see LICENSE.

Copyright 2025-2026 Hanzo AI Inc. Based on hhftechnology/statiq (Apache 2.0).

Documentation

Overview

Package static provides a static file server middleware for Hanzo Ingress.

Index

• func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)
• type Config
  • func CreateConfig() *Config
• type Handler
  • func (h *Handler) GetTracingInformation() (string, string)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type S3Config
• type S3FS
  • func NewS3FS(_ context.Context, cfg S3Config) (*S3FS, error)
  • func (s *S3FS) Open(name string) (http.File, error)

Functions

func New

func New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

New creates a new static file server middleware.

Types

type Config

type Config struct {
	// Root directory to serve files from (local filesystem).
	Root string `json:"root,omitempty"`

	// S3 backend configuration (if set, takes precedence over Root).
	S3 *S3Config `json:"s3,omitempty"`

	// EnableDirectoryListing enables directory listing.
	EnableDirectoryListing bool `json:"enableDirectoryListing,omitempty"`

	// IndexFiles is a list of filenames to try when a directory is requested.
	IndexFiles []string `json:"indexFiles,omitempty"`

	// SPAMode redirects all not-found requests to a single page.
	SPAMode bool `json:"spaMode,omitempty"`

	// SPAIndex is the file to serve in SPA mode.
	SPAIndex string `json:"spaIndex,omitempty"`

	// ErrorPage404 is the path to a custom 404 error page.
	ErrorPage404 string `json:"errorPage404,omitempty"`

	// CacheControl sets cache control headers for static files.
	CacheControl map[string]string `json:"cacheControl,omitempty"`
}

Config holds the static file server middleware configuration.

func CreateConfig

func CreateConfig() *Config

CreateConfig creates the default plugin configuration.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler is a static file server handler.

func (*Handler) GetTracingInformation

func (h *Handler) GetTracingInformation() (string, string)

GetTracingInformation returns the middleware name and type for observability.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves HTTP requests with static files.

type S3Config

type S3Config struct {
	Endpoint  string `json:"endpoint,omitempty"`  // S3 endpoint (e.g. s3:9000)
	Bucket    string `json:"bucket,omitempty"`    // Bucket name
	Region    string `json:"region,omitempty"`    // Region (default us-east-1)
	AccessKey string `json:"accessKey,omitempty"` // Access key ID
	SecretKey string `json:"secretKey,omitempty"` // Secret access key
	Prefix    string `json:"prefix,omitempty"`    // Key prefix
	UseSSL    bool   `json:"useSSL,omitempty"`    // Use HTTPS
}

S3Config holds S3 backend configuration.

type S3FS

type S3FS struct {
	// contains filtered or unexported fields
}

S3FS implements http.FileSystem backed by S3-compatible s3.

func NewS3FS

func NewS3FS(_ context.Context, cfg S3Config) (*S3FS, error)

NewS3FS creates an http.FileSystem backed by S3-compatible s3.

func (*S3FS) Open

func (s *S3FS) Open(name string) (http.File, error)

Open implements http.FileSystem.