static

package module
v6.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 25 Imported by: 0

README

Documentation

Overview

Package static provides an HTTP middleware that serves static files from a configured directory. It supports extension-based allow and forbid lists, ETag generation, and custom request and response headers. The middleware forwards a request that matches no static file to the next handler.

Index

Constants

View Source
const (
	PluginName     = "static"
	RootPluginName = "http"
)

PluginName is the default service name.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	// Dir is the name of the directory to control access to.
	// The default is ".".
	Dir string `mapstructure:"dir"`

	// CalculateEtag turns on etag calculation for static files.
	CalculateEtag bool `mapstructure:"calculate_etag"`

	// Weak turns the etag into a weak validator (`W/`).
	Weak bool `mapstructure:"weak"`

	// Forbid lists the file extensions the plugin does not serve.
	// For example: .php, .exe, .bat, .htaccess.
	Forbid []string `mapstructure:"forbid"`

	// Allow lists the file extensions the plugin serves.
	// For example: .php, .exe, .bat, .htaccess.
	Allow []string `mapstructure:"allow"`

	// Request lists the headers to add to each static request.
	Request map[string]string `mapstructure:"request"`

	// Response lists the headers to add to each static response.
	Response map[string]string `mapstructure:"response"`

	// Prefixes, when set, limit static serving to request paths that start with
	// one of these prefixes. The match uses raw strings.HasPrefix semantics.
	Prefixes []string `mapstructure:"prefixes"`

	// CacheTTL is the positive metadata cache TTL. A nil value means the 10s
	// default. An explicit 0 turns the positive cache off.
	CacheTTL *time.Duration `mapstructure:"cache_ttl"`

	// CacheMissTTL is the miss cache TTL. A nil value means the 10s default. An
	// explicit 0 turns the miss cache off.
	CacheMissTTL *time.Duration `mapstructure:"cache_miss_ttl"`

	// CacheMaxEntries caps each cache map. A 0 value means the 16384 default.
	CacheMaxEntries int `mapstructure:"cache_max_entries"`
	// contains filtered or unexported fields
}

Config describes the file location and controls access to the files.

func (*Config) Valid

func (c *Config) Valid() error

Valid returns nil when the config is valid.

type Configurer

type Configurer interface {
	UnmarshalKey(name string, out any) error
	Has(name string) bool
}

type Logger

type Logger interface {
	NamedLogger(name string) *slog.Logger
}

type Plugin

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

Plugin serves static files.

func (*Plugin) Init

func (s *Plugin) Init(cfg Configurer, log Logger) error

Init sets up the plugin from its config. It returns a Disabled error when the config is absent, and another error when the config is invalid. The plugin must not run without a valid config.

func (*Plugin) Middleware

func (s *Plugin) Middleware(next http.Handler) http.Handler

Middleware returns a handler that serves static files. It forwards every other request to the next handler.

func (*Plugin) Name

func (s *Plugin) Name() string

func (*Plugin) Reset

func (s *Plugin) Reset() error

Reset clears the metadata cache. The resetter plugin calls it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL