Changelog — page 21

New features, improvements, and fixes in the Fluxzero SDK.

2026

May 16, 2026

May 16, 2026 · 1.169.0

GitHub

1.169.0 (2026-05-16)

Features

errors: add human-readable SDK error reports (GitHub)

Introduce stable Fluxzero SDK error codes with formatted guidance, docs URLs, and compact repeated-message summaries. Wire the reports into timeout, dispatch, tracking, scheduling, user-provider, and missing-instance failures while preserving existing exception constructors.

Document the codes in the README and downstream agent docs.

Tests

caching: stabilize memory eviction listener test (GitHub)

Wait for asynchronous reference-queue eviction instead of relying on a fixed sleep. Use a thread-safe event list and close test caches so purger threads do not leak between tests.
validation: add test for deserialization of ValidationException without summaries (GitHub)

May 16, 2026

May 16, 2026 · 1.168.0

GitHub

1.168.0 (2026-05-16)

Features

validation: expose violation summaries (GitHub)

Add string-only violation summaries to ValidationException so callers can inspect validation messages by property path even when legacy violation strings contain custom messages.

Closes #67.

May 16, 2026

May 16, 2026 · 1.167.0

GitHub

1.167.0 (2026-05-16)

Features

tracking: support message log truncation (GitHub)

Add a truncate command and expose it through GatewayClient and GenericGateway, with local stores and the test server clearing message logs and associated positions.

Also tighten caching tracking invalidation around truncate support and document the public API/Javadoc expectation.

May 15, 2026

May 15, 2026 · 1.166.0

GitHub

1.166.0 (2026-05-15)

Features

configuration: support additional property locations (GitHub)

Load extra Fluxzero configuration from FLUXZERO_CONFIG_LOCATIONS, with a lowercase JVM alias of fluxzero.config.locations. This lets deployments mount secrets or environment-specific config outside the application artifact without having to overload application.properties.

The source supports comma-separated file:, plain path, and classpath: locations. optional: locations are ignored when missing, later configured locations override earlier ones, and the source sits below environment/JVM system properties but above application-<env>.properties and application.properties.
configuration: load fluxzero property resources (GitHub)

Add a Fluxzero-specific default configuration source for classpath-root fluxzero.properties and fluxzero.json resources. This gives SDK settings an explicit home without forcing customers to mix Fluxzero defaults into application.properties.

The new source is intentionally lower priority than application.properties and application-<env>.properties, so applications can override SDK defaults through their existing config files. JSON files are flattened to dot-separated property names, and fluxzero.properties overrides fluxzero.json within this source.
validation: validate request handler return values (GitHub)

Validate constrained return values for non-passive request handler methods, covering command, query, custom, and web request handlers. This catches invalid handler responses before they are published as result or web response messages.

The behavior is limited to annotated handler methods that declare return-value validation. Passive handlers and event handlers keep their previous behavior, and web request handlers are wired only for return-value validation so request payload handling is not broadened accidentally.
validation: allow bean getter compatibility mode (GitHub)

Keep Fluxzero validation annotation-led by default while adding a compatibility switch for projects that relied on Hibernate Validator only treating JavaBean-style getters as constrained bean properties.

Setting fluxzero.validation.beanPropertyMethodNamesOnly=true limits method-property validation to getX(), isX(), and hasX() methods. Fields, Kotlin constructor parameter support, groups, cascaded validation, and executable validation remain unchanged.
validation: add built-in Jakarta validator (GitHub)

Replace the Hibernate Validator-backed JSR380 adapter with Fluxzero's own reflection-based validation implementation. The new default validator supports Jakarta constraints, custom validators, groups, group sequences and conversions, cascaded and type-use validation, executable validation, provider bootstrap, metadata lookup, value extractors, Fluxzero clocks, and SDK-owned constraint violations.

Add Fluxzero convenience constraints, OpenAPI rendering for those constraints, Kotlin annotation coverage, provider/TCK-inspired tests, and a runnable validation benchmark. Document the supported Jakarta Validation profile and the intentionally unsupported XML/CDI/full-EL/TCK edge cases.

May 14, 2026

May 14, 2026 · 1.165.1

GitHub

1.165.1 (2026-05-14)

Bug Fixes

websocket: reuse session users after open (GitHub)

Pin the user accepted during socket creation for established websocket frames, while keeping handshake and open authorization tied to the current request. Refresh-capable user providers can update the pinned identity before authorization without re-authenticating every socket frame.

Also preserves web request invocation semantics so missing request users do not fall back to active users during handler execution.
websocket: authorize automatic handshakes (GitHub)

Use handler metadata on synthetic automatic handshake invokers so the existing authentication interceptor can enforce requirements before a socket is established. Split websocket handling into handshake and lifecycle decorators so handshake authorization still flows through the normal handler chain while open failures continue to close the socket.

May 14, 2026

May 14, 2026 · 1.165.0

GitHub

1.165.0 (2026-05-14)

Build System

maven: add downstream project checks (GitHub)

Add parentless Java and Kotlin downstream project modules that exercise the published BOM, SDK test-jar, annotation processors, test-server, and proxy without producing deployable artifacts.

Enforce Maven 3.9+ and Java 21+ in the build, keep compilation at release 21, and ensure release version bumps include parentless modules.
testing: make surefire argLine merge-friendly (GitHub)

May 13, 2026

May 13, 2026 · 1.164.1

GitHub

1.164.1 (2026-05-13)

Dependency updates

bump org.slf4j:slf4j-api from 2.0.17 to 2.0.18 (GitHub)

org.slf4j:slf4j-api: 2.0.17 -> 2.0.18

May 12, 2026

May 12, 2026 · 1.164.0

GitHub

1.164.0 (2026-05-12)

Features

publishing: limit recursive publication depth (GitHub)

Add a publication-depth guard that tracks nested publications in metadata and blocks chains above the configured maximum. Expose maxPublicationDepth through configuration, support fluxzero.maxPublicationDepth through PropertySource, and allow negative values to disable the guard.

May 12, 2026

May 12, 2026 · 1.163.1

GitHub

1.163.1 (2026-05-12)

Bug Fixes

tracking: separate local notification tracking (GitHub)

Keep local notification tracking on the shared event store while exposing it as MessageType.NOTIFICATION, so notification consumers keep their own tracking semantics even when a handler also has event methods and a custom consumer name.

Add regression coverage for handlers that define both @HandleEvent and @HandleNotification methods, including a @Consumer-annotated handler.

May 12, 2026

May 12, 2026 · 1.163.0

GitHub

1.163.0 (2026-05-12)

Features

modeling: support aggregate event routing (GitHub)

Add aggregate and apply-level controls for event segment routing so aggregate events can opt into aggregate-id based segments while preserving message routing as the default. Set aggregate-id segments before serialized dispatch interceptors run, leaving the regular routing interceptor as a fallback for unset segments.

Chores

run: add ProxyServer configuration and simplify TestServer run config (GitHub)

May 12, 2026

May 12, 2026 · 1.162.5

GitHub

1.162.5 (2026-05-12)

Dependency updates

bump distroless/java25-debian13 in /test-server (GitHub)

distroless/java25-debian13: b1eb8a1 -> c0d379f
bump distroless/java25-debian13 in /proxy (GitHub)

distroless/java25-debian13: b1eb8a1 -> c0d379f

Continuous Integration

switch to app token for Dependabot auto-merge (GitHub)

May 11, 2026

May 11, 2026 · 1.162.4

GitHub

1.162.4 (2026-05-11)

Bug Fixes

web: dedupe automatic API docs endpoints (GitHub)

Package-level ApiDocInfo created the same generated OpenAPI and API reference handlers once per web handler in the package. Deduplicate these automatic endpoints by their route path so a proxied docs request receives a single response per app, matching the static file handler behavior.

May 11, 2026

May 11, 2026 · 1.162.3

GitHub

1.162.3 (2026-05-11)

Bug Fixes

web: avoid Jackson discovery in OpenAPI processor (GitHub)

Use a processor-local JsonMapper for generated OpenAPI JSON so annotation processing does not initialize JsonUtils and trigger Jackson ServiceLoader module discovery. This avoids Gradle and kapt classloader failures such as Jdk8Module or ParameterNamesModule not being assignable to the processor's Module type.

May 11, 2026

May 11, 2026 · 1.162.2

GitHub

1.162.2 (2026-05-11)

Bug Fixes

test-server: clean up websocket sessions reliably (GitHub)

Align the test server websocket lifecycle with the runtime by tracking active sessions, sending server-side pings, removing sessions on close or ping timeout, and sharing command idempotency across endpoints. This prevents queued work from re-registering stale trackers after a websocket close.

May 11, 2026

May 11, 2026 · 1.162.1

GitHub

1.162.1 (2026-05-11)

Bug Fixes

web: serve generated OpenAPI document for instances (GitHub)

May 11, 2026

May 11, 2026 · 1.162.0

GitHub

1.162.0 (2026-05-11)

Continuous Integration

replace Renovate with Dependabot (GitHub)

Configure Dependabot for Maven, GitHub Actions, and Docker updates, and add a pull_request_target workflow that enables rebase auto-merge for selected Dependabot PRs once required checks pass.

Also serialize main deploy runs so a running release is allowed to finish while newer pending deploys replace older pending deploys in the concurrency group.

Checks: go run github.com/rhysd/actionlint/cmd/actionlint@latest; ruby YAML parse for workflows and dependabot.yml; bash -n for workflow run steps;

May 11, 2026

May 11, 2026 · 1.161.1

GitHub

1.161.1 (2026-05-11)

Bug Fixes

web: guard OpenAPI processor meta annotation cycles (GitHub)

May 10, 2026

May 10, 2026 · 1.161.0

GitHub

1.161.0 (2026-05-10)

Features

web: serve generated API reference pages (GitHub)

Add ApiDocInfo configuration for Redoc, Scalar, and Swagger UI reference pages, and register the generated HTML endpoints alongside the OpenAPI JSON endpoint.

Fix OpenAPI JSON serving through the proxy by returning a JSON tree instead of serializing the document as a string, and prefer runtime extraction for handler instances so scoped docs stay correct.

Add a proxy test-scope demo app that starts TestServer, ProxyServer, and documented SDK handlers for browser
web: use Javadoc fallback for OpenAPI schema docs (GitHub)

Use source Javadoc as the last description fallback in the OpenAPI annotation processor, after Swagger @Schema metadata and Fluxzero @ApiDoc metadata. Document that this only works for source available in the same javac compilation, and add Lombok coverage so generated getters do not mask field documentation.
web: support shared OpenAPI refs (GitHub)

Add SDK-native OpenAPI security requirements and reusable response references to both the runtime renderer and annotation processor. This keeps projects dependency-free while still allowing shared components such as error responses and bearer auth schemes.
web: serve generated OpenAPI docs (GitHub)

Add opt-in ApiDocInfo settings for serving the generated OpenAPI document through an internal Fluxzero web handler. Relative openApiPath values resolve against the package or handler Path where ApiDocInfo is declared, and the generated endpoint is marked NoUserRequired.
web: generate OpenAPI docs from SDK annotations (GitHub)

Add SDK-native API documentation metadata, an OpenAPI renderer, and an annotation processor that emits META-INF/fluxzero/openapi.json for opted-in web handlers. The generated schemas cover ApiDoc metadata, repeatable responses, ApiDocInfo components, validation hints, JsonValue types, Jackson polymorphism, multipart forms, and sorted component schemas.

Tighten generated web parameter signatures so annotated parameters with type-use metadata compile cleanly, and index route matching candidates by method, origin, and literal path prefix before applying regex matching.
web: render api docs as openapi (GitHub)

Render ApiDocCatalog as OpenAPI 3.1 JSON via OpenApiRenderer and OpenApiOptions.

Cover parameters, request bodies, responses, inline schemas, servers, and docs metadata while skipping Fluxzero websocket pseudo methods.
web: add api doc metadata extractor (GitHub)

Introduce generic ApiDoc annotations and a format-neutral API documentation catalog for web handlers. The extractor reuses runtime WebPattern resolution, expands optional route fragments, infers web parameters and request bodies, and supports docs-only exclusions at package, type, and method level.

ApiDocResponse is repeatable and response metadata merges from package/class to endpoint with endpoint-specific values winning.
web: support optional route fragments (GitHub)

Expand bracketed route fragments such as /users[/{id}] into concrete matcher variants while preserving the specificity ordering. Explicit routes beat equivalent optional variants, WebRequestContext.matches uses the same expansion, and adjacent optional parameters bind left-to-right.

Document the syntax in README, agent rules, and web annotation javadocs.
web: ignore trailing slashes in routes (GitHub)

Treat non-root web routes with and without a final slash as equivalent during route matching, while preserving root route behavior and existing wildcard semantics. Document the policy and cover both direct matcher and handler invocation paths.
web: add automatic HEAD and OPTIONS helpers (GitHub)

Generate HEAD responses from matching GET handlers and OPTIONS Allow responses from matching web routes while keeping explicit HEAD, OPTIONS, and ANY handlers authoritative across handlers in the same factory. Add route-level autoHead and autoOptions opt-outs for multi-service deployments.
web: negotiate response content type (GitHub)

Apply best-effort content negotiation for automatically mapped web handler results before web responses are serialized. Explicit WebResponse content types and explicit Content-Type metadata keep taking precedence, while unsupported Accept values fall back to existing defaults.

Document the behavior in the README and project-files agent rules.
web: support multipart form parameters (GitHub)

Parse multipart/form-data bodies inside DefaultWebRequestContext and expose each part through the new WebFormPart type. @FormParam can now resolve text fields as String and file parts as WebFormPart, byte[], or InputStream while URL-encoded form behavior is preserved.

Update README, javadocs, and project-files agent docs to describe the multipart support.

Bug Fixes

web: ignore non-web current context (GitHub)

Content negotiation is best-effort and may run while a non-web handler sends websocket updates. Avoid constructing a DefaultWebRequestContext unless the current message is a WEBREQUEST, so notification/event handlers in mixed web classes can still send websocket messages.

Performance Improvements

web: reduce route matcher overhead (GitHub)

Find the most specific matching route before materializing path parameters. This avoids stream, Optional, comparator-chain, and path-parameter map allocation for every candidate route, while keeping the same specificity ordering.

JFR benchmark: 5k mixed routes, 3M matches improved from ~1977 ns/match to ~1126 ns/match; remaining hot methods are regex matching.

Tests

entity: stabilize snapshot previous replay test (GitHub)
proxy: serialize cors property tests (GitHub)

The proxy CORS tests mutate FLUXZERO_CORS_DOMAINS, which is a JVM-wide system property. Add a JUnit resource lock so parallel test execution cannot clear or change the property while another CORS request is in flight.
proxy: cover cors preflight options boundary (GitHub)

Verify that configured and allowed CORS preflight OPTIONS requests are answered by the proxy without invoking runtime @HandleOptions handlers, while non-preflight OPTIONS requests still reach runtime routing and can use the SDK automatic OPTIONS helper. Document that proxy preflight handling sits before WebRequest forwarding.

May 10, 2026

May 10, 2026 · 1.160.0

GitHub

1.160.0 (2026-05-10)

Code Refactoring

web: replace Jooby route matching (GitHub)

Remove the Jooby dependency from the SDK web dispatch path and introduce a small SDK-owned route matcher with specificity ordering for literals, parameters, constrained parameters, wildcards, and catch-all routes.

Keep web parameter binding working without Jooby, document the route rules, clarify multipart/raw-payload behavior, and add an explicit slf4j-api dependency for common annotation processing now that Jooby no longer brings it transitively.

May 10, 2026

May 10, 2026 · 1.159.5

GitHub

1.159.5 (2026-05-10)

Bug Fixes

websocket: isolate JDK websocket callbacks (GitHub)

Route the native JDK websocket client and listener callbacks through a Fluxzero-managed executor from ObjectUtils instead of relying on the common pool. Preserve custom HttpClient executors and add coverage for default and supplied callback executors.

Changes

Revert "deps(sdk): remove nullable annotation dependency" (GitHub)

This reverts commit fde13f86