Merge pull request #224 from SpineEventEngine/message-validator

Support custom message validators

Author: yevhenii-nadtochii

buildSrc/src/main/kotlin/io/spine/dependency/Dependency.kt

@@ -58,7 +58,7 @@ abstract class Dependency {
     /**
      * The [modules] given with the [version].
      */
-    final val artifacts: Map<String, String> by lazy {
+    val artifacts: Map<String, String> by lazy {
         modules.associateWith { "$it:$version" }
     }
 
@@ -114,3 +114,19 @@ private fun ResolutionStrategy.forceWithLogging(
     force(artifact)
     project.log { "Forced the version of `$artifact` in " + configuration.diagSuffix(project) }
 }
+
+/**
+ * Obtains full Maven coordinates for the requested [module].
+ *
+ * This extension allows referencing properties of the [Dependency],
+ * upon which it is invoked.
+ *
+ * An example usage:
+ *
+ * ```
+ * // Supposing there is `Ksp.symbolProcessingApi: String` property declared.
+ * Ksp.artifact { symbolProcessingApi }
+ * ```
+ */
+fun <T : Dependency> T.artifact(module: T.() -> String): String =
+    artifact(module())

buildSrc/src/main/kotlin/io/spine/dependency/test/KotlinCompileTesting.kt

@@ -33,7 +33,7 @@ package io.spine.dependency.test
  */
 @Suppress("unused", "ConstPropertyName")
 object KotlinCompileTesting {
-    private const val version = "0.7.0"
+    private const val version = "0.7.1"
     private const val group = "dev.zacsweers.kctfork"
     const val libCore = "$group:core:$version"
     const val libKsp = "$group:ksp:$version"

buildSrc/src/main/kotlin/module.gradle.kts

@@ -28,6 +28,7 @@ import io.spine.dependency.boms.BomsPlugin
 import io.spine.dependency.build.Dokka
 import io.spine.dependency.build.ErrorProne
 import io.spine.dependency.build.JSpecify
+import io.spine.dependency.build.Ksp
 import io.spine.dependency.lib.Grpc
 import io.spine.dependency.lib.Kotlin
 import io.spine.dependency.lib.Protobuf
@@ -144,8 +145,10 @@ fun Module.forceConfigurations() {
         all {
             resolutionStrategy {
                 Grpc.forceArtifacts(project, this@all, this@resolutionStrategy)
+                Ksp.forceArtifacts(project, this@all, this@resolutionStrategy)
                 force(
                     Kotlin.bom,
+                    Kotlin.Compiler.embeddable,
                     Reflect.lib,
                     Base.lib,
                     Protobuf.compiler,

dependencies.md

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import io.spine.base.FieldPath
+import io.spine.validate.TemplateString
+
+/**
+ * Abstract base for violations detected by [MessageValidator]s.
+ *
+ * @param message The error message describing the violation.
+ * @param fieldPath The path to the field where the violation occurred, if applicable.
+ * @param fieldValue The field value that caused the violation, if any.
+ */
+public abstract class DetectedViolation(
+    public val message: TemplateString,
+    public val fieldPath: FieldPath?,
+    public val fieldValue: Any?,
+)
+
+/**
+ * A violation tied to a specific field in a message.
+ *
+ * @param message The error message describing the violation.
+ * @param fieldPath The path to the field where the violation occurred.
+ * @param fieldValue The field value that caused the violation, if any.
+ */
+public class FieldViolation(
+    message: TemplateString,
+    fieldPath: FieldPath,
+    fieldValue: Any? = null,
+) : DetectedViolation(message, fieldPath, fieldValue)
+
+/**
+ * A violation related to the message level (not tied to a specific field).
+ *
+ * @param message The error message describing the violation.
+ */
+public class MessageViolation(
+    message: TemplateString
+) : DetectedViolation(message, fieldPath = null, fieldValue = null)

java-api/src/main/kotlin/io/spine/validation/api/DetectedViolation.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import io.spine.annotation.Internal
+import java.io.File
+
+/**
+ * Holds a path to a file with the discovered validators.
+ *
+ * The KSP processor generates a resource file using this path.
+ * Then, the Java codegen plugin picks up this file.
+ */
+@Internal
+public object DiscoveredValidators {
+
+    /**
+     * The path to the file with the discovered message validators.
+     *
+     * The path is relative to the output directory of the KSP processor.
+     */
+   public const val RESOURCES_LOCATION: String = "spine/validation/message-validators"
+
+    /**
+     * Resolves the path to the file containing discovered message validators.
+     *
+     * @param kspOutputDirectory The path to the KSP output.
+     */
+    public fun resolve(kspOutputDirectory: File): File = kspOutputDirectory
+        .resolve("resources")
+        .resolve(RESOURCES_LOCATION)
+}

java-api/src/main/kotlin/io/spine/validation/api/DiscoveredValidators.kt

@@ -0,0 +1,142 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import com.google.protobuf.Message
+import io.spine.annotation.SPI
+
+/**
+ * A validator for an external Protobuf message of type [M].
+ *
+ * This interface enforces validation rules for `Message`s whose Java/Kotlin classes
+ * are already generated by third parties, in case they are used in the Protobuf
+ * codebase to which the Validation library is applied.
+ *
+ * ## Problem
+ *
+ * Java/Kotlin libraries that use Protobuf messages often distribute both the `.proto`
+ * definitions and the compiled class files (`.class`) for these messages.
+ * As these classes are pre-generated, consumers cannot modify their underlying
+ * `.proto` files to define validation constraints and the Validation library
+ * cannot use code generation to enforce the constraints.
+ *
+ * Thus, the library effectively deals with the two types of messages:
+ *
+ * 1. **Local messages** are message types for which end-users generate and control
+ *    the Java/Kotlin classes by compiling the corresponding `.proto` definitions
+ *    within their own codebase. For such messages, the Validation library allows
+ *    declaring validation constraints and enforces them with the generated code.
+ *
+ * 2. **External messages** are message types for which end-users do not generate or control
+ *    the Java/Kotlin classes. Because the classes are already generated, users cannot modify
+ *    the underlying `.proto` definitions and add validation options at compile time.
+ *
+ * ## Validation of external messages
+ *
+ * The Validation library provides a mechanism that allows validating of
+ * the external messages, **which are used for fields within local messages**.
+ * Implement this interface and annotate the implementing class with
+ * the [@Validator][Validator] annotation, specifying the message type to validate.
+ *
+ * For each field of type [M] within any local message, the library will invoke
+ * the [MessageValidator.validate] method when validating the local message.
+ *
+ * The following Protobuf field types are supported:
+ *
+ * 1. Singular fields of type [M].
+ * 2. Repeated field of type [M].
+ * 3. Map field with values of type [M].
+ *
+ * An example of the validator declaration for the `Earphones` message:
+ *
+ * ```kotlin
+ * @Validator(Earphones::class)
+ * public class EarphonesValidator : MessageValidator<Earphones> {
+ *     public override fun validate(message: Earphones): List<DetectedViolation> {
+ *         return emptyList() // Always valid.
+ *     }
+ * }
+ * ```
+ *
+ * Please note that standalone instances of [M] and fields of [M] type that occur in
+ * other external messages **will not be validated**.
+ *
+ * Consider the following example:
+ *
+ * ```proto
+ * // Brings the `Earphones` message from dependencies.
+ * // Suppose we don't control the generated code of declarations from this file.
+ * import "earphones.proto";
+ *
+ * // A locally-declared message.
+ * message WorkingSetup {
+ *
+ *     // The field of external message type.
+ *     Earphones earphones = 1;
+ * }
+ * ```
+ *
+ * Supposing that the Validation library applied to the module where both `WorkingSetup`
+ * and `EarphonesValidator` classes are declared, then the generated code of `WorkingSetup`
+ * will apple the validator to each instance passed to the `WorkingSetup.earphones` field.
+ *
+ * Please note that the following use cases are NOT supported and will lead to an error:
+ *
+ * 1) Declaring a validator for a local message is prohibited. Only external messages are
+ *    allowed to have a validator. Use built-in or custom validation options to declare
+ *    constraints for local messages.
+ * 2) Declaring multiple validators for the same message type is prohibited. The library
+ *    scans the module’s classpath to discover validators, and expects exactly one validator
+ *    per message type.
+ *
+ * ## Implementation
+ *
+ * The interface offers flexible validation strategies. Implementations can choose to
+ * validate a particular field, several fields, the whole message instance (for example,
+ * checking the field relations), and perform a deep validation.
+ *
+ * It is a responsibility of the validator to provide the correct instances
+ * of [DetectedViolation]. Before reporting to the user, the library converts
+ * [DetectedViolation] to a [ConstraintViolation][io.spine.validate.ConstraintViolation].
+ * Returning of an empty list of violations means that the given message is valid.
+ *
+ * Please keep in mind that for each invocation a new instance of [MessageValidator]
+ * is created. Every implementation of [MessageValidator] must have a public,
+ * no-args constructor.
+ *
+ * @param M the type of Protobuf [Message] being validated.
+ */
+@SPI
+public interface MessageValidator<M : Message> {
+
+    /**
+     * Validates the given [message].
+     *
+     * @return the detected violations or empty list.
+     */
+    public fun validate(message: M): List<DetectedViolation>
+}

java-api/src/main/kotlin/io/spine/validation/api/MessageValidator.kt

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2025, TeamDev. All rights reserved.
+ *
+ * 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
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.validation.api
+
+import com.google.protobuf.Message
+import kotlin.annotation.AnnotationRetention.SOURCE
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.reflect.KClass
+
+/**
+ * Marks the class as a message validator.
+ *
+ * Applying this annotation to an implementation of [MessageValidator]
+ * makes the class visible to the validation library.
+ *
+ * Please note that the following requirements are imposed to the marked class:
+ *
+ * 1. The class must implement the [MessageValidator] interface.
+ * 2. The class must have a public, no-args constructor.
+ * 3. The class cannot be `inner`, but nested classes are allowed.
+ * 4. The message type of [Validator.value] and [MessageValidator] must match.
+ */
+@Target(CLASS)
+@Retention(SOURCE)
+public annotation class Validator(
+
+    /**
+     * The class of the validated external message.
+     */
+    val value: KClass<out Message>
+)