httpsnoop

The httpsnoop package uses code generation to create specialized wrappers for http.ResponseWriter. These wrappers (named rwXXX where XXX is a combination index) are designed to preserve the original interface capabilities of the underlying http.ResponseWriter while adding snooping functionality.

When you use a snooping function, it returns a wrapper that implements a specific combination of standard Go interfaces. This ensures that if the original ResponseWriter supported features like http.Pusher, http.Hijacker, or io.StringWriter, the wrapped version continues to support them, preventing type assertion failures in middleware or downstream handlers.

Commonly supported interface combinations include:

• http.ResponseWriter + httpFlushError + io.ReaderFrom + http.Pusher + io.StringWriter (e.g., rw147, rw151, rw155, rw159, rw171, rw175, rw183)
• http.ResponseWriter + httpFlushError + http.Hijacker + deadliner (e.g., rw168, rw169, rw170, rw171, rw172, rw173, rw174, rw175)
• http.ResponseWriter + httpFlushError + http.Hijacker + fullDuplexEnabler (e.g., rw164, rw165, rw166, rw167, rw168)

All generated wrappers implement the Unwrap() http.ResponseWriter method, allowing you to retrieve the original, unwrapped http.ResponseWriter.

Use httpsnoop.CaptureMetrics to wrap an http.Handler and automatically capture request metrics including the HTTP status code, response duration, and the number of bytes written. This is useful for logging or monitoring request performance.

CaptureMetrics returns an httpsnoop.Metrics struct containing:

• Code: The HTTP status code.
• Duration: The time taken to process the request.
• Written: The number of bytes written to the response.

Note that CaptureMetrics handles edge cases like WriteHeader being called multiple times or not at all, and manages concurrent calls to http.ResponseWriter methods.

// myH is your app's http handler, perhaps a http.ServeMux or similar.
var myH http.Handler
// wrappedH wraps myH in order to log every request.
wrappedH := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	m := httpsnoop.CaptureMetrics(myH, w, r)
	log.Printf(
		"%s %s (code=%d dt=%s written=%d)",
		r.Method,
		r.URL,
		m.Code,
		m.Duration,
		m.Written,
	)
})
http.ListenAndServe(":8080", wrappedH)

Use Wrap(w http.ResponseWriter, hooks Hooks) to create a wrapped version of an existing http.ResponseWriter. The returned object implements the exact same set of optional interfaces as the original (e.g., http.Flusher, http.Hijacker, io.StringWriter, etc.).

Each field in the Hooks struct acts as a middleware for a specific method. If a hook is provided, it intercepts the call, allowing you to modify arguments or return values. If no hook is provided for a method, the call is passed through to the underlying ResponseWriter directly.

Key Behaviors:

• Interface Fidelity: The wrapped ResponseWriter preserves all optional interfaces implemented by the original w.
• Precedence: Exact matching hooks take precedence. For example, if a WriteString hook is configured, it will be called even if a Write hook is also present.
• Fallbacks:
  • If WriteString is called but only a Write hook is configured, the call is routed through the Write hook using []byte(s).
  • If FlushError is called but only a Flush hook is configured, FlushError is routed through the Flush hook while preserving the original error.

// Example conceptual usage
wrapped := httpsnoop.Wrap(originalResponseWriter, httpsnoop.Hooks{
	Write: func(next httpsnoop.WriteFunc) httpsnoop.WriteFunc {
		return func(b []byte) (int, error) {
			// Do something before or after the write
			return next(b)
		}
	},
})