Fluxzero 1.161.0

1.161.0 (2026-05-10)

Features

• feat(web): serve generated API reference pages (25aeb87)

  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 verification.

  Tests run: ./mvnw -pl sdk -Dtest=ApiDocExtractorTest,OpenApiRendererTest,HandleWebTest test; ./mvnw -pl proxy -am -Dtest='ProxyServerTest#openApiDocumentIsServedAsJsonDocument' -Dsurefire.failIfNoSpecifiedTests=false test

• feat(web): use Javadoc fallback for OpenAPI schema docs (4c9b73d)

  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.

  Tests: ./mvnw -pl sdk -Dtest=OpenApiRendererTest test

  Tests: ./mvnw -pl annotation-processor-tests -am -Dtest=OpenApiProcessorTest -Dsurefire.failIfNoSpecifiedTests=false test

• feat(web): support shared OpenAPI refs (3ee04b1)

  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.

  Tests: ./mvnw -pl sdk,annotation-processor-tests -am -Dtest=OpenApiRendererTest,OpenApiProcessorTest -Dsurefire.failIfNoSpecifiedTests=false test

• feat(web): serve generated OpenAPI docs (910bd94)

  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.

  Tests: ./mvnw -pl sdk -Dtest=HandleWebTest test

• feat(web): generate OpenAPI docs from SDK annotations (0bd0888)

  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.

  Tests: ./mvnw -B install; ./mvnw -pl sdk,annotation-processor-tests -am test -Dtest=WebRouteMatcherTest,HandleWebTest,RestTests,OpenApiRendererTest,OpenApiProcessorTest -Dsurefire.failIfNoSpecifiedTests=false; Flowmaps system-api clean compile.

• feat(web): render api docs as openapi (ba14d7c)

  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.

  Tests run: git diff --check; ./mvnw -pl sdk -am -Dtest=OpenApiRendererTest,ApiDocExtractorTest,WebRouteMatcherTest,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test; ./mvnw -B install

• feat(web): add api doc metadata extractor (2ae9782)

  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.

  Tests: git diff --check; ./mvnw -pl sdk -am -Dtest=ApiDocExtractorTest,WebRouteMatcherTest,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test; ./mvnw -B install

• feat(web): support optional route fragments (0603ee3)

  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.

  Tests: git diff --check; ./mvnw -pl sdk -am -Dtest=WebRouteMatcherTest,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test; ./mvnw -B install

• feat(web): ignore trailing slashes in routes (0d1d90a)

  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.

  Tests: git diff --check; ./mvnw -pl sdk -am -Dtest=WebRouteMatcherTest,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test

• feat(web): add automatic HEAD and OPTIONS helpers (9a3e3d2)

  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.

  Tests: git diff --check; ./mvnw -pl sdk -am -Dtest=WebMatcherTest,WebRouteMatcherTest,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test; ./mvnw -B install

• feat(web): negotiate response content type (dcb47bc)

  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.

  Tests: ./mvnw -pl sdk -Dtest=DefaultWebResponseMapperTest,HandleWebTest test; ./mvnw -pl sdk test; ./mvnw -B clean install

• feat(web): support multipart form parameters (26fd6fe)

  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.

  Tests: ./mvnw -pl sdk -Dtest=DefaultWebRequestContextTest,HandleWebTest,WebRouteMatcherTest,WebMatcherTest test; ./mvnw -pl sdk test; ./mvnw -B clean install

Bug Fixes

• fix(web): ignore non-web current context (7a4a763)

  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.

  Tests: ./mvnw -pl sdk -Dtest=DefaultWebResponseMapperTest,DefaultWebRequestContextTest,HandleWebTest test

Performance Improvements

• perf(web): reduce route matcher overhead (29a8b4e)

  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: ./mvnw -pl sdk,annotation-processor-tests -am -Dtest=HandleWebTest,WebRouteMatcherTest,OpenApiRendererTest,OpenApiProcessorTest -Dsurefire.failIfNoSpecifiedTests=false test

Tests

• test(entity): stabilize snapshot previous replay test (9769f8e)
• test(proxy): serialize cors property tests (93bf4b8)

  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.

  Tests: ./mvnw -pl proxy -am -Dtest=ProxyServerTest$CorsTests -Dsurefire.failIfNoSpecifiedTests=false test

• test(proxy): cover cors preflight options boundary (d43961b)

  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.

  Tests: git diff --check; ./mvnw -pl proxy -am -Dtest=ProxyServerTest$CorsTests,HandleWebTest -Dsurefire.failIfNoSpecifiedTests=false test; ./mvnw -B install