restx

package
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 6, 2026 License: MIT Imports: 28 Imported by: 0

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

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 Gunzip

func Gunzip() httpx.FilterFunc

Gunzip transparently decompresses gzip request bodies.

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(policies ...ratelimitx.Policy) httpx.FilterFunc

Shedding applies Kernel's public rate-limit provider contract as an HTTP self-protection filter.

func SheddingWithProvider added in v0.2.2

func SheddingWithProvider(policy ratelimitx.Policy, provider ratelimitx.Provider) httpx.FilterFunc

SheddingWithProvider applies a caller-supplied rate-limit provider. A nil provider uses the in-memory provider for local self-protection.

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.

func (*CSRFTokenManager) Generate

func (m *CSRFTokenManager) Generate(sessionID string, now time.Time) (string, error)

Generate creates a token for sessionID.

func (*CSRFTokenManager) Verify

func (m *CSRFTokenManager) Verify(sessionID, token string, now time.Time) bool

Verify reports whether token is valid for sessionID.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL