feat: add support for the HTTP QUERY method (RFC 10008) (#1187)

RFC 10008 defines QUERY, a safe and idempotent HTTP method that carries the query as request content, filling the gap between GET and POST.

- Add the MethodQuery constant.
- Add the Request.Query(url) helper, matching the existing verb helpers.
- Send the request body for QUERY (isPayloadSupported), since QUERY always carries content.
- Classify QUERY as idempotent (enables automatic retries) and read-only (enables hedging), per its RFC 10008 safe and idempotent semantics.
- Add tests for the helper and the classification.

* docs: add early-adoption note to Request.Query (review)

Author: thatwasyahya

client.go

@@ -47,6 +47,9 @@ const (
 
 	// MethodTrace is the HTTP TRACE method.
 	MethodTrace = "TRACE"
+
+	// MethodQuery is the HTTP QUERY method.
+	MethodQuery = "QUERY"
 )
 
 const (

hedging.go

@@ -284,7 +284,7 @@ func (ht *Hedging) RoundTrip(req *http.Request) (*http.Response, error) {
 // isReadOnlyMethod reports whether the HTTP method is read-only (safe for hedging).
 func isReadOnlyMethod(method string) bool {
 	switch method {
-	case MethodGet, MethodHead, MethodOptions, MethodTrace:
+	case MethodGet, MethodHead, MethodOptions, MethodTrace, MethodQuery:
 		return true
 	default:
 		return false

query_test.go

@@ -0,0 +1,41 @@
+package resty
+
+import (
+	"io"
+	"net/http"
+	"testing"
+)
+
+func TestQuery(t *testing.T) {
+	ts := createTestServer(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != MethodQuery {
+			t.Errorf("expected method %q, got %q", MethodQuery, r.Method)
+		}
+		body, _ := io.ReadAll(r.Body)
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write(body)
+	})
+	defer ts.Close()
+
+	resp, err := dcnl().R().
+		SetHeader("Content-Type", "application/sql").
+		SetBody("select * from users limit 10").
+		Query(ts.URL + "/")
+
+	assertError(t, err)
+	assertEqual(t, http.StatusOK, resp.StatusCode())
+	assertEqual(t, "select * from users limit 10", resp.String())
+
+	logResponse(t, resp)
+}
+
+func TestQueryMethodClassification(t *testing.T) {
+	// QUERY is safe and idempotent per RFC 10008, so it must be treated as
+	// read-only (hedging) and idempotent (automatic retries).
+	assertEqual(t, true, isReadOnlyMethod(MethodQuery))
+
+	r := dcnl().R()
+	r.Method = MethodQuery
+	assertEqual(t, true, r.isIdempotent())
+}

request.go

@@ -1438,6 +1438,18 @@ func (r *Request) Trace(url string) (*Response, error) {
 	return r.Execute(MethodTrace, url)
 }
 
+// Query method does QUERY HTTP request. QUERY is a safe, idempotent method that
+// carries the query as request content; it's defined in section 2 of [RFC 10008].
+//
+// NOTE:
+//   - RFC is in the early stage of adoption in the industry; server side and browsers
+//     are yet to add support. You may run into unexpected failures due to infrastructure/environment.
+//
+// [RFC 10008]: https://datatracker.ietf.org/doc/html/rfc10008.html#section-2
+func (r *Request) Query(url string) (*Response, error) {
+	return r.Execute(MethodQuery, url)
+}
+
 // Send method performs the HTTP request using the method and URL already defined
 // for current [Request].
 //
@@ -1800,7 +1812,8 @@ func (r *Request) isPayloadSupported() bool {
 		return true
 	}
 
-	if r.Method == MethodPost || r.Method == MethodPut || r.Method == MethodPatch {
+	// QUERY (RFC 10008) always carries the query as request content.
+	if r.Method == MethodPost || r.Method == MethodPut || r.Method == MethodPatch || r.Method == MethodQuery {
 		return true
 	}
 
@@ -1853,6 +1866,7 @@ var idempotentMethods = map[string]struct{}{
 	MethodHead:    {},
 	MethodOptions: {},
 	MethodPut:     {},
+	MethodQuery:   {},
 	MethodTrace:   {},
 }