Feature Request: Automatic HEAD request handling

[dmeremyanin]

Currently, Echo requires explicit HEAD route registration for every GET route. Some other frameworks like Fiber, Express and Fastify handle this automatically. According to HTTP semantics, HEAD should behave identically to GET except that the response body is omitted. Automatically supporting HEAD for GET routes aligns with this expectation and reduces boilerplate.

Related: #654

Proposal

Add automatic HEAD handling for GET routes when no explicit HEAD route is registered.

Implementation Options

Option 1: Middleware approach

e := echo.New()
e.Use(middleware.AutoHead())

Pros:

• Opt-in
• No changes to core routing
• Simple implementation

Cons:

• Must be registered last in the middleware chain. Otherwise, middlewares registered after it will not execute for HEAD requests, since the middleware directly invokes the handler and bypasses the remaining chain

I've already implemented this approach, but after testing I realized the middleware ordering requirement makes it less convenient and more error-prone.

Option 2: Core integration

Auto-register HEAD routes during e.GET() calls, controlled by config :

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

Default value could remain false to avoid breaking existing behavior.

Pros:

• No middleware ordering constraints
• Slightly better performance, since re-routing is avoided

Cons:

• Requires changes to core Echo router/route registration

Questions

1. Would the Echo team be interested in this functionality?
2. If so, which implementation approach would be preferred: middleware or core integration? Would you consider a PR for either approach?

[aldas]

I've already implemented this approach, but after testing I realized the middleware ordering requirement makes it less convenient.

You can procably use e.Pre(middleware.AutoHead()) as it is run before routing is done. Switch the r.Method and maybe switch responseWriter to no-op one.

[dmeremyanin]

I actually tried the e.Pre() approach, but ran into two issues:

1. Detecting explicit HEAD routes

With e.Pre(), routing hasn't happened yet, so I'd need to manually run the router to detect if an explicit HEAD route exists - essentially routing twice.

2. Method visible in downstream middleware

With e.Pre(), I rewrite request method to GET before calling next(c). The method stays as GET through the entire chain (routing -> e.Use() middleware -> handler) and only gets restored to HEAD after next(c) returns. This means loggers, auth middleware, etc. would log/see GET instead of HEAD, which is misleading.

[aldas]

With e.Pre(), routing hasn't happened yet, so I'd need to manually run the router to detect if an explicit HEAD route exists - essentially routing twice

for skipping specific cases the Skipper callback exists. Are you trying to create some universal solution or is it custom application? For later case - you already know what actual HEAD routes you actually have and can skip them probably by doing simple prefix check.

[aldas]

Another remark: this logic does not suit into Router because HEAD responses as omitted. But GET routes can be duplicated to HEAD routes when custom Router router adds it be GET is added. Another way is to use echo.OnAddRoute callback.

	e.OnAddRoute = func(route echo.Route) error {
		if route.Method == http.MethodHead {
			return nil
		}
		if route.Method == http.MethodGet {
			// route.Method = http.MethodHead 
			// route.Middlewares = append(route.Middlewares, noopResponseMw())
			//_, _ = e.AddRoute(route) // add head route for each GET
			return nil
		}
		return nil
	}

but omitting response body can be done with custom http.ResponseWriter implementation and that can be done with (pre)middleware.

---

Here is example custom router implementation that composes default router https://github.com/labstack/echo/blob/master/router_concurrent.go

[dmeremyanin]

But GET routes can be duplicated to HEAD routes when custom Router router adds it be GET is added. Another way is to use echo.OnAddRoute callback.

That's exactly what I had in mind for option 2: using OnAddRoute to auto-register HEAD routes when GET routes are added. However, if it were implemented as a built-in Echo feature (e.g., an e.AutoHead = true config), it would need to preserve the ability for users to set their own OnAddRoute callback.

Are you trying to create some universal solution or is it custom application?

I think it would be beneficial to have this built into Echo, since it aligns with the HTTP spec and other frameworks handle it automatically.
For my specific application, I can live with custom middleware, which must be included last in the chain.