middleware

package
v2.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 23, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnnotationArgs

type AnnotationArgs struct {
	Args []string
	KV   map[string]string
}

type AnnotationSpec

type AnnotationSpec struct {
	Name  string
	Scope Scope
	Stage Stage
}

type BeforeAfter

type BeforeAfter interface {
	Before(ctx context.Context, args AnnotationArgs) error
	After(ctx context.Context, args AnnotationArgs) error
}

BeforeAfter is an optional backward-compatible interface. If a middleware only needs simple Before/After hooks, it can implement this and be wrapped via WrapBeforeAfter.

type Bound

type Bound struct {
	MW   Middleware
	Args AnnotationArgs
}

type Handler

type Handler func(context.Context) error

func Chain

func Chain(handler Handler, globalMW []Bound, controllerMW []Bound, methodMW []Bound) Handler

Chain builds a Handler that executes middleware layers in onion order: globalBefore → controllerBefore → methodMiddleware → handler → (unwinding)

Each middleware's Handle receives a next function that calls the next layer.

The same middleware can be bound at several levels at once — for example a middleware registered with Engine.Use() and also annotated on the controller. Executing it once per level would double its side effects (duplicated log lines, doubled timings, repeated auth checks), so layers are de-duplicated by middleware name, keeping the most specific binding: method > controller > global.

type Middleware

type Middleware interface {
	Spec() AnnotationSpec
	Handle(ctx context.Context, args AnnotationArgs, next Handler) error
}

Middleware is the core middleware interface using the onion (Handle + next) model. Implementations receive the request context, annotation arguments, and a next function that invokes the rest of the middleware chain plus the final handler.

Simple before/after logic:

func (m *MyMW) Handle(ctx context.Context, args AnnotationArgs, next Handler) error {
    // before
    if err := next(ctx); err != nil { return err }
    // after
    return nil
}

Hijacking (e.g. WebSocket): the middleware may call next() zero or many times, and may block in a loop.

func WrapBeforeAfter

func WrapBeforeAfter(spec AnnotationSpec, ba BeforeAfter) Middleware

WrapBeforeAfter adapts a BeforeAfter into a full Middleware.

type Scope

type Scope string
const (
	ScopeController Scope = "controller"
	ScopeMethod     Scope = "method"
	ScopeBoth       Scope = "both"
)

type SecurityProvider

type SecurityProvider interface {
	SecurityScheme() SecurityScheme
}

SecurityProvider is an optional interface that auth middlewares can implement to declare their OpenAPI security scheme. When a middleware implements this interface, the framework will automatically add the corresponding security scheme to the OpenAPI document and mark operations protected by this middleware with a lock icon.

type SecurityScheme

type SecurityScheme struct {
	// Name is the security scheme identifier (e.g. "BasicAuth", "BearerAuth", "ApiKeyAuth").
	Name string
	// Type is the scheme type: "http" or "apiKey".
	Type SecuritySchemeType
	// Scheme is the HTTP auth scheme, used when Type is "http" (e.g. "basic", "bearer").
	Scheme string
	// BearerFormat is optional, e.g. "JWT", used when Scheme is "bearer".
	BearerFormat string
	// In is where the apiKey is sent, used when Type is "apiKey" (e.g. "header", "query", "cookie").
	In SecuritySchemeIn
	// FieldName is the header/query/cookie name, used when Type is "apiKey" (e.g. "Authorization", "X-API-Key").
	FieldName string
	// Description is an optional description for the security scheme.
	Description string
}

SecurityScheme describes an OpenAPI security scheme that an auth middleware provides.

type SecuritySchemeIn

type SecuritySchemeIn string

SecuritySchemeIn defines where an apiKey is sent.

const (
	SecurityInHeader SecuritySchemeIn = "header"
	SecurityInQuery  SecuritySchemeIn = "query"
	SecurityInCookie SecuritySchemeIn = "cookie"
)

type SecuritySchemeType

type SecuritySchemeType string

SecuritySchemeType defines supported OpenAPI security scheme types.

const (
	SecurityHTTP   SecuritySchemeType = "http"
	SecurityAPIKey SecuritySchemeType = "apiKey"
)

type Stage

type Stage string
const (
	StageBefore Stage = "before"
	StageAfter  Stage = "after"
	StageBoth   Stage = "both"
)

Jump to

Keyboard shortcuts

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