Add ValidateContext for cancellation and timeout support by tonobo · Pull Request #327 · bufbuild/protovalidate-go

tonobo · 2026-07-02T07:36:19Z

Add a context-aware ValidateContext(ctx, msg, options...) function alongside Validate() to let callers constrain lengthy or complex validations (e.g., CEL rule evaluation over large collections) using context cancellation or deadlines.

Content:

Add a ContextValidator interface (Validator plus ValidateContext). New now returns ContextValidator, so New() callers get ValidateContext directly while still satisfying Validator. This keeps the change backward compatible: the Validator interface is unchanged, so external implementations of Validator keep compiling.
Add the package-level ValidateContext helper and implement ValidateContext on the global validator. Validate() delegates to ValidateContext(context.Background(), ...), keeping a single code path.
Thread context through every evaluator via parallel *Context methods; the non-context methods delegate with context.Background(), so behavior is unchanged on the Validate() path.
Evaluate CEL through cel-go's ContextEval and enable InterruptCheckFrequency so a single long-running expression can be interrupted mid-evaluation.
Check ctx.Err() at message entry and in the repeated/map iteration loops so native validation of large messages also honors cancellation.
Return the raw context error (context.Canceled / DeadlineExceeded), never wrapped, so callers can match it with errors.Is.

CLAassistant · 2026-07-02T07:36:32Z

All committers have signed the CLA.

tonobo · 2026-07-02T07:43:37Z

@pkwarren Would you like to give it a shot? 😄

rodaine · 2026-07-09T14:24:00Z

Hi, @tonobo, thanks for the patch! I'd like to dig into your use-case here, could you share some details on the size of the message you're validating where cancellation is relevant? What type of validation rules are you using that are this CPU intensive?

It's cool to see that cel-go added support for context-aware execution, but I'm wary of foisting this behavior onto all users of this library when most messages are evaluated on the order of a microsecond. I'd love it if you could add benchmarks to show that this does not regress the default usage.

tonobo · 2026-07-09T15:19:17Z

Hey, great to hear someone is interested in this contribution!

First, the use case: imagine a global repository managing all contracts, so
besides the actual proto definitions there is also type validation in place.
As time goes on, types get more nested and more complicated. CEL rules start
iterating over objects, and one thing leads to another: inefficient rules get
introduced. Nothing actually prevents you from writing nested loops over
maps :D

To make this concrete, here is an example. A message holds a list of named sets plus several rule lists that reference
those sets by key, and cross-field CEL rules enforce referential integrity:

    message Firewall {
      option (buf.validate.message).cel = {
        id: "ipset_keys_unique"
        message: "ipset keys must be unique within this firewall"
        expression: "this.ipsets.map(s, string(s.key.type) + ':' + s.key.name).unique()"
      };

      // one of these exists per rule list (ingress/egress, several stages),
      // so this pattern repeats 4+ times on the same message
      option (buf.validate.message).cel = {
        id: "ingress_ipsets_exist"
        message: "all ingress rules must only reference ipsets which exist within this firewall"
        expression:
          "this.ingress.rules.all(rule, rule.remote_ipsets.all(key,"
          "this.ipsets.exists(ipset, ipset.key.type == key.type && ipset.key.name == key.name)))"
      };

      // ...
    }

Each of those rules is O(rules * refs_per_rule * ipsets), so validation cost
grows roughly cubically with message size, and there are several such rules
per message. Perfectly reasonable contracts to enforce, but on large messages
the evaluation time explodes.

CEL provides different options to tackle this. On one end, you can set
program-based cost limits. I considered that as well, but program compilation
happens at a different level, so it would have to be an option on the
initializer, not a per-validation option. That's why we decided to go the
other way around and address the problem from the other end: context
cancellation. AFAIR cel-go internally uses context.Background() anyway, the
main adjustment is the InterruptCheckFrequency() we attach to the evaluation.
I haven't fully dug into the cel-go internals, but it probably just adds a
periodic check and might cost a few extra cycles. My guess is the overhead is
minimal.

In conclusion: protovalidate is used to enforce contracts between parties,
and context cancellation brings more trust into "anonymous rules". Assume a
bad case: a message in the queue costs you 10s to validate, your workers are
busy validating protos all the time, and suddenly quadratic (or worse) CEL
expression costs are a real problem.

Regarding the benchmarks: fair point! I'll attach a benchmark test comparing
the default branch against this one.

Introduce a context-aware ValidateContext(ctx, msg, options...) alongside the existing Validate(), so callers can bound long or expensive validation with a context deadline or cancellation. The motivating case is complex validation work such as CEL rules over large collections. Content: - Add a ContextValidator interface (Validator plus ValidateContext). New now returns ContextValidator, so New() callers get ValidateContext directly while still satisfying Validator. The change is backward compatible: the Validator interface is unchanged, so external implementations of it keep compiling. - Add the package-level ValidateContext helper and implement ValidateContext on the global validator. - Thread context through every evaluator via parallel *Context methods. - Evaluate CEL through cel-go's ContextEval and enable InterruptCheckFrequency so a long-running expression can be interrupted mid-evaluation. - Check ctx.Err() at message entry and in the repeated/map iteration loops so native validation of large messages also honors cancellation. - Return the raw context error (context.Canceled / DeadlineExceeded), never wrapped, so callers can match it with errors.Is. Keeping Validate() free of overhead: A context that can never be cancelled (context.Background) has a nil Done channel. ValidateContext detects this once per call and selects one of two validation configs built at New(); evaluation then skips every per-node ctx.Err() check and calls cel-go's Eval rather than ContextEval, whose activation wrapping would otherwise be paid on every expression. Validate() therefore takes the same path it did before context support existed, and neither entry point allocates to carry the flag. Choosing the interrupt check frequency: cel-go only checks for cancellation inside comprehension loops (all, exists, map, filter), once per iteration, and never for expressions without a comprehension. The frequency does not skip that per-iteration bookkeeping; it only gates a cheap non-blocking poll of ctx.Done(). Raising it therefore buys no measurable throughput while making cancellation latency proportionally worse: on the BenchCrossReference fixture a 50ms deadline is honored in 50ms at frequency 1, but takes 2.2s at frequency 100. The default is therefore 1, and WithCELInterruptCheckFrequency lets callers tune or disable it (0). Benchmarks: - BenchmarkContextOverhead compares Validate, ValidateContext with a background context, and ValidateContext with a cancellable context. - BenchmarkInterruptCheckFrequency shows throughput is flat across frequencies. - BenchCrossReference is a new message whose CEL rule costs O(n^3), used to test that an expensive expression is actually interrupted by a deadline.

tonobo · 2026-07-09T20:46:51Z

Validate no longer pays for context support: the validator now detects whether the context can be cancelled at all (ctx.Done() != nil). If
not, it skips every ctx.Err() check and uses plain Eval instead of ContextEval, so the non-context path costs the same as before this PR.
Benchmarks added (BenchmarkContextOverhead).
New BenchCrossReference test message with an expensive cross-referencing CEL rule, used to prove a deadline actually interrupts a
long-running expression.

tonobo · 2026-07-16T07:24:57Z

@rodaine Is there anything else I can do for you? It would be great if we could make some progress here :D Sorry for bugging you. 🙈

pkwarren

Thank you for adding some benchmarks. It would be good to gather benchstat output from before/after this change to ensure no regressions.

Overall the changes look good but this should be opt-in behavior for users with expensive validation constraints.

pkwarren · 2026-07-16T19:15:26Z

+// frequency only gates the (very cheap) non-blocking channel poll. Raising it
+// therefore buys no measurable throughput, while making cancellation latency
+// proportionally worse. 1 is the responsive default.
+const DefaultInterruptCheckFrequency = 1


We should remove this constant and interrupt checks should be disabled by default (matching CEL's defaults). To this point no users of protovalidate-go have requested this feature and shouldn't require this additional overhead by default. We can always re-evaluate the default later.

pkwarren · 2026-07-16T19:39:39Z

 	Evaluate(msg protoreflect.Message, val protoreflect.Value, cfg *validationConfig) error
+
+	// EvaluateContext is like Evaluate, but honors context cancellation.
+	EvaluateContext(ctx context.Context, msg protoreflect.Message, val protoreflect.Value, cfg *validationConfig) error


Instead of overloads on the evaluator (internal interface) all the way down we should just update the signature for Evaluate to take a ctx context.Context.

pkwarren · 2026-07-16T19:39:50Z

+
+	// EvaluateMessageContext is like EvaluateMessage, but honors context
+	// cancellation.
+	EvaluateMessageContext(ctx context.Context, msg protoreflect.Message, cfg *validationConfig) error


Same here for EvaluateMessage.

pkwarren · 2026-07-16T19:41:52Z


-func (m *kvPairs) evalPairs(msg protoreflect.Message, key protoreflect.MapKey, value protoreflect.Value, cfg *validationConfig) (err error) {
-	evalErr := m.KeyRules.EvaluateField(msg, key.Value(), cfg, true)
+func (m *kvPairs) evalPairsContext(ctx context.Context, msg protoreflect.Message, key protoreflect.MapKey, value protoreflect.Value, cfg *validationConfig) (err error) {


Just change the existing method to take a context as the first argument instead of changing every method to add Context suffix.

pkwarren · 2026-07-16T19:43:19Z

 	val.Map().Range(func(key protoreflect.MapKey, value protoreflect.Value) bool {
-		evalErr := m.evalPairs(msg, key, value, cfg)
+		if cfg.cancellable {
+			if ctxErr := ctx.Err(); ctxErr != nil {


We should update these checks to use context.Cause(ctx) instead of ctx.Err().

pkwarren · 2026-07-16T19:45:11Z

 		return nil
 	}
+	if cfg.cancellable {
+		if err := ctx.Err(); err != nil {


Should use context.Cause(ctx) here.

pkwarren · 2026-07-16T19:46:27Z

+		// is a genuine evaluation error and must keep its RuntimeError identity
+		// (with the rule id) even if the context has expired in the meantime.
+		if errors.Is(err, interpreter.InterruptError{}) {
+			if ctxErr := ctx.Err(); ctxErr != nil {


Use context.Cause(ctx) here.

pkwarren · 2026-07-16T19:48:50Z


+func TestCompiled_ContextCancelled(t *testing.T) {
+	t.Parallel()
+	ctx, cancel := context.WithCancel(context.Background())


Suggested change

ctx, cancel := context.WithCancel(context.Background())

ctx, cancel := context.WithCancel(t.Context())

pkwarren · 2026-07-16T20:45:13Z

+//
+// ContextValidator is a separate interface (rather than a method on Validator)
+// to preserve backward compatibility for external implementations of Validator.
+type ContextValidator interface {


Instead of introducing a new ContextValidator and changing the primary API for users, we should add a ValidationOption named WithContext which takes a context to bound the validate call. The default value would be context.Background() if unset.

The rest of the changes (checking cancelable, passing down a context to evaluators) would largely stay the same.

rodaine self-assigned this Jul 9, 2026

tonobo force-pushed the add-validate-context branch from c9a35a6 to 0686058 Compare July 9, 2026 20:45

pkwarren reviewed Jul 16, 2026

View reviewed changes

	ctx, cancel := context.WithCancel(context.Background())
	ctx, cancel := context.WithCancel(t.Context())

Uh oh!

Conversation

tonobo commented Jul 2, 2026

Uh oh!

CLAassistant commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tonobo commented Jul 2, 2026

Uh oh!

rodaine commented Jul 9, 2026

Uh oh!

tonobo commented Jul 9, 2026

Uh oh!

tonobo commented Jul 9, 2026

Uh oh!

tonobo commented Jul 16, 2026

Uh oh!

pkwarren left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkwarren Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Jul 2, 2026 •

edited

Loading

pkwarren Jul 16, 2026 •

edited

Loading