middleware

Documentation

Index

• func AuthHTTP(opts ...AuthOption) func(http.Handler) http.Handler
• func AuthInterceptor(opts ...AuthOption) grpc.UnaryServerInterceptor
• func AuthPlugin(opts ...AuthOption) minato.Plugin
• func CORS(opts ...CORSOption) func(http.Handler) http.Handler
• func Logger(opts ...LoggerOption) func(http.Handler) http.Handler
• func LoggerInterceptor(opts ...LoggerOption) grpc.UnaryServerInterceptor
• func LoggerPlugin(opts ...LoggerOption) minato.Plugin
• func Recovery(opts ...RecoveryOption) func(http.Handler) http.Handler
• func RecoveryInterceptor(opts ...RecoveryOption) grpc.UnaryServerInterceptor
• func RecoveryPlugin(opts ...RecoveryOption) minato.Plugin
• func RequestID() func(http.Handler) http.Handler
• func RequestIDFromContext(ctx context.Context) string
• func RequestIDInterceptor() grpc.UnaryServerInterceptor
• func RequestIDPlugin() minato.Plugin
• type AuthOption
  • func WithAuthSkipPaths(paths ...string) AuthOption
  • func WithAuthValidator(fn AuthValidatorFunc) AuthOption
• type AuthValidatorFunc
• type CORSOption
  • func WithAllowedHeaders(headers ...string) CORSOption
  • func WithAllowedMethods(methods ...string) CORSOption
  • func WithAllowedOrigins(origins ...string) CORSOption
• type LogPrinter
• type LoggerOption
  • func WithBodyLogging(enabled bool) LoggerOption
  • func WithLogPrinter(p LogPrinter) LoggerOption
• type RecoveryOption
  • func WithRecoveryPrinter(p LogPrinter) RecoveryOption

Functions

func AuthHTTP

func AuthHTTP(opts ...AuthOption) func(http.Handler) http.Handler

AuthHTTP returns an HTTP middleware that:

1. Skips authentication for paths registered via WithAuthSkipPaths.
2. Extracts the "Authorization" header from the HTTP request.
3. Validates the Bearer scheme and strips the prefix.
4. Delegates to the client-provided validator for token verification.
5. Passes the enriched context to downstream handlers.

Error responses: returns 401 JSON if token is missing, invalid scheme, or validator rejects.

func AuthInterceptor

func AuthInterceptor(opts ...AuthOption) grpc.UnaryServerInterceptor

AuthInterceptor returns a gRPC UnaryServerInterceptor that:

1. Skips authentication for methods registered via WithAuthSkipPaths.
2. Extracts the "authorization" value from incoming gRPC metadata.
3. Validates the Bearer scheme and strips the prefix.
4. Delegates to the client-provided validator for token verification.
5. Passes the enriched context to downstream handlers.

Error passthrough: if the validator returns a *merr.Error or any error with a GRPCStatus() method, it is passed directly to the client. Otherwise, the error is wrapped as codes.Unauthenticated.

func AuthPlugin

func AuthPlugin(opts ...AuthOption) minato.Plugin

AuthPlugin bundles AuthHTTP (HTTP) and AuthInterceptor (gRPC) into a single minato.Plugin for dual-transport registration via srv.UsePlugin().

This is the recommended entry point when your server handles both pure HTTP and gRPC traffic.

Example:

v := auth.NewTokenValidator(publicKey, blacklist)
srv.UsePlugin(middleware.AuthPlugin(
    middleware.WithAuthSkipPaths(
        "/auth.v1.AuthService/Login",     // gRPC
        "/api/v1/auth/login",             // HTTP
    ),
    middleware.WithAuthValidator(v.Validate),
))

func CORS

func CORS(opts ...CORSOption) func(http.Handler) http.Handler

func Logger

func Logger(opts ...LoggerOption) func(http.Handler) http.Handler

Logger returns a middleware that logs requests.

func LoggerInterceptor

func LoggerInterceptor(opts ...LoggerOption) grpc.UnaryServerInterceptor

LoggerInterceptor is the gRPC unary interceptor form of Logger.

func LoggerPlugin

func LoggerPlugin(opts ...LoggerOption) minato.Plugin

LoggerPlugin bundles Logger (HTTP) and LoggerInterceptor (gRPC).

func Recovery

func Recovery(opts ...RecoveryOption) func(http.Handler) http.Handler

func RecoveryInterceptor

func RecoveryInterceptor(opts ...RecoveryOption) grpc.UnaryServerInterceptor

RecoverInterceptor is the gRPC unary interceptor form of recovery.

func RecoveryPlugin

func RecoveryPlugin(opts ...RecoveryOption) minato.Plugin

RecoveryPlugin bundles Recovery (HTTP) and RecoveryInterceptor (gRPC).

func RequestID

func RequestID() func(http.Handler) http.Handler

RequestID returns a middleware that generates a unique request ID for each request.

func RequestIDFromContext

func RequestIDFromContext(ctx context.Context) string

RequestIDFromContext returns the request ID from the context.

func RequestIDInterceptor

func RequestIDInterceptor() grpc.UnaryServerInterceptor

RequestIDInterceptor is the gRPC unary interceptor form of RequestID It reads x-request-id from incoming gRPC metadata ; generates a UUID if absent;

func RequestIDPlugin

func RequestIDPlugin() minato.Plugin

RequestIDPlugin bundles RequestID (HTTP) and RequestIDInterceptor (gRPC).

Types

type AuthOption

type AuthOption func(*authConfig)

AuthOption is a functional option for configuring the Auth middleware.

func WithAuthSkipPaths

func WithAuthSkipPaths(paths ...string) AuthOption

WithAuthSkipPaths registers paths that do NOT require authentication.

For gRPC: use the full method path, e.g. "/auth.v1.AuthService/Login". For HTTP: use the URL path, e.g. "/api/v1/auth/login".

Paths are checked with an O(1) map lookup — no regex or prefix matching overhead.

func WithAuthValidator

func WithAuthValidator(fn AuthValidatorFunc) AuthOption

WithAuthValidator registers the token validation function.

The function receives:

• ctx: the current request context
• token: the raw token string (e.g. "eyJhbGciOi..."), Bearer prefix already stripped

It must return:

• A (possibly enriched) context — e.g. with user claims injected via context.WithValue
• An error if the token is invalid/expired/revoked

Performance note: heavy initialization (JWT parser allocation, key loading, connection pooling) should be done OUTSIDE this function and captured via closure.

type AuthValidatorFunc

type AuthValidatorFunc func(ctx context.Context, token string) (context.Context, error)

AuthValidatorFunc is the signature that client business logic must implement. It receives the raw JWT token string (Bearer prefix already stripped). It must return an enriched context (e.g. with user claims) or an error.

type CORSOption

type CORSOption func(*corsConfig)

func WithAllowedHeaders

func WithAllowedHeaders(headers ...string) CORSOption

func WithAllowedMethods

func WithAllowedMethods(methods ...string) CORSOption

func WithAllowedOrigins

func WithAllowedOrigins(origins ...string) CORSOption

type LogPrinter

type LogPrinter interface {
	Info(msg string, args ...any)
	Error(msg string, args ...any)
}

LogPrinter defines the logging methods required by middlewares.

type LoggerOption

type LoggerOption func(*loggerConfig)

func WithBodyLogging

func WithBodyLogging(enabled bool) LoggerOption

WithBodyLogging enables logging of request and response bodies.

func WithLogPrinter

func WithLogPrinter(p LogPrinter) LoggerOption

WithLogPrinter allows injecting a custom logger into the middleware.

type RecoveryOption

type RecoveryOption func(*recoveryConfig)

func WithRecoveryPrinter

func WithRecoveryPrinter(p LogPrinter) RecoveryOption

WithRecoveryPrinter allows injecting a custom logger for panic reporting.