Add infrastructure to support native rules (#160)

Author: jonbodner-buf

packages/protovalidate/src/native/dispatcher.ts

@@ -0,0 +1,68 @@
+// Copyright 2024-2026 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { DescField } from "@bufbuild/protobuf";
+import type {
+  PathBuilder,
+  ReflectMessageGet,
+} from "@bufbuild/protobuf/reflect";
+import type { FieldRules } from "../gen/buf/validate/validate_pb.js";
+import type { Eval } from "../eval.js";
+import type { RegexMatcher } from "../func.js";
+
+/**
+ * Result of {@link tryBuildNative}.
+ *
+ * - "none": no native handler applies; the planner enrolls every set field in
+ *   the CEL evaluator as it does today.
+ * - "partial" / "full": at least one field is handled natively. The planner
+ *   skips CEL enrollment for fields in `handledFields` and appends `eval` to
+ *   the rule's `EvalMany`. "full" indicates every set field on the rules
+ *   message was handled natively, so the trailing `EvalStandardRulesCel` will
+ *   be empty and pruned.
+ */
+export type NativeDispatchResult =
+  | { kind: "none" }
+  | {
+      kind: "partial" | "full";
+      eval: Eval<ReflectMessageGet>;
+      handledFields: ReadonlySet<DescField>;
+    };
+
+/**
+ * Inputs to the native rule dispatcher.
+ *
+ * Future phases add per-field-type evaluators here. Phase 0 wires the seam
+ * but always returns `{ kind: "none" }`.
+ */
+export type NativeDispatchInput = {
+  rules: Exclude<FieldRules["type"]["value"], undefined>;
+  rulePath: PathBuilder;
+  forMapKey: boolean;
+  regexMatch: RegexMatcher | undefined;
+};
+
+/**
+ * Decide whether the given rules submessage can be evaluated natively, and
+ * return an `Eval` for the handled subset plus the set of rule fields that
+ * have been claimed (so the planner skips them on the CEL path).
+ *
+ * Phase 0: stub. Returns `{ kind: "none" }` so the CEL path handles every
+ * rule exactly as before.
+ */
+export function tryBuildNative(
+  _input: NativeDispatchInput,
+): NativeDispatchResult {
+  return { kind: "none" };
+}

packages/protovalidate/src/native/format.test.ts

@@ -0,0 +1,66 @@
+// Copyright 2024-2026 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { suite, test } from "node:test";
+import * as assert from "node:assert/strict";
+import { codepointLength, printFloat } from "./format.js";
+
+void suite("codepointLength", () => {
+  void test("counts ASCII as one per char", () => {
+    assert.strictEqual(codepointLength(""), 0);
+    assert.strictEqual(codepointLength("a"), 1);
+    assert.strictEqual(codepointLength("abc"), 3);
+  });
+
+  void test("counts surrogate pair as one code point", () => {
+    // U+1D44E MATHEMATICAL ITALIC SMALL A → surrogate pair "𝑎"
+    const s = "𝑎";
+    assert.strictEqual(s.length, 2);
+    assert.strictEqual(codepointLength(s), 1);
+  });
+
+  void test("counts combining marks separately", () => {
+    // "é" as e + combining acute accent: 2 code points.
+    const s = "é";
+    assert.strictEqual(codepointLength(s), 2);
+  });
+
+  void test("matches CEL size() spread-based count", () => {
+    const cases = ["", "x", "𝑎b", "🇺🇸", "héllo"];
+    for (const s of cases) {
+      assert.strictEqual(codepointLength(s), [...s].length);
+    }
+  });
+});
+
+void suite("printFloat", () => {
+  void test("formats finite numbers via toString", () => {
+    assert.strictEqual(printFloat(0), "0");
+    assert.strictEqual(printFloat(1), "1");
+    assert.strictEqual(printFloat(-1.5), "-1.5");
+    assert.strictEqual(printFloat(1e20), "100000000000000000000");
+  });
+
+  void test("formats NaN", () => {
+    assert.strictEqual(printFloat(Number.NaN), "NaN");
+  });
+
+  void test("formats +Infinity", () => {
+    assert.strictEqual(printFloat(Number.POSITIVE_INFINITY), "Infinity");
+  });
+
+  void test("formats -Infinity", () => {
+    assert.strictEqual(printFloat(Number.NEGATIVE_INFINITY), "-Infinity");
+  });
+});

packages/protovalidate/src/native/format.ts

@@ -0,0 +1,47 @@
+// Copyright 2024-2026 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Number of Unicode code points in a string.
+ *
+ * Matches CEL's `size(string)` semantics — counting code points rather than
+ * UTF-16 code units. A surrogate pair like "𝑎" counts as 1.
+ */
+export function codepointLength(s: string): number {
+  // String iteration yields one element per code point.
+  let n = 0;
+  for (const _ of s) {
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Format a number for inclusion in a violation message.
+ *
+ * Mirrors protovalidate-go's `printFloat` so error messages match the CEL
+ * implementation byte-for-byte.
+ */
+export function printFloat(n: number): string {
+  if (Number.isNaN(n)) {
+    return "NaN";
+  }
+  if (n === Number.POSITIVE_INFINITY) {
+    return "Infinity";
+  }
+  if (n === Number.NEGATIVE_INFINITY) {
+    return "-Infinity";
+  }
+  return n.toString();
+}

packages/protovalidate/src/native/index.ts

@@ -0,0 +1,19 @@
+// Copyright 2024-2026 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export {
+  tryBuildNative,
+  type NativeDispatchInput,
+  type NativeDispatchResult,
+} from "./dispatcher.js";

packages/protovalidate/src/planner.ts

@@ -79,13 +79,17 @@ import {
   EvalStandardRulesCel,
 } from "./cel.js";
 import { CompilationError } from "./error.js";
+import { tryBuildNative } from "./native/index.js";
+import type { RegexMatcher } from "./func.js";
 
 export class Planner {
   private readonly messageCache = new Map<DescMessage, Eval<ReflectMessage>>();
 
   constructor(
     private readonly celMan: CelManager,
     private readonly legacyRequired: boolean,
+    private readonly disableNativeRules: boolean,
+    private readonly regexMatch: RegexMatcher | undefined,
   ) {}
 
   plan(message: DescMessage): Eval<ReflectMessage> {
@@ -431,15 +435,27 @@ export class Planner {
   ) {
     const ruleDesc = getRuleDescriptor(rules.$typeName);
     const prepared = this.celMan.compileRules(ruleDesc);
+    const native = this.disableNativeRules
+      ? ({ kind: "none" } as const)
+      : tryBuildNative({
+          rules,
+          rulePath,
+          forMapKey,
+          regexMatch: this.regexMatch,
+        });
     const evalStandard = new EvalStandardRulesCel(
       this.celMan,
       rules,
       forMapKey,
     );
+    const handled = native.kind === "none" ? undefined : native.handledFields;
     for (const plan of prepared.standard) {
       if (!isFieldSet(rules, plan.field)) {
         continue;
       }
+      if (handled?.has(plan.field)) {
+        continue;
+      }
       evalStandard.add(
         plan.compiled,
         rulePath.clone().field(plan.field).toPath(),
@@ -468,7 +484,14 @@ export class Planner {
         }
       }
     }
-    return new EvalMany(evalStandard, evalExtended);
+    const combined = new EvalMany<ReflectMessageGet>(
+      evalStandard,
+      evalExtended,
+    );
+    if (native.kind !== "none") {
+      combined.add(native.eval);
+    }
+    return combined;
   }
 
   private messageCel(messageRules: MessageRules): Eval<ReflectMessage> {

packages/protovalidate/src/validator.test.ts

@@ -296,6 +296,45 @@ void suite("Validator", () => {
       assert.equal(result.kind, "valid");
     });
   });
+  void suite("option disableNativeRules", () => {
+    const schema = compileMessage(
+      `
+        syntax="proto3";
+        import "buf/validate/validate.proto";
+        message Example {
+          int32 n = 1 [(buf.validate.field).int32.gt = 0];
+          string s = 2 [(buf.validate.field).string.min_len = 3];
+        }
+        `,
+      bufCompileOptions,
+    );
+    const invalid = create(schema, { n: 0, s: "ab" });
+    const valid = create(schema, { n: 1, s: "abc" });
+    void test("createValidator accepts the option", () => {
+      const v = createValidator({ disableNativeRules: true });
+      assert.ok(typeof v.validate == "function");
+    });
+    void test("default and disabled paths agree on a valid message", () => {
+      const def = createValidator().validate(schema, valid);
+      const off = createValidator({ disableNativeRules: true }).validate(
+        schema,
+        valid,
+      );
+      assert.equal(def.kind, "valid");
+      assert.equal(off.kind, "valid");
+    });
+    void test("default and disabled paths produce identical violations", () => {
+      const def = createValidator().validate(schema, invalid);
+      const off = createValidator({ disableNativeRules: true }).validate(
+        schema,
+        invalid,
+      );
+      assert.equal(def.kind, "invalid");
+      assert.equal(off.kind, "invalid");
+      const fmt = (v: Violation) => v.toString();
+      assert.deepEqual(def.violations?.map(fmt), off.violations?.map(fmt));
+    });
+  });
   void suite("predefined rules", () => {
     const descFile = compileFile(
       `

packages/protovalidate/src/validator.ts

@@ -77,6 +77,17 @@ export type ValidatorOptions = {
    * By default, legacy required field are not validated.
    */
   legacyRequired?: boolean;
+
+  /**
+   * Disable the native (non-CEL) implementation of standard rules.
+   *
+   * By default, validation uses hand-written checks for most standard
+   * buf.validate.field rules. Setting this option to true forces every
+   * standard rule through CEL instead. Behavior is identical either way;
+   * the flag exists to isolate the native path during debugging or to
+   * compare conformance.
+   */
+  disableNativeRules?: boolean;
 };
 
 /**
@@ -136,8 +147,14 @@ export function createValidator(opt?: ValidatorOptions): Validator {
     ? createMutableRegistry(opt.registry, file_buf_validate_validate)
     : createMutableRegistry(file_buf_validate_validate);
   const failFast = opt?.failFast ?? false;
-  const celMan = new CelManager(registry, opt?.regexMatch);
-  const planner = new Planner(celMan, opt?.legacyRequired ?? false);
+  const regexMatch = opt?.regexMatch;
+  const celMan = new CelManager(registry, regexMatch);
+  const planner = new Planner(
+    celMan,
+    opt?.legacyRequired ?? false,
+    opt?.disableNativeRules ?? false,
+    regexMatch,
+  );
   return {
     validate<
       Desc extends DescMessage,