Implement MessageOneofRule (#308)

Signed-off-by: Sri Krishna <skrishna@buf.build>

Author: srikrsna-buf

gradle.properties

@@ -1,5 +1,5 @@
 # Version of buf.build/bufbuild/protovalidate to use.
-protovalidate.version = v0.12.0
+protovalidate.version = v1.0.0-rc.2
 
 # Arguments to the protovalidate-conformance CLI
 protovalidate.conformance.args = --strict_message --strict_error --expected_failures=expected-failures.yaml

src/main/java/build/buf/protovalidate/EvaluatorBuilder.java

@@ -19,6 +19,7 @@
 import build.buf.validate.FieldPathElement;
 import build.buf.validate.FieldRules;
 import build.buf.validate.Ignore;
+import build.buf.validate.MessageOneofRule;
 import build.buf.validate.MessageRules;
 import build.buf.validate.OneofRules;
 import build.buf.validate.Rule;
@@ -176,6 +177,7 @@ private void buildMessage(Descriptor desc, MessageEvaluator msgEval)
           return;
         }
         processMessageExpressions(descriptor, msgRules, msgEval, defaultInstance);
+        processMessageOneofRules(descriptor, msgRules, msgEval);
         processOneofRules(descriptor, msgEval);
         processFields(descriptor, msgEval);
       } catch (InvalidProtocolBufferException e) {
@@ -203,6 +205,23 @@ private void processMessageExpressions(
       msgEval.append(new CelPrograms(null, compiledPrograms));
     }
 
+    private void processMessageOneofRules(
+        Descriptor desc, MessageRules msgRules, MessageEvaluator msgEval)
+        throws CompilationException {
+      for (MessageOneofRule rule : msgRules.getOneofList()) {
+        List<FieldDescriptor> fields = new ArrayList<>(rule.getFieldsCount());
+        for (String name : rule.getFieldsList()) {
+          FieldDescriptor field = desc.findFieldByName(name);
+          if (field == null) {
+            throw new CompilationException(
+                String.format("field \"%s\" not found in %s", name, desc.getFullName()));
+          }
+          fields.add(field);
+        }
+        msgEval.append(new MessageOneofEvaluator(fields, rule.getRequired()));
+      }
+    }
+
     private void processOneofRules(Descriptor desc, MessageEvaluator msgEval)
         throws InvalidProtocolBufferException, CompilationException {
       List<Descriptors.OneofDescriptor> oneofs = desc.getOneofs();

src/main/java/build/buf/protovalidate/MessageOneofEvaluator.java

@@ -0,0 +1,76 @@
+// Copyright 2023-2024 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.
+
+package build.buf.protovalidate;
+
+import build.buf.protovalidate.exceptions.ExecutionException;
+import com.google.protobuf.Descriptors.FieldDescriptor;
+import com.google.protobuf.Message;
+import java.util.Collections;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * A specialized {@link Evaluator} for applying {@code buf.validate.MessageOneofRule} to a {@link
+ * com.google.protobuf.Message}.
+ */
+class MessageOneofEvaluator implements Evaluator {
+  /** List of fields that are part of the oneof */
+  public final List<FieldDescriptor> fields;
+
+  /** If at least one must be set. */
+  public final boolean required;
+
+  MessageOneofEvaluator(List<FieldDescriptor> fields, boolean required) {
+    this.fields = fields;
+    this.required = required;
+  }
+
+  @Override
+  public boolean tautology() {
+    return false;
+  }
+
+  @Override
+  public List<RuleViolation.Builder> evaluate(Value val, boolean failFast)
+      throws ExecutionException {
+    Message msg = val.messageValue();
+    if (msg == null) {
+      return RuleViolation.NO_VIOLATIONS;
+    }
+    int hasCount = 0;
+    for (FieldDescriptor field : fields) {
+      if (msg.hasField(field)) {
+        hasCount++;
+      }
+    }
+    if (hasCount > 1) {
+      return Collections.singletonList(
+          RuleViolation.newBuilder()
+              .setRuleId("message.oneof")
+              .setMessage(String.format("only one of %s can be set", fieldNames())));
+    }
+    if (this.required && hasCount == 0) {
+      return Collections.singletonList(
+          RuleViolation.newBuilder()
+              .setRuleId("message.oneof")
+              .setMessage(String.format("one of %s must be set", fieldNames())));
+    }
+    return Collections.emptyList();
+  }
+
+  String fieldNames() {
+    return fields.stream().map(FieldDescriptor::getName).collect(Collectors.joining(", "));
+  }
+}

src/main/resources/buf/validate/validate.proto

@@ -76,7 +76,7 @@ extend google.protobuf.FieldOptions {
 // `Rule` represents a validation rule written in the Common Expression
 // Language (CEL) syntax. Each Rule includes a unique identifier, an
 // optional error message, and the CEL expression to evaluate. For more
-// information on CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md).
+// information, [see our documentation](https://buf.build/docs/protovalidate/schemas/custom-rules/).
 //
 // ```proto
 // message Foo {
@@ -121,8 +121,8 @@ message MessageRules {
   optional bool disabled = 1;
 
   // `cel` is a repeated field of type Rule. Each Rule specifies a validation rule to be applied to this message.
-  // These rules are written in Common Expression Language (CEL) syntax. For more information on
-  // CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md).
+  // These rules are written in Common Expression Language (CEL) syntax. For more information,
+  // [see our documentation](https://buf.build/docs/protovalidate/schemas/custom-rules/).
   //
   //
   // ```proto
@@ -137,6 +137,46 @@ message MessageRules {
   // }
   // ```
   repeated Rule cel = 3;
+
+  // `oneof` is a repeated field of type MessageOneofRule that specifies a list of fields
+  // of which at most one can be present. If `required` is also specified, then exactly one
+  // of the specified fields _must_ be present.
+  //
+  // This will enforce oneof-like constraints with a few features not provided by
+  // actual Protobuf oneof declarations:
+  //   1. Repeated and map fields are allowed in this validation. In a Protobuf oneof,
+  //      only scalar fields are allowed.
+  //   2. Fields with implicit presence are allowed. In a Protobuf oneof, all member
+  //      fields have explicit presence. This means that, for the purpose of determining
+  //      how many fields are set, explicitly setting such a field to its zero value is
+  //      effectively the same as not setting it at all.
+  //   3. This will generate validation errors when unmarshalling, even from the binary
+  //      format. With a Protobuf oneof, if multiple fields are present in the serialized
+  //      form, earlier values are usually silently ignored when unmarshalling, with only
+  //      the last field being present when unmarshalling completes.
+  //
+  //
+  // ```proto
+  // message MyMessage {
+  //   // Only one of `field1` or `field2` _can_ be present in this message.
+  //   option (buf.validate.message).oneof = { fields: ["field1", "field2"] };
+  //   // Only one of `field3` or `field4` _must_ be present in this message.
+  //   option (buf.validate.message).oneof = { fields: ["field3", "field4"], required: true };
+  //   string field1 = 1;
+  //   bytes field2 = 2;
+  //   bool field3 = 3;
+  //   int32 field4 = 4;
+  // }
+  // ```
+  repeated MessageOneofRule oneof = 4;
+}
+
+message MessageOneofRule {
+  // A list of field names to include in the oneof. All field names must be
+  // defined in the message.
+  repeated string fields = 1;
+  // If true, one of the fields specified _must_ be set.
+  optional bool required = 2;
 }
 
 // The `OneofRules` message type enables you to manage rules for
@@ -166,8 +206,8 @@ message OneofRules {
 // the field, the correct set should be used to ensure proper validations.
 message FieldRules {
   // `cel` is a repeated field used to represent a textual expression
-  // in the Common Expression Language (CEL) syntax. For more information on
-  // CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md).
+  // in the Common Expression Language (CEL) syntax. For more information,
+  // [see our documentation](https://buf.build/docs/protovalidate/schemas/custom-rules/).
   //
   // ```proto
   // message MyMessage {
@@ -184,7 +224,7 @@ message FieldRules {
   // described as "serialized in the wire format," which includes:
   //
   // - the following "nullable" fields must be explicitly set to be considered populated:
-  //   - singular message fields (whose fields may be unpopulated / default values)
+  //   - singular message fields (whose fields may be unpopulated/default values)
   //   - member fields of a oneof (may be their default value)
   //   - proto3 optional fields (may be their default value)
   //   - proto2 scalar fields (both optional and required)
@@ -251,8 +291,8 @@ message FieldRules {
 // multiple fields.
 message PredefinedRules {
   // `cel` is a repeated field used to represent a textual expression
-  // in the Common Expression Language (CEL) syntax. For more information on
-  // CEL, [see our documentation](https://github.com/bufbuild/protovalidate/blob/main/docs/cel.md).
+  // in the Common Expression Language (CEL) syntax. For more information,
+  // [see our documentation](https://buf.build/docs/protovalidate/schemas/predefined-rules/).
   //
   // ```proto
   // message MyMessage {
@@ -276,7 +316,7 @@ message PredefinedRules {
 // Specifies how FieldRules.ignore behaves. See the documentation for
 // FieldRules.required for definitions of "populated" and "nullable".
 enum Ignore {
-  // Validation is only skipped if it's an unpopulated nullable fields.
+  // Validation is only skipped if it's an unpopulated nullable field.
   //
   // ```proto
   // syntax="proto3";
@@ -3809,7 +3849,7 @@ message StringRules {
   extensions 1000 to max;
 }
 
-// WellKnownRegex contain some well-known patterns.
+// KnownRegex contains some well-known patterns.
 enum KnownRegex {
   KNOWN_REGEX_UNSPECIFIED = 0;
 
@@ -4816,7 +4856,7 @@ message TimestampRules {
 }
 
 // `Violations` is a collection of `Violation` messages. This message type is returned by
-// protovalidate when a proto message fails to meet the requirements set by the `Rule` validation rules.
+// Protovalidate when a proto message fails to meet the requirements set by the `Rule` validation rules.
 // Each individual violation is represented by a `Violation` message.
 message Violations {
   // `violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected.
@@ -4828,11 +4868,42 @@ message Violations {
 // caused the violation, the specific rule that wasn't fulfilled, and a
 // human-readable error message.
 //
+// For example, consider the following message:
+//
+// ```proto
+// message User {
+//     int32 age = 1 [(buf.validate.field).cel = {
+//         id: "user.age",
+//         expression: "this < 18 ? 'User must be at least 18 years old' : ''",
+//     }];
+// }
+// ```
+//
+// It could produce the following violation:
+//
 // ```json
 // {
-//   "fieldPath": "bar",
-//   "ruleId": "foo.bar",
-//   "message": "bar must be greater than 0"
+//   "ruleId": "user.age",
+//   "message": "User must be at least 18 years old",
+//   "field": {
+//     "elements": [
+//       {
+//         "fieldNumber": 1,
+//         "fieldName": "age",
+//         "fieldType": "TYPE_INT32"
+//       }
+//     ]
+//   },
+//   "rule": {
+//     "elements": [
+//       {
+//         "fieldNumber": 23,
+//         "fieldName": "cel",
+//         "fieldType": "TYPE_MESSAGE",
+//         "index": "0"
+//       }
+//     ]
+//   }
 // }
 // ```
 message Violation {
@@ -4857,7 +4928,7 @@ message Violation {
   // ```
   optional FieldPath field = 5;
 
-  // `rule` is a machine-readable path that points to the specific rule rule that failed validation.
+  // `rule` is a machine-readable path that points to the specific rule that failed validation.
   // This will be a nested field starting from the FieldRules of the field that failed validation.
   // For custom rules, this will provide the path of the rule, e.g. `cel[0]`.
   //