feat(ext-validation): add request validation with compiled constraints
Standard jakarta.validation annotations, compiled once per type into a flat
check table. No configuration: constraints come from the annotations already on
your types, and ValidationException extends HttpException with status 422 so
the default handler renders it without this extension registering anything.
record CreateUser(@NotBlank @Size(max = 80) String name,
@Email String email,
@Min(18) int age) {}
CreateUser dto = validation.body(req, CreateUser.class);
Annotations only — Hibernate Validator's engine is deliberately absent. It
resolves constraints reflectively per call and pulls ~2 MB plus EL, which is
the per-request cost this module exists to avoid. jakarta.validation-api is
~90 KB of annotations.
The passing path allocates nothing. Constraints resolve at first use into an
opcode plus operands cached in a ClassValue, so there is no map lookup and no
lock. Fields are read through MethodHandles adapted to an exact signature —
(Object)Object for references, (Object)long for primitive integrals — so
invokeExact neither boxes nor builds the argument array Field.get and
Method.invoke allocate. Checks are a flat array walked by a tableswitch rather
than a class hierarchy behind a virtual call. @Size reads a length the object
already knows and @Email scans with indexOf, because Pattern.matcher allocates
a matcher and two int arrays per call. Messages are pre-rendered at compile
time. The violation list and the exception exist only once something fails.
@Pattern is the marked exception: its regex compiles once but matcher()
allocates per call.
Constraints are read from declared fields, so records and plain classes take
one code path — a constraint on a record component propagates to its backing
field.
Jakarta null semantics are exact: only @NotNull rejects null.
flash-ext-openapi now mirrors the same annotations into the generated schema —
minLength, maxLength, minItems, minimum, maximum, pattern, format: email and
required — via an optional jakarta.validation dependency detected at boot. A
type declares its rules once and both the validator and the published contract
read them. An explicit @Schema still wins; the bridge only fills keys nobody
set, and without the annotations on the classpath the bridge class is never
loaded.
flash-ext-jackson is optional too: validate(value) works without it, only
body(req, type) needs a codec.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Zakaria El Orche
co-authored by
Claude Opus 5
Claude Opus 5
parent
fe8c6ed162
commit
f68e661296
@@ -0,0 +1,143 @@
|
||||
# flash-ext-validation
|
||||
|
||||
Request validation for Flash. Standard `jakarta.validation` annotations, compiled once per type
|
||||
into a flat check table, with zero allocation on the passing path.
|
||||
|
||||
## What it provides
|
||||
|
||||
| Component | Description |
|
||||
|---|---|
|
||||
| `Validation` | The service — `body(req, type)` parses and verifies, `validate(value)` verifies |
|
||||
| `Validator` | One type's compiled constraints; reusable and thread-safe |
|
||||
| `ValidationException` | 422 carrying every violation, not just the first |
|
||||
|
||||
## Dependency
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash-ext-validation</artifactId>
|
||||
<version>${flash.version}</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```java
|
||||
FlashApp.create(8080)
|
||||
.install(new JacksonExtension())
|
||||
.install(new ValidationExtension())
|
||||
.scan("dev.example.api");
|
||||
```
|
||||
|
||||
```java
|
||||
public record CreateUser(
|
||||
@NotBlank @Size(max = 80) String name,
|
||||
@Email String email,
|
||||
@Min(18) int age) {}
|
||||
```
|
||||
|
||||
```java
|
||||
@POST("/api/users")
|
||||
public final class CreateUserHandler extends RequestHandler {
|
||||
|
||||
private Validation validation;
|
||||
private UserService users;
|
||||
|
||||
@Override protected void onInit() {
|
||||
validation = require(Validation.class);
|
||||
users = require(UserService.class);
|
||||
}
|
||||
|
||||
@Override public Object handle(Request req, Response res) throws Exception {
|
||||
CreateUser dto = validation.body(req, CreateUser.class);
|
||||
return res.status(201).body(users.create(dto));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
There is nothing to configure. Constraints come from the annotations already on your types, and
|
||||
failures reach the client as `422` on their own — see [Error responses](#error-responses).
|
||||
|
||||
## Supported constraints
|
||||
|
||||
`@NotNull` · `@NotBlank` · `@NotEmpty` · `@Size` · `@Min` · `@Max` · `@Email` · `@Pattern`
|
||||
|
||||
Jakarta null semantics are honoured exactly: **only `@NotNull` rejects null**. Every other
|
||||
constraint passes a null value, so `@Email String email` means "if present, must look like an
|
||||
email" — combine with `@NotNull` when it is mandatory.
|
||||
|
||||
`@Size` applies to `CharSequence`, `Collection`, `Map` and object arrays. `@Min`/`@Max` apply to
|
||||
primitive integrals and to `Number` subtypes.
|
||||
|
||||
An unsupported annotation is ignored rather than rejected, so adding one is never a boot failure.
|
||||
|
||||
## Records and classes
|
||||
|
||||
Constraints are read from **declared fields**. A constraint on a record component propagates to
|
||||
its backing field, so records and plain classes take the same path with no extra configuration:
|
||||
|
||||
```java
|
||||
record CreateUser(@NotBlank String name) {} // works
|
||||
class CreateUser { @NotBlank private String name; } // works
|
||||
```
|
||||
|
||||
## Error responses
|
||||
|
||||
`ValidationException` extends Flash's `HttpException` with status 422, so the default exception
|
||||
handler renders it. Nothing is registered, and your own `onException` still wins if you set one.
|
||||
|
||||
```json
|
||||
{"error":"name must not be blank; age must be at least 18","status":422}
|
||||
```
|
||||
|
||||
Malformed JSON is a different failure and comes back as `400` from the codec, before any
|
||||
constraint runs.
|
||||
|
||||
## OpenAPI
|
||||
|
||||
Install `flash-ext-openapi` alongside and the generated schema mirrors the same annotations —
|
||||
`minLength`, `maxLength`, `minItems`, `minimum`, `maximum`, `pattern`, `format: email`, and
|
||||
`required`. Declared once, enforced and published.
|
||||
|
||||
Nothing registers this. `flash-ext-openapi` carries `jakarta.validation-api` as an optional
|
||||
dependency and detects it at boot; without it the bridge class is never loaded.
|
||||
|
||||
An explicit `@Schema` always wins — the bridge only fills keys nobody set.
|
||||
|
||||
## Without Jackson
|
||||
|
||||
`flash-ext-jackson` is optional. Without it `validate(value)` still works on values you construct
|
||||
or parse yourself; only `body(req, type)` needs a codec and says so if one is missing.
|
||||
|
||||
## Performance
|
||||
|
||||
The passing path is the one that runs on every request, so it allocates nothing:
|
||||
|
||||
- **Compiled once per type.** Constraints resolve to an opcode plus operands at first use, cached
|
||||
in a `ClassValue` — stored beside the class by the JVM, so no map lookup, no lock, and the entry
|
||||
is collected with the class rather than pinning it.
|
||||
- **No reflection per request.** Fields are read through `MethodHandle`s adapted to an exact
|
||||
signature: `(Object)Object` for references, `(Object)long` for primitive integrals. `invokeExact`
|
||||
neither boxes nor builds the argument array that `Field.get` and `Method.invoke` allocate.
|
||||
- **No megamorphic dispatch.** Checks are a flat array walked by a `tableswitch` on an opcode, not
|
||||
a class hierarchy behind a virtual call.
|
||||
- **No copies.** `@Size` reads a length the object already knows; `@Email` scans with `indexOf`
|
||||
rather than a regex, because `Pattern.matcher` allocates a matcher and two int arrays per call.
|
||||
- **Messages pre-rendered at compile time**, so even a failure formats nothing.
|
||||
|
||||
The list, the violations and the exception exist only once something fails.
|
||||
|
||||
`@Pattern` is the deliberate exception: its regex is compiled once, but `matcher()` allocates per
|
||||
call. It is marked in the source. Prefer `@Size`/`@Email` on hot routes, or validate the shape
|
||||
structurally.
|
||||
|
||||
## Pre-warming
|
||||
|
||||
Compilation happens on a type's first request. To pay it at boot instead:
|
||||
|
||||
```java
|
||||
ctx.onReady(() -> ctx.require(Validation.class).forType(CreateUser.class));
|
||||
```
|
||||
|
||||
Worth it only for a route that must not pay first-call cost. Everything else warms itself.
|
||||
@@ -0,0 +1,51 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash-extensions</artifactId>
|
||||
<version>2.1.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>flash-ext-validation</artifactId>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash</artifactId>
|
||||
</dependency>
|
||||
<!--
|
||||
Annotations only (~90 KB). Hibernate Validator's engine is deliberately absent: it
|
||||
resolves constraints reflectively per call and pulls ~2 MB plus EL. This module
|
||||
compiles the same annotations into a flat check table once per class instead.
|
||||
-->
|
||||
<dependency>
|
||||
<groupId>jakarta.validation</groupId>
|
||||
<artifactId>jakarta.validation-api</artifactId>
|
||||
</dependency>
|
||||
<!-- Only needed for Validation.body(...); check(...) works without it. -->
|
||||
<dependency>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash-ext-jackson</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.junit.jupiter</groupId>
|
||||
<artifactId>junit-jupiter</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash-testing</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<!-- Interop only: proves constraints reach the published schema. -->
|
||||
<dependency>
|
||||
<groupId>dev.relism</groupId>
|
||||
<artifactId>flash-ext-openapi</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</project>
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import java.lang.invoke.MethodHandle;
|
||||
import java.util.regex.Pattern;
|
||||
|
||||
/**
|
||||
* One constraint, compiled. Flattened into an opcode plus its operands rather than a class per
|
||||
* constraint type: the check loop becomes a {@code tableswitch} over a monomorphic array instead
|
||||
* of a megamorphic virtual call, and a passing check touches no allocation at all.
|
||||
*
|
||||
* <p>Field access goes through a {@link MethodHandle} adapted at compile time to an exact
|
||||
* signature — {@code (Object)Object} for reference fields, {@code (Object)long} for primitive
|
||||
* integrals — so {@code invokeExact} neither boxes nor allocates an argument array the way
|
||||
* {@code Field.get} and {@code Method.invoke} do.
|
||||
*/
|
||||
final class Check {
|
||||
|
||||
static final int NOT_NULL = 0;
|
||||
static final int NOT_BLANK = 1;
|
||||
static final int NOT_EMPTY = 2;
|
||||
static final int SIZE = 3;
|
||||
static final int RANGE_PRIMITIVE = 4;
|
||||
static final int RANGE_BOXED = 5;
|
||||
static final int EMAIL = 6;
|
||||
static final int PATTERN = 7;
|
||||
|
||||
final int op;
|
||||
final String field;
|
||||
/** Pre-rendered at compile time, so even the failure path formats nothing. */
|
||||
final String message;
|
||||
|
||||
/** {@code (Object)Object} — set for every op except {@link #RANGE_PRIMITIVE}. */
|
||||
final MethodHandle ref;
|
||||
/** {@code (Object)long} — set only for {@link #RANGE_PRIMITIVE}. */
|
||||
final MethodHandle num;
|
||||
|
||||
final int min;
|
||||
final int max;
|
||||
final long lo;
|
||||
final long hi;
|
||||
final Pattern pattern;
|
||||
|
||||
private Check(int op, String field, String message, MethodHandle ref, MethodHandle num,
|
||||
int min, int max, long lo, long hi, Pattern pattern) {
|
||||
this.op = op;
|
||||
this.field = field;
|
||||
this.message = message;
|
||||
this.ref = ref;
|
||||
this.num = num;
|
||||
this.min = min;
|
||||
this.max = max;
|
||||
this.lo = lo;
|
||||
this.hi = hi;
|
||||
this.pattern = pattern;
|
||||
}
|
||||
|
||||
static Check reference(int op, String field, String message, MethodHandle ref) {
|
||||
return new Check(op, field, message, ref, null, 0, 0, 0, 0, null);
|
||||
}
|
||||
|
||||
static Check size(String field, String message, MethodHandle ref, int min, int max) {
|
||||
return new Check(SIZE, field, message, ref, null, min, max, 0, 0, null);
|
||||
}
|
||||
|
||||
static Check rangePrimitive(String field, String message, MethodHandle num, long lo, long hi) {
|
||||
return new Check(RANGE_PRIMITIVE, field, message, null, num, 0, 0, lo, hi, null);
|
||||
}
|
||||
|
||||
static Check rangeBoxed(String field, String message, MethodHandle ref, long lo, long hi) {
|
||||
return new Check(RANGE_BOXED, field, message, ref, null, 0, 0, lo, hi, null);
|
||||
}
|
||||
|
||||
static Check pattern(String field, String message, MethodHandle ref, Pattern pattern) {
|
||||
return new Check(PATTERN, field, message, ref, null, 0, 0, 0, 0, pattern);
|
||||
}
|
||||
}
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import dev.relism.flash.ext.jackson.Json;
|
||||
import dev.relism.flash.models.Request;
|
||||
|
||||
/**
|
||||
* The validation service. Resolve it with {@code require(Validation.class)}.
|
||||
*
|
||||
* <pre>{@code
|
||||
* CreateUser dto = validation.body(req, CreateUser.class); // parse + verify
|
||||
* }</pre>
|
||||
*
|
||||
* <p>Constraints are compiled the first time a type is seen and cached in a {@link ClassValue},
|
||||
* which the JVM stores beside the class itself — no map lookup, no lock, and the entry is
|
||||
* collected with the class rather than pinning it. Every later request walks the compiled table.
|
||||
*/
|
||||
public final class Validation {
|
||||
|
||||
private final ClassValue<Validator> validators = new ClassValue<>() {
|
||||
@Override protected Validator computeValue(Class<?> type) {
|
||||
return Validator.compile(type);
|
||||
}
|
||||
};
|
||||
|
||||
/** Null when flash-ext-jackson is absent; only {@link #body} needs it. */
|
||||
private Json json;
|
||||
|
||||
Validation() {}
|
||||
|
||||
/** Called once at boot by {@link ValidationExtension}, after the service graph resolves. */
|
||||
void bindCodec(Json json) {
|
||||
this.json = json;
|
||||
}
|
||||
|
||||
/**
|
||||
* Deserializes the request body into {@code type} and verifies its constraints.
|
||||
*
|
||||
* @throws dev.relism.flash.exceptions.HttpException 400 if the body is not valid JSON
|
||||
* @throws ValidationException 422 if it parses but violates a constraint
|
||||
*/
|
||||
public <T> T body(Request request, Class<T> type) throws Exception {
|
||||
if (json == null)
|
||||
throw new IllegalStateException(
|
||||
"Validation.body(...) needs a JSON codec — install JacksonExtension, "
|
||||
+ "or parse yourself and call validate(...)");
|
||||
T value = json.body(request, type);
|
||||
validators.get(type).verify(value);
|
||||
return value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Verifies an already-constructed value.
|
||||
*
|
||||
* @return {@code value}, so it can be used inline
|
||||
* @throws ValidationException 422 on the first type's worth of failures
|
||||
*/
|
||||
public <T> T validate(T value) {
|
||||
validators.get(value.getClass()).verify(value);
|
||||
return value;
|
||||
}
|
||||
|
||||
/**
|
||||
* The compiled constraints of {@code type}. Useful to pre-warm a hot DTO at boot, or to
|
||||
* check whether a type declares constraints at all.
|
||||
*/
|
||||
public Validator forType(Class<?> type) {
|
||||
return validators.get(type);
|
||||
}
|
||||
}
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import dev.relism.flash.exceptions.HttpException;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Raised when a value fails its constraints. Extends {@link HttpException} with status 422, so
|
||||
* Flash's default exception handler renders it without this extension registering anything.
|
||||
*
|
||||
* <p>Allocated only on failure — a passing validation constructs nothing.
|
||||
*/
|
||||
public final class ValidationException extends HttpException {
|
||||
|
||||
private final transient List<Violation> violations;
|
||||
|
||||
ValidationException(List<Violation> violations) {
|
||||
super(422, describe(violations));
|
||||
this.violations = List.copyOf(violations);
|
||||
}
|
||||
|
||||
/** The individual failures, in field declaration order. */
|
||||
public List<Violation> violations() {
|
||||
return violations;
|
||||
}
|
||||
|
||||
private static String describe(List<Violation> violations) {
|
||||
StringBuilder out = new StringBuilder(32 * violations.size());
|
||||
for (int i = 0; i < violations.size(); i++) {
|
||||
if (i > 0) out.append("; ");
|
||||
Violation v = violations.get(i);
|
||||
out.append(v.field()).append(' ').append(v.message());
|
||||
}
|
||||
return out.toString();
|
||||
}
|
||||
|
||||
/** One failed constraint. */
|
||||
public record Violation(String field, String message) {}
|
||||
}
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import dev.relism.flash.ext.jackson.Json;
|
||||
import dev.relism.flash.extension.FlashContext;
|
||||
import dev.relism.flash.extension.FlashExtension;
|
||||
import dev.relism.flash.extension.FlashRegistrar;
|
||||
|
||||
/**
|
||||
* Installs request validation.
|
||||
*
|
||||
* <pre>{@code
|
||||
* FlashApp.create(8080)
|
||||
* .install(new JacksonExtension())
|
||||
* .install(new ValidationExtension())
|
||||
* .scan("dev.example.api");
|
||||
* }</pre>
|
||||
*
|
||||
* <p>No configuration. There is nothing to tune: constraints come from the annotations already on
|
||||
* your types, failures come back as 422 through Flash's default exception handler because
|
||||
* {@link ValidationException} carries its own status, and the JSON codec is picked up if
|
||||
* {@code flash-ext-jackson} is installed.
|
||||
*
|
||||
* <p>Install order does not matter — Flash resolves the whole service graph before any handler
|
||||
* initialises.
|
||||
*/
|
||||
public final class ValidationExtension implements FlashExtension {
|
||||
|
||||
@Override
|
||||
public void configure(FlashRegistrar<?> app, FlashContext ctx) {
|
||||
ctx.supply(Validation.class, Validation::new);
|
||||
|
||||
// Resolved here rather than declared as a dependency: jackson is optional, and a declared
|
||||
// dependency would make it mandatory. By the time ready callbacks run the graph is
|
||||
// complete, so find() sees whatever was actually installed.
|
||||
ctx.onReady(() -> ctx.require(Validation.class).bindCodec(ctx.find(Json.class).orElse(null)));
|
||||
}
|
||||
}
|
||||
+216
@@ -0,0 +1,216 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import jakarta.validation.constraints.Email;
|
||||
import jakarta.validation.constraints.Max;
|
||||
import jakarta.validation.constraints.Min;
|
||||
import jakarta.validation.constraints.NotBlank;
|
||||
import jakarta.validation.constraints.NotEmpty;
|
||||
import jakarta.validation.constraints.NotNull;
|
||||
import jakarta.validation.constraints.Pattern;
|
||||
import jakarta.validation.constraints.Size;
|
||||
|
||||
import java.lang.invoke.MethodHandle;
|
||||
import java.lang.invoke.MethodHandles;
|
||||
import java.lang.invoke.MethodType;
|
||||
import java.lang.reflect.Field;
|
||||
import java.lang.reflect.Modifier;
|
||||
import java.util.ArrayList;
|
||||
import java.util.Collection;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* The compiled constraints of one type. Built once per class and reused for every request.
|
||||
*
|
||||
* <p>{@link #verify} allocates nothing when a value passes: the loop walks an array (no iterator),
|
||||
* reads fields through exact-signature {@link MethodHandle}s (no boxing, no argument array), and
|
||||
* compares against operands resolved at compile time. The violation list and the exception are
|
||||
* constructed only once something actually fails.
|
||||
*/
|
||||
public final class Validator {
|
||||
|
||||
private static final Check[] NONE = new Check[0];
|
||||
|
||||
private final Check[] checks;
|
||||
|
||||
private Validator(Check[] checks) {
|
||||
this.checks = checks;
|
||||
}
|
||||
|
||||
/** True when the type declares no constraints at all — {@link #verify} is then a no-op. */
|
||||
public boolean isEmpty() {
|
||||
return checks.length == 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* Verifies every constraint on {@code target}.
|
||||
*
|
||||
* @throws ValidationException with all failures, never just the first
|
||||
*/
|
||||
public void verify(Object target) {
|
||||
List<ValidationException.Violation> failures = null;
|
||||
for (Check check : checks) {
|
||||
if (passes(check, target)) continue;
|
||||
if (failures == null) failures = new ArrayList<>(4);
|
||||
failures.add(new ValidationException.Violation(check.field, check.message));
|
||||
}
|
||||
if (failures != null) throw new ValidationException(failures);
|
||||
}
|
||||
|
||||
private static boolean passes(Check check, Object target) {
|
||||
try {
|
||||
if (check.op == Check.RANGE_PRIMITIVE) {
|
||||
long value = (long) check.num.invokeExact(target);
|
||||
return value >= check.lo && value <= check.hi;
|
||||
}
|
||||
Object value = (Object) check.ref.invokeExact(target);
|
||||
// Jakarta semantics: only @NotNull rejects null; every other constraint passes it.
|
||||
return switch (check.op) {
|
||||
case Check.NOT_NULL -> value != null;
|
||||
case Check.NOT_BLANK -> value instanceof String text && !text.isBlank();
|
||||
case Check.NOT_EMPTY -> value != null && sizeOf(value) > 0;
|
||||
case Check.SIZE -> value == null || withinSize(check, value);
|
||||
case Check.RANGE_BOXED -> value == null || withinRange(check, (Number) value);
|
||||
case Check.EMAIL -> value == null || (value instanceof String text && isEmail(text));
|
||||
case Check.PATTERN -> value == null
|
||||
|| (value instanceof String text && check.pattern.matcher(text).matches());
|
||||
default -> true;
|
||||
};
|
||||
} catch (Throwable failure) {
|
||||
throw new IllegalStateException("Could not read " + check.field + " for validation", failure);
|
||||
}
|
||||
}
|
||||
|
||||
private static boolean withinSize(Check check, Object value) {
|
||||
int size = sizeOf(value);
|
||||
return size >= check.min && size <= check.max;
|
||||
}
|
||||
|
||||
private static boolean withinRange(Check check, Number value) {
|
||||
long asLong = value.longValue();
|
||||
return asLong >= check.lo && asLong <= check.hi;
|
||||
}
|
||||
|
||||
/** No copies: every branch reads a length the object already knows. */
|
||||
private static int sizeOf(Object value) {
|
||||
if (value instanceof CharSequence text) return text.length();
|
||||
if (value instanceof Collection<?> items) return items.size();
|
||||
if (value instanceof Map<?, ?> entries) return entries.size();
|
||||
if (value instanceof Object[] array) return array.length;
|
||||
return 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Structural check rather than a regex: {@code Pattern.matcher} allocates a matcher, an int
|
||||
* array and a group array on every call, which is exactly the per-request cost this module
|
||||
* exists to avoid. {@code indexOf} allocates nothing.
|
||||
*
|
||||
* <p>Accepts what a mail server would plausibly route and rejects the shapes people actually
|
||||
* typo. Deliverability is the confirmation mail's job, not a validator's.
|
||||
*/
|
||||
private static boolean isEmail(String value) {
|
||||
int at = value.indexOf('@');
|
||||
if (at <= 0 || at == value.length() - 1) return false;
|
||||
if (value.indexOf('@', at + 1) >= 0) return false;
|
||||
int dot = value.indexOf('.', at + 2);
|
||||
return dot > 0 && dot < value.length() - 1 && value.indexOf(' ') < 0;
|
||||
}
|
||||
|
||||
// ── Compilation ──────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Compiles {@code type}'s constraints once.
|
||||
*
|
||||
* <p>Reads declared fields rather than record accessors: a constraint on a record component
|
||||
* propagates to the backing field, so records and plain classes need one code path, not two.
|
||||
*/
|
||||
static Validator compile(Class<?> type) {
|
||||
MethodHandles.Lookup lookup;
|
||||
try {
|
||||
lookup = MethodHandles.privateLookupIn(type, MethodHandles.lookup());
|
||||
} catch (IllegalAccessException denied) {
|
||||
throw new IllegalStateException(
|
||||
"Cannot read " + type.getName() + " for validation — open its module or package", denied);
|
||||
}
|
||||
|
||||
List<Check> checks = new ArrayList<>();
|
||||
for (Field field : type.getDeclaredFields()) {
|
||||
if (Modifier.isStatic(field.getModifiers())) continue;
|
||||
MethodHandle getter;
|
||||
try {
|
||||
getter = lookup.unreflectGetter(field);
|
||||
} catch (IllegalAccessException denied) {
|
||||
continue;
|
||||
}
|
||||
compileField(field, getter, checks);
|
||||
}
|
||||
return new Validator(checks.isEmpty() ? NONE : checks.toArray(new Check[0]));
|
||||
}
|
||||
|
||||
private static void compileField(Field field, MethodHandle getter, List<Check> checks) {
|
||||
String name = field.getName();
|
||||
Class<?> type = field.getType();
|
||||
MethodHandle ref = type.isPrimitive() ? null : asReference(getter);
|
||||
|
||||
if (field.isAnnotationPresent(NotNull.class) && ref != null)
|
||||
checks.add(Check.reference(Check.NOT_NULL, name, "must not be null", ref));
|
||||
|
||||
if (field.isAnnotationPresent(NotBlank.class) && ref != null)
|
||||
checks.add(Check.reference(Check.NOT_BLANK, name, "must not be blank", ref));
|
||||
|
||||
if (field.isAnnotationPresent(NotEmpty.class) && ref != null)
|
||||
checks.add(Check.reference(Check.NOT_EMPTY, name, "must not be empty", ref));
|
||||
|
||||
Size size = field.getAnnotation(Size.class);
|
||||
if (size != null && ref != null)
|
||||
checks.add(Check.size(name, sizeMessage(size), ref, size.min(), size.max()));
|
||||
|
||||
Min min = field.getAnnotation(Min.class);
|
||||
Max max = field.getAnnotation(Max.class);
|
||||
if (min != null || max != null) {
|
||||
long lo = min != null ? min.value() : Long.MIN_VALUE;
|
||||
long hi = max != null ? max.value() : Long.MAX_VALUE;
|
||||
String message = rangeMessage(min, max);
|
||||
if (isIntegralPrimitive(type)) {
|
||||
checks.add(Check.rangePrimitive(name, message, asLong(getter), lo, hi));
|
||||
} else if (Number.class.isAssignableFrom(type) && ref != null) {
|
||||
checks.add(Check.rangeBoxed(name, message, ref, lo, hi));
|
||||
}
|
||||
}
|
||||
|
||||
if (field.isAnnotationPresent(Email.class) && ref != null)
|
||||
checks.add(Check.reference(Check.EMAIL, name, "must be a well-formed email address", ref));
|
||||
|
||||
Pattern pattern = field.getAnnotation(Pattern.class);
|
||||
if (pattern != null && ref != null) {
|
||||
// ponytail: the one allocating check — Pattern.matcher() per call. The regex itself is
|
||||
// compiled once here; swap for a structural check if a hot route ever needs it.
|
||||
checks.add(Check.pattern(name, "must match " + pattern.regexp(), ref,
|
||||
java.util.regex.Pattern.compile(pattern.regexp())));
|
||||
}
|
||||
}
|
||||
|
||||
private static boolean isIntegralPrimitive(Class<?> type) {
|
||||
return type == int.class || type == long.class || type == short.class || type == byte.class;
|
||||
}
|
||||
|
||||
private static MethodHandle asReference(MethodHandle getter) {
|
||||
return getter.asType(MethodType.methodType(Object.class, Object.class));
|
||||
}
|
||||
|
||||
private static MethodHandle asLong(MethodHandle getter) {
|
||||
return getter.asType(MethodType.methodType(long.class, Object.class));
|
||||
}
|
||||
|
||||
private static String sizeMessage(Size size) {
|
||||
if (size.min() == 0) return "size must be at most " + size.max();
|
||||
if (size.max() == Integer.MAX_VALUE) return "size must be at least " + size.min();
|
||||
return "size must be between " + size.min() + " and " + size.max();
|
||||
}
|
||||
|
||||
private static String rangeMessage(Min min, Max max) {
|
||||
if (min == null) return "must be at most " + max.value();
|
||||
if (max == null) return "must be at least " + min.value();
|
||||
return "must be between " + min.value() + " and " + max.value();
|
||||
}
|
||||
}
|
||||
+68
@@ -0,0 +1,68 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import dev.relism.flash.ext.jackson.JacksonExtension;
|
||||
import dev.relism.flash.ext.openapi.APIResponse;
|
||||
import dev.relism.flash.ext.openapi.ApiOperation;
|
||||
import dev.relism.flash.ext.openapi.Content;
|
||||
import dev.relism.flash.ext.openapi.OpenApiExtension;
|
||||
import dev.relism.flash.http.ContentType;
|
||||
import dev.relism.flash.models.Request;
|
||||
import dev.relism.flash.models.RequestHandler;
|
||||
import dev.relism.flash.models.Response;
|
||||
import dev.relism.flash.routing.GET;
|
||||
import dev.relism.flash.testing.FlashTest;
|
||||
import jakarta.validation.constraints.Email;
|
||||
import jakarta.validation.constraints.Max;
|
||||
import jakarta.validation.constraints.Min;
|
||||
import jakarta.validation.constraints.NotBlank;
|
||||
import jakarta.validation.constraints.Size;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.extension.RegisterExtension;
|
||||
|
||||
/**
|
||||
* Constraints are declared once and read twice: the validator enforces them, the published schema
|
||||
* describes them. Nothing registers this bridge — flash-ext-openapi picks the annotations up on
|
||||
* its own when they are on the classpath.
|
||||
*/
|
||||
class ValidationOpenApiInteropTest {
|
||||
|
||||
record Account(
|
||||
@NotBlank @Size(max = 40) String name,
|
||||
@Email String email,
|
||||
@Min(18) @Max(120) int age) {}
|
||||
|
||||
@GET("/accounts")
|
||||
@ApiOperation(summary = "List accounts")
|
||||
@APIResponse(responseCode = "200", content = @Content(contentType = ContentType.JSON, schema = Account.class))
|
||||
public static class ListAccounts extends RequestHandler {
|
||||
@Override public Object handle(Request request, Response response) {
|
||||
return new Account("alice", "a@b.com", 30);
|
||||
}
|
||||
}
|
||||
|
||||
@RegisterExtension
|
||||
static FlashTest app = FlashTest.of(configured -> {
|
||||
configured.install(new JacksonExtension());
|
||||
configured.install(new ValidationExtension());
|
||||
configured.install(new OpenApiExtension("/openapi", "Accounts", "1.0.0"));
|
||||
configured.scan("dev.relism.flash.ext.validation");
|
||||
});
|
||||
|
||||
@Test
|
||||
void constraintsAppearInTheGeneratedSchema() {
|
||||
app.get("/openapi.json")
|
||||
.expectStatus(200)
|
||||
.expectBodyContains("\"maxLength\":40")
|
||||
.expectBodyContains("\"format\":\"email\"")
|
||||
.expectBodyContains("\"minimum\":18")
|
||||
.expectBodyContains("\"maximum\":120");
|
||||
}
|
||||
|
||||
@Test
|
||||
void notBlankMarksThePropertyRequiredAndNonEmpty() {
|
||||
app.get("/openapi.json")
|
||||
.expectStatus(200)
|
||||
.expectBodyContains("\"minLength\":1")
|
||||
.expectBodyContains("\"required\":[\"name\"]");
|
||||
}
|
||||
}
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import dev.relism.flash.ext.jackson.JacksonExtension;
|
||||
import dev.relism.flash.testing.FlashTest;
|
||||
import jakarta.validation.constraints.Email;
|
||||
import jakarta.validation.constraints.Min;
|
||||
import jakarta.validation.constraints.NotBlank;
|
||||
import jakarta.validation.constraints.Size;
|
||||
import org.junit.jupiter.api.Test;
|
||||
import org.junit.jupiter.api.extension.RegisterExtension;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals;
|
||||
|
||||
/** The whole path: JSON in, constraints checked, status out — with no error handling wired up. */
|
||||
class ValidationRoutesTest {
|
||||
|
||||
record CreateUser(@NotBlank @Size(max = 8) String name, @Email String email, @Min(18) int age) {}
|
||||
|
||||
@RegisterExtension
|
||||
static FlashTest app = FlashTest.of(configured -> {
|
||||
configured.install(new JacksonExtension());
|
||||
configured.install(new ValidationExtension());
|
||||
|
||||
configured.ctx().onReady(() -> {
|
||||
Validation validation = configured.ctx().require(Validation.class);
|
||||
configured.post("/users", (req, res) ->
|
||||
res.status(201).body("created:" + validation.body(req, CreateUser.class).name()));
|
||||
});
|
||||
});
|
||||
|
||||
@Test
|
||||
void validBodyReachesTheHandler() {
|
||||
app.request().json("{\"name\":\"alice\",\"email\":\"a@b.com\",\"age\":30}").post("/users")
|
||||
.expectStatus(201)
|
||||
.expectBody("created:alice");
|
||||
}
|
||||
|
||||
@Test
|
||||
void constraintViolationBecomes422WithEveryFailureListed() {
|
||||
app.request().json("{\"name\":\"\",\"email\":\"nope\",\"age\":5}").post("/users")
|
||||
.expectStatus(422)
|
||||
.expectHeader("Content-Type", "application/json")
|
||||
.expectBodyContains("name must not be blank")
|
||||
.expectBodyContains("email must be a well-formed email address")
|
||||
.expectBodyContains("age must be at least 18");
|
||||
}
|
||||
|
||||
@Test
|
||||
void malformedJsonBecomes400NotAValidationFailure() {
|
||||
app.request().json("not json").post("/users")
|
||||
.expectStatus(400)
|
||||
.expectBodyContains("Invalid request body");
|
||||
}
|
||||
|
||||
/** Regression guard: HttpException used to reach the catch-all and come back as 500. */
|
||||
@Test
|
||||
void statusCarriedByTheExceptionSurvivesToTheWire() {
|
||||
assertEquals(422, app.request().json("{\"name\":\"x\",\"email\":\"a@b.com\",\"age\":1}")
|
||||
.post("/users").status());
|
||||
}
|
||||
|
||||
@Test
|
||||
void errorBodyIsValidJsonEvenWhenTheMessageContainsQuotes() {
|
||||
app.request().json("{\"name\":\"waaaaaaaaaay-too-long\",\"email\":\"a@b.com\",\"age\":30}").post("/users")
|
||||
.expectStatus(422)
|
||||
.expectBodyContains("\"status\":422")
|
||||
.expectBodyContains("size must be at most 8");
|
||||
}
|
||||
}
|
||||
+117
@@ -0,0 +1,117 @@
|
||||
package dev.relism.flash.ext.validation;
|
||||
|
||||
import jakarta.validation.constraints.Email;
|
||||
import jakarta.validation.constraints.Max;
|
||||
import jakarta.validation.constraints.Min;
|
||||
import jakarta.validation.constraints.NotBlank;
|
||||
import jakarta.validation.constraints.NotEmpty;
|
||||
import jakarta.validation.constraints.NotNull;
|
||||
import jakarta.validation.constraints.Pattern;
|
||||
import jakarta.validation.constraints.Size;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.*;
|
||||
|
||||
class ValidatorTest {
|
||||
|
||||
record CreateUser(
|
||||
@NotBlank @Size(max = 8) String name,
|
||||
@Email String email,
|
||||
@Min(18) @Max(120) int age,
|
||||
@NotNull String role) {}
|
||||
|
||||
record Boxed(@Min(1) Integer count) {}
|
||||
|
||||
record Sized(@NotEmpty List<String> tags, @Size(min = 2, max = 4) String code) {}
|
||||
|
||||
record Patterned(@Pattern(regexp = "[a-z]+") String slug) {}
|
||||
|
||||
record Plain(String anything) {}
|
||||
|
||||
private static ValidationException failureOf(Object value) {
|
||||
return assertThrows(ValidationException.class, () -> Validator.compile(value.getClass()).verify(value));
|
||||
}
|
||||
|
||||
@Test
|
||||
void aValidValuePasses() {
|
||||
assertDoesNotThrow(() ->
|
||||
Validator.compile(CreateUser.class).verify(new CreateUser("alice", "a@b.com", 30, "admin")));
|
||||
}
|
||||
|
||||
@Test
|
||||
void reportsEveryViolationNotJustTheFirst() {
|
||||
ValidationException failure = failureOf(new CreateUser(" ", "nope", 5, null));
|
||||
|
||||
assertEquals(List.of("name", "email", "age", "role"),
|
||||
failure.violations().stream().map(ValidationException.Violation::field).toList());
|
||||
}
|
||||
|
||||
@Test
|
||||
void violationsCarryFieldAndMessage() {
|
||||
ValidationException failure = failureOf(new CreateUser("alice", "a@b.com", 5, "admin"));
|
||||
|
||||
assertEquals(1, failure.violations().size());
|
||||
assertEquals("age", failure.violations().get(0).field());
|
||||
assertEquals("must be between 18 and 120", failure.violations().get(0).message());
|
||||
assertEquals(422, failure.status());
|
||||
assertEquals("age must be between 18 and 120", failure.getMessage());
|
||||
}
|
||||
|
||||
@Test
|
||||
void sizeCountsCharactersWithoutCopying() {
|
||||
assertEquals("name", failureOf(new CreateUser("far-too-long", "a@b.com", 30, "x"))
|
||||
.violations().get(0).field());
|
||||
}
|
||||
|
||||
@Test
|
||||
void onlyNotNullRejectsNull() {
|
||||
// @Email, @Size and @Min all accept null per Jakarta semantics; @NotNull is the one that does not.
|
||||
ValidationException failure = failureOf(new CreateUser("alice", null, 30, null));
|
||||
|
||||
assertEquals(List.of("role"),
|
||||
failure.violations().stream().map(ValidationException.Violation::field).toList());
|
||||
}
|
||||
|
||||
@Test
|
||||
void boxedNumbersUseTheReferencePathAndTolerateNull() {
|
||||
assertDoesNotThrow(() -> Validator.compile(Boxed.class).verify(new Boxed(null)));
|
||||
assertEquals("count", failureOf(new Boxed(0)).violations().get(0).field());
|
||||
}
|
||||
|
||||
@Test
|
||||
void sizeAppliesToCollectionsAndStrings() {
|
||||
assertDoesNotThrow(() -> Validator.compile(Sized.class).verify(new Sized(List.of("a"), "abc")));
|
||||
|
||||
ValidationException failure = failureOf(new Sized(List.of(), "x"));
|
||||
assertEquals(List.of("tags", "code"),
|
||||
failure.violations().stream().map(ValidationException.Violation::field).toList());
|
||||
}
|
||||
|
||||
@Test
|
||||
void patternIsAnchoredLikeJakarta() {
|
||||
assertDoesNotThrow(() -> Validator.compile(Patterned.class).verify(new Patterned("abc")));
|
||||
assertEquals("slug", failureOf(new Patterned("Abc1")).violations().get(0).field());
|
||||
}
|
||||
|
||||
@Test
|
||||
void emailAcceptsPlausibleAddressesAndRejectsTypos() {
|
||||
assertDoesNotThrow(() ->
|
||||
Validator.compile(CreateUser.class).verify(new CreateUser("a", "first.last@sub.example.co", 20, "x")));
|
||||
|
||||
for (String bad : List.of("no-at", "@leading.com", "trailing@", "two@@at.com", "no dots@x", "a@b")) {
|
||||
assertThrows(ValidationException.class,
|
||||
() -> Validator.compile(CreateUser.class).verify(new CreateUser("a", bad, 20, "x")),
|
||||
bad);
|
||||
}
|
||||
}
|
||||
|
||||
@Test
|
||||
void aTypeWithNoConstraintsCompilesToANoOp() {
|
||||
Validator validator = Validator.compile(Plain.class);
|
||||
|
||||
assertTrue(validator.isEmpty());
|
||||
assertDoesNotThrow(() -> validator.verify(new Plain(null)));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user