Documentation
¶
Overview ¶
Package server implements the application's HTTP server: middleware stack, route mounting, and graceful lifecycle management.
TLS ¶
By default this server speaks plain HTTP and assumes TLS is terminated upstream by a reverse proxy, load balancer, or ingress controller (the common posture for containerised/Kubernetes deployments). It does not redirect HTTP→HTTPS or set HSTS; that belongs to the terminating layer.
For standalone deployments where the Go process is itself internet-facing, enable in-process TLS termination with WithTLS (certificate + key paths). That negotiates a TLS 1.2 protocol floor by default; WithTLSConfig overrides the full *tls.Config for advanced setups (mutual TLS, a raised MinVersion, a pinned cipher-suite list). When TLS is enabled the server calls ListenAndServeTLS; otherwise it calls ListenAndServe.
Index ¶
- func WithCORSOrigins(origins []string) func(*Webserver)
- func WithFileServer(fs http.Handler) func(*Webserver)
- func WithHost(host string) func(*Webserver)
- func WithIdleTimeout(timeout time.Duration) func(*Webserver)
- func WithLogger(logger *zap.Logger) func(*Webserver)
- func WithMaxBodyBytes(maxBytes int64) func(*Webserver)
- func WithMaxHeaderBytes(maxBytes int) func(*Webserver)
- func WithPort(port int) func(*Webserver)
- func WithPprof(enabled bool) func(*Webserver)
- func WithReadHeaderTimeout(timeout time.Duration) func(*Webserver)
- func WithReadTimeout(timeout time.Duration) func(*Webserver)
- func WithRequestTimeout(timeout time.Duration) func(*Webserver)
- func WithShutdownTimeout(timeout time.Duration) func(*Webserver)
- func WithTLS(certFile, keyFile string) func(*Webserver)
- func WithTLSConfig(cfg *tls.Config) func(*Webserver)
- func WithWriteTimeout(timeout time.Duration) func(*Webserver)
- type ListRequest
- type ListResponse
- type OrderBy
- type Webserver
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithCORSOrigins ¶
WithCORSOrigins sets the origins permitted by the CORS middleware. Each entry may contain a "*" wildcard (e.g. "https://*.example.com"). An empty slice is ignored so the permissive default remains in place. Restrict this to your front-end origins before deploying to production.
func WithFileServer ¶
func WithIdleTimeout ¶
func WithLogger ¶
func WithMaxBodyBytes ¶
WithMaxBodyBytes caps the size of each request body the server will read, bounding the memory a single request can force the server to buffer. Unlike WithMaxHeaderBytes, a non-positive value disables the limit entirely (unbounded bodies), overriding the safe 10 MiB default rather than preserving it — 0 means "no limit", not "reject everything".
func WithMaxHeaderBytes ¶
WithMaxHeaderBytes caps the total size of request headers the server will read, bounding the memory a single request can force the server to buffer. A non-positive value is ignored so the safe 1 MiB default remains in place.
func WithPprof ¶
WithPprof toggles the /debug/pprof/* profiling endpoints. They are disabled by default because they expose process internals and are unauthenticated on the public mux; enable only in trusted environments or behind separate access controls.
func WithReadHeaderTimeout ¶
WithReadHeaderTimeout bounds how long the server waits for a client to send its request headers, mitigating Slowloris-style attacks. A non-positive timeout is ignored so the safe default remains in place.
func WithReadTimeout ¶
func WithRequestTimeout ¶
WithRequestTimeout bounds total request-processing time via chi's Timeout middleware, cancelling the request context once the deadline elapses so a slow handler or stalled client can't hold a connection indefinitely. A non-positive timeout disables the middleware entirely (unbounded processing), overriding the safe 60s default rather than preserving it.
func WithShutdownTimeout ¶
WithShutdownTimeout bounds how long a graceful shutdown waits for in-flight requests to drain before the server is forced closed, so a wedged handler can't hang the process on SIGTERM. A non-positive timeout is ignored so the safe 15s default remains in place.
func WithTLS ¶
WithTLS enables in-process TLS termination using the PEM-encoded certificate and key at the given paths. Use this only for standalone deployments where the Go process is internet-facing; when TLS is terminated upstream by a reverse proxy or load balancer (the default posture) leave it unset. Both paths must be non-empty for TLS to activate — if either is empty the option is a no-op and the server continues to serve plain HTTP. Unless a full tls.Config is supplied via WithTLSConfig, the server negotiates a TLS 1.2 protocol floor.
func WithTLSConfig ¶
WithTLSConfig sets the tls.Config used when TLS is enabled via WithTLS, overriding the default (a TLS 1.2 floor). Use it for advanced setups such as mutual TLS, a raised MinVersion, or a pinned cipher-suite list. A nil config is ignored so the safe default remains in place. This option only takes effect when WithTLS has also supplied certificate and key paths.
func WithWriteTimeout ¶
Types ¶
type ListRequest ¶
type ListRequest struct {
Page int `json:"-" qs:"page" validate:"required|int|min:1|" label:"page"`
Limit int `json:"-" qs:"limit" validate:"required|int|min:1|max:1000" label:"limit"`
SortBy string `json:"-" qs:"sort_by" label:"sort_by"`
OrderBy OrderBy `json:"-" qs:"order_by" validate:"int|in:0,1" label:"order_by"`
}
ListRequest defines options related to paging and ordering to be used when listing objects
type ListResponse ¶
type Webserver ¶
type Webserver struct {
// contains filtered or unexported fields
}
func (*Webserver) Run ¶
Run starts the HTTP server and blocks until ctx is cancelled or the server fails. On cancellation it performs a graceful shutdown, bounded by the configured shutdown timeout. It returns nil on a clean shutdown so it composes with an errgroup without treating an intentional stop as an error.
Source Files