-
Notifications
You must be signed in to change notification settings - Fork 0
middleware_en.md
The middleware package provides a series of plug-and-play middleware tailored for HypGo's context.Context. Through the built-in middleware chain and group management features, you can easily add cross-origin request handling, logging, rate limiting, caching, and more to your routes.
- Logger: High-performance request logging, supports recording duration and response size, can exclude specific paths.
- Recovery: Automatically catches panics to prevent server crashes, with customizable panic handling logic and HTTP status responses.
- CORS: Cross-Origin Resource Sharing handling, supports fine-grained configuration and Preflight request caching.
- Security: HTTP security header configuration (HSTS, X-Frame-Options, CSP), all header values pre-computed at initialization with zero GC pressure.
- RateLimiter: Simple Token Bucket-based rate limiting, configurable by IP or custom rules.
- Timeout: Maximum time limit for HTTP request processing; forces interruption and responds with timeout message when exceeded.
- Cache: Caches frequently accessed APIs in memory, with customizable TTL, key generation algorithm, and validation logic.
HypGo uses Chain and Group patterns for middleware management. You can combine one or more middleware like building blocks, then attach them to the final Handler using Then.
Using Logger as an example, mount with default configuration:
package main import ( "github.com/maoxiaoyue/hypgo/pkg/middleware" "github.com/maoxiaoyue/hypgo/pkg/router" "github.com/maoxiaoyue/hypgo/pkg/context" ) func main() { r := router.New() // Add Logger middleware with default settings r.Use(middleware.Logger(middleware.LoggerConfig{})) r.GET("/ping", func(c *context.Context) { c.String(200, "pong") }) }
You can also bundle middleware into a group via middleware.Chain before applying:
// Create a basic security call chain apiChain := middleware.NewChain( middleware.Recovery(middleware.RecoveryConfig{}), // Prevent crashes middleware.Logger(middleware.LoggerConfig{}), // Logging middleware.CORS(middleware.CORSConfig{ AllowOrigins: []string{"https://example.com"}, }), ) // Combine with custom function r.GET("/api/data", apiChain.Then(func(c *context.Context) { c.JSON(200, map[string]string{"msg": "secure data"}) }))
If specific route prefixes (e.g., /admin) need specific middleware logic:
// Declare a group starting with `/admin` and attach RateLimiter adminGroup := middleware.NewGroup("/admin", middleware.RateLimiter(middleware.RateLimiterConfig{ Rate: 10, // 10 requests per second Burst: 20, // Maximum burst capacity of 20 })) // Apply the group's middleware to specific routes r.GET("/admin/dashboard", adminGroup.Handle(func(c *context.Context) { c.String(200, "Admin View") }))
You can write your own middleware following the func(*hypcontext.Context) type signature. Just make sure to call c.Next() at the end to proceed through the execution chain:
func MyCustomMiddleware() hypcontext.HandlerFunc { return func(c *hypcontext.Context) { // 1. Logic before request processing c.Set("my_key", "my_value") // 2. Hand control to the next middleware or Handler c.Next() // 3. Logic after processing, before response status := c.Writer.Status() log.Printf("Response Status: %d", status) } }
Prevents large payload DoS attacks:
r.Use(middleware.BodyLimit(middleware.BodyLimitConfig{ MaxBytes: 5 << 20, // 5MB ErrorMsg: "Payload too large", }))
Supports clients that don't support PUT/DELETE (e.g., HTML forms):
r.Use(middleware.MethodOverride()) // POST /users?_method=DELETE -> becomes DELETE /users // POST /users (X-HTTP-Method-Override: PUT) -> becomes PUT /users
| Issue | Fix |
|---|---|
| RateLimiter sync.Map memory leak | Added periodic cleanup (clears keys unseen for 10 minutes every 5 minutes) |
| JWT middleware validation was a stub | Changed to require Validator function, rejects all without one (secure default) |
| Brotli compression sent fake header | Removed fake Content-Encoding: br, keeping only gzip |
| CircuitBreaker race condition | Added sync.Mutex to protect state reads/writes |
| CSRF/RequestID used insecure fastrand | Changed to crypto/rand
|
The Security middleware pre-computes all header values (XSS, nosniff, HSTS, CSP) as immutable strings at initialization, captured by closures. During request processing, strings are set directly without fmt.Sprintf or string concatenation:
// One-time computation at initialization sec := middleware.Security(middleware.SecurityConfig{ HSTSMaxAge: 31536000, HSTSIncludeSubdomains: true, }) // -> Pre-computes hstsValue = "max-age=31536000; includeSubDomains" // -> Each request only executes c.Header("Strict-Transport-Security", hstsValue) // -> Zero allocation, zero GC pressure
設計文件
套件
- config — 設定
- context — 請求上下文
- router — 路由器
- server — 伺服器
- middleware — 中介層
- websocket — WebSocket
- hidb — 資料庫 ORM
- hidb/cassandra — Cassandra
- logger — 日誌
- json — JSON 處理
- grpc — gRPC
AI 協作工具鏈
- schema — Schema-first 路由
- manifest — 專案 Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — 智慧 Scaffold
- airules — AI Rules
CLI 命令
- hyp 總覽
- hyp new
- hyp api
- hyp run
- hyp restart
- hyp generate
- hyp migrate
- hyp context
- hyp ai-rules
- hyp chkcomment
- hyp impact
- hyp docker
- hyp health
- hyp version
- hyp difflog
Design Docs
Packages
- config — Configuration
- context — Request Context
- router — Router
- server — Server
- middleware — Middleware
- websocket — WebSocket
- hidb — Database ORM
- hidb/cassandra - Cassandra 5.0
- logger — Logger
- json — JSON
- grpc — gRPC
AI Collaboration Toolchain
- schema — Schema-first Routing
- manifest — Project Manifest
- contract — Contract Testing
- errors — Typed Error Catalog
- migrate — Migration Diff
- scaffold — Smart Scaffold
- airules — AI Rules
CLI Commands