middleware

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HeaderAPIVersion = "X-API-Version"
	APIVersionV1     = "v1"
)
View Source 
const (
	EnvMaintenanceMode    = "MAINTENANCE_MODE"
	EnvMaintenanceMessage = "MAINTENANCE_MESSAGE"
)

Variables

This section is empty.

Functions

func APIVersionMiddleware added in v0.2.1 

func APIVersionMiddleware() gin.HandlerFunc

APIVersionMiddleware accepts X-API-Version (default v1), echoes it on the response, and returns 400 for unsupported versions (only v1 today).

func AuthRateLimiter added in v0.2.1 

func AuthRateLimiter(perWindow int, window time.Duration, burst int) gin.HandlerFunc

AuthRateLimiter returns a gin middleware that throttles requests by client IP. perWindow specifies how many requests are allowed in the rolling window of length window; burst is the initial token bucket capacity (controls "thundering" behaviour at process start).

Returns 429 with a Retry-After-style hint when the limit is exceeded. nil-safe: zero values fall back to safe defaults (5 req / 5 min).

func CSRFMiddleware added in v0.2.1 

func CSRFMiddleware(config *SecurityConfig) gin.HandlerFunc

CSRFMiddleware CSRF保护中间件

func CircuitBreakerMiddleware added in v0.2.1 

func CircuitBreakerMiddleware() gin.HandlerFunc

CircuitBreakerMiddleware 熔断器中间件

func CombinedTimeoutCircuitMiddleware added in v0.2.1 

func CombinedTimeoutCircuitMiddleware() gin.HandlerFunc

CombinedTimeoutCircuitMiddleware 组合超时和熔断中间件。 Respects enableTimeout / enableCircuitBreaker set via InitTimeoutCircuitManager.

func DeprecationHeaders added in v0.2.1 

func DeprecationHeaders(sunset string) gin.HandlerFunc

DeprecationHeaders sets RFC 8594-style Deprecation / Sunset response headers on marked routes. sunset is an HTTP-date or opaque token (e.g. "2027-01-01").

func ErrorHandler added in v0.2.1 

func ErrorHandler() gin.HandlerFunc

ErrorHandler is a Gin middleware that recovers from panics and converts them to structured AppError responses. It also handles any errors stored in the gin.Context via c.Error().

func GetCircuitBreakerStats added in v0.2.1 

func GetCircuitBreakerStats() map[string]interface{}

GetCircuitBreakerStats 获取所有熔断器统计信息

func IPACLDecision added in v0.2.1 

func IPACLDecision(globalBlocked, globalAllowed, routeBlocked, routeAllowed IPList, clientIP string) (allowed bool, reason string)

IPACLDecision evaluates block-first, then allow-if-configured semantics.

func InitRedisRateBackend added in v0.2.1 

func InitRedisRateBackend(addr, password string) error

func InitTimeoutCircuitManager added in v0.2.1 

func InitTimeoutCircuitManager(timeoutCfg TimeoutConfig, cbCfg CircuitBreakerConfig, enableTimeout, enableCircuitBreaker bool)

InitTimeoutCircuitManager configures the global timeout/circuit manager from app config. Safe to call once at startup; subsequent calls are no-ops (sync.Once).

func InjectDB 

func InjectDB(db *gorm.DB) gin.HandlerFunc

InjectDB 注入数据库实例到 Gin 上下文

func InputValidationMiddleware added in v0.2.1 

func InputValidationMiddleware() gin.HandlerFunc

InputValidationMiddleware 输入验证中间件

func LoggerMiddleware added in v0.2.1 

func LoggerMiddleware(log *zap.Logger) gin.HandlerFunc

LoggerMiddleware logs completed HTTP requests (requires RequestIDMiddleware first). log is kept for API compatibility; logging uses logger.*Ctx on the global logger.

func MaintenanceMode added in v0.2.1 

func MaintenanceMode(bypass MaintenanceBypassFunc) gin.HandlerFunc

MaintenanceMode returns 503 for non-probe routes when MAINTENANCE_MODE=true. bypass (optional) lets specific requests (e.g. platform admins) through.

func MarkOperationLogged added in v0.2.1 

func MarkOperationLogged(c *gin.Context)

MarkOperationLogged records that this HTTP request already wrote an operation log.

func OperationAlreadyLogged added in v0.2.1 

func OperationAlreadyLogged(c *gin.Context) bool

OperationAlreadyLogged reports whether an operation log was written for this request.

func PanicRecovery added in v0.2.1 

func PanicRecovery() gin.HandlerFunc

PanicRecovery logs panics and returns 500.

func RedisAllow added in v0.2.1 

func RedisAllow(key string, limit int, window time.Duration) bool

RedisAllow is a minimal fixed-window counter shared across replicas.

func RedisRateEnabled added in v0.2.1 

func RedisRateEnabled() bool

func ReqIDFromGin added in v0.2.1 

func ReqIDFromGin(c *gin.Context) string

ReqIDFromGin is a convenience alias for ginlogger.ReqIDFromGin.

func RequestIDMiddleware added in v0.2.1 

func RequestIDMiddleware() gin.HandlerFunc

RequestIDMiddleware assigns X-Reqid on every HTTP request (reuse inbound header or generate). Must run before LoggerMiddleware and handlers so logger.*Ctx helpers see the id.

func SanitizeString added in v0.2.1 

func SanitizeString(input string) string

SanitizeString 清理字符串，移除危险字符

func SecureCompare added in v0.2.1 

func SecureCompare(a, b string) bool

SecureCompare 安全比较字符串，防止时序攻击

func SecurityMiddleware added in v0.2.1 

func SecurityMiddleware(config *SecurityConfig) gin.HandlerFunc

SecurityMiddleware 安全中间件

func SetMaintenanceAllowedPaths added in v0.2.1 

func SetMaintenanceAllowedPaths(paths, prefixes []string)

SetMaintenanceAllowedPaths configures which paths/prefixes stay open during maintenance mode. Pass nil/empty to clear. Must be called before the middleware is first invoked.

func SetSkipAccessLogPaths added in v0.2.1 

func SetSkipAccessLogPaths(paths []string)

SetSkipAccessLogPaths configures which path substrings should skip access logging. Pass nil/empty to clear. Must be called before the middleware is first invoked (not safe to mutate concurrently with request handling).

func TimeoutMiddleware added in v0.2.1 

func TimeoutMiddleware() gin.HandlerFunc

TimeoutMiddleware 超时中间件

func ValidateEmail added in v0.2.1 

func ValidateEmail(email string) bool

ValidateEmail 验证邮箱格式

func ValidatePassword added in v0.2.1 

func ValidatePassword(password string) error

ValidatePassword 验证密码强度

func WriteError added in v0.2.1 

func WriteError(c *gin.Context, err error)

WriteError is a convenience helper to attach an error to the context and abort.

func XSSProtectionMiddleware added in v0.2.1 

func XSSProtectionMiddleware() gin.HandlerFunc

XSSProtectionMiddleware XSS防护中间件

Types

type Breaker added in v0.2.1 

type Breaker interface {
	Allow() error
	MarkSuccess()
	MarkFailed()
}

Breaker is the circuit-breaker interface used by the timeout/circuit middleware. Both ling-base/circuitbreaker.CircuitBreaker and circuitbreaker.SREBreaker satisfy this interface, so applications can choose the strategy that fits their traffic profile.

type BreakerFactory added in v0.2.1 

type BreakerFactory func(endpoint string) Breaker

BreakerFactory creates a Breaker for a given endpoint key. Used by TimeoutCircuitManager to lazily create per-endpoint breakers.

func DefaultBreakerFactory added in v0.2.1 

func DefaultBreakerFactory(cfg circuitbreaker.Config) BreakerFactory

DefaultBreakerFactory returns a factory that creates circuitbreaker.CircuitBreaker instances with the given config.

func NoopBreakerFactory added in v0.2.1 

func NoopBreakerFactory() BreakerFactory

NoopBreakerFactory returns a factory that creates breakers which never reject. Useful for disabling circuit breaking while keeping the middleware chain intact.

func SREBreakerFactory added in v0.2.1 

func SREBreakerFactory(opts ...circuitbreaker.SREOption) BreakerFactory

SREBreakerFactory returns a factory that creates SRE-style adaptive breakers with the given options.

type CircuitBreaker added in v0.2.1 

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

CircuitBreaker 熔断器

func NewCircuitBreaker added in v0.2.1 

func NewCircuitBreaker(config CircuitBreakerConfig) *CircuitBreaker

NewCircuitBreaker 创建新的熔断器

func (*CircuitBreaker) Allow added in v0.2.1 

func (cb *CircuitBreaker) Allow() bool

Allow 检查是否允许请求

func (*CircuitBreaker) GetState added in v0.2.1 

func (cb *CircuitBreaker) GetState() CircuitBreakerState

GetState 获取熔断器状态

func (*CircuitBreaker) GetStats added in v0.2.1 

func (cb *CircuitBreaker) GetStats() map[string]interface{}

GetStats 获取熔断器统计信息

func (*CircuitBreaker) RecordFailure added in v0.2.1 

func (cb *CircuitBreaker) RecordFailure()

RecordFailure 记录失败

func (*CircuitBreaker) RecordSuccess added in v0.2.1 

func (cb *CircuitBreaker) RecordSuccess()

RecordSuccess 记录成功

type CircuitBreakerConfig added in v0.2.1 

type CircuitBreakerConfig struct {
	// 失败阈值
	FailureThreshold int
	// 成功阈值（半开状态下）
	SuccessThreshold int
	// 超时时间
	Timeout time.Duration
	// 熔断器打开后的等待时间
	OpenTimeout time.Duration
	// 最大并发请求数
	MaxConcurrentRequests int
}

CircuitBreakerConfig 熔断器配置

func DefaultCircuitBreakerConfig added in v0.2.1 

func DefaultCircuitBreakerConfig() CircuitBreakerConfig

DefaultCircuitBreakerConfig 默认熔断器配置

type CircuitBreakerState added in v0.2.1 

type CircuitBreakerState int

CircuitBreakerState 熔断器状态 

const (
	StateClosed CircuitBreakerState = iota
	StateHalfOpen
	StateOpen
)

type IPACLRule added in v0.2.1 

type IPACLRule struct {
	Allowed string
	Blocked string
}

IPACLRule is a per-route IP allow/block overlay.

type IPList added in v0.2.1 

type IPList struct {
	Any  bool
	IPs  []net.IP
	Nets []*net.IPNet
}

IPList holds parsed IP/CIDR entries for allow/block checks.

func ParseIPList added in v0.2.1 

func ParseIPList(raw string) IPList

ParseIPList parses a comma-separated list of IPs and CIDRs. "*" means allow any (used by allowlists only).

func (IPList) Contains added in v0.2.1 

func (l IPList) Contains(ipStr string) bool

Contains reports whether ipStr matches the list.

func (IPList) Empty added in v0.2.1 

func (l IPList) Empty() bool

type MaintenanceBypassFunc added in v0.2.1 

type MaintenanceBypassFunc func(c *gin.Context) bool

MaintenanceBypassFunc returns true if the request should bypass maintenance. Apps can plug in their own admin-token check here; nil means no bypass.

type SecurityConfig added in v0.2.1 

type SecurityConfig struct {
	// CSRF配置
	CSRFSecret    string            `json:"csrf_secret"`
	CSRFTokenName string            `json:"csrf_token_name"`
	CSRFMaxAge    time.Duration     `json:"csrf_max_age"`
	CSRFSecure    bool              `json:"csrf_secure"`
	CSRFHttpOnly  bool              `json:"csrf_http_only"`
	CSRFSameSite  csrf.SameSiteMode `json:"csrf_same_site"`

	// XSS配置
	XSSProtection      bool   `json:"xss_protection"`
	ContentTypeNosniff bool   `json:"content_type_nosniff"`
	XFrameOptions      string `json:"x_frame_options"`

	// 输入验证配置
	MaxRequestSize int64    `json:"max_request_size"`
	AllowedOrigins []string `json:"allowed_origins"`

	// 安全头配置
	HSTSMaxAge     int    `json:"hsts_max_age"`
	ReferrerPolicy string `json:"referrer_policy"`
}

SecurityConfig 安全配置

func DefaultSecurityConfig added in v0.2.1 

func DefaultSecurityConfig() *SecurityConfig

DefaultSecurityConfig 默认安全配置

type TimeoutCircuitManager added in v0.2.1 

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

TimeoutCircuitManager 超时和熔断管理器

func GetTimeoutCircuitManager added in v0.2.1 

func GetTimeoutCircuitManager() *TimeoutCircuitManager

GetTimeoutCircuitManager 获取全局超时熔断管理器

func NewTimeoutCircuitManager added in v0.2.1 

func NewTimeoutCircuitManager(timeoutConfig TimeoutConfig, cbConfig CircuitBreakerConfig) *TimeoutCircuitManager

NewTimeoutCircuitManager 创建超时和熔断管理器

func (*TimeoutCircuitManager) SetBreakerFactory added in v0.2.1 

func (m *TimeoutCircuitManager) SetBreakerFactory(f BreakerFactory)

SetBreakerFactory overrides the default breaker creation strategy. Pass DefaultBreakerFactory, SREBreakerFactory, or a custom factory. Must be called before the middleware is first invoked.

func (*TimeoutCircuitManager) SetLongLivedPrefixes added in v0.2.1 

func (m *TimeoutCircuitManager) SetLongLivedPrefixes(prefixes []string)

SetLongLivedPrefixes registers additional path prefixes that should skip timeout/circuit wrapping (e.g. WebSocket / SSE / streaming endpoints).

type TimeoutConfig added in v0.2.1 

type TimeoutConfig struct {
	// 默认超时时间
	DefaultTimeout time.Duration
	// 接口级别超时配置
	EndpointTimeouts map[string]time.Duration
	// 超时后的降级响应
	FallbackResponse interface{}
}

TimeoutConfig 超时配置

func DefaultTimeoutConfig added in v0.2.1 

func DefaultTimeoutConfig() TimeoutConfig

DefaultTimeoutConfig 默认超时配置（仅包含探针，应用可自行注入 EndpointTimeouts）

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.