Optimize compile time

Author: owjs3901

crates/vespera/src/serve.rs

@@ -47,3 +47,21 @@ impl Serve for axum::Router {
         axum::serve(listener, self).await
     }
 }
+
+/// Lets a **stateless** merged app from `vespera!(merge = [...])` —
+/// which returns a [`crate::VesperaRouter<()>`] rather than a plain
+/// `axum::Router` — start with the same one-liner, without the user
+/// having to remember the `.with_state(())` finalizer first:
+///
+/// ```ignore
+/// vespera!(merge = [other::App]).serve("0.0.0.0:3000").await
+/// ```
+///
+/// Finalizing with `()` runs the deferred child-router merge and layer
+/// replay (see [`crate::VesperaRouter::with_state`]) before binding, so
+/// merged routes and layers are present when the listener starts.
+impl Serve for crate::VesperaRouter<()> {
+    async fn serve(self, addr: impl ToSocketAddrs) -> io::Result<()> {
+        self.with_state(()).serve(addr).await
+    }
+}

crates/vespera_inprocess/src/dispatch.rs

@@ -470,6 +470,23 @@ async fn finish_direct_write(
     };
     let mut required = header_total;
 
+    // Fast overflow: when the body length is known exactly (a `Full` body /
+    // explicit `Content-Length`) and the response cannot fit, report the
+    // exact required size immediately instead of draining every frame just
+    // to count bytes — this is the undersized-buffer retry path the pooled
+    // JNI `dispatchDirect` takes. Unknown-length (streaming) bodies have no
+    // exact hint and fall through to the drain loop unchanged.
+    if let Some(exact) = body.size_hint().exact() {
+        let required_u64 = u64::try_from(header_total)
+            .unwrap_or(u64::MAX)
+            .saturating_add(exact);
+        if required_u64 > u64::try_from(out.len()).unwrap_or(u64::MAX) {
+            return DirectWriteResult::Overflow(
+                usize::try_from(required_u64).unwrap_or(usize::MAX),
+            );
+        }
+    }
+
     loop {
         match body.frame().await {
             Some(Ok(frame)) => {

crates/vespera_inprocess/src/wire.rs

@@ -555,9 +555,16 @@ fn body_is_json(headers: &http::HeaderMap) -> bool {
         .get(http::header::CONTENT_TYPE)
         .and_then(|v| v.to_str().ok())
         .is_some_and(|s| {
-            let mime = s.split(';').next().unwrap_or("").trim();
-            mime.eq_ignore_ascii_case("application/json")
-                || (mime.len() >= 5 && mime[mime.len() - 5..].eq_ignore_ascii_case("+json"))
+            // Any `application/json`, `*/json`, or `*+json` media type. The
+            // trailing-5-byte suffix is compared on raw bytes (not a `str`
+            // slice), so an exotic non-ASCII value can never panic on a
+            // non-char-boundary index — and `/json` (e.g. `text/json`) now
+            // hoists too, matching the documented contract.
+            let mime = s.split(';').next().unwrap_or("").trim().as_bytes();
+            mime.len() >= 5 && {
+                let suffix = &mime[mime.len() - 5..];
+                suffix.eq_ignore_ascii_case(b"/json") || suffix.eq_ignore_ascii_case(b"+json")
+            }
         })
 }
 

libs/vespera-bridge/README.md

@@ -341,9 +341,11 @@ vespera:
 | Small (≤ 256 KiB Content-Length) + unsafe (POST/PUT/PATCH/DELETE) | `SYNC` | ~3,200 |
 | Large or unknown-length body | `BIDIRECTIONAL_STREAMING` | ~24,100 |
 
-The idempotency gate on DIRECT matters because a response that
+The safe-method gate on DIRECT matters because a response that
 overflows the pooled buffer (`vespera.direct.maxBufferBytes`, default
 4 MiB) is retried by default — which re-runs the Rust handler once.
+Safe methods are not intended to mutate server state, but the replayed
+response may still differ (for example timestamps or generated IDs).
 Set `vespera.bridge.direct-retry-on-overflow=false` to surface the
 overflow instead.  SYNC never re-runs the handler (safe for POST), but
 buffers the full response on the JVM heap, which the request-size gate

libs/vespera-bridge/src/main/java/com/devfive/vespera/bridge/HttpMethods.java

@@ -16,9 +16,9 @@ private HttpMethods() {
 
     /**
      * Whether {@code method} is idempotent per RFC 9110
-     * (GET / HEAD / PUT / DELETE / OPTIONS).  Idempotent requests are
-     * safe to re-run, which the DIRECT dispatch path requires for its
-     * response-overflow retry.  {@code null} is treated as non-idempotent.
+     * (GET / HEAD / PUT / DELETE / OPTIONS). Idempotent requests are not
+     * necessarily replay-identical, so this is NOT the DIRECT overflow-retry
+     * gate. {@code null} is treated as non-idempotent.
      */
     static boolean isIdempotent(String method) {
         if (method == null) {
@@ -33,8 +33,8 @@ static boolean isIdempotent(String method) {
 
     /**
      * Whether {@code method} is "safe" per RFC 9110 §9.2.1
-     * (GET / HEAD / OPTIONS) — read-only, so re-running it yields the
-     * <em>same response</em>, not merely the same server-state effect.
+     * (GET / HEAD / OPTIONS) — not intended to mutate server state. Re-running
+     * it can still yield a different response (timestamps, random IDs).
      *
      * <p>This is the correct gate for the DIRECT overflow retry, which
      * re-runs the handler: an idempotent-but-unsafe method (PUT / DELETE)

libs/vespera-bridge/src/main/java/com/devfive/vespera/bridge/SmartDispatchModeResolver.java

@@ -44,6 +44,9 @@
  */
 public class SmartDispatchModeResolver implements DispatchModeResolver {
 
+    private static final String CURRENT_THREAD_IS_VIRTUAL_ATTRIBUTE =
+            SmartDispatchModeResolver.class.getName() + ".currentThreadIsVirtual";
+
     /**
      * Default DIRECT request-size gate: 1 MiB (raised from 256 KiB,
      * measured 2026-06).  Safe requests up to this size dispatch
@@ -101,6 +104,19 @@ public SmartDispatchModeResolver(long maxDirectBytes, long maxSyncBytes) {
 
     @Override
     public DispatchMode resolveMode(HttpServletRequest request) {
+        return resolveMode(request, null);
+    }
+
+    static Boolean cachedCurrentThreadIsVirtual(HttpServletRequest request) {
+        Object value = request.getAttribute(CURRENT_THREAD_IS_VIRTUAL_ATTRIBUTE);
+        return value instanceof Boolean ? (Boolean) value : null;
+    }
+
+    DispatchMode resolveMode(HttpServletRequest request, boolean currentThreadIsVirtual) {
+        return resolveMode(request, Boolean.valueOf(currentThreadIsVirtual));
+    }
+
+    private DispatchMode resolveMode(HttpServletRequest request, Boolean currentThreadIsVirtual) {
         long contentLength = request.getContentLengthLong();
         // Bodyless requests fit the direct buffer by definition even when
         // Content-Length is absent (the common shape of GET) — without this,
@@ -124,7 +140,11 @@ public DispatchMode resolveMode(HttpServletRequest request) {
             // SYNC (no off-heap pooling, no re-run) when small, but stream
             // above the SYNC gate — SYNC's heap buffering loses to streaming
             // for larger bodies, idempotent or not.
-            if (VesperaBridge.currentThreadIsVirtual()) {
+            boolean virtualThread = currentThreadIsVirtual != null
+                    ? currentThreadIsVirtual.booleanValue()
+                    : VesperaBridge.currentThreadIsVirtual();
+            request.setAttribute(CURRENT_THREAD_IS_VIRTUAL_ATTRIBUTE, Boolean.valueOf(virtualThread));
+            if (virtualThread) {
                 return syncSized(contentLength, bodyless)
                         ? DispatchMode.SYNC
                         : DispatchMode.BIDIRECTIONAL_STREAMING;

libs/vespera-bridge/src/main/java/com/devfive/vespera/bridge/VesperaBridge.java

@@ -706,6 +706,21 @@ public static ByteBuffer dispatchDirectPooled(
                 appName, method, path, query, headers, body, retryOnOverflow);
     }
 
+    static ByteBuffer dispatchDirectPooled(
+            String appName,
+            String method,
+            String path,
+            String query,
+            HeaderSource headers,
+            byte[] body,
+            boolean retryOnOverflow,
+            boolean currentThreadIsVirtual) {
+        requireRequestInputs(method, path);
+        return VesperaDirectBufferPool.dispatchDirectPooled(
+                appName, method, path, query, headers, body,
+                retryOnOverflow, currentThreadIsVirtual);
+    }
+
     /**
      * Encode a request <strong>directly into</strong> {@code target}
      * starting at position 0 — no intermediate wire-sized {@code byte[]}.

libs/vespera-bridge/src/main/java/com/devfive/vespera/bridge/VesperaDirectBufferPool.java

@@ -1,6 +1,5 @@
 package com.devfive.vespera.bridge;
 
-import java.lang.ref.SoftReference;
 import java.nio.ByteBuffer;
 import java.util.Map;
 import java.util.Objects;
@@ -74,17 +73,13 @@ private static int directMaxCapacity() {
     /**
      * Index 0 = request buffer, index 1 = response buffer.
      *
-     * <p>Held through a {@link SoftReference} so the JVM can reclaim the
-     * off-heap direct buffers under memory pressure — the
-     * {@code DirectByteBuffer} Cleaner frees the native memory once the
-     * soft reference is cleared — instead of pinning up to {@code 2 ×}
-     * {@link #DIRECT_MAX_CAPACITY} per thread for the whole thread
-     * lifetime.  Under normal load the soft reference survives, so the
-     * pooling benefit is preserved; see {@link #directPool()} for the
-     * resolve + retention-cap logic.
+     * <p>Held strongly per platform thread so baseline direct buffers stay
+     * resident on the hot DIRECT path. Oversized buffers are shrunk
+     * deterministically by {@link #recordDirectPoolUse(ByteBuffer[], int, int)}
+     * after an idle streak instead of relying on heap-pressure-driven soft
+     * reference clearing to manage off-heap memory.
      */
-    private static final ThreadLocal<SoftReference<ByteBuffer[]>> DIRECT_POOL =
-            new ThreadLocal<>();
+    private static final ThreadLocal<ByteBuffer[]> DIRECT_POOL = new ThreadLocal<>();
 
     private static final int DIRECT_SHRINK_IDLE_DISPATCHES = 8;
     private static final ThreadLocal<Integer> DIRECT_UNDER_RETAIN_STREAK =
@@ -133,17 +128,15 @@ static boolean currentThreadIsVirtual() {
 
     /**
      * Resolve the calling thread's pooled direct buffers, (re)allocating
-     * a baseline pair when the {@link SoftReference} has been cleared
-     * under memory pressure.
+     * a baseline pair when none exists for this thread.
      */
     private static ByteBuffer[] directPool() {
-        SoftReference<ByteBuffer[]> ref = DIRECT_POOL.get();
-        ByteBuffer[] pool = ref == null ? null : ref.get();
+        ByteBuffer[] pool = DIRECT_POOL.get();
         if (pool == null) {
             pool = new ByteBuffer[] {
                     ByteBuffer.allocateDirect(DIRECT_INITIAL_CAPACITY),
                     ByteBuffer.allocateDirect(DIRECT_INITIAL_CAPACITY)};
-            DIRECT_POOL.set(new SoftReference<>(pool));
+            DIRECT_POOL.set(pool);
             DIRECT_UNDER_RETAIN_STREAK.set(0);
             return pool;
         }
@@ -160,13 +153,24 @@ private static void recordDirectPoolUse(ByteBuffer[] pool, int requestLen, int r
             DIRECT_UNDER_RETAIN_STREAK.set(streak);
             return;
         }
-        DIRECT_POOL.remove();
+        boolean requestGrown = pool[0].capacity() > DIRECT_INITIAL_CAPACITY;
+        boolean responseGrown = pool[1].capacity() > DIRECT_INITIAL_CAPACITY;
+        if (requestGrown) {
+            pool[0] = ByteBuffer.allocateDirect(DIRECT_INITIAL_CAPACITY);
+        }
+        if (responseGrown) {
+            pool[1] = ByteBuffer.allocateDirect(DIRECT_INITIAL_CAPACITY);
+        }
         DIRECT_UNDER_RETAIN_STREAK.set(0);
     }
 
+    static void clearCurrentThreadBuffers() {
+        DIRECT_POOL.remove();
+        DIRECT_UNDER_RETAIN_STREAK.remove();
+    }
+
     static boolean directPoolPresentForTest() {
-        SoftReference<ByteBuffer[]> ref = DIRECT_POOL.get();
-        return ref != null && ref.get() != null;
+        return DIRECT_POOL.get() != null;
     }
 
     static ByteBuffer[] directPoolForTest() {
@@ -195,8 +199,13 @@ private static int grownCapacity(int needed) {
      * boolean)} for the full contract.
      */
     static ByteBuffer dispatchDirectPooled(byte[] wireRequest, boolean retryOnOverflow) {
+        return dispatchDirectPooled(wireRequest, retryOnOverflow, currentThreadIsVirtual());
+    }
+
+    static ByteBuffer dispatchDirectPooled(
+            byte[] wireRequest, boolean retryOnOverflow, boolean currentThreadIsVirtual) {
         Objects.requireNonNull(wireRequest, "wireRequest");
-        if (currentThreadIsVirtual() || wireRequest.length > DIRECT_MAX_CAPACITY) {
+        if (currentThreadIsVirtual || wireRequest.length > DIRECT_MAX_CAPACITY) {
             // Virtual thread: the per-thread direct buffer pool would
             // accumulate off-heap memory per vthread (ThreadLocal binds to
             // the vthread, not the carrier) — use the GC-managed heap path.
@@ -260,12 +269,26 @@ static ByteBuffer dispatchDirectPooled(
             HeaderSource headers,
             byte[] body,
             boolean retryOnOverflow) {
+        return dispatchDirectPooled(
+                appName, method, path, query, headers, body,
+                retryOnOverflow, currentThreadIsVirtual());
+    }
+
+    static ByteBuffer dispatchDirectPooled(
+            String appName,
+            String method,
+            String path,
+            String query,
+            HeaderSource headers,
+            byte[] body,
+            boolean retryOnOverflow,
+            boolean currentThreadIsVirtual) {
         byte[] bodyBytes = body != null ? body : VesperaWireCodec.EMPTY_BODY;
         ExposedByteArrayOutputStream hdr =
                 VesperaWireCodec.fillHeaderJson(appName, method, path, query, headers);
         int headerLen = hdr.size();
         int total = VesperaWireCodec.wireTotalLength(headerLen, bodyBytes.length);
-        if (currentThreadIsVirtual() || total > DIRECT_MAX_CAPACITY) {
+        if (currentThreadIsVirtual || total > DIRECT_MAX_CAPACITY) {
             return ByteBuffer.wrap(
                     VesperaBridge.dispatchBytes(
                             VesperaWireCodec.assembleWire(hdr.backingArray(), headerLen, bodyBytes)))