feat(context): add ValidateCtx (#3152)

* feat: pass request context to context-aware validators

* feat: make context-aware validation explicit

* test(context): cover request replacement in ValidateCtx

Document context-aware validation precedence, embedded wrapper responsibilities, and cancellation handling.

---------

Co-authored-by: Vishal Rana <v@labstack.com>

Author: shblue21

context.go

@@ -5,6 +5,7 @@ package echo
 
 import (
 	"bytes"
+	stdContext "context"
 	"encoding/xml"
 	"errors"
 	"fmt"
@@ -460,6 +461,10 @@ func (c *Context) Bind(i any) error {
 	return c.echo.Binder.Bind(c, i)
 }
 
+type validatorCtx interface {
+	ValidateCtx(ctx stdContext.Context, i any) error
+}
+
 // Validate validates provided `i`. It is usually called after `Context#Bind()`.
 // Validator must be registered using `Echo#Validator`.
 func (c *Context) Validate(i any) error {
@@ -469,6 +474,27 @@ func (c *Context) Validate(i any) error {
 	return c.echo.Validator.Validate(i)
 }
 
+// ValidateCtx validates i using the current request's context. If the registered
+// Validator implements ValidateCtx(context.Context, any) error, that method is
+// called instead of Validate. Otherwise, Validate is called.
+//
+// The validator must still implement Validate to satisfy the Validator interface.
+// Wrappers that embed a context-aware validator must implement ValidateCtx if they
+// need to preserve checks performed by their own Validate method.
+//
+// If there is no request, context.Background() is used. Cancellation and deadlines
+// are passed to the validator; the validator is responsible for honoring them.
+func (c *Context) ValidateCtx(i any) error {
+	if v, ok := c.echo.Validator.(validatorCtx); ok {
+		ctx := stdContext.Background()
+		if req := c.Request(); req != nil {
+			ctx = req.Context()
+		}
+		return v.ValidateCtx(ctx, i)
+	}
+	return c.Validate(i)
+}
+
 // Render renders a template with data and sends a text/html response with status
 // code. Renderer must be registered using `Echo.Renderer`.
 func (c *Context) Render(code int, name string, data any) (err error) {

context_test.go

@@ -5,9 +5,11 @@ package echo
 
 import (
 	"bytes"
+	stdContext "context"
 	"crypto/tls"
 	"encoding/json"
 	"encoding/xml"
+	"errors"
 	"fmt"
 	"io"
 	"io/fs"
@@ -1119,10 +1121,137 @@ func TestContext_Validate(t *testing.T) {
 	e := New()
 	c := e.NewContext(nil, nil)
 
-	assert.Error(t, c.Validate(struct{}{}))
+	assert.ErrorIs(t, c.Validate(struct{}{}), ErrValidatorNotRegistered)
+	assert.ErrorIs(t, c.ValidateCtx(struct{}{}), ErrValidatorNotRegistered)
 
 	e.Validator = &validator{}
 	assert.NoError(t, c.Validate(struct{}{}))
+	assert.NoError(t, c.ValidateCtx(struct{}{}))
+}
+
+type validationFunc func(any) error
+
+func (v validationFunc) Validate(i any) error { return v(i) }
+
+type contextValidator struct {
+	validationFunc
+	validateCtx func(stdContext.Context, any) error
+}
+
+func (v contextValidator) ValidateCtx(ctx stdContext.Context, i any) error {
+	return v.validateCtx(ctx, i)
+}
+
+func TestContext_Validate_legacyError(t *testing.T) {
+	e := New()
+	c := e.NewContext(nil, nil)
+	payload := &struct{ Name string }{Name: "Jon Snow"}
+	wantErr := errors.New("validation failed")
+	e.Validator = validationFunc(func(i any) error {
+		assert.Same(t, payload, i)
+		return wantErr
+	})
+	assert.Same(t, wantErr, c.Validate(payload))
+	assert.Same(t, wantErr, c.ValidateCtx(payload))
+}
+
+type validationWrapper struct {
+	contextValidator
+	err error
+}
+
+func (v validationWrapper) Validate(any) error { return v.err }
+
+func TestContext_Validate_wrapper(t *testing.T) {
+	e := New()
+	c := e.NewContext(nil, nil)
+	wantErr := errors.New("wrapper validation failed")
+	e.Validator = validationWrapper{
+		contextValidator: contextValidator{
+			validateCtx: func(stdContext.Context, any) error {
+				t.Fatal("Validate must not call an embedded ValidateCtx method")
+				return nil
+			},
+		},
+		err: wantErr,
+	}
+	assert.Same(t, wantErr, c.Validate(struct{}{}))
+}
+
+func TestContext_ValidateCtx_withContext(t *testing.T) {
+	ctx, cancel := stdContext.WithCancel(stdContext.Background())
+	defer cancel()
+	e := New()
+	c := e.NewContext(nil, nil)
+	c.SetRequest(httptest.NewRequest(http.MethodGet, "/", nil).WithContext(ctx))
+	payload := &struct{ Name string }{Name: "Jon Snow"}
+	wantErr := errors.New("validation failed")
+	calls := 0
+	e.Validator = contextValidator{
+		validationFunc: func(any) error {
+			t.Fatal("Validate must not be called when ValidateCtx is implemented")
+			return nil
+		},
+		validateCtx: func(got stdContext.Context, i any) error {
+			calls++
+			assert.Same(t, ctx, got)
+			assert.Same(t, payload, i)
+			return wantErr
+		},
+	}
+
+	assert.Same(t, wantErr, c.ValidateCtx(payload))
+	assert.Equal(t, 1, calls)
+
+	cancel()
+	assert.Same(t, wantErr, c.ValidateCtx(payload))
+	assert.Equal(t, 2, calls)
+}
+
+func TestContext_ValidateCtx_requestReplacement(t *testing.T) {
+	firstCtx, cancelFirst := stdContext.WithCancel(stdContext.Background())
+	defer cancelFirst()
+	secondCtx, cancelSecond := stdContext.WithCancel(stdContext.Background())
+	defer cancelSecond()
+
+	e := New()
+	c := e.NewContext(httptest.NewRequest(http.MethodGet, "/", nil).WithContext(firstCtx), nil)
+	var gotCtx stdContext.Context
+	e.Validator = contextValidator{
+		validationFunc: func(any) error {
+			t.Fatal("Validate must not be called when ValidateCtx is implemented")
+			return nil
+		},
+		validateCtx: func(ctx stdContext.Context, _ any) error {
+			gotCtx = ctx
+			return nil
+		},
+	}
+
+	assert.NoError(t, c.ValidateCtx(struct{}{}))
+	assert.Same(t, firstCtx, gotCtx)
+
+	c.SetRequest(c.Request().WithContext(secondCtx))
+	assert.NoError(t, c.ValidateCtx(struct{}{}))
+	assert.Same(t, secondCtx, gotCtx)
+}
+
+func TestContext_ValidateCtx_withoutRequest(t *testing.T) {
+	e := New()
+	c := e.NewContext(nil, nil)
+	var gotCtx stdContext.Context
+	e.Validator = contextValidator{
+		validateCtx: func(ctx stdContext.Context, i any) error {
+			gotCtx = ctx
+			return nil
+		},
+	}
+
+	assert.NoError(t, c.ValidateCtx(struct{}{}))
+	if assert.NotNil(t, gotCtx) {
+		assert.NoError(t, gotCtx.Err())
+		assert.Nil(t, gotCtx.Done())
+	}
 }
 
 func TestContext_QueryString(t *testing.T) {