middleware

func CORS ¶

func CORS(config CORSConfig) forge.Middleware

CORS returns middleware that handles Cross-Origin Resource Sharing.

package main

import (
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/middleware"
)

func main() {
	app := forge.New()
	router := app.Router()

	// Development: Allow all origins (NOT for production)
	cors := middleware.CORS(middleware.DefaultCORSConfig())

	router.Use(cors)

	router.GET("/api/users", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusOK, map[string]string{"user": "john"})
	})

	_ = app.Run()
}

Output:

package main

import (
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/middleware"
)

func main() {
	app := forge.New()
	router := app.Router()

	corsConfig := middleware.CORSConfig{
		AllowOrigins: []string{
			"https://web.example.com",
			"https://mobile.example.com",
			"https://partner.acme.com",
		},
		AllowMethods:     []string{"GET", "POST", "PATCH"},
		AllowHeaders:     []string{"Content-Type", "Authorization", "X-API-Key"},
		ExposeHeaders:    []string{"X-Request-ID"},
		AllowCredentials: true,
		MaxAge:           3600,
	}

	cors := middleware.CORS(corsConfig)
	router.Use(cors)

	router.POST("/api/orders", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusCreated, map[string]string{"id": "123"})
	})

	_ = app.Run()
}

Output:

package main

import (
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/middleware"
)

func main() {
	app := forge.New()
	router := app.Router()

	// Production: Specific origins with credentials
	corsConfig := middleware.CORSConfig{
		AllowOrigins: []string{
			"https://app.example.com",
			"https://admin.example.com",
		},
		AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},
		AllowHeaders:     []string{"Content-Type", "Authorization"},
		ExposeHeaders:    []string{"X-Request-ID", "X-Total-Count"},
		AllowCredentials: true, // Enable cookies/auth headers
		MaxAge:           7200, // 2 hours
	}

	cors := middleware.CORS(corsConfig)
	router.Use(cors)

	router.GET("/api/users", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusOK, map[string]string{"user": "john"})
	})

	_ = app.Run()
}

Output:

package main

import (
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/middleware"
)

func main() {
	app := forge.New()
	router := app.Router()

	// Public API: Permissive CORS
	publicCORS := middleware.CORS(middleware.CORSConfig{
		AllowOrigins:     []string{"*"},
		AllowMethods:     []string{"GET"},
		AllowHeaders:     []string{"Content-Type"},
		AllowCredentials: false,
		MaxAge:           3600,
	})

	// Private API: Strict CORS with credentials
	privateCORS := middleware.CORS(middleware.CORSConfig{
		AllowOrigins:     []string{"https://app.example.com"},
		AllowMethods:     []string{"GET", "POST", "PUT", "DELETE"},
		AllowHeaders:     []string{"Content-Type", "Authorization"},
		AllowCredentials: true,
		MaxAge:           3600,
	})

	// Public routes
	public := router.Group("/public")
	public.Use(publicCORS)
	public.GET("/status", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusOK, map[string]string{"status": "ok"})
	})

	// Private routes
	private := router.Group("/api")
	private.Use(privateCORS)
	private.GET("/users", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusOK, map[string]string{"user": "john"})
	})

	_ = app.Run()
}

Output:

package main

import (
	"net/http"

	"github.com/xraph/forge"
	"github.com/xraph/forge/middleware"
)

func main() {
	app := forge.New()
	router := app.Router()

	// Allow all subdomains of example.com
	corsConfig := middleware.CORSConfig{
		AllowOrigins:     []string{"*.example.com"},
		AllowMethods:     []string{"GET", "POST"},
		AllowHeaders:     []string{"Content-Type"},
		AllowCredentials: false,
		MaxAge:           3600,
	}

	cors := middleware.CORS(corsConfig)
	router.Use(cors)

	router.GET("/api/data", func(ctx forge.Context) error {
		return ctx.JSON(http.StatusOK, map[string]string{"data": "value"})
	})

	_ = app.Run()
}

Output:

func ClientIP ¶ added in v1.9.0

func ClientIP(r *http.Request) string

ClientIP returns the client's IP address from RemoteAddr, discarding the port.

This is the default rate-limit key. Using RemoteAddr verbatim does not work: Go's HTTP server sets it to "IP:ephemeral-port" and the port changes per connection, so every connection would get a fresh bucket — no effective limit at all, plus unbounded map growth.

This deliberately ignores X-Forwarded-For. Behind a proxy every client collapses into the proxy's IP, so supply a RateLimitKeyFunc that reads the forwarded header only for hops you actually trust — reading it unconditionally is a header-spoofing bypass.

func Compress ¶

func Compress(level int) forge.Middleware

Compress middleware compresses HTTP responses using gzip Only compresses if client supports gzip and response is suitable for compression This is the new forge middleware pattern using forge.Handler.

func CompressDefault ¶

func CompressDefault() forge.Middleware

CompressDefault returns Compress middleware with default compression level.

func DefaultIdempotencyPrincipal ¶ added in v1.12.2

func DefaultIdempotencyPrincipal(ctx forge.Context) string

DefaultIdempotencyPrincipal reads "auth.subject", then the Subject of "auth_context" (as "provider:subject" when its ProviderName is set), and returns "" for an anonymous request.

func GetRequestID ¶

func GetRequestID(ctx context.Context) string

GetRequestID retrieves the request ID from standard context.

func GetRequestIDFromForgeContext ¶ added in v0.5.0

func GetRequestIDFromForgeContext(ctx forge.Context) string

GetRequestIDFromForgeContext retrieves the request ID from Forge context.

func Idempotency ¶ added in v1.12.2

func Idempotency(store IdempotencyStore, opts ...IdempotencyOption) forge.Middleware

Idempotency runs a write handler at most once per principal, METHOD /path and Idempotency-Key, and replays the stored response to every repeat.

A repeat with a different body gets 422. A repeat that arrives while the first is still running waits for it (or gets 409 with IdempotencyOnConflict(IdempotencyReject)); that 409 carries Retry-After: 1. A handler that returns an error, panics or answers 408, 429 or 5xx stores nothing, so the client's retry runs it again. A 4xx the handler writes itself is stored, while a 4xx returned as an error is not, because the error handler writes it outside this middleware. A response larger than IdempotencyMaxResponse is replayed without its body, marked Idempotent-Truncated: true. GET, HEAD and OPTIONS and writes without the header pass straight through. So does a keyed request without a principal (unless IdempotencyAllowAnonymous is set), undeduplicated: its response carries Idempotency-Skipped: anonymous, and the first one on each route is logged as a warning, because the usual cause is auth registered after this middleware.

The handler runs on a fresh context that shares the outer context's values and session, so ctx.Get and ctx.Session work behind this middleware. Other private state of the outer context, such as a DI scope it opened, is not carried across.

Prefer forge.WithIdempotency on the route: it installs this middleware and also marks the operation x-forge-idempotent so generated clients know a replay is safe.

func Logging ¶

func Logging(logger forge.Logger) forge.Middleware

Logging middleware logs HTTP requests with timing information.

func LoggingWithConfig ¶

func LoggingWithConfig(logger forge.Logger, config LoggingConfig) forge.Middleware

LoggingWithConfig middleware logs HTTP requests with custom configuration.

func RateLimit ¶

func RateLimit(limiter *RateLimiter, logger forge.Logger) forge.Middleware

RateLimit middleware enforces rate limiting per client, keyed on client IP.

func RateLimitWithKey ¶ added in v1.9.0

func RateLimitWithKey(limiter *RateLimiter, keyFunc RateLimitKeyFunc, logger forge.Logger) forge.Middleware

RateLimitWithKey enforces rate limiting using a caller-supplied key function. Use this to key on an authenticated user ID, an API key, or a trusted forwarded-for hop instead of the client IP.

func Recovery ¶

func Recovery(logger forge.Logger) forge.Middleware

Recovery middleware recovers from panics and logs them with a stack trace. Returns http.StatusInternalServerError on panic.

http.ErrAbortHandler is deliberately re-panicked: net/http uses it as the signal to drop the connection without logging, and swallowing it here would turn an intentional abort into a bogus 500.

func RequestID ¶

func RequestID() forge.Middleware

RequestID middleware adds a unique request ID to each request If X-Request-ID header is present and well-formed, it is used; otherwise a new UUID is generated.

func Timeout ¶

func Timeout(duration time.Duration, logger forge.Logger) func(http.Handler) http.Handler

Timeout middleware enforces a timeout on request handling Returns http.StatusGatewayTimeout if request exceeds duration Note: This middleware uses http.Handler pattern due to goroutine requirements.