Crate vespera_inprocess 

In-process transport: dispatch HTTP-like requests through an axum Router without a TCP socket.

This crate is transport-agnostic — it knows nothing about JNI, C FFI, or WASM. It exposes two API layers on top of a single shared dispatch core:

1. Direct API — dispatch / dispatch_typed / dispatch_owned drive a Router with a RequestEnvelope and return a ResponseEnvelope. Bodies on this path are UTF-8 text only; if the upstream response body is not valid UTF-8 (binary content), ResponseEnvelope::body is the empty string. Callers that need raw bytes must use the binary wire API below.

2. Binary wire API — dispatch_from_bytes is the zero-overhead FFI entry point. Wire format (request and response use the same layout):

   bytes 0..4      : u32 BE = header_json byte length N
   bytes 4..4+N    : UTF-8 JSON
                       (request)  { "v":1, "method", "path",
                                    "query"?, "headers"? }
                       (response) { "v":1, "status", "headers",
                                    "metadata" }
   bytes 4+N..end  : raw body bytes (UTF-8 text or binary —
                      no encoding applied)

   All failure modes return a valid wire-format response so the caller’s decoder never has to special-case errors.

Example (direct)

let response = dispatch_typed(router, &envelope).await;

Example (binary wire / FFI)

// At init time (e.g. JNI_OnLoad, DllMain, _start)
vespera_inprocess::register_app(|| create_app());

// On each FFI call
let response_bytes =
    vespera_inprocess::dispatch_from_bytes(request_bytes, &runtime);

Router caching semantics

register_app invokes the supplied factory once at registration time and stores the resulting Router. Subsequent dispatch_from_bytes calls reuse the cached router via Router::clone, which is cheap because axum’s router is internally Arc-shared.

Structs

RequestEnvelope

Inbound request envelope (direct-API path).

ResponseEnvelope

Outbound response envelope.

ResponseMetadata

Metadata included in every response envelope.

Router

Re-export axum::Router so consumers don’t need a direct axum dependency. The router type for composing handlers and services.

Enums

HeaderValue

Response header value — single string or multiple values.

Constants

DEFAULT_APP_NAME

Canonical name of the default app — used when the wire header omits "app" or sets it to an empty string, and when callers use the BC register_app entry point.

Functions

dispatch

Dispatch a RequestEnvelope through an axum Router and return the serialised ResponseEnvelope JSON.

dispatch_bidirectional_streaming

Bidirectional streaming dispatch — both request and response bodies are streamed chunk-by-chunk; neither side materialises the full payload in memory.

dispatch_bidirectional_streaming_with_header

Bidirectional streaming with explicit header callback — the with_header counterpart of dispatch_bidirectional_streaming. Emits the wire-format response header via on_header before any response body byte reaches on_chunk, so Spring-style HttpServletResponse controllers can commit status / headers from the callback while the response is still uncommitted.

dispatch_from_bytes

Dispatch a wire-format request through the registered app and return a wire-format response.

dispatch_from_bytes_async

Async sibling of dispatch_from_bytes. Use this when the caller is already inside a Tokio runtime (e.g. an axum handler embedding another vespera router, or a tokio-spawned task in the JNI bridge’s async dispatch path).

dispatch_owned

Dispatch an owned RequestEnvelope — moves the envelope into the HTTP request so the body, path, and headers are never cloned.

dispatch_streaming_async

Streaming sibling of dispatch_from_bytes_async.

dispatch_streaming_with_header_async

Streaming dispatch with explicit header callback — emits the wire-format response header via on_header before any body chunk is delivered to on_chunk.

dispatch_typed

Typed dispatch — returns a ResponseEnvelope directly.

error_envelope

Build an error ResponseEnvelope with status 500.

error_wire

Build a wire-format error response with a plain-text body.

register_app

Register the default global router factory.

register_app_named

Register a named global router factory for multi-app routing.