middleware

package
v2.33.7 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package middleware defines nexus's cross-transport middleware model.

Two shapes coexist here:

  1. 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.

  2. 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

Constants

This section is empty.

Variables

AllTransports is the common declaration for write-once middleware.

View Source
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".

View Source
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

func ClientIPFromCtx(ctx context.Context) string

ClientIPFromCtx returns the IP a transport stashed via WithClientIP, or empty when absent.

func WithClientIP

func WithClientIP(ctx context.Context, ip string) context.Context

WithClientIP returns ctx carrying ip. Transports (the gin REST handler, the GraphQL adapter, the WS upgrade) call this so per-IP middleware can find it.

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) Handle

func (f Func) Handle(rc *RequestCtx, n Next) error

func (Func) Name

func (f Func) Name() string

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 Kind

type Kind string
const (
	KindBuiltin Kind = "builtin"
	KindCustom  Kind = "custom"
)

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

type Rejection struct {
	Status int
	Err    error
}

Rejection is the error a middleware's Reject returns on GraphQL: the error, and the HTTP status it would have answered with on REST.

func (*Rejection) Error

func (r *Rejection) Error() string

func (*Rejection) Unwrap

func (r *Rejection) Unwrap() error

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
)

func (Stage) Rank

func (s Stage) Rank() int

Rank orders stages outermost first.

func (Stage) String

func (s Stage) String() string

type Transport

type Transport uint8

Transport identifies which wire protocol a request arrived on.

const (
	TransportREST Transport = iota
	TransportGraphQL
	TransportWebSocket
)

func (Transport) String

func (t Transport) String() string

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}".

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.

Jump to

Keyboard shortcuts

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