Skip to content

README.md

Latest commit

 

History

History
158 lines (113 loc) · 4.46 KB

README.md

File metadata and controls

158 lines (113 loc) · 4.46 KB

Middleware

Production-ready HTTP middleware for rivaas/router. Each middleware is provided in its own sub-package with comprehensive configuration options, examples, and tests.

📚 Full Documentation: For comprehensive middleware documentation, see the Middleware Guide and Middleware Reference.

Available Middlewares

Security

  • Security - Security headers (HSTS, CSP, X-Frame-Options, etc.)
  • CORS - Cross-Origin Resource Sharing
  • BasicAuth - HTTP Basic Authentication

Observability

  • AccessLog - Structured HTTP access logging
  • RequestID - Request ID generation and tracking

Reliability

  • Recovery - Panic recovery with graceful error handling
  • Timeout - Request timeout handling
  • RateLimit - Token bucket rate limiting
  • BodyLimit - Request body size limiting

Performance

Other

Quick Start

package main

import (
    "log/slog"
    "net/http"
    "os"
    
    "rivaas.dev/router"
    "rivaas.dev/middleware/accesslog"
    "rivaas.dev/middleware/recovery"
    "rivaas.dev/middleware/requestid"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    r := router.New()
    
    // Apply middleware globally
    r.Use(requestid.New())
    r.Use(accesslog.New(accesslog.WithLogger(logger)))
    r.Use(recovery.New())
    
    r.GET("/", func(c *router.Context) {
        c.String(200, "Hello, World!")
    })
    
    http.ListenAndServe(":8080", r)
}

Package Structure

Each middleware package typically contains:

middleware/
├── accesslog/
│   ├── accesslog.go              # Implementation
│   ├── accesslog_test.go         # Unit tests
│   ├── options.go                # Configuration options
│   ├── doc.go                    # Package documentation
│   ├── go.mod                    # Module definition
│   └── example/                  # Runnable example (most packages)
│       ├── main.go
│       └── go.mod
├── basicauth/
│   └── ...
└── ...

Some packages have extra files (for example, ratelimit has stores.go for rate limit storage backends). Not every middleware has an options.go (e.g. trailingslash uses defaults only).

Examples

Each middleware package includes a runnable example in an example/ subdirectory.

# Run the BasicAuth example
cd middleware/basicauth/example
go run main.go

# Run the AccessLog example
cd middleware/accesslog/example
go run main.go

Each example shows basic usage, common patterns, and how to configure the middleware.

Testing

Each middleware has unit tests:

# Run all middleware tests
go test ./middleware/...

# Run tests for a specific middleware
go test ./middleware/basicauth/...
go test ./middleware/accesslog/...

Middleware Ordering

Recommended middleware order:

r := router.New()

r.Use(requestid.New())       // 1. Request ID
r.Use(accesslog.New())       // 2. AccessLog
r.Use(recovery.New())        // 3. Recovery
r.Use(security.New())        // 4. Security/CORS
r.Use(cors.New())            
r.Use(bodylimit.New())       // 5. Body Limit
r.Use(ratelimit.New())       // 6. Rate Limit
r.Use(timeout.New())         // 7. Timeout
r.Use(basicauth.New())       // 8. Authentication
r.Use(compression.New())     // 9. Compression (last)

Learn More

Contributing

When adding new middleware:

  1. Create a new subdirectory under middleware/
  2. Follow the existing pattern: name.go, options.go, doc.go, name_test.go
  3. Use functional options for configuration
  4. Include unit tests
  5. Add a runnable example in an example/ subdirectory
  6. Create its own go.mod for independent versioning
  7. Add a README.md in the package and update this doc and the documentation site

License

Apache License 2.0 - see LICENSE for details.