Add HTTP QUERY Method Support (RFC 10008)

docs/advanced-guide/http-communication/page.md

@@ -12,7 +12,7 @@ GoFr promotes microservice architecture and to facilitate the same, it provides
 at application level using `AddHTTPService()` method.
 
 Support for inter-service HTTP calls provide the following benefits:
-1. Access to the methods from container - GET, PUT, POST, PATCH, DELETE.
+1. Access to the methods from container - GET, PUT, POST, PATCH, DELETE, QUERY.
 2. Logs and traces for the request.
 3. {% new-tab-link newtab=false title="Circuit breaking" href="/docs/advanced-guide/circuit-breaker" /%} for enhanced resilience and fault tolerance.
 4. {% new-tab-link newtab=false title="Custom Health Check" href="/docs/advanced-guide/monitoring-service-health" /%} Endpoints
@@ -83,6 +83,9 @@ The HTTP service client provides methods for making requests to downstream servi
 
 - `Delete(ctx, path, body)`
 
+- `Query(ctx, path, queryParams, body)`
+
+
 **For scenarios requiring custom header propagation (authentication, multi-tenancy, user identity propagation), use the `WithHeaders` variants:**
 
 - `GetWithHeaders(ctx, path, queryParams, headers)`
@@ -95,6 +98,13 @@ The HTTP service client provides methods for making requests to downstream servi
 
 - `DeleteWithHeaders(ctx, path, body, headers)`
 
+- `QueryWithHeaders(ctx, path, queryParams, body, headers)`
+
+> **QUERY** (RFC 10008) is a safe, idempotent method that carries the query in the
+> request body — bridging the gap between GET (no body) and POST (not safe/idempotent).
+> Like GET, QUERY calls are wrapped by the circuit-breaker and retry options when configured.
+
+
 ```go
 func Customer(ctx *gofr.Context) (any, error) {
 	// Get the payment service client

examples/http-server/main.go

@@ -28,6 +28,10 @@ func main() {
 	a.GET("/trace", TraceHandler)
 	a.GET("/mysql", MysqlHandler)
 
+	// QUERY (RFC 10008): a safe, idempotent method that carries the query in the
+	// request body. Read the body via ctx.Bind, the same as a POST.
+	a.QUERY("/search", SearchHandler)
+
 	// Run the application
 	a.Run()
 }
@@ -46,6 +50,20 @@ func ErrorHandler(c *gofr.Context) (any, error) {
 	return nil, errors.New("some error occurred")
 }
 
+// SearchHandler demonstrates the HTTP QUERY method: the search criteria arrive in
+// the request body and are echoed back as the query result.
+func SearchHandler(c *gofr.Context) (any, error) {
+	criteria := struct {
+		Filter string `json:"filter"`
+	}{}
+
+	if err := c.Bind(&criteria); err != nil {
+		return nil, err
+	}
+
+	return map[string]string{"matched": criteria.Filter}, nil
+}
+
 func RedisHandler(c *gofr.Context) (any, error) {
 	val, err := c.Redis.Get(c, "test").Result()
 	if err != nil && err != redis.Nil { // If key is not found, we are not considering this an error and returning "".

examples/http-server/main_test.go

@@ -25,6 +25,7 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/go-redis/redismock/v9"
 	"github.com/stretchr/testify/assert"
@@ -95,6 +96,39 @@ func TestIntegration_SimpleAPIServer(t *testing.T) {
 	}
 }
 
+func TestIntegration_QueryHandler(t *testing.T) {
+	httpPort := testutil.GetFreePort(t)
+	port := testutil.GetFreePort(t)
+
+	t.Setenv("HTTP_PORT", strconv.Itoa(httpPort))
+	t.Setenv("METRICS_PORT", strconv.Itoa(port))
+
+	host := fmt.Sprintf("http://localhost:%d", httpPort)
+
+	go main()
+	time.Sleep(100 * time.Millisecond) // Giving some time to start the server
+
+	req, _ := http.NewRequest("QUERY", host+"/search", strings.NewReader(`{"filter":"golang"}`))
+	req.Header.Set("content-type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	b, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	data := struct {
+		Data map[string]string `json:"data"`
+	}{}
+	require.NoError(t, json.Unmarshal(b, &data))
+	assert.Equal(t, "golang", data.Data["matched"])
+}
+
+
 func TestIntegration_SimpleAPIServer_Errors(t *testing.T) {
 	httpPort := testutil.GetFreePort(t)
 	port := testutil.GetFreePort(t)
@@ -347,6 +381,7 @@ func TestTraceHandler(t *testing.T) {
 
 	ctx := createTestContext(http.MethodGet, "/trace", mockContainer)
 
+
 	// HTTP service mock - use mocks.HTTPServices["serviceName"] to access the specific service
 	// Important: Use the map keyed by service name, not mocks.HTTPService (singular)
 	mockResp := &http.Response{

pkg/gofr/gofr_test.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"path/filepath"
 	"strconv"
+	"strings"
 	"sync"
 	"testing"
 	"time"
@@ -1935,3 +1936,55 @@ func Test_HTTPMethods(t *testing.T) {
 		})
 	}
 }
+
+// Test_QUERY_Registration verifies that app.QUERY registers a route for the HTTP
+// QUERY method (RFC 10008) and that the handler can read the request body via Bind.
+func Test_QUERY_Registration(t *testing.T) {
+	port := testutil.GetFreePort(t)
+
+	c := container.NewContainer(config.NewMockConfig(nil))
+
+	app := &App{
+		httpServer: &httpServer{
+			router: gofrHTTP.NewRouter(),
+			port:   port,
+		},
+		container: c,
+		Config: config.NewMockConfig(map[string]string{
+			"REQUEST_TIMEOUT":       "5",
+			"SHUTDOWN_GRACE_PERIOD": "1s",
+		}),
+	}
+
+	app.QUERY("/search", func(ctx *Context) (any, error) {
+		body := struct {
+			Filter string `json:"filter"`
+		}{}
+		if err := ctx.Bind(&body); err != nil {
+			return nil, err
+		}
+
+		return map[string]string{"filter": body.Filter}, nil
+	})
+
+	go app.Run()
+
+	time.Sleep(100 * time.Millisecond)
+
+	netClient := &http.Client{Timeout: 500 * time.Millisecond}
+
+	req, _ := http.NewRequestWithContext(t.Context(), "QUERY",
+		fmt.Sprintf("http://localhost:%d/search", port), strings.NewReader(`{"filter":"title"}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := netClient.Do(req)
+	require.NoError(t, err)
+
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+
+	respBody, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	assert.Contains(t, string(respBody), `"filter":"title"`)
+}

pkg/gofr/mcp.go

@@ -29,10 +29,12 @@ func WithExcludedRoutes(paths ...string) MCPOption {
 	}
 }
 
-// EnableMCP exposes the app's read-only HTTP handlers (GET/HEAD/OPTIONS) as agent-callable tools over
-// an MCP server on its own port (MCP_PORT, default 8200; MCP_PORT=0 disables the server). Write
-// handlers are never exposed, so an agent cannot mutate state through this surface. The tools are also
-// reachable in handlers via ctx.LLM().Tools() regardless of whether the server is enabled.
+// EnableMCP exposes the app's safe HTTP handlers — read-only methods (GET/HEAD/OPTIONS) and QUERY
+// (RFC 10008, safe and idempotent, whose query payload is passed as a "body" tool argument) — as
+// agent-callable tools over an MCP server on its own port (MCP_PORT, default 8200; MCP_PORT=0 disables
+// the server). Write handlers (POST/PUT/PATCH/DELETE) are never exposed, so an agent cannot mutate
+// state through this surface. The tools are also reachable in handlers via ctx.LLM().Tools() regardless
+// of whether the server is enabled.
 func (a *App) EnableMCP(opts ...MCPOption) {
 	cfg := &mcpConfig{exclude: make(map[string]bool)}
 	for _, o := range opts {

pkg/gofr/mcp_test.go

@@ -328,3 +328,72 @@ func TestHelpers(t *testing.T) {
 	assert.Equal(t, "42", scalar(json.RawMessage(`"42"`)))
 	assert.Equal(t, "true", scalar(json.RawMessage(`true`)))
 }
+
+func TestRouterTools_List_ExposesQuery(t *testing.T) {
+	app, rt := testRouterTools(t)
+	app.QUERY("/search", func(*Context) (any, error) { return nil, nil })
+	app.POST("/write", func(*Context) (any, error) { return nil, nil })
+
+	specs := rt.List()
+	names := toolNames(specs)
+
+	assert.Contains(t, names, "query_search", "QUERY handlers are exposed (safe + idempotent)")
+	assert.NotContains(t, names, "post_write", "write handlers remain unexposed")
+
+	// The QUERY tool must advertise a required "body" argument for the query payload.
+	var querySpec ai.ToolSpec
+
+	for _, s := range specs {
+		if s.Name == "query_search" {
+			querySpec = s
+		}
+	}
+
+	require.NotEmpty(t, querySpec.Name)
+	assert.Equal(t, ai.ReadOnly, querySpec.Access, "QUERY is safe, so it is ReadOnly")
+
+	schema := map[string]any{}
+	require.NoError(t, json.Unmarshal(querySpec.InputSchema, &schema))
+
+	props, _ := schema["properties"].(map[string]any)
+	assert.Contains(t, props, "body", "QUERY tool schema must include a body property")
+	assert.Contains(t, schema["required"], "body", "body must be required")
+}
+
+func TestRouterTools_Call_QueryForwardsBody(t *testing.T) {
+	app, rt := testRouterTools(t)
+	app.QUERY("/search", func(c *Context) (any, error) {
+		payload := map[string]any{}
+		if err := c.Bind(&payload); err != nil {
+			return nil, err
+		}
+
+		return payload, nil
+	})
+
+	res, err := rt.Call(t.Context(), "query_search", json.RawMessage(`{"body":{"filter":"title"}}`))
+	require.NoError(t, err)
+
+	body, err := res.JSON()
+	require.NoError(t, err)
+	assert.Contains(t, string(body), `"filter":"title"`, "the QUERY body must reach the handler")
+}
+
+func TestRouterTools_Call_QueryWithPathParamAndBody(t *testing.T) {
+	app, rt := testRouterTools(t)
+	app.QUERY("/index/{name}/search", func(c *Context) (any, error) {
+		payload := map[string]any{}
+		_ = c.Bind(&payload)
+		payload["index"] = c.PathParam("name")
+
+		return payload, nil
+	})
+
+	res, err := rt.Call(t.Context(), "query_index_name_search",
+		json.RawMessage(`{"name":"books","body":{"q":"go"}}`))
+	require.NoError(t, err)
+
+	body, _ := res.JSON()
+	assert.Contains(t, string(body), `"index":"books"`)
+	assert.Contains(t, string(body), `"q":"go"`)
+}

pkg/gofr/rest.go

@@ -30,6 +30,16 @@ func (a *App) PATCH(pattern string, handler Handler) {
 	a.add("PATCH", pattern, handler)
 }
 
+// QUERY adds a Handler for the HTTP QUERY method (RFC 10008) for a route pattern.
+// QUERY is a safe, idempotent method that carries a request body describing the
+// query; read it in the handler via ctx.Bind, the same way as a POST body.
+// Per RFC 10008 a server should reject a QUERY with a missing/invalid Content-Type
+// with 400; gofr does not enforce this automatically, so validate it in the handler
+// when required.
+func (a *App) QUERY(pattern string, handler Handler) {
+	a.add(methodQuery, pattern, handler)
+}
+
 func (a *App) add(method, pattern string, h Handler) {
 	if !a.httpRegistered && !isPortAvailable(a.httpServer.port) {
 		a.container.Logger.Fatalf("http port %d is blocked or unreachable", a.httpServer.port)

pkg/gofr/service/auth.go

@@ -82,3 +82,18 @@ func (a *authProvider) DeleteWithHeaders(ctx context.Context, path string, body
 
 	return a.HTTP.DeleteWithHeaders(ctx, path, body, headers)
 }
+
+func (a *authProvider) Query(ctx context.Context, path string, queryParams map[string]any,
+	body []byte) (*http.Response, error) {
+	return a.QueryWithHeaders(ctx, path, queryParams, body, nil)
+}
+
+func (a *authProvider) QueryWithHeaders(ctx context.Context, path string, queryParams map[string]any,
+	body []byte, headers map[string]string) (*http.Response, error) {
+	headers, err := a.auth(ctx, headers)
+	if err != nil {
+		return nil, err
+	}
+
+	return a.HTTP.QueryWithHeaders(ctx, path, queryParams, body, headers)
+}

pkg/gofr/service/auth_test.go

@@ -60,7 +60,7 @@ func TestAuthProvider(t *testing.T) {
 		{authOption: validOAuthConfig, headers: map[string]string{AuthHeader: "auth-string"}, err: authHeaderExistsErr},
 	}
 
-	httpMethods := []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete}
+	httpMethods := []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete, methodQuery}
 
 	for i, tc := range testCases {
 		t.Run(fmt.Sprintf("Test Case #%d", i), func(t *testing.T) {
@@ -143,6 +143,8 @@ func callHTTPServiceWithHeaders(ctx context.Context, service HTTP, method string
 		return service.PatchWithHeaders(ctx, path, queryParams, body, headers)
 	case http.MethodDelete:
 		return service.DeleteWithHeaders(ctx, path, body, headers)
+	case methodQuery:
+		return service.QueryWithHeaders(ctx, path, queryParams, body, headers)
 	default:
 		return nil, AuthErr{Message: "unknown method"}
 	}
@@ -164,6 +166,8 @@ func callHTTPServiceWithoutHeaders(ctx context.Context, service HTTP, method str
 		return service.Patch(ctx, path, queryParams, body)
 	case http.MethodDelete:
 		return service.Delete(ctx, path, body)
+	case methodQuery:
+		return service.Query(ctx, path, queryParams, body)
 	default:
 		return nil, AuthErr{Message: "unknown method"}
 	}

pkg/gofr/service/circuit_breaker.go

@@ -3,6 +3,7 @@ package service
 import (
 	"context"
 	"errors"
+	"fmt"
 	"net/http"
 	"sync"
 	"time"
@@ -18,6 +19,8 @@ var (
 	// ErrCircuitOpen indicates that the circuit breaker is open.
 	ErrCircuitOpen                        = errors.New("unable to connect to server at host")
 	ErrUnexpectedCircuitBreakerResultType = errors.New("unexpected result type from circuit breaker")
+	// ErrUnsupportedMethod indicates that the circuit breaker was asked to route an HTTP method it does not handle.
+	ErrUnsupportedMethod = errors.New("unsupported HTTP method for circuit breaker")
 )
 
 // CircuitBreakerConfig holds the configuration for the circuitBreaker.
@@ -255,6 +258,12 @@ func (cb *circuitBreaker) doRequest(ctx context.Context, method, path string, qu
 		result, err = cb.executeWithCircuitBreaker(ctx, func(ctx context.Context) (*http.Response, error) {
 			return cb.HTTP.DeleteWithHeaders(ctx, path, body, headers)
 		})
+	case methodQuery:
+		result, err = cb.executeWithCircuitBreaker(ctx, func(ctx context.Context) (*http.Response, error) {
+			return cb.HTTP.QueryWithHeaders(ctx, path, queryParams, body, headers)
+		})
+	default:
+		return nil, fmt.Errorf("%w: %q", ErrUnsupportedMethod, method)
 	}
 
 	resp, err := cb.handleCircuitBreakerResult(result, err)
@@ -321,3 +330,15 @@ func (cb *circuitBreaker) Delete(ctx context.Context, path string, body []byte)
 	*http.Response, error) {
 	return cb.doRequest(ctx, http.MethodDelete, path, nil, body, nil)
 }
+
+// QueryWithHeaders is a wrapper for doRequest with the QUERY method and headers.
+func (cb *circuitBreaker) QueryWithHeaders(ctx context.Context, path string, queryParams map[string]any,
+	body []byte, headers map[string]string) (*http.Response, error) {
+	return cb.doRequest(ctx, methodQuery, path, queryParams, body, headers)
+}
+
+// Query is a wrapper for doRequest with the QUERY method.
+func (cb *circuitBreaker) Query(ctx context.Context, path string, queryParams map[string]any,
+	body []byte) (*http.Response, error) {
+	return cb.doRequest(ctx, methodQuery, path, queryParams, body, nil)
+}