net

Documentation

Overview

Package net provides the Go-native HTTP server with TLS, multi-site routing, and all production middleware (security headers, CORS, rate limiting, CSRF).

Index

• func CORSMiddleware(allowedOrigins []string) gin.HandlerFunc
• func RegisterPathSiteRoutes(router *gin.Engine, sr *SiteRouter, spaFS fs.FS)
• func RequestIDMiddleware() gin.HandlerFunc
• func SecurityHeadersMiddleware(tlsEnabled bool) gin.HandlerFunc
• func SetSecureCookie(c *gin.Context, name, value string, maxAge int, path string, httpOnly bool)
• type LoadedSite
• type RateLimiter
  • func NewRateLimiter(rps float64, burst int) *RateLimiter
  • func (rl *RateLimiter) Middleware() gin.HandlerFunc
• type Server
  • func NewServer(handler http.Handler, addr string, cfg *TLSConfig) *Server
  • func (s *Server) ListenAndServe() error
• type SiteRouter
  • func NewSiteRouter(sites []*LoadedSite) *SiteRouter
  • func (sr *SiteRouter) AddSite(s *LoadedSite)
  • func (sr *SiteRouter) AllDomains() []string
  • func (sr *SiteRouter) AllSites() []*LoadedSite
  • func (sr *SiteRouter) Middleware() gin.HandlerFunc
  • func (sr *SiteRouter) RemoveSite(name string) *LoadedSite
  • func (sr *SiteRouter) SiteByName(name string) *LoadedSite
• type SiteRouterConfig
• type TLSConfig

Functions

func CORSMiddleware

func CORSMiddleware(allowedOrigins []string) gin.HandlerFunc

CORSMiddleware configures cross-origin access. When allowedOrigins is empty (dev mode), origins are reflected from the request. This is safe with credentials because the origin is reflected, not wildcarded. In production, always pass explicit allowed origins.

func RegisterPathSiteRoutes

func RegisterPathSiteRoutes(router *gin.Engine, sr *SiteRouter, spaFS fs.FS)

RegisterPathSiteRoutes adds a NoRoute handler that intercepts /s/:site/* requests, injects site context, rewrites the path, and serves directly. This allows multi-site access without DNS or /etc/hosts.

localhost:8000/s/airtime/workspace → airtime site
localhost:8000/s/fieldwork/api/...  → fieldwork site

func RequestIDMiddleware

func RequestIDMiddleware() gin.HandlerFunc

RequestIDMiddleware ensures every request has a traceable ID.

func SecurityHeadersMiddleware

func SecurityHeadersMiddleware(tlsEnabled bool) gin.HandlerFunc

SecurityHeadersMiddleware sets production security headers via gin-contrib/secure.

func SetSecureCookie

func SetSecureCookie(c *gin.Context, name, value string, maxAge int, path string, httpOnly bool)

SetSecureCookie sets a cookie with Secure auto-detected from the request's TLS state and appends SameSite=Lax. Use this instead of c.SetCookie for security-sensitive cookies.

Types

type LoadedSite

type LoadedSite struct {
	Name     string
	Config   SiteRouterConfig
	DB       *sql.DB
	Registry *doctype.Registry
}

LoadedSite holds the runtime state for a single site.

type RateLimiter

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

RateLimiter implements per-user token bucket rate limiting.

func NewRateLimiter

func NewRateLimiter(rps float64, burst int) *RateLimiter

NewRateLimiter creates a rate limiter. rps: requests per second allowed per user. burst: max burst size.

func (*RateLimiter) Middleware

func (rl *RateLimiter) Middleware() gin.HandlerFunc

Middleware returns a Gin middleware that rate-limits requests per user.

type Server

type Server struct {
	*http.Server
	// contains filtered or unexported fields
}

Server wraps an http.Server with TLS and lifecycle management.

func NewServer

func NewServer(handler http.Handler, addr string, cfg *TLSConfig) *Server

NewServer creates a production-ready HTTP server.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the server with TLS (if configured) or plain HTTP.

type SiteRouter

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

SiteRouter maps Host headers to loaded sites.

func NewSiteRouter

func NewSiteRouter(sites []*LoadedSite) *SiteRouter

NewSiteRouter creates a site router from loaded sites.

func (*SiteRouter) AddSite

func (sr *SiteRouter) AddSite(s *LoadedSite)

AddSite hot-adds a site to the running router without a restart. Used by the console when creating a new site via API.

func (*SiteRouter) AllDomains

func (sr *SiteRouter) AllDomains() []string

AllDomains returns every domain across all sites (for autocert).

func (*SiteRouter) AllSites

func (sr *SiteRouter) AllSites() []*LoadedSite

AllSites returns all loaded sites (for console, path-based routing, etc.).

func (*SiteRouter) Middleware

func (sr *SiteRouter) Middleware() gin.HandlerFunc

Middleware returns a Gin middleware that resolves the Host header to a site.

func (*SiteRouter) RemoveSite

func (sr *SiteRouter) RemoveSite(name string) *LoadedSite

RemoveSite removes a site from the router by name. Returns the removed site or nil if not found. Updates the default site if the removed site was the default.

func (*SiteRouter) SiteByName

func (sr *SiteRouter) SiteByName(name string) *LoadedSite

SiteByName returns a site by its name or short name. E.g., both "airtime.local" and "airtime" match the airtime site.

type SiteRouterConfig

type SiteRouterConfig struct {
	Hostname string
	Domains  []string
}

SiteRouterConfig is the minimal config needed for routing.

type TLSConfig

type TLSConfig struct {
	Mode    string   // "auto" (Let's Encrypt), "manual" (cert files), "off" (HTTP only)
	Domains []string // All domains across all sites (for autocert whitelist)
	Email   string   // Contact email for Let's Encrypt
	CertDir string   // Directory to cache certs (default: "certs")
}

TLSConfig controls TLS behavior.