Middleware

Nova has ready-to-use middleware for net/http. In this document, you will find the list of built-in middleware and how to use them.

What is Middleware?
Custom Middleware
Built-in Middleware

What is Middleware?

In the context of Nova’s web handling capabilities (using Go’s standard net/http package), middleware refers to a function that wraps an http.Handler. It follows the standard Go pattern: a function that takes an http.Handler and returns a new http.Handler.

// Middleware defines the function signature for middleware.
// A middleware is a function that wraps an http.Handler, adding extra behavior.
type Middleware func(http.Handler) http.Handler

Middleware functions sit between the server’s routing logic (like nova.Router) and your final request handler (http.HandlerFunc). They provide a way to process the http.Request and http.ResponseWriter or perform actions before or after your main handler logic runs.

Think of it like layers processing an incoming HTTP request:

An HTTP request arrives.
Nova’s router directs the request towards the appropriate handler.
If middleware is applied (e.g., via router.Use(...)), the request passes through each middleware function in sequence.
Each middleware can:
- Examine or modify the http.Request (e.g., add context values, parse headers).
- Wrap the http.ResponseWriter to intercept or modify the response (e.g., capture status code, compress data).
- Perform tasks like logging, timing, authentication checks, authorization, rate limiting, or setting common headers.
- Decide whether to pass control to the next handler in the chain by calling next.ServeHTTP(w, r).
- Perform tasks after the next handler has completed (e.g., logging the response status, cleanup).
Finally, the core http.HandlerFunc for the route is executed (if the middleware chain allowed it).

Key Benefits of Using Middleware:

Separation of Concerns: Keeps cross-cutting logic (like logging, authentication, compression, security headers) separate from your core request handling logic, making handlers cleaner and more focused.
Reusability: Write common pre-processing or post-processing logic once as middleware and apply it to multiple routes or groups of routes easily using router.Use(...) or group.Use(...).
Composability: Chain multiple, small middleware functions together to build complex request processing pipelines in a modular and maintainable way.

This pattern is fundamental to building web applications and APIs in Go.

Custom Middleware

You can easily create your own middleware by defining a function that matches the nova.Middleware type signature:

type Middleware func(http.Handler) http.Handler

Here’s a simple example of a custom middleware that adds a custom header to every response:

// CustomHeaderMiddleware adds a "X-Custom-Header" to responses.
func CustomHeaderMiddleware(headerName, headerValue string) nova.Middleware {
    // Return the actual middleware function
    return func(next http.Handler) http.Handler {
        // Return the HandlerFunc that wraps the next handler
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // Set the header before calling the next handler
            w.Header().Set(headerName, headerValue)

            // Call the next middleware or handler in the chain
            next.ServeHTTP(w, r)

            // Could also perform actions *after* the handler runs here
        })
    }
}

// And then somewhere else where you want to use it on a router/group/subrouter:
router.Use(CustomHeaderMiddleware("X-App-Version", "1.2.3"))

Built-in Middleware

Nova provides a collection of standard net/http middleware. Each middleware is typically configured using a specific Config struct and applied using router.Use(...) for global application or group.Use(...) for group-specific application.

LoggingMiddleware

Description: Logs incoming requests (start) and outgoing responses (completion), including method, path, remote address, status code, response size, and duration.
Configuration: nova.LoggingConfig
- Logger *log.Logger: Logger instance (defaults to log.Default()).
- LogRequestID bool: Include request ID in logs (defaults to true). Requires RequestIDMiddleware.
- RequestIDKey contextKey: Context key for request ID (defaults to internal key).