middleware

type AccessLogConfig struct {
	// Logger is used to log request information.
	// Default: ctx.Logger() (the request-scoped logger from the app).
	Logger *slog.Logger

	// Skipper defines a function to skip logging for certain requests.
	// When Skipper returns true, the request is not logged.
	// Useful for health check endpoints or static assets.
	// Default: DefaultSkipper (all requests are logged).
	Skipper Skipper
}

type CORSConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// AllowOrigins defines allowed origins.
	// Default: ["*"].
	AllowOrigins []string

	// AllowOriginFunc overrides AllowOrigins matching.
	AllowOriginFunc func(ctx *credo.Context, origin string) (allowedOrigin string, allowed bool, err error)

	// AllowMethods defines allowed methods for preflight.
	// Default: GET, HEAD, PUT, PATCH, POST, DELETE.
	AllowMethods []string

	// AllowHeaders defines allowed request headers for preflight.
	// If empty, Access-Control-Request-Headers is echoed.
	AllowHeaders []string

	// AllowCredentials enables Access-Control-Allow-Credentials.
	AllowCredentials bool

	// ExposeHeaders defines exposed response headers.
	ExposeHeaders []string

	// MaxAge sets Access-Control-Max-Age in seconds.
	// Zero disables this header.
	MaxAge int
}

type CSRFConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// TrustedOrigins lists origins whose cross-origin requests are allowed.
	// Each entry must be of the form "scheme://host[:port]" and is matched
	// exactly against the request's Origin header.
	//
	// Subdomains are cross-origin: a form on app.example.com posting to
	// api.example.com is rejected unless "https://app.example.com" is listed
	// here (browsers send Sec-Fetch-Site: same-site for that case, which is
	// not trusted by default).
	TrustedOrigins []string

	// InsecureBypassPatterns lists path patterns exempt from cross-origin
	// checks, using [http.ServeMux] pattern syntax (e.g. "/webhooks/",
	// "POST /payments/callback"). Matching requests skip CSRF protection
	// entirely — reserve this for endpoints that authenticate by other
	// means (signed webhooks, mTLS) and keep the list as narrow as possible.
	InsecureBypassPatterns []string

	// ErrorHandler maps a rejected request to the error returned by the
	// middleware. The rejection reason from the detector is passed as err.
	// Default: 403 *credo.HTTPError with the reason attached as internal
	// error (logged, never exposed to the client).
	ErrorHandler func(ctx *credo.Context, err error) error
}

type CompressConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// Level is the gzip/deflate compression level (1–9). The zero value
	// selects the default (5); level 0 (NoCompression) cannot be requested
	// through this middleware — omit the middleware or use Skipper to skip
	// compression entirely.
	Level int

	// Types limits compression to specific content types.
	// Supports exact values ("application/json") and wildcards ("text/*").
	// Default: common textual MIME types.
	Types []string
}

type ContractConfig struct {
	// Skipper defines a function to skip the middleware for a request.
	Skipper Skipper

	// ScopeChecker enforces the MetaScope contract. It receives the request
	// context and a single required scope and reports whether the request
	// satisfies it. Because authenticated users are stored generically
	// (ctx.GetUser[T]), the framework cannot inspect scopes on its own —
	// supply this to bridge to your auth model. When nil, any route that
	// declares a scope contract is rejected with 403.
	ScopeChecker func(ctx *credo.Context, requiredScope string) bool

	// APIVersionHeader is the request header inspected for the MetaAPIVersion
	// contract. Defaults to "X-API-Version".
	APIVersionHeader string

	// CustomChecks run after all built-in contracts have passed, in order.
	// A check returns a non-nil error (typically a *credo.HTTPError) to reject
	// the request. This is the extension point for user-defined contracts.
	CustomChecks []func(ctx *credo.Context) error
}

type RateLimitConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// Store is the backing limiter store.
	// Default: in-memory store with Tokens/Interval.
	Store limiter.Store

	// Tokens is the number of allowed requests per interval.
	// Default: 60.
	Tokens uint64

	// Interval is the refill interval.
	// Default: 1 minute.
	Interval time.Duration

	// KeyFunc builds a limiter key from the request context.
	// Default: client IP from ctx.Request().RealIP().
	KeyFunc func(ctx *credo.Context) (string, error)

	// InternalErrorHandler handles internal limiter/key errors (key
	// extraction failure, store failure). Over-limit responses go through
	// DeniedHandler instead.
	InternalErrorHandler func(ctx *credo.Context, err error) error

	// DeniedHandler handles over-limit responses.
	DeniedHandler func(ctx *credo.Context, limit, remaining uint64, reset time.Time) error
}

type RateLimiter struct {
	// contains filtered or unexported fields
}

type RecoverConfig struct {
	// Logger is used to log panic information.
	// Default: ctx.Logger() (the request-scoped logger from the app).
	Logger *slog.Logger

	// DisableStackTrace disables stack trace logging on panic.
	// Default: false (stack traces are enabled).
	DisableStackTrace bool

	// StackSize is the maximum number of bytes for the stack trace.
	// Default: 8192.
	StackSize int
}

type RequestIDConfig struct {
	// Header is the HTTP header name used to read/write the request ID.
	// Default: "X-Request-Id".
	Header string

	// Generator creates a new request ID when one is not provided by the
	// client. Default: crypto/rand.Text (128-bit base32 string).
	Generator func() string

	// Limit is the maximum allowed length for incoming request IDs. IDs
	// exceeding this length are discarded and a new one is generated.
	// This prevents clients from injecting arbitrarily large values.
	// Default: 64.
	Limit int
}

type RewriteConfig struct {
	// Skipper skips rewriting for matching requests.
	Skipper Skipper

	// Rules are evaluated in order; the first match wins.
	Rules []RewriteRule
}

type RewriteRule struct {
	// Host restricts the rule to requests matching this exact host (case-insensitive).
	// Empty matches all hosts.
	Host string

	// From is the path pattern to match. Supports Credo route syntax:
	//   - {name}      — matches a single path segment
	//   - {name...}   — matches the rest of the path
	//   - {name:regex} — matches with regex constraint
	// Ignored when Regexp is set.
	From string

	// To is the replacement path. Named placeholders ({name}) are expanded
	// with captured values.
	To string

	// Regexp is an optional pre-compiled regex. When set, From is ignored.
	// Named capture groups (?P<name>...) are used for placeholder expansion.
	Regexp *regexp.Regexp

	// PreserveQuery appends the original query string to the rewritten URL
	// when To does not contain a query string.
	PreserveQuery bool
}

type SecureConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// XSSProtection sets the X-XSS-Protection header value.
	XSSProtection string

	// ContentTypeNosniff sets the X-Content-Type-Options header value.
	ContentTypeNosniff string

	// XFrameOptions sets the X-Frame-Options header value.
	XFrameOptions string

	// HSTSMaxAge sets Strict-Transport-Security max-age in seconds.
	HSTSMaxAge int

	// HSTSExcludeSubdomains disables includeSubDomains in HSTS.
	HSTSExcludeSubdomains bool

	// HSTSPreloadEnabled adds preload token in HSTS.
	HSTSPreloadEnabled bool

	// ContentSecurityPolicy sets CSP or CSP-Report-Only header value.
	ContentSecurityPolicy string

	// CSPReportOnly uses Content-Security-Policy-Report-Only header.
	CSPReportOnly bool

	// ReferrerPolicy sets the Referrer-Policy header value.
	ReferrerPolicy string
}

type Skipper func(ctx *credo.Context) bool

type TimeoutConfig struct {
	// Skipper defines a function to skip middleware.
	Skipper Skipper

	// Timeout defines request context timeout.
	// Zero or negative values disable timeout behavior.
	Timeout time.Duration

	// ErrorHandler maps downstream errors after timeout wrapping.
	ErrorHandler func(ctx *credo.Context, err error) error
}