Skip to content

v3.2.1.md

Latest commit

 

History

History
209 lines (154 loc) · 7.67 KB

v3.2.1.md

File metadata and controls

209 lines (154 loc) · 7.67 KB
Raw

Rust-Java REST Framework v3.2.1

v3.2.1 is a stable patch release for production packaging and runtime hardening.

The application programming model does not change. Handlers, services, components, request records, response records, DB code, and business logic stay in Java. Rust continues to own the HTTP I/O plane, native memory limits, file streaming, WebSocket transport, and selected serialization-heavy paths.

What Is New For Users

  • The Maven dependency is now 3.2.1.
  • Production-like benchmark images can use rust-java-rest-*-core-runtime.jar instead of framework target/classes.
  • The default jar, core-runtime jar, sources jar, and javadocs exclude framework sample, benchmark, and Dubbo sample packages.
  • The sample classifier remains available for demos and local benchmarks, but should not be used as a production dependency.
  • Runtime profiles no longer overwrite values that users explicitly set in rust-spring.properties. JVM -D... system properties and environment variables still have the highest priority.
  • Benchmark/demo comparison routes can be marked @BenchmarkOnlyRoute; diagnostics now separate production route counts from sample comparison routes.
  • Documentation now calls out the production artifact rule directly: use the normal Maven dependency or core-runtime; keep sample/example classes out of production-like RSS measurements.

Maven

<dependency>
  <groupId>com.reactor</groupId>
  <artifactId>rust-java-rest</artifactId>
  <version>3.2.1</version>
</dependency>

GitHub Packages repository:

<repositories>
  <repository>
    <id>github</id>
    <url>https://maven.pkg.github.com/esasmer-dou/rust-java-rest</url>
  </repository>
</repositories>

For private package access, users need a GitHub token in ~/.m2/settings.xml with package access.

Production Artifact Rule

Use this in normal applications:

<dependency>
  <groupId>com.reactor</groupId>
  <artifactId>rust-java-rest</artifactId>
  <version>3.2.1</version>
</dependency>

Use this only when building a single framework runtime classpath for benchmark/container checks:

  • rust-java-rest-3.2.1-core-runtime.jar

Do not use this in production:

  • rust-java-rest-3.2.1-sample.jar

The sample jar intentionally contains demo handlers, DTOs, benchmark endpoints, and a sample startup index. It is useful for examples, but it can pollute production-like RSS measurements.

Documentation clarification:

  • The existing 3.2.1 Maven package already applies this split.
  • rust-java-rest-3.2.1.jar, rust-java-rest-3.2.1-core-runtime.jar, sources, and javadocs do not contain framework sample/benchmark packages.
  • rust-java-rest-3.2.1-sample.jar intentionally keeps those packages for demos and local endpoint benchmarks.
  • Do not republish changed package bytes under the same version. If packaged code or native assets must change, publish the next patch version instead.

Verified package shape:

Jar Sample/benchmark package count
rust-java-rest-3.2.1.jar 0
rust-java-rest-3.2.1-core-runtime.jar 0
rust-java-rest-3.2.1-sample.jar 115

Runtime Profile Override Behavior

Profiles still provide safe defaults. For example, micro-rest keeps optional runtime surfaces small.

If a user explicitly sets a value in rust-spring.properties, the profile no longer overwrites it:

reactor.runtime.profile=micro-rest
reactor.websocket.enabled=true

This is useful when a small service really needs WebSocket or static files. Do not enable optional surfaces "just in case"; enable only features that are part of the service contract.

Priority order remains:

  1. JVM system property, for example -Dreactor.websocket.enabled=true
  2. Environment variable, for example REACTOR_WEBSOCKET_ENABLED=true
  3. rust-spring.properties
  4. Runtime profile defaults
  5. Built-in framework defaults

Benchmark And RSS Notes

Latest native-static Dubbo consumer smoke check, cpu1, idle 5s:

Framework artifact mode Ready RSS MiB After first RPC RSS MiB Docker Mem MiB ready Image build context
core-runtime 57.27 58.28 30.00 5.01 MB
classes 58.75 59.88 31.48 9.99 MB

Read this correctly: this patch is not a broad JVM RSS breakthrough. The main value is measurement correctness and packaging discipline. RSS can remain close because unloaded classes do not always become live RSS, but core-runtime avoids accidental sample classpath and startup-index pollution.

For production RSS reporting, prefer the minimal production smaps runner:

powershell -ExecutionPolicy Bypass -File .\benchmark\linux_smaps_breakdown.ps1 `
  -AppMode minimal `
  -RuntimeProfile micro-rest `
  -ConcurrencyValues 64,256 `
  -DurationSeconds 4 `
  -IdleSeconds 3 `
  -FinalIdleSeconds 6

Local comparison after separating sample and minimal production app modes:

Phase Sample app Minimal production app Delta
Baseline cgroup RSS 42.863 MiB 30.164 MiB -12.699 MiB
Baseline loaded classes 2505 1965 -540
Final idle cgroup RSS 58.723 MiB 45.219 MiB -13.504 MiB
Final heap used 9.490 MiB 2.720 MiB -6.770 MiB

Use the bundled sample app only for demo-route behavior. Use the minimal production app, or the real service image, for package/RSS claims.

Optional JIT-Cap Gate

openj9-micro-rss-jitcap.options is intentionally not the default runtime recipe. It caps OpenJ9 JIT code cache with -Xcodecachetotal8m, so it can lower RSS, but it must not be selected only by memory gain.

Full local gate, micro-rest, c64/c256/c512, sample repeat 3, minimal smaps repeat 3:

Gate Result
Optional JIT-cap usable for the common endpoint set FAIL
Default profile candidate FAIL
Minimal production RSS gain 5.952 MiB
p99 regression failures 4
Legacy dynamic DTO c256/c512 regressions 2

Minimal production memory moved in the right direction:

Metric Default JIT-cap Delta
cgroup current 57.358 MiB 51.406 MiB -5.952 MiB
cgroup anon 45.301 MiB 45.024 MiB -0.277 MiB
JIT code committed 22 MiB 10 MiB -12 MiB

The profile still failed because p99 regressed for parts of the mixed endpoint matrix. For hot heavy JSON routes, move from dynamic DTO graph creation to JsonProducerResponse or direct writer first, then retest the service-specific matrix. In the current branch, the bundled sample benchmark exposes that split directly: /api/v1/heavy/dto is the optimized DTO-shaped producer path and /api/v1/heavy/dto/legacy is the real DTO graph comparison path.

Native Assets

Release assets include:

  • rust_hyper-windows-x64.dll
  • librust_hyper-linux-x64.so
  • SHA256SUMS

The Maven package also includes native resources under:

  • native/windows-x64/rust_hyper.dll
  • native/windows-x64/rust_hyper-windows-x64.dll
  • native/linux-x64/librust_hyper.so
  • native/linux-x64/librust_hyper-linux-x64.so

Java checks the native ABI at startup and fails early if the DLL/SO does not match the Java artifact.

Validation

Validated before release:

mvn -q test
mvn -q -DskipTests package

Additional release checks:

  • Main jar, core-runtime, and sources jar contain no sample/benchmark packages.
  • Native-static Dubbo consumer smoke benchmark works with -FrameworkArtifactMode core-runtime.
  • Sample consumer/provider documentation was updated to reference rust-java-rest 3.2.1.