middleware

type AccessLogConfig struct {
	Logger                 LoggerFunc
	CapturePayload         bool
	PayloadLogLevel        string
	MaxBodyBytes           int64
	AllowedContentTypes    []string
	AllowedRequestHeaders  []string
	AllowedResponseHeaders []string
	ShouldCapturePayload   func(*gin.Context, int) bool
	Multipart              MultipartConfig
	Redaction              RedactionConfig

	// SkipPaths 精确匹配路径跳过日志记录。
	// 示例: []string{"/health", "/readyz", "/livez"}
	SkipPaths []string

	// ShouldLog 完全自定义的日志过滤。
	// 返回 false 时跳过全部日志。
	ShouldLog func(*gin.Context) bool
}

type CORSConfig struct {
	// AllowOrigins 允许的 Origin 列表。
	// 如果包含 "*"，则允许所有 Origin（不可与 AllowCredentials 同时使用）。
	AllowOrigins []string

	// AllowOriginFunc 动态判断 Origin 是否允许。
	// 设置后完全接管 origin 判断，AllowOrigins 不再生效。
	// 返回 true 表示允许，返回 false 表示拒绝（不 fallback 到 AllowOrigins）。
	AllowOriginFunc func(origin string) bool

	AllowMethods  string
	AllowHeaders  string
	ExposeHeaders string

	// AllowCredentials 是否允许携带凭证。
	// 为 true 时不可使用 "*" 作为 AllowOrigin。
	AllowCredentials bool

	// MaxAge 预检请求缓存时间。
	MaxAge time.Duration
}

type CompressionConfig struct {
	MinSizeBytes         int
	Level                int
	AllowedContentTypes  []string
	ExcludedContentTypes []string
	ShouldCompress       func(*gin.Context, int) bool
}

type ConcurrencyLimitConfig struct {
	Limit int
	// OnRejected 允许业务自定义限流拒绝响应；如果回调未写出响应，则回退到默认 503。
	OnRejected func(*gin.Context)
}

type LoggerFunc func(ctx context.Context, level string, event string, fields map[string]any)

type MultipartCaptureMode string

type MultipartConfig struct {
	Mode              MultipartCaptureMode
	PartAllowlist     []string
	MaxPartValueBytes int64
	RedactFilenames   bool
}

type RateLimitConfig struct {
	// Rate 每秒允许的请求数。
	Rate float64

	// Burst 突发上限，默认为 max(1, int(Rate))。
	Burst int

	// OnRejected 自定义拒绝响应。
	// 如果回调已写出响应，不再回退默认 429。
	OnRejected func(*gin.Context)
}

type RealIPConfig struct {
	// TrustedCIDRs 信任代理的 CIDR 列表。
	// 默认空列表，表示不信任任何代理（直接使用 RemoteAddr）。
	TrustedCIDRs []string

	// OnUntrusted 当检测到不可信代理时的处理函数。
	// 如果为 nil，则使用 RemoteAddr。
	OnUntrusted func(c *gin.Context, remoteAddr string)
}

type RecoveryConfig struct {
	// Logger 输出结构化恢复日志。
	// 复用 AccessLog 已有的 LoggerFunc 签名。
	Logger LoggerFunc

	// OnPanic 允许业务自定义 panic 后处理（如上报 Sentry）。
	// 在日志输出之后调用。
	OnPanic func(c *gin.Context, recovered any, stack []byte)
}

type RedactionConfig struct {
	Rules         []RedactionRule
	MaxValueBytes int
	HashSalt      string
}

type RedactionRule struct {
	Scope    string
	Key      string
	Strategy RedactionStrategy
}

type RedactionStrategy string

type SecurityHeadersConfig struct {
	// HSTS 设置 Strict-Transport-Security 头。
	// 示例: "max-age=31536000; includeSubDomains"
	HSTS string

	// ContentSecurityPolicy 设置 Content-Security-Policy 头。
	// 示例: "default-src 'self'"
	ContentSecurityPolicy string

	// PermissionsPolicy 设置 Permissions-Policy 头。
	// 示例: "camera=(), microphone=()"
	PermissionsPolicy string
}

type TimeoutConfig struct {
	// Timeout 请求处理超时时间。
	Timeout time.Duration

	// OnTimeout 自定义超时响应。
	// 如果回调未写出响应，回退到 504。
	OnTimeout func(*gin.Context)
}