Documentation
¶
Overview ¶
Package restx contains go-zero-inspired HTTP runtime helpers for Kernel.
restx deliberately does not replace transportx/http. It builds a standard HTTP filter chain and server options on top of the existing transport so that Kernel services get a consistent startup path: recover, max bytes, gunzip, CORS/security headers, max-connections, breaker and adaptive shedding.
Index ¶
- func AccessLog(logger logx.Logger) httpx.FilterFunc
- func Breaker() httpx.FilterFunc
- func CORS(conf CORSConfig) httpx.FilterFunc
- func CSRF(conf CSRFConfig) httpx.FilterFunc
- func Filters(conf MiddlewaresConf) []httpx.FilterFunc
- func Gunzip() httpx.FilterFunc
- func InstallProtovalidateRequestValidator(v protovalidate.Validator)
- func MaxBytes(limit int64) httpx.FilterFunc
- func MaxConns(limit int) httpx.FilterFunc
- func Metrics(manager metricsx.Manager) httpx.FilterFunc
- func Recover() httpx.FilterFunc
- func RequestContext(conf RequestContextConfig) httpx.FilterFunc
- func RuntimeFilters(rt Runtime) []httpx.FilterFunc
- func SanitizeHeaders() httpx.FilterFunc
- func SecurityHeaders() httpx.FilterFunc
- func ServerOptions(conf Conf, extra ...httpx.FilterFunc) []httpx.ServerOption
- func Shedding(opts ...internalratelimit.Option) httpx.FilterFunc
- func Timeout(timeout time.Duration) httpx.FilterFunc
- func Trace(operation string) httpx.FilterFunc
- type CORSConfig
- type CSRFConfig
- type CSRFTokenManager
- type Conf
- type MiddlewaresConf
- type RequestContextConfig
- type Runtime
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AccessLog ¶
func AccessLog(logger logx.Logger) httpx.FilterFunc
AccessLog records one structured log line per request using the request-bound contextx logger when available.
func Breaker ¶
func Breaker() httpx.FilterFunc
Breaker rejects requests when the route-level circuit breaker is open.
func CORS ¶
func CORS(conf CORSConfig) httpx.FilterFunc
CORS handles simple and preflight CORS requests.
func CSRF ¶
func CSRF(conf CSRFConfig) httpx.FilterFunc
CSRF validates unsafe methods using a token bound to a session cookie. It is designed for browser Gateway/BFF endpoints that use HttpOnly cookie sessions.
func Filters ¶
func Filters(conf MiddlewaresConf) []httpx.FilterFunc
Filters builds the Kernel HTTP filter chain in go-zero order where the concepts overlap.
func InstallProtovalidateRequestValidator ¶
func InstallProtovalidateRequestValidator(v protovalidate.Validator)
InstallProtovalidateRequestValidator installs a process-wide validator used by protoc-gen-go-http generated handlers. It validates decoded protobuf request messages after HTTP binding and before business middleware runs.
func MaxBytes ¶
func MaxBytes(limit int64) httpx.FilterFunc
MaxBytes caps request body size before JSON/form decoders read it.
func MaxConns ¶
func MaxConns(limit int) httpx.FilterFunc
MaxConns bounds concurrent in-flight HTTP requests.
func Metrics ¶
func Metrics(manager metricsx.Manager) httpx.FilterFunc
Metrics records low-cardinality HTTP request metrics through metricsx. The instruments are lazily registered once; projects can also register them during startup for stricter control.
func Recover ¶
func Recover() httpx.FilterFunc
Recover converts panics into a 500 response and logs the stack. It is the HTTP-filter counterpart of middleware/recovery for raw HTTP/BFF handlers.
func RequestContext ¶
func RequestContext(conf RequestContextConfig) httpx.FilterFunc
RequestContext injects request_id, trace_id, logx logger, metrics manager and optional ServiceContext into contextx. It is intentionally protocol-agnostic so generated Gateway/BFF logic can depend on contextx only.
func RuntimeFilters ¶
func RuntimeFilters(rt Runtime) []httpx.FilterFunc
RuntimeFilters builds the Kernel HTTP filter chain in go-zero order and also injects request-scoped contextx/logx/metricsx values when configured.
func SanitizeHeaders ¶
func SanitizeHeaders() httpx.FilterFunc
SanitizeHeaders rejects requests with CR/LF in header values. net/http protects response splitting in normal writes, but this early check gives Gateway/BFF code a single place to fail closed before proxying upstream.
func SecurityHeaders ¶
func SecurityHeaders() httpx.FilterFunc
SecurityHeaders adds conservative browser-facing security headers.
func ServerOptions ¶
func ServerOptions(conf Conf, extra ...httpx.FilterFunc) []httpx.ServerOption
ServerOptions converts Conf to existing transportx/http options. Extra filters are appended after the standard chain and before the router.
func Shedding ¶
func Shedding(opts ...internalratelimit.Option) httpx.FilterFunc
Shedding applies Kernel's adaptive BBR limiter as an HTTP filter.
func Timeout ¶
func Timeout(timeout time.Duration) httpx.FilterFunc
Timeout attaches a request context timeout. Handlers should respect r.Context().Done(); this filter avoids transport replacement and stays compatible with transportx/http's own timeout option.
func Trace ¶
func Trace(operation string) httpx.FilterFunc
Trace starts an OpenTelemetry span for HTTP requests and extracts incoming W3C trace context through otelhttp. It also makes the active trace id visible to downstream RequestContext.
Types ¶
type CORSConfig ¶
type CORSConfig struct {
AllowedOrigins []string
AllowedMethods []string
AllowedHeaders []string
ExposedHeaders []string
AllowCredentials bool
MaxAge time.Duration
}
CORSConfig configures the CORS filter.
type CSRFConfig ¶
type CSRFConfig struct {
Secret []byte
Header string
Cookie string
SessionCookie string
SkipPaths []string
MaxAge time.Duration
}
CSRFConfig configures the double-submit/HMAC CSRF filter.
type CSRFTokenManager ¶
type CSRFTokenManager struct {
// contains filtered or unexported fields
}
CSRFTokenManager signs and verifies stateless CSRF tokens bound to a session id. It is intentionally small so Gateway/BFF code can use it before a Redis backed session store exists.
func NewCSRFTokenManager ¶
func NewCSRFTokenManager(secret []byte, maxAge time.Duration) *CSRFTokenManager
NewCSRFTokenManager creates a token manager. secret must be non-empty in production. maxAge <= 0 disables token age checks.
type Conf ¶
type Conf struct {
Network string
Address string
Timeout time.Duration
// ServiceName is used by tracing, metrics and access logs.
ServiceName string
// Logger is injected into request contexts and used by the standard log filter.
Logger logx.Logger
// Metrics is injected into request contexts and used by the standard metrics filter.
Metrics metricsx.Manager
// ServiceContext is optionally injected into request contexts for generated
// Gateway/BFF logic that follows the go-zero ServiceContext pattern.
ServiceContext *servicecontextx.Context
Middlewares MiddlewaresConf
}
Conf is the high-level REST server configuration used by new Kernel services.
type MiddlewaresConf ¶
type MiddlewaresConf struct {
Trace bool // reserved for tracingx/otel integration
Log bool // transportx/http already owns access logs; kept for config compatibility
Prometheus bool // transport metrics are enabled via transportx/http.Metrics
MaxConns bool
Breaker bool
Shedding bool
Timeout bool
Recover bool
Metrics bool // reserved for app-level metrics filters
MaxBytes bool
Gunzip bool
CORS bool
CSRF bool
SecurityHeaders bool
SanitizeHeaders bool
MaxConnsLimit int
MaxBytesLimit int64
TimeoutValue time.Duration
CORSConfig CORSConfig
CSRFConfig CSRFConfig
}
MiddlewaresConf mirrors the useful part of go-zero's RestConf.Middlewares, adapted to Kernel's transportx/http FilterFunc chain.
func DefaultMiddlewares ¶
func DefaultMiddlewares() MiddlewaresConf
DefaultMiddlewares returns a conservative production-friendly chain. It keeps authn/authz out of the generic chain; services add those explicitly.
type RequestContextConfig ¶
type RequestContextConfig struct {
Logger logx.Logger
Metrics metricsx.Manager
ServiceContext *servicecontextx.Context
RequestIDHeader string
TraceIDHeader string
}
RequestContextConfig configures request-scoped value injection.
type Runtime ¶
type Runtime struct {
ServiceName string
Logger logx.Logger
Metrics metricsx.Manager
ServiceContext *servicecontextx.Context
Middlewares MiddlewaresConf
}
Runtime carries non-serializable runtime dependencies for the standard chain.