Feature Request: Automatic HEAD request handling

Open
#2,895 16 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
42/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
go
Domain
api, backend

Research direction

Start at the e.GET() route-registration entry point and compare it with the proposed middleware.AutoHead() approach. Review the existing router and route-registration behavior, then determine how automatic HEAD handling should work when no explicit HEAD route exists. Done means GET routes serve HEAD requests with response bodies omitted without changing explicit HEAD behavior.

Written by the indexing model from the issue text.

Description

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?
Dominant language
Go
Stars
32.7k
Forks
2.8k
Avg merge
9h 39m
Merged PRs (30d)
6

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from labstack/echo

All issues in labstack/echo

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.