Feat: Add Automatic HEAD Support for GET Routes

[atharvaSharma17]

What this does

This adds an optional AutoHead flag that automatically enables HEAD requests for any GET route. No need to define separate HEAD handlers anymore.

Why this is useful

Right now, if you want proper HEAD support, you have to manually add a HEAD route for every GET route. That leads to:

• Repeated boilerplate
• Easy-to-miss HEAD routes (resulting in 405 errors)
• Inconsistent headers like missing Content-Length

According to HTTP spec (RFC 7231), HEAD should behave like GET without a body — so this just makes Echo handle that for you.

How it works

When AutoHead is turned on:

• Every GET route automatically gets a HEAD equivalent
• The same handler runs, but the response body is suppressed
• Headers and status code are preserved
• Content-Length is still set correctly
• If you’ve defined a HEAD route manually, it won’t be overridden

Implementation notes

• Added AutoHead to Echo and Config
• Wrapped handlers using a custom response writer
• Hooked into route registration (add()) to register HEAD routes

Usage

e := echo.New()
e.AutoHead = true

e.GET("/api/users", handler)
// HEAD /api/users now works automatically

Performance

Very small overhead:

• ~532 ns per request
• 3 allocations

No impact if the feature is disabled (default).

Testing

Covers:

• Enabled vs disabled behavior
• Explicit HEAD route priority
• Middleware compatibility

All tests pass.

---

Compatibility

• No breaking changes
• Fully opt-in
• Existing code works as-is
  Feature Request: Automatic HEAD request handling #2895 @markbates @aldas

[vishr]

Thank you for tackling this — automatic HEAD support has been one of our most-requested features (#2895). We're consolidating the work into #2949, which takes a router-level approach with an opt-in hook so users keep control. Closing this in favor of that PR, but your work helped shape the direction and it's genuinely appreciated. Please follow and review #2949. 🙏