feat: add support for HTTP QUERY method (#3036)

Add first-class support for the QUERY HTTP method (RFC 10008) so it can
be registered with dedicated helpers instead of the generic `Add`.

QUERY is not (yet) part of the `net/http` standard library, so it is
defined in Echo the same way the existing non-standard PROPFIND and
REPORT methods are handled:

- add the `QUERY` method constant
- add `Echo.QUERY` and `Group.QUERY` route helpers
- give QUERY a dedicated field in `routeMethods` and wire it into
  `set`, `find`, `updateAllowHeader` and `isHandler`
- bind URL query parameters for QUERY (like GET/DELETE/HEAD), since
  QUERY is semantically a GET carrying its query in the body

Closes #3036

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

bind.go

@@ -125,11 +125,11 @@ func (b *DefaultBinder) Bind(c *Context, target any) error {
 	if err := BindPathValues(c, target); err != nil {
 		return err
 	}
-	// Only bind query parameters for GET/DELETE/HEAD to avoid unexpected behavior with destination struct binding from body.
+	// Only bind query parameters for GET/DELETE/HEAD/QUERY to avoid unexpected behavior with destination struct binding from body.
 	// For example a request URL `&id=1&lang=en` with body `{"id":100,"lang":"de"}` would lead to precedence issues.
 	// The HTTP method check restores pre-v4.1.11 behavior to avoid these problems (see issue #1670)
 	method := c.Request().Method
-	if method == http.MethodGet || method == http.MethodDelete || method == http.MethodHead {
+	if method == http.MethodGet || method == http.MethodDelete || method == http.MethodHead || method == QUERY {
 		if err := BindQueryParams(c, target); err != nil {
 			return err
 		}

bind_test.go

@@ -814,6 +814,13 @@ func TestDefaultBinder_BindToStructFromMixedSources(t *testing.T) {
 			givenContent: strings.NewReader(`{"id": 1, "node": "zzz"}`),
 			expect:       &Opts{ID: 1, Node: "zzz"}, // for DELETE body is bound after query params
 		},
+		{
+			name:         "ok, QUERY bind to struct with: path param + query param + body",
+			givenMethod:  QUERY,
+			givenURL:     "/api/real_node/endpoint?node=xxx",
+			givenContent: strings.NewReader(`{"id": 1}`),
+			expect:       &Opts{ID: 1, Node: "xxx"}, // for QUERY query overwrites previous path value (like GET)
+		},
 		{
 			name:         "ok, POST bind to struct with: path param + body",
 			givenMethod:  http.MethodPost,

echo.go

@@ -170,6 +170,9 @@ const (
 	PROPFIND = "PROPFIND"
 	// REPORT Method can be used to get information about a resource, see rfc 3253
 	REPORT = "REPORT"
+	// QUERY Method is a safe, idempotent request method carrying request content (a query) in its body, see rfc 10008.
+	// It is not (yet) part of the `net/http` standard library, so Echo defines it here.
+	QUERY = "QUERY"
 	// RouteNotFound is special method type for routes handling "route not found" (404) cases
 	RouteNotFound = "echo_route_not_found"
 	// RouteAny is special method type that matches any HTTP method in request. Any has lower
@@ -539,6 +542,12 @@ func (e *Echo) PUT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
 	return e.Add(http.MethodPut, path, h, m...)
 }
 
+// QUERY registers a new QUERY route for a path with matching handler in the
+// router with optional route-level middleware. Panics on error.
+func (e *Echo) QUERY(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
+	return e.Add(QUERY, path, h, m...)
+}
+
 // TRACE registers a new TRACE route for a path with matching handler in the
 // router with optional route-level middleware. Panics on error.
 func (e *Echo) TRACE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {

echo_test.go

@@ -908,6 +908,23 @@ func TestEchoTrace(t *testing.T) {
 	assert.Equal(t, "OK", body)
 }
 
+func TestEchoQuery(t *testing.T) {
+	e := New()
+
+	ri := e.QUERY("/", func(c *Context) error {
+		return c.String(http.StatusTeapot, "OK")
+	})
+
+	assert.Equal(t, QUERY, ri.Method)
+	assert.Equal(t, "/", ri.Path)
+	assert.Equal(t, QUERY+":/", ri.Name)
+	assert.Nil(t, ri.Parameters)
+
+	status, body := request(QUERY, "/", e)
+	assert.Equal(t, http.StatusTeapot, status)
+	assert.Equal(t, "OK", body)
+}
+
 func TestEcho_Any(t *testing.T) {
 	e := New()
 

group.go

@@ -63,6 +63,11 @@ func (g *Group) PUT(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
 	return g.Add(http.MethodPut, path, h, m...)
 }
 
+// QUERY implements `Echo#QUERY()` for sub-routes within the Group. Panics on error.
+func (g *Group) QUERY(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
+	return g.Add(QUERY, path, h, m...)
+}
+
 // TRACE implements `Echo#TRACE()` for sub-routes within the Group. Panics on error.
 func (g *Group) TRACE(path string, h HandlerFunc, m ...MiddlewareFunc) RouteInfo {
 	return g.Add(http.MethodTrace, path, h, m...)

group_test.go

@@ -306,6 +306,24 @@ func TestGroup_TRACE(t *testing.T) {
 	assert.Equal(t, `OK`, body)
 }
 
+func TestGroup_QUERY(t *testing.T) {
+	e := New()
+
+	users := e.Group("/users")
+	ri := users.QUERY("/activate", func(c *Context) error {
+		return c.String(http.StatusTeapot, "OK")
+	})
+
+	assert.Equal(t, QUERY, ri.Method)
+	assert.Equal(t, "/users/activate", ri.Path)
+	assert.Equal(t, QUERY+":/users/activate", ri.Name)
+	assert.Nil(t, ri.Parameters)
+
+	status, body := request(QUERY, "/users/activate", e)
+	assert.Equal(t, http.StatusTeapot, status)
+	assert.Equal(t, `OK`, body)
+}
+
 func TestGroup_RouteNotFound(t *testing.T) {
 	var testCases = []struct {
 		expectRoute any

router.go

@@ -161,6 +161,7 @@ type routeMethods struct {
 	put      *routeMethod
 	trace    *routeMethod
 	report   *routeMethod
+	query    *routeMethod
 	any      *routeMethod
 	anyOther map[string]*routeMethod
 
@@ -196,6 +197,8 @@ func (m *routeMethods) set(method string, r *routeMethod) {
 		m.trace = r
 	case REPORT:
 		m.report = r
+	case QUERY:
+		m.query = r
 	case RouteAny:
 		m.any = r
 	case RouteNotFound:
@@ -239,6 +242,8 @@ func (m *routeMethods) find(method string, fallbackToAny bool) *routeMethod {
 		r = m.trace
 	case REPORT:
 		r = m.report
+	case QUERY:
+		r = m.query
 	case RouteAny:
 		r = m.any
 	case RouteNotFound:
@@ -295,6 +300,9 @@ func (m *routeMethods) updateAllowHeader() {
 	if hasAnyMethod || m.report != nil {
 		buf.WriteString(", REPORT")
 	}
+	if hasAnyMethod || m.query != nil {
+		buf.WriteString(", QUERY")
+	}
 	for method := range m.anyOther { // for simplicity, we use map and therefore order is not deterministic here
 		buf.WriteString(", ")
 		buf.WriteString(method)
@@ -314,6 +322,7 @@ func (m *routeMethods) isHandler() bool {
 		m.propfind != nil ||
 		m.trace != nil ||
 		m.report != nil ||
+		m.query != nil ||
 		m.any != nil ||
 		len(m.anyOther) != 0
 	// RouteNotFound/404 is not considered as a handler

router_test.go

@@ -761,6 +761,7 @@ func TestRouter_addAndMatchAllSupportedMethods(t *testing.T) {
 		{name: "ok, PUT", whenMethod: http.MethodPut},
 		{name: "ok, TRACE", whenMethod: http.MethodTrace},
 		{name: "ok, REPORT", whenMethod: REPORT},
+		{name: "ok, QUERY", whenMethod: QUERY},
 		{name: "ok, NON_TRADITIONAL_METHOD", whenMethod: "NON_TRADITIONAL_METHOD"},
 		{
 			name:            "ok, NOT_EXISTING_METHOD",