Merge pull request #136 from dev-five-git/improve-performance-2

Improve performance 2

Author: owjs3901

.changepacks/changepack_log_openapi-3-1-schema-output.json

@@ -0,0 +1 @@
+{"changes":{"Cargo.toml":"Minor","crates/vespera_core/Cargo.toml":"Minor","crates/vespera_macro/Cargo.toml":"Minor","crates/vespera_inprocess/Cargo.toml":"Minor","crates/vespera_jni/Cargo.toml":"Minor","crates/vespera/Cargo.toml":"Minor","libs/vespera-bridge/build.gradle.kts":"Minor"},"note":"BREAKING (0.x minor): OpenAPI schema output is now strict OpenAPI 3.1 / JSON Schema 2020-12: nullable schemas serialize as type:[...,\"null\"] or nullable $ref anyOf, and schema-level #[schema(example = ...)] serializes as examples:[...] instead of singular example. SecurityScheme now includes OAuth/OpenID fields flows and openIdConnectUrl. vespera-bridge 0.2.0 DecodedResponse.body() returns a read-only ByteBuffer; use bodyBytes() for an owned byte[] copy.","date":"2026-06-20T00:00:00.000Z"}

.changepacks/changepack_log_release-0-2-0-bridge.json

@@ -0,0 +1 @@
+{"changes":{"Cargo.toml":"Minor","libs/vespera-bridge/build.gradle.kts":"Minor","libs/vespera-bridge-gradle-plugin/build.gradle.kts":"Minor"},"note":"0.2.0 / 0.3.0 release — BREAKING (0.x minor): DecodedResponse.body() returns read-only ByteBuffer (bodyBytes() copies on demand); SmartDispatchModeResolver is the autoconfigured default (DIRECT ~2.2µs / SYNC ~3.2µs for small requests, opt out via vespera.bridge.dispatch-mode=bidirectional-streaming); Gradle plugin now also publishes to the Plugin Portal. Perf: JMethodID+GlobalRef caching for streaming closures, daemon-attached dispatchAsync completion, lazy bidirectional request-pull (spawn on first body poll), JsonGenerator wire-header encoding, zero-copy get_byte_array_region input conversion. Rust: Validated 422 envelope via derive(Serialize) (byte-identical, snapshot-locked), per-invocation fs::metadata epoch caching in vespera_macro, collector clone elimination. See libs/vespera-bridge/docs/jni-before-after-2026-06-11.md for measured numbers.","date":"2026-06-12T13:00:00.000Z"}

.changepacks/config.json

@@ -9,6 +9,7 @@
     ]
   },
   "publish": {
-    "java": "./gradlew publishToMavenCentral --stacktrace"
+    "java": "./gradlew publishToMavenCentral --stacktrace",
+    "libs/vespera-bridge-gradle-plugin/build.gradle.kts": "./gradlew publishToMavenCentral publishPlugins --stacktrace"
   }
 }

.github/workflows/CI.yml

@@ -24,7 +24,7 @@ jobs:
       image: xd009642/tarpaulin:develop-nightly
       options: --security-opt seccomp=unconfined
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: latest
@@ -39,6 +39,11 @@ jobs:
         run: cargo clippy --all-targets --all-features -- -D warnings
       - name: Test Deploy
         run: cargo publish --dry-run
+      - name: Doctest
+        # tarpaulin's --all-targets / default run never compiles doc
+        # tests, which let a never-passing doctest land unnoticed —
+        # run them explicitly before the (slow) coverage step.
+        run: cargo test --workspace --doc
       - name: Test
         run: |
           # rust coverage issue
@@ -53,18 +58,86 @@ jobs:
           cargo fmt
           cargo tarpaulin --out Lcov Stdout --engine llvm
       - name: Upload to codecov.io
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@v7
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: true
           files: lcov.info
         if: github.ref == 'refs/heads/main'
 
+  # OBSERVATIONAL ONLY — this job must never gate, and its percentage must
+  # never become a threshold. Rust's branch instrumentation is still unstable
+  # (rust-lang/rust#79649), and rust-lang/rust#124118 lists as NOT yet
+  # supported: match arms and or-patterns, the `?` operator, `.await`, and
+  # any branch introduced by macro expansion — "the current implementation
+  # discards any branch span that isn't directly visible in the function
+  # body". vespera_macro owns roughly four fifths of the measured branches
+  # and exists to generate code inside `quote!`, so those generated branches
+  # are not reported as uncovered — they are dropped from the denominator.
+  # The number therefore under-counts precisely where this codebase is most
+  # complex, which is why it is a trend signal and not a pass/fail metric.
+  #
+  # vespera_jni is excluded for the same reason tarpaulin excludes it: it
+  # cannot run without a JVM, and jni-e2e is its real coverage. Including it
+  # reports ~4% branch and drowns out every other crate.
+  rust-branch-coverage:
+    name: Rust branch coverage (observational)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: dtolnay/rust-toolchain@nightly
+        with:
+          components: llvm-tools-preview
+      - uses: taiki-e/install-action@cargo-llvm-cov
+      - name: Run instrumented tests
+        # Allowed to fail. This pins a MOVING nightly, and toolchain drift
+        # breaks tests that assert compiler output — the trybuild UI suite
+        # blesses its .stderr files against stable, so a nightly diagnostic
+        # reword fails it with nothing actually broken. The profraw data is
+        # still written, so the report step below runs regardless.
+        continue-on-error: true
+        run: cargo llvm-cov --branch --workspace --no-fail-fast --no-report
+      - name: Summarise branch coverage
+        run: |
+          # `--branch` belongs on the instrumented RUN above, not here: the
+          # profdata already carries branch counters, and `report` rejects
+          # the flag.
+          cargo llvm-cov report --summary-only \
+            --ignore-filename-regex '(benches|examples|vespera_jni)' \
+            | tee branch-coverage.txt
+          {
+            echo '### Rust branch coverage (observational)'
+            echo
+            echo 'Excludes benches, examples and `vespera_jni` (JVM-only — covered by jni-e2e).'
+            echo 'Not a gate: see the job comment in CI.yml for why this number under-counts.'
+            echo
+            echo '```'
+            cat branch-coverage.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+      - name: Generate lcov
+        if: always()
+        run: |
+          cargo llvm-cov report --lcov --output-path branch-lcov.info \
+            --ignore-filename-regex '(benches|examples|vespera_jni)'
+      - name: Upload branch coverage report
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: rust-branch-coverage
+          path: |
+            branch-coverage.txt
+            branch-lcov.info
+
   # publish
   changepacks:
     name: changepacks
     runs-on: ubuntu-latest
-    needs: test
+    # jni-e2e gates publishing: a release must never ship with a broken
+    # JNI dispatch path on any supported OS.
+    needs: [test, jni-e2e]
     permissions:
       # create pull request comments
       pull-requests: write
@@ -76,7 +149,7 @@ jobs:
       # Publish to GitHub Packages
       packages: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
@@ -101,6 +174,105 @@ jobs:
           # GPG signing (in-memory key, no keyring file)
           ORG_GRADLE_PROJECT_signingInMemoryKey: ${{ secrets.GPG_SIGNING_KEY }}
           ORG_GRADLE_PROJECT_signingInMemoryKeyPassword: ${{ secrets.GPG_SIGNING_PASSWORD }}
+          # Gradle Plugin Portal credentials (read natively by
+          # com.gradle.plugin-publish for the `publishPlugins` task)
+          GRADLE_PUBLISH_KEY: ${{ secrets.GRADLE_PUBLISH_KEY }}
+          GRADLE_PUBLISH_SECRET: ${{ secrets.GRADLE_PUBLISH_SECRET }}
     outputs:
       changepacks: ${{ steps.changepacks.outputs.changepacks }}
       release_assets_urls: ${{ steps.changepacks.outputs.release_assets_urls }}
+
+  # Java gate — builds the rust-jni-demo cdylib, runs the vespera-bridge unit
+  # suite, publishes the bridge JAR to mavenLocal (so the demo-app Gradle
+  # plugin can resolve kr.devfive:vespera-bridge), then runs the full
+  # :demo-app:test suite (StreamingClosureStressTest + JNI dispatch tests)
+  # across all three target host OSes.
+  #
+  # This is the ONLY thing that exercises Java in this repository, and it is
+  # also what covers `crates/vespera_jni`: that crate is excluded from
+  # tarpaulin (`#![cfg(not(tarpaulin_include))]`) because its symbols cannot
+  # run without a JVM, so this job is its coverage — not the Rust line
+  # coverage number.
+  #
+  # Runs unconditionally on every push/PR (matching the existing CI job's
+  # style — no per-job paths-filter). The whole workflow already inherits
+  # the workflow-level `paths-ignore` for docs-only changes.
+  jni-e2e:
+    name: JNI E2E (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+          cache: 'gradle'
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+      - name: Build rust-jni-demo cdylib (release)
+        # The vespera-bridge Gradle plugin's bundleNativeLib task copies
+        # this cdylib from target/release into demo-app's resources, so it
+        # must exist before `:demo-app:test` (processResources) runs.
+        run: cargo build -p rust-jni-demo --release
+      - name: Make gradlew executable (unix)
+        if: runner.os != 'Windows'
+        run: |
+          chmod +x libs/vespera-bridge/gradlew
+          chmod +x libs/vespera-bridge-gradle-plugin/gradlew
+          chmod +x examples/rust-jni-demo/java/gradlew
+      - name: Publish vespera-bridge Gradle plugin to mavenLocal
+        # demo-app's plugins block resolves kr.devfive.vespera-bridge from
+        # mavenLocal (settings.gradle.kts pluginManagement) — the plugin is
+        # not on the Gradle Plugin Portal.
+        shell: bash
+        working-directory: libs/vespera-bridge-gradle-plugin
+        run: ./gradlew publishToMavenLocal --console=plain --no-daemon
+      - name: Run vespera-bridge unit tests
+        # The bridge's own suite: wire codec, zero-copy header reader, direct
+        # buffer pool, hop-by-hop header policy, dispatch-mode resolvers and
+        # the Spring autoconfiguration. Until now the workflow only PUBLISHED
+        # this library, so none of these ever ran in CI — the Rust side was
+        # gated while ~2 kLOC of Java shipped untested. Runs before the publish
+        # step so a broken bridge fails here rather than as a confusing
+        # demo-app failure. Bench knobs are NOT propagated, so the
+        # `vespera.bench`-gated PerfAllocBench cases stay skipped.
+        shell: bash
+        working-directory: libs/vespera-bridge
+        run: ./gradlew test --console=plain --no-daemon
+      - name: Publish vespera-bridge to mavenLocal
+        # demo-app resolves kr.devfive:vespera-bridge from mavenLocal at the
+        # version declared in libs/vespera-bridge/build.gradle.kts (see
+        # examples/rust-jni-demo/java/demo-app/build.gradle.kts — the version
+        # is read from that file, never pinned, so bumping the bridge cannot
+        # silently fall back to the last release on Maven Central).
+        shell: bash
+        working-directory: libs/vespera-bridge
+        run: ./gradlew publishToMavenLocal --console=plain --no-daemon
+      - name: Run demo-app JNI E2E tests
+        # Includes StreamingClosureStressTest (1000 × 1 MiB SHA256
+        # bidirectional round-trip). Bench knobs are NOT propagated —
+        # gated bench tests stay skipped in CI.
+        shell: bash
+        working-directory: examples/rust-jni-demo/java
+        run: ./gradlew :demo-app:test --console=plain --no-daemon
+      - name: Merge Java coverage
+        # Regenerates the bridge's JaCoCo report now that demo-app has run, so
+        # it also credits the classes only reachable with a loaded cdylib — the
+        # JNI wrappers and the Spring proxy, which the unit suite cannot drive.
+        # The report task reads demo-app/build/jacoco/test.exec when present.
+        shell: bash
+        working-directory: libs/vespera-bridge
+        run: ./gradlew jacocoTestReport --console=plain --no-daemon
+      - name: Upload Java test results and coverage
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: jni-e2e-${{ matrix.os }}-test-results
+          path: |
+            examples/rust-jni-demo/java/demo-app/build/test-results/test/*.xml
+            libs/vespera-bridge/build/test-results/test/*.xml
+            libs/vespera-bridge/build/reports/jacoco/test/jacocoTestReport.xml

.github/workflows/bench.yml

@@ -0,0 +1,112 @@
+name: Bench
+
+# Criterion regression gate for the in-process dispatch hot path.
+#
+# - push to main: runs the gated bench groups and saves the results as
+#   the `main` criterion baseline in the actions cache.
+# - pull_request: restores the latest main baseline and compares; the
+#   job FAILS when any bench regresses by more than 10% mean change
+#   AND the 95% confidence interval lower bound exceeds +5% (the
+#   double condition filters shared-runner noise).
+#
+# Gated groups are the stable per-request paths (wire_path,
+# headers_path, request_headers_path, resolve_path, dispatch_path). The
+# streaming and contended groups are noisier (spawn_blocking / scheduler
+# timing) and the router_path setup micro-bench is low-signal, so those
+# are validated locally instead — see PERF_REPORT.md.
+#
+# This TIMING gate fires only at a loose ±10% (shared-runner drift), so it
+# catches BIG regressions. Small, deterministic ALLOCATION regressions are
+# caught noise-free by the `alloc_budget` integration test (a counting
+# global allocator asserting exact per-dispatch allocation budgets) in the
+# normal `cargo test` job — the two gates are complementary.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'crates/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.github/workflows/bench.yml'
+  pull_request:
+    paths:
+      - 'crates/**'
+      - 'Cargo.toml'
+      - 'Cargo.lock'
+      - '.github/workflows/bench.yml'
+
+concurrency:
+  group: bench-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  BENCH_FILTER: 'wire_path|headers_path|request_headers_path|resolve_path|dispatch_path'
+
+jobs:
+  bench:
+    name: Criterion regression gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+
+      - name: Restore criterion baseline (latest main)
+        id: restore-baseline
+        uses: actions/cache/restore@v6
+        with:
+          path: target/criterion
+          key: bench-baseline-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            bench-baseline-${{ runner.os }}-
+
+      - name: Run benches and save main baseline
+        if: github.event_name == 'push'
+        run: |
+          cargo bench -p vespera_inprocess --bench dispatch -- \
+            --save-baseline main "${BENCH_FILTER}"
+
+      - name: Save criterion baseline cache
+        if: github.event_name == 'push'
+        uses: actions/cache/save@v6
+        with:
+          path: target/criterion
+          key: bench-baseline-${{ runner.os }}-${{ github.sha }}
+
+      - name: Compare against main baseline
+        if: github.event_name == 'pull_request'
+        run: |
+          if [ ! -d target/criterion ] || ! find target/criterion -maxdepth 4 -type d -name main | grep -q .; then
+            echo "::notice::No main baseline in cache yet — running benches without a gate."
+            cargo bench -p vespera_inprocess --bench dispatch -- "${BENCH_FILTER}"
+            exit 0
+          fi
+          cargo bench -p vespera_inprocess --bench dispatch -- \
+            --baseline main "${BENCH_FILTER}"
+
+      - name: Enforce regression gate
+        if: github.event_name == 'pull_request'
+        run: |
+          shopt -s nullglob
+          fail=0
+          found=0
+          while IFS= read -r f; do
+            found=1
+            mean=$(jq -r '.mean.point_estimate' "$f")
+            lower=$(jq -r '.mean.confidence_interval.lower_bound' "$f")
+            bench=$(dirname "$(dirname "$f")")
+            bench=${bench#target/criterion/}
+            printf '%s: mean %+.2f%% (CI lower %+.2f%%)\n' \
+              "$bench" "$(awk -v v="$mean" 'BEGIN{print v*100}')" \
+              "$(awk -v v="$lower" 'BEGIN{print v*100}')"
+            if awk -v m="$mean" -v l="$lower" 'BEGIN{exit !(m > 0.10 && l > 0.05)}'; then
+              echo "::error::Performance regression: ${bench} mean change exceeds +10% with CI lower bound > +5%"
+              fail=1
+            fi
+          done < <(find target/criterion -path '*/change/estimates.json')
+          if [ "$found" -eq 0 ]; then
+            echo "::notice::No change estimates found (first run against this baseline?) — nothing to gate."
+          fi
+          exit $fail

.github/workflows/deploy-pages.yml

@@ -23,26 +23,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Install bun
         uses: oven-sh/setup-bun@v2
 
       - name: Cache bun dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: ~/.bun/install/cache
           key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
           restore-keys: |
             bun-${{ runner.os }}-
 
       - name: Install Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@v7
         with:
           node-version: 22
 
       - name: Cache Next.js build
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: |
             apps/landing/.next/cache