Config
Configuration is set via functional options passed to kruda.New().
Functional Options
WithReadTimeout
func WithReadTimeout(d time.Duration) OptionSets the maximum duration for reading the entire request. Default: 30s.
WithWriteTimeout
func WithWriteTimeout(d time.Duration) OptionSets the maximum duration for writing the response. Default: 30s.
WithIdleTimeout
func WithIdleTimeout(d time.Duration) OptionSets the maximum duration for idle keep-alive connections. Default: 120s.
WithBodyLimit
func WithBodyLimit(bytes int) OptionSets the maximum request body size in bytes. Default: 4194304 (4 MB). Bodies exceeding this limit receive HTTP 413.
WithMaxBodySize
func WithMaxBodySize(size int) OptionAlias for WithBodyLimit.
WithHeaderLimit
func WithHeaderLimit(limit int) OptionSets the maximum total request-header size in bytes (default 8 KB). Requests whose headers exceed this limit get HTTP 431. Raise it for clients that send large Authorization/Cookie headers (e.g. big JWTs); 0 disables the limit.
WithDevMode
func WithDevMode(enabled bool) OptionEnables development mode. When enabled:
- Rich HTML error pages are rendered instead of JSON
X-Frame-Optionsis relaxed toSAMEORIGIN
Default: false. Also auto-detected via KRUDA_ENV=development.
WithSecureHeaders
func WithSecureHeaders() OptionExplicitly enables default security headers. Use this to make security enablement explicit in your code.
Security headers are opt-in. Use WithSecureHeaders() to enable, or WithSecurity() to enable all security features.
WithLegacySecurityHeaders
func WithLegacySecurityHeaders() OptionRestores Phase 1-4 security header defaults for backward compatibility.
WithErrorHandler
func WithErrorHandler(h func(c *Ctx, err *KrudaError)) OptionSets a custom error handler. Receives *KrudaError (not error).
WithLogger
func WithLogger(l *slog.Logger) OptionSets a custom structured logger.
WithTransport
func WithTransport(t transport.Transport) OptionSets a custom transport implementation. With WithTLS, App.Listen requires the transport to implement transport.TLSServer; App.Serve continues to use the caller-supplied listener as-is.
FastHTTP
func FastHTTP() OptionSelects the fasthttp transport. On Linux the default is Wing (epoll+eventfd) which is faster — use FastHTTP() only if you need fasthttp compatibility. On macOS, fasthttp is already the default.
NetHTTP
func NetHTTP() OptionSelects the net/http transport for HTTP/2, TLS, and Windows compatibility.
WithTLS
func WithTLS(certFile, keyFile string) OptionEnables TLS with the given certificate and key files.
WithTrustProxy
func WithTrustProxy(trust bool) OptionWhen true, trusts X-Forwarded-For / X-Real-IP headers. Default: false.
WithShutdownTimeout
func WithShutdownTimeout(d time.Duration) OptionSets the graceful shutdown timeout. Default: 10s.
WithJSONEncoder / WithJSONDecoder
func WithJSONEncoder(enc func(v any) ([]byte, error)) Option
func WithJSONDecoder(dec func(data []byte, v any) error) OptionOverride the JSON encoder/decoder.
WithEnvPrefix
func WithEnvPrefix(prefix string) OptionLoads configuration from environment variables with the given prefix.
WithValidator
func WithValidator(v *Validator) OptionSets a custom validator for typed handler input validation.
WithoutValidation
func WithoutValidation() OptionTurns validation off, leaving validate tags inert: input is parsed and bound, and nothing is checked.
Validation became the default in v1.7.1. Before that it ran only when a Validator was configured, so an application written against an earlier version may carry validate tags it never actually enforced. This restores the old behaviour while those tags are reviewed.
WithContainer
func WithContainer(c *Container) OptionSets the DI container for the app.
WithOpenAPIInfo
func WithOpenAPIInfo(title, version, description string) OptionSets OpenAPI spec metadata.
WithOpenAPIPath
func WithOpenAPIPath(path string) OptionSets the path to serve the OpenAPI spec (default: /openapi.json).
WithOpenAPITag
func WithOpenAPITag(name, description string) OptionAdds an OpenAPI tag definition.
WithOpenAPISecurityScheme
func WithOpenAPISecurityScheme(name string, scheme OpenAPISecurityScheme) OptionAdds an OpenAPI security scheme under components.securitySchemes.
WithOpenAPIBearerAuth
func WithOpenAPIBearerAuth(name string) OptionAdds a standard HTTP bearer security scheme. An empty name defaults to bearerAuth.
Defaults Summary
| Option | Default |
|---|---|
| ReadTimeout | 30s |
| WriteTimeout | 30s |
| IdleTimeout | 120s |
| BodyLimit | 4 MB |
| ShutdownTimeout | 10s |
| DevMode | false |
| SecurityHeaders | false |
| TrustProxy | false |
| TransportName | "wing" (Linux), "fasthttp" (macOS), "nethttp" (Windows) |