Support custom message validators #224

yevhenii-nadtochii · 2025-05-06T16:24:22Z

This PR brings support for the custom MessageValidators.

The feature specification resides in the docs to the MessageValidator interface.

This feature is based around two main entities residing in the :java-api module:

MessageValidator<T : Message> – an interface that defines behavior of the validators.
@Validator(T::class) – an annotation used for the discovering of the validators by the library.

The following modules were added:

:java-ksp – responsible for discovering of the annotated validators. The module outputs the discovered validators to a plain text file within the task output directory of KSP.
:java-tests:validator-dependency – declares an external message for tests.
:java-tests:validator – tests validators with external and well-known Protobuf messages.

JavaValidationPlugin fetches the file left by the KSP task, and passes the class names of the validators and their target messages to the renderer. The renderer bypasses them to ValidatorGenerator, which generates the actual invocations.

Note that ValidatorGenerator does not belong to the hierarchy of the option generators. It stands on its own for the following reasons:

Conceptually, it has nothing to do with the options.
It has to accept MessageType instead of TypeName because it needs to go through the message fields.

Additional changes

Added an extension fun <T : Dependency> T.artifact(module: T.() -> String): String, which allows using the properties of the target Depenency object without referencing the object itself.

# Conflicts: # dependencies.md # pom.xml # version.gradle.kts

yevhenii-nadtochii · 2025-05-30T12:18:54Z

@armiol @alexander-yevsyukov PTAL

armiol

@yevhenii-nadtochii please see my comments so far.

armiol · 2025-05-30T12:51:07Z

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

+/**
+ * A custom validator for Protobuf messages of type [M] that are defined externally.
+ *
+ * External messages are those that come from dependencies.


We consider "external" those Message definitions for which our end-users do not generate the Java/Kotlin code.

The definition you give is just misleading because end-users can generate code for any Proto type, including those coming from any third-party dependency. Many libraries come with their own generated and compiled Java code for their Proto definitions (such as Google Cloud libraries). And it is pretty difficult to generate another version of Java code and still make the libraries work properly.

I think the beginning (maybe even including the first paragraph) should be updated accordingly. Let's consider the readers much less prepared.

armiol · 2025-05-30T12:52:29Z

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

+ *
+ * ## Applicability
+ *
+ * A validator is applied only to the local messages of the module it is declared in.


I don't understand what you are trying to say here.

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

yevhenii-nadtochii · 2025-05-30T14:17:51Z

@armiol PTAL

armiol

@yevhenii-nadtochii please see more comments on the same matter.

armiol · 2025-05-30T13:07:08Z

java-ksp/src/test/kotlin/io/spine/validation/java/ksp/ValidatorProcessorKotlinSpec.kt

+            val result = compilation.compileSilently()
+            result.exitCode shouldBe OK
+
+            val output = compilation.kspSourcesDir


What if the DiscoveredValidators have the API on performing these resolve ops, instead of being just a holder for some constant?

armiol · 2025-05-30T14:36:20Z

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

+ *
+ * **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


"Validation". It's a name.

armiol · 2025-05-30T14:36:56Z

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

+/**
+ * A custom validator for an external Protobuf message of type [M].
+ *
+ * ## Notation of external and local messages


"## "External" and "local" `Message`s types

armiol · 2025-05-30T14:40:51Z

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

+import io.spine.annotation.SPI
+
+/**
+ * A custom validator for an external Protobuf message of type [M].


A custom validator ...

Do we have our own implementations of this MessageValidator? I mean, is it expected that all implementations are for the custom "external" Message types only?

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

alexander-yevsyukov

Please see my comments.

alexander-yevsyukov · 2025-05-30T14:41:15Z

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

+ * ## Validation of external messages
+ *
+ * The validation library provides a customization mechanism that allows validating
+ * of the external messages, **which are embedded within local messages**.


The "embedded" sounds a bit confusing in this context. Why don't we tell that these message types are used for fields in the local messages?

I mean "embedded" to me means that a message type is nested under another message type. This is not possible in the case we describe here. So, the reader has to conclude it to himself and then "decipher" it to the usage scenario I described above.

alexander-yevsyukov · 2025-05-30T14:44:26Z

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

 * of [DetectedViolation]. Before reporting to the user, the validation library
 * converts [DetectedViolation] to a [ConstraintViolation][io.spine.validate.ConstraintViolation].
- * Returning of an empty list of violations means that the message is valid.
+ * Returning of an empty list of violations means that the passed message is valid.


Let's replace "passed" with "given".

yevhenii-nadtochii · 2025-05-30T16:19:39Z

@armiol @alexander-yevsyukov PTAL

armiol

@yevhenii-nadtochii getting closer. Please see my comments.

armiol · 2025-05-30T16:58:08Z

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

+/**
+ * A validator for an external Protobuf message of type [M].
+ *
+ * This interface allows adding validation logic to messages, for which there is


No, we don't add any logic to messages which we don't control.

We enforce the validation rules for Messages that have Java/Kotlin code already generated by a third party, in case they are used in the Proto codebase to which the Validation library is applied.

armiol · 2025-05-30T16:58:30Z

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

+ * ## Problem
+ *
+ * Java/Kotlin libraries that use Protobuf messages often distribute both the `.proto`
+ * definitions and the compiled class files (.class) for these messages.


armiol · 2025-05-30T17:06:56Z

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

+ *
+ * 1) It is used to validate a local message. Only external messages are allowed
+ *    to have a validator.
+ * 2) There already exists a validator for the specified message type. Having several


Let's also describe the scope in which these rules apply. E.g. one may think it's scoped by a Gradle module, while it is certainly not.

Please have it somewhere above, as it is an important point.

armiol · 2025-05-30T17:07:39Z

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

+ *
+ * ## Implementation
+ *
+ * The message validator does not have restrictions upon how exactly the message


Let's start with a positive sentence, not with the one built around the negation.

alexander-yevsyukov

LGTM

yevhenii-nadtochii · 2025-05-30T18:02:26Z

@armiol PTAL

yevhenii-nadtochii added 12 commits May 5, 2025 17:26

Add MessageValidator SPI interface

44f253e

Merge branch 'master' into message-validator

a38cb3b

Bump the version -> 2.0.0-SNAPSHOT.333

12e9905

Update reports

eed6eea

Introduce @Validator annotation

ceb4763

Remove an empty line

a25515a

Implement a test stub

8f473c7

Make MessageValidator return a list of violations

1e17875

Create :java-tests:validator module

dc2d9e0

Implement FileDescriptorSetValidator

afe5c2f

Create :java-ksp module

b1a232f

Try to discover custom validators in JavaValidationPlugin

11a9b7e

yevhenii-nadtochii self-assigned this May 6, 2025

yevhenii-nadtochii added 17 commits May 13, 2025 13:48

Comment out task dependencies

8fa81fc

Suppress Detekt warnings

5adc510

Make kspKotlin run before ProtoData

4baa44c

Implement ValidatorRegistry

767b8e3

Prototype ValidatorProcessor and ValidatorRegistry coordination

1c2fbe6

Remove ValidatorRegistry class

c6700d4

Merge branch 'master' into message-validator

6d7356d

# Conflicts: # dependencies.md # pom.xml # version.gradle.kts

Add a new shortcut for declaring dependencies

af9a2f1

Declare KSP dependency using new API

e5b719c

Assert WhenFactory respectively

d369e60

Bump the version -> 2.0.0-SNAPSHOT.342

3e44ac1

Update reports

42b6caf

Make sure KSP always runs

68e1724

Merge branch 'master' into message-validator

47662fc

# Conflicts: # dependencies.md # pom.xml # version.gradle.kts

Bump the version -> 2.0.0-SNAPSHOT.342

77acacc

Have discovered validators in ProtoData using a plain file

b661a4f

Pass customValidators to JavaValidationRenderer

7c94b89

yevhenii-nadtochii added 2 commits May 30, 2025 13:59

Remain only the necessary task dependencies

4015a23

Update reports

ad0a8fc

yevhenii-nadtochii marked this pull request as ready for review May 30, 2025 12:18

yevhenii-nadtochii requested review from alexander-yevsyukov and armiol May 30, 2025 12:18

armiol requested changes May 30, 2025

View reviewed changes

yevhenii-nadtochii added 2 commits May 30, 2025 15:46

Explain the difference between local and external messages

fe7991d

Remove duplicate mentioning of the restriction

9fbe3f0

yevhenii-nadtochii requested a review from armiol May 30, 2025 14:17

armiol requested changes May 30, 2025

View reviewed changes

alexander-yevsyukov requested changes May 30, 2025

View reviewed changes

yevhenii-nadtochii added 6 commits May 30, 2025 17:09

Capitalize the library name

0a712b3

Rename the section

5aeba49

Get rid of custom bound

eff29ff

Introduce the Problem section

b0f1766

Avoid embedded in docs to the validator

4f65755

Move the resolving logic to the DiscoveredValidators object

34f7049

yevhenii-nadtochii requested review from alexander-yevsyukov and armiol May 30, 2025 16:19

armiol requested changes May 30, 2025

View reviewed changes

alexander-yevsyukov approved these changes May 30, 2025

View reviewed changes

Enhance docs

ed00afe

yevhenii-nadtochii requested a review from armiol May 30, 2025 18:02

armiol approved these changes May 30, 2025

View reviewed changes

yevhenii-nadtochii merged commit 7ad0eeb into master May 30, 2025
7 checks passed

yevhenii-nadtochii deleted the message-validator branch May 30, 2025 18:04

Support custom message validators #224

Support custom message validators #224

Uh oh!

Conversation

yevhenii-nadtochii commented May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional changes

Uh oh!

yevhenii-nadtochii commented May 30, 2025

Uh oh!

armiol 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!

Uh oh!

yevhenii-nadtochii commented May 30, 2025

Uh oh!

armiol 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexander-yevsyukov 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!

yevhenii-nadtochii commented May 30, 2025

Uh oh!

armiol 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!

Choose a reason for hiding this comment

Uh oh!

alexander-yevsyukov left a comment

Choose a reason for hiding this comment

Uh oh!

yevhenii-nadtochii commented May 30, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yevhenii-nadtochii commented May 6, 2025 •

edited

Loading