middleware

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(handler Handler, globalMW []Bound, controllerMW []Bound, methodMW []Bound) Handler

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(spec AnnotationSpec, ba BeforeAfter) 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"
)