Documentation
¶
Overview ¶
Package middleware defines nexus's cross-transport middleware model.
Two shapes coexist here:
Info — the static descriptor the registry stores and the dashboard renders. Just metadata: name, kind (builtin/custom), description. Every resolver / route that uses a middleware contributes its name to the endpoint's Middleware list; Info tells the dashboard how to label each entry.
Middleware — an executable BUNDLE. Carries one realization per transport (HTTP for REST + WS upgrades, Graph for GraphQL field resolution). Factories like ratelimit.NewMiddleware produce one, and nexus.Use(mw) accepts it on any registration regardless of transport. Transports pick the field they can honor and ignore the rest.
Keeping these side-by-side means dashboard readers get a uniform view (name + kind + description) while implementers get a uniform API (write once, use everywhere).
Index ¶
- Variables
- func ClientIPFromCtx(ctx context.Context) string
- func WithClientIP(ctx context.Context, ip string) context.Context
- type Func
- type Handler
- type Info
- type Kind
- type Middleware
- type Next
- type Rejection
- type RequestCtx
- func (rc *RequestCtx) ClientIP() string
- func (rc *RequestCtx) Get(key any) (any, bool)
- func (rc *RequestCtx) Header(key string) string
- func (rc *RequestCtx) Path() string
- func (rc *RequestCtx) Reject(status int, err error) error
- func (rc *RequestCtx) RejectJSON(status int, body any) error
- func (rc *RequestCtx) Set(key, val any)
- func (rc *RequestCtx) SetHeader(key, val string)
- func (rc *RequestCtx) WithContext(ctx context.Context)
- type Stage
- type Transport
- type TransportSet
Constants ¶
This section is empty.
Variables ¶
var AllTransports = Transports(TransportREST, TransportGraphQL, TransportWebSocket)
AllTransports is the common declaration for write-once middleware.
var Builtins = []Info{ {Name: "auth", Kind: KindBuiltin, Description: "Bearer token / session validation"}, {Name: "cors", Kind: KindBuiltin, Description: "CORS preflight + header policy"}, {Name: "rate-limit", Kind: KindBuiltin, Description: "Request rate limiting"}, {Name: "request-id", Kind: KindBuiltin, Description: "Attach X-Request-ID per request"}, {Name: "logger", Kind: KindBuiltin, Description: "Structured request logger"}, {Name: "recovery", Kind: KindBuiltin, Description: "Panic recovery"}, {Name: "permission", Kind: KindBuiltin, Description: "RBAC permission check"}, {Name: "csrf", Kind: KindBuiltin, Description: "CSRF token validation"}, {Name: "compression", Kind: KindBuiltin, Description: "Response compression"}, }
Builtins are well-known names nexus pre-registers. When your code attaches a middleware with one of these names, the dashboard labels it "builtin"; any other name falls back to "custom".
var ErrorBody = func(status int, err error) (int, any) { if status == 0 { status = http.StatusInternalServerError } return status, httpx.H{"message": err.Error()} }
ErrorBody renders a rejection on REST/WS: the response status and JSON body for err, given the status the middleware asked for. The nexus package installs its error model here, so a middleware's rejection reads like any other failed request ({"code", "message", "errors"}); the default is {"message": …}. A status of 0 asks for the error's own.
Functions ¶
func ClientIPFromCtx ¶
ClientIPFromCtx returns the IP a transport stashed via WithClientIP, or empty when absent.
Types ¶
type Func ¶
type Func struct {
// contains filtered or unexported fields
}
Func is the closure adapter — most middleware is one of these.
func NewFunc ¶
func NewFunc(name string, set TransportSet, fn func(rc *RequestCtx, next Next) error) Func
NewFunc builds a Func Handler.
func (Func) Transports ¶
func (f Func) Transports() TransportSet
type Handler ¶
type Handler interface {
Name() string
Transports() TransportSet
Handle(rc *RequestCtx, next Next) error
}
Handler is the unified middleware shape (see docs/design/middleware-redesign.md §3). Transitional name — it becomes Middleware in step 5, once the current Middleware struct is renamed to Bundle. A single implementation serves every transport it declares in Transports().
func AsHandler ¶
func AsHandler(mw Middleware) Handler
AsHandler wraps a legacy bundle as a Handler so existing nexus.Use(...) bundles flow through the new pipeline and participate in fail-closed (step 3).
type Info ¶
type Info struct {
Name string `json:"name"`
Kind Kind `json:"kind"`
Description string `json:"description,omitempty"`
// Stage is set for app-wide middleware (nexus.Middleware): where in
// the pipeline it runs.
Stage string `json:"stage,omitempty"`
}
Info is the registry entry shown in the dashboard — pure metadata, no execution. Every Middleware bundle carries an Info so its name is self-describing when attached.
type Middleware ¶
type Middleware struct {
Name string
Description string
Kind Kind // defaults to KindCustom when unset by factories
HTTP httpx.HandlerFunc // REST + WS upgrade path
Graph gql.Middleware // GraphQL field resolution
// Stage places an app-wide middleware (nexus.Middleware) in the
// request pipeline; per-endpoint bundles ignore it. Zero is App.
Stage Stage
// Requires is declarative metadata: the permission codenames this
// bundle enforces (set by auth.Requires). The framework stamps them
// onto the endpoint's registry entry (registry.AuthRequiresTag) so
// gate evaluation (auth.OpGates) reads the SAME declaration the
// enforcing middleware closed over — one source, no drift. Purely
// metadata; attaching a bundle with Requires set enforces nothing
// by itself.
Requires []string
// Tags are declarative registry tags the framework stamps onto every
// endpoint the bundle is attached to; a tag a second bundle stamps again
// joins with ";". auth.RequiresAny and auth.Kind record their gates this
// way. Purely metadata, like Requires.
Tags map[string]string
}
Middleware is an executable bundle with per-transport realizations. A single definition serves REST (HTTP), GraphQL (Graph), and WebSocket (WS — runs at upgrade time; per-frame hooks are out of scope for v1). Leave a field nil when the middleware doesn't make sense for that transport (e.g. graphql-specific auth might only set Graph).
The Info() companion returns the metadata the registry stores — factories pre-populate it so dashboard listings "just work" without users touching the static side.
func FromHandler ¶
func FromHandler(h Handler) Middleware
FromHandler turns one unified Handler into a transport bundle, generating exactly the realizations the Handler declares it can serve (redesign §3–4). A Handler that declares AllTransports gets both an HTTP and a Graph realization from a SINGLE implementation — this is what lets the built-ins (auth, ratelimit, …) drop their duplicated HTTP/Graph pairs.
The returned bundle's Name/Kind come from the Handler; callers may set Description (and override Kind) on the value before attaching:
mw := middleware.FromHandler(h) mw.Description = "30 rpm, per-IP" mw.Kind = middleware.KindBuiltin
The current execution path is unchanged: REST/WS still run mw.HTTP in the gin chain, GraphQL still wraps mw.Graph around the resolver. FromHandler is the authoring layer; the carriers below bridge each transport into the neutral RequestCtx the Handler sees.
func (Middleware) AsInfo ¶
func (m Middleware) AsInfo() Info
AsInfo returns the registry-side metadata for this bundle, defaulting the kind to Custom when a factory didn't supply one.
type Next ¶
type Next func(*RequestCtx) error
Next advances the chain. Returning an error (or calling rc.Reject) short-circuits; the active carrier translates the outcome per transport.
type Rejection ¶
Rejection is the error a middleware's Reject returns on GraphQL: the error, and the HTTP status it would have answered with on REST.
type RequestCtx ¶
type RequestCtx struct {
Context context.Context
Transport Transport
// contains filtered or unexported fields
}
RequestCtx is the transport-neutral request handle middleware sees (§3.2). Middleware never touches httpx.Ctx or gql.Field — those are carrier internals.
func (*RequestCtx) ClientIP ¶
func (rc *RequestCtx) ClientIP() string
ClientIP returns the request's client IP via a single shared implementation.
func (*RequestCtx) Get ¶
func (rc *RequestCtx) Get(key any) (any, bool)
Get reads a value stashed by Set.
func (*RequestCtx) Header ¶
func (rc *RequestCtx) Header(key string) string
Header returns the named request header, transport-backed.
func (*RequestCtx) Path ¶
func (rc *RequestCtx) Path() string
Path returns the REST route or GraphQL field path.
func (*RequestCtx) Reject ¶
func (rc *RequestCtx) Reject(status int, err error) error
Reject short-circuits the chain. Returns the error so callers can write `return rc.Reject(401, ErrUnauthenticated)`; the carrier renders the transport-appropriate response (the ErrorBody rendering on REST/WS, the error surfaced on GraphQL).
func (*RequestCtx) RejectJSON ¶
func (rc *RequestCtx) RejectJSON(status int, body any) error
RejectJSON short-circuits the chain with a CUSTOM response body on REST/WS, rendered as JSON with the given status — the neutral way for an extension to emit its own error envelope without importing gin. GraphQL has no per-field response body, so there RejectJSON only short-circuits (a GraphQL-facing ErrorHandler should branch on rc.Transport and return a wrapped error instead). Returns a non-nil error so callers can write `return rc.RejectJSON(401, MyEnvelope{...})` uniformly.
func (*RequestCtx) Set ¶
func (rc *RequestCtx) Set(key, val any)
Set shares a typed value across the chain without internal-package coupling.
func (*RequestCtx) SetHeader ¶
func (rc *RequestCtx) SetHeader(key, val string)
SetHeader sets a response header on REST/WS (e.g. Retry-After). On GraphQL — which has no per-field response headers — it is a no-op, so middleware can call it unconditionally without branching on transport.
func (*RequestCtx) WithContext ¶
func (rc *RequestCtx) WithContext(ctx context.Context)
WithContext replaces the underlying context — the functional equivalent of stashing a value on gin.Context for downstream middleware and the handler.
type Stage ¶
type Stage int
Stage is where an app-wide middleware runs, outermost first: Edge, then the framework's own (CORS, security headers, rate limit), then Session, Auth and App. Within a stage, declaration order holds, across modules. Declaring the stage, not a position, is what keeps "compression wraps everything" true wherever a module registers it.
const ( // App is the default: application middleware, innermost. App Stage = iota // Edge is outermost: compression, client IP, request IDs. Edge // Session runs once the request passed the framework's edge checks. Session // Auth runs after sessions are loaded, before application middleware. Auth )
type Transport ¶
type Transport uint8
Transport identifies which wire protocol a request arrived on.
type TransportSet ¶
type TransportSet uint8
TransportSet is a bitset over Transport. The zero value is the empty set.
func Transports ¶
func Transports(ts ...Transport) TransportSet
Transports builds a set from its members.
func (TransportSet) Has ¶
func (s TransportSet) Has(t Transport) bool
Has reports whether t is a member of the set.
func (TransportSet) String ¶
func (s TransportSet) String() string
String renders the set for fail-closed error messages, e.g. "{REST, GraphQL}".
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package secure holds the transport-neutral implementations of the two web-security defenses nexus applies — security response headers and CSRF — with no dependency beyond httpx and the standard library.
|
Package secure holds the transport-neutral implementations of the two web-security defenses nexus applies — security response headers and CSRF — with no dependency beyond httpx and the standard library. |