Documentation
¶
Overview ¶
Package server wraps Echo v4 with functional options, production-safe defaults, and graceful shutdown.
Index ¶
- Variables
- type GzipConfig
- type Option
- func WithDevMode(dev bool) Option
- func WithEmbeddedStatic(fsys fs.FS, pathPrefix string) Option
- func WithErrorHandler(h echo.HTTPErrorHandler) Option
- func WithGeneratedDir(dir string) Option
- func WithGzipConfig(cfg GzipConfig) Option
- func WithHost(host string) Option
- func WithMaxBodySize(size string) Option
- func WithMiddleware(mw ...echo.MiddlewareFunc) Option
- func WithPort(port int) Option
- func WithShutdownTimeout(d time.Duration) Option
- func WithStaticDir(path string) Option
- func WithStaticDistDir(path string) Option
- func WithTimeout(d time.Duration) Option
- func WithTrustedProxies(cidrs ...string) Option
- type Server
- func (s *Server) Addr() string
- func (s *Server) DELETE(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
- func (s *Server) Echo() *echo.Echo
- func (s *Server) GET(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
- func (s *Server) GenerateStatic(dir string) error
- func (s *Server) Group(prefix string, m ...echo.MiddlewareFunc) *echo.Group
- func (s *Server) PATCH(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
- func (s *Server) POST(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
- func (s *Server) PUT(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
- func (s *Server) Shutdown(ctx context.Context) error
- func (s *Server) Start() error
- func (s *Server) StaticPage(path string, handler echo.HandlerFunc)
Constants ¶
This section is empty.
Variables ¶
var CloudflareCIDRs = []string{
"173.245.48.0/20",
"103.21.244.0/22",
"103.22.200.0/22",
"103.31.4.0/22",
"141.101.64.0/18",
"108.162.192.0/18",
"190.93.240.0/20",
"188.114.96.0/20",
"197.234.240.0/22",
"198.41.128.0/17",
"162.158.0.0/15",
"104.16.0.0/13",
"104.24.0.0/14",
"172.64.0.0/13",
"131.0.72.0/22",
"2400:cb00::/32",
"2606:4700::/32",
"2803:f800::/32",
"2405:b500::/32",
"2405:8100::/32",
"2a06:98c0::/29",
"2c0f:f248::/32",
}
CloudflareCIDRs is Cloudflare's published edge IP list (IPv4 and IPv6), pinned at release. Pass it to WithTrustedProxies for a static list that is never refreshed, or use the "cloudflare" keyword to start from this list and refresh it every 24h.
Fetched 2026-09-16 from https://api.cloudflare.com/client/v4/ips.
Functions ¶
This section is empty.
Types ¶
type GzipConfig ¶
type GzipConfig struct {
// Enabled enables or disables gzip response compression.
Enabled bool
// Level is the gzip compression level. Zero uses Echo's default.
Level int
// MinLength is the minimum response size before compression is applied.
MinLength int
// Skipper skips gzip for matching requests.
Skipper echoMw.Skipper
}
GzipConfig configures gzip response compression.
type Option ¶
type Option func(*Server)
Option configures a Server.
func WithDevMode ¶
WithDevMode enables or disables development mode. In dev mode, security headers middleware is skipped.
func WithEmbeddedStatic ¶
WithEmbeddedStatic serves static files from an embed.FS at the given path prefix. The pathPrefix must not be empty.
func WithErrorHandler ¶
func WithErrorHandler(h echo.HTTPErrorHandler) Option
WithErrorHandler sets a custom Echo error handler.
func WithGeneratedDir ¶
WithGeneratedDir sets the directory for pre-rendered static pages. Routes registered via StaticPage serve files from this directory when available, falling back to the handler otherwise.
func WithGzipConfig ¶
func WithGzipConfig(cfg GzipConfig) Option
WithGzipConfig configures gzip response compression. Default: Gzip enabled with Echo defaults.
func WithMaxBodySize ¶
WithMaxBodySize sets the maximum request body size in Echo BodyLimit format (e.g. "2M", "500K"). Validated at construction time.
func WithMiddleware ¶
func WithMiddleware(mw ...echo.MiddlewareFunc) Option
WithMiddleware appends global middleware to the server.
func WithShutdownTimeout ¶
WithShutdownTimeout sets the graceful shutdown timeout (default 10s). Must be positive.
func WithStaticDir ¶
WithStaticDir serves static files from the given filesystem path at /static.
func WithStaticDistDir ¶
WithStaticDistDir sets a dist directory that takes priority over the static directory when serving files at /static. Files are looked up in distDir first; if not found, the request falls back to the regular static directory.
func WithTimeout ¶
WithTimeout sets the request context timeout. Must be positive.
func WithTrustedProxies ¶
WithTrustedProxies configures which upstream proxy CIDRs are trusted to set the X-Forwarded-For header, controlling how c.RealIP() (and therefore the default rate-limit key) derives the client IP.
- Default (this option unset / no CIDRs): the client IP is the direct TCP peer; X-Forwarded-For / X-Real-IP are IGNORED. This is the safe default — a client cannot spoof its IP to evade rate limiting.
- With one or more CIDRs: X-Forwarded-For is honored, but ONLY the configured ranges are trusted (loopback/link-local/private auto-trust is disabled), so the left-most untrusted hop is used as the client IP.
Set this to your load balancer / reverse-proxy ranges when running behind one.
The entry "cloudflare" expands to CloudflareCIDRs and makes Start refresh that list from Cloudflare every 24h (a failed or implausible fetch keeps the current list). Combine it with your own proxy's CIDR when stacking proxies. For a static list with no outbound fetch, pass CloudflareCIDRs instead. Empty or blank entries are ignored; non-empty entries must be valid CIDRs or New returns an error.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps an Echo instance with lifecycle management.
func New ¶
New creates a Server with sensible defaults, applies options, and configures production middleware. It returns an error if any option value is invalid.
func (*Server) DELETE ¶
func (s *Server) DELETE(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
DELETE registers a DELETE route.
func (*Server) GET ¶
func (s *Server) GET(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
GET registers a GET route.
func (*Server) GenerateStatic ¶
GenerateStatic renders all registered static pages to files in dir. Path mapping: "/" → dir/index.html, "/about" → dir/about/index.html. The output directory is wiped first so that stale files from previous runs (e.g. pages that were removed or renamed) do not linger.
func (*Server) PATCH ¶
func (s *Server) PATCH(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
PATCH registers a PATCH route.
func (*Server) POST ¶
func (s *Server) POST(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
POST registers a POST route.
func (*Server) PUT ¶
func (s *Server) PUT(path string, h echo.HandlerFunc, m ...echo.MiddlewareFunc) *echo.Route
PUT registers a PUT route.
func (*Server) Start ¶
Start begins listening and blocks until SIGINT/SIGTERM or a listener error. It performs graceful shutdown when a signal is received.
func (*Server) StaticPage ¶
func (s *Server) StaticPage(path string, handler echo.HandlerFunc)
StaticPage registers a handler for both build-time static generation and runtime serving. It stores the path+handler for GenerateStatic and registers a GET route that serves the pre-rendered file from the generated directory (if configured and the file exists), falling back to the handler otherwise.
Source Files