Split lib

Author: owjs3901

AGENTS.md

@@ -1,34 +1,36 @@
 # VESPERA PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-03-19
+**Generated:** 2026-03-21
 **Branch:** main
 
 ## OVERVIEW
 
 Vespera is a fully automated OpenAPI 3.1 engine for Axum - delivers FastAPI-like DX to Rust. Zero-config route discovery via compile-time macro scanning.
 
-Also provides in-process dispatch (`inprocess` feature) and JNI integration (`jni` feature) for embedding Rust axum apps inside Java/Spring applications without HTTP overhead.
+Also provides in-process dispatch (`vespera_inprocess` crate) and JNI integration (`vespera_jni` crate) for embedding Rust axum apps inside Java/Spring applications without HTTP overhead.
 
 ## STRUCTURE
 
 ```
 vespera/
 ├── crates/
 │ ├── vespera/ # Public API - re-exports everything
-│ │ ├── src/lib.rs # Core re-exports + conditional modules
-│ │ ├── src/inprocess.rs # In-process dispatch (feature: inprocess)
-│ │ └── src/jni.rs # JNI integration (feature: jni)
+│ │ └── src/lib.rs # Core re-exports (no transport deps)
 │ ├── vespera_core/ # OpenAPI types, route/schema abstractions
-│ └── vespera_macro/ # Proc-macros (main logic lives here)
+│ ├── vespera_macro/ # Proc-macros (main logic lives here)
+│ ├── vespera_inprocess/ # In-process dispatch (transport-agnostic)
+│ │ └── src/lib.rs # dispatch(), register_app(), dispatch_from_json()
+│ └── vespera_jni/ # JNI bridge (depends on vespera_inprocess)
+│ └── src/lib.rs # RUNTIME, jni_app! macro, JNI symbol export
 ├── libs/
 │ └── vespera-bridge/ # Java library (com.devfive.vespera.bridge)
 │ ├── VesperaBridge.java # JNI native loader + dispatch
 │ └── VesperaProxyController.java # Auto-configured Spring proxy
 ├── examples/
 │ ├── axum-example/ # Standard axum server demo
 │ └── rust-jni-demo/ # JNI + standalone server demo
-│ ├── src/ # Rust: routes, create_app(), JNI_OnLoad
-│ └── java/demo-app/ # Java: Spring Boot proxy (16 lines)
+│ ├── src/ # Rust: routes, create_app(), jni_app!
+│ └── java/demo-app/ # Java: Spring Boot proxy
 ```
 
 ## WHERE TO LOOK
@@ -43,8 +45,9 @@ vespera/
 | Modify schema_type! macro | `crates/vespera_macro/src/schema_macro.rs` | Type derivation & SeaORM support |
 | Add core types | `crates/vespera_core/src/` | OpenAPI spec types |
 | Test new features | `examples/axum-example/` | Add route, run example |
-| In-process dispatch | `crates/vespera/src/inprocess.rs` | RequestEnvelope → Router → ResponseEnvelope |
-| JNI integration | `crates/vespera/src/jni.rs` | JNI_OnLoad macro, fixed JNI symbol export |
+| In-process dispatch | `crates/vespera_inprocess/src/lib.rs` | RequestEnvelope → Router → ResponseEnvelope |
+| App factory (FFI pattern) | `crates/vespera_inprocess/src/lib.rs` | register_app(), dispatch_from_json() |
+| JNI integration | `crates/vespera_jni/src/lib.rs` | RUNTIME, jni_app! macro, JNI symbol export |
 | Java bridge library | `libs/vespera-bridge/` | com.devfive.vespera.bridge package |
 | JNI demo (Rust) | `examples/rust-jni-demo/src/` | Routes + vespera::jni_app! |
 | JNI demo (Java) | `examples/rust-jni-demo/java/` | Spring Boot proxy app |
@@ -59,30 +62,69 @@ vespera/
 | `vespera_macro/src/parser/parameters.rs` | ~845 | Extract path/query params from handlers |
 | `vespera_macro/src/openapi_generator.rs` | ~808 | OpenAPI doc assembly |
 | `vespera_macro/src/collector.rs` | ~707 | Filesystem route scanning |
-| `vespera/src/inprocess.rs` | ~150 | In-process HTTP dispatch via oneshot |
-| `vespera/src/jni.rs` | ~155 | JNI exports + `jni_app!` macro |
+| `vespera_inprocess/src/lib.rs` | ~175 | In-process dispatch + app factory |
+| `vespera_jni/src/lib.rs` | ~95 | JNI RUNTIME + jni_app! macro + JNI symbol |
 
-## FEATURES (crates/vespera)
+## CRATE DEPENDENCY GRAPH
+
+```
+vespera (OpenAPI framework)
+ ├── vespera_core
+ ├── vespera_macro
+ ├── vespera_inprocess (optional, feature = "inprocess")
+ └── vespera_jni (optional, feature = "jni", implies "inprocess")
+
+vespera_inprocess (transport layer — no JNI deps)
+ ├── axum (direct — owns Router re-export)
+ ├── http, http-body-util, tower
+ ├── serde, serde_json
+ └── tokio (rt only — for dispatch_from_json Runtime param)
+
+vespera_jni (JNI glue — thin layer)
+ ├── vespera_inprocess (via workspace)
+ ├── jni
+ └── tokio (rt-multi-thread — for LazyLock<Runtime>)
+
+rust-jni-demo (example — depends on vespera ONLY)
+ └── vespera = { features = ["jni"] }
+```
+
+## USER-FACING API
+
+Users depend on `vespera` only. Internal crates are never depended on directly.
 
 ```toml
-[features]
-default = [...] # axum-extra features
-inprocess = [http, http-body-util, tower, serde] # In-process dispatch
-jni = [inprocess, jni-crate, tokio] # JNI = inprocess + JVM glue
+# Cargo.toml — the only dependency needed
+[dependencies]
+vespera = { version = "...", features = ["jni"] }
+```
+
+```rust
+// lib.rs — all imports come from vespera
+use vespera::{axum, vespera};
+
+pub fn create_app() -> axum::Router {
+ vespera!(title = "My API", version = "1.0.0")
+}
+
+vespera::jni_app!(create_app);
 ```
 
-- `inprocess`: Transport-agnostic `dispatch(Router, &RequestEnvelope) -> String`
-- `jni`: Adds `jni_app!` macro + `JNI_OnLoad` + fixed JNI symbol export
-- JNI symbol: `Java_com_devfive_vespera_bridge_VesperaBridge_dispatch`
+Feature flags:
+
+| Feature | Re-exports | Adds |
+|---------|-----------|------|
+| `inprocess` | `vespera::inprocess` (= `vespera_inprocess`) | dispatch, register_app, envelopes |
+| `jni` | `vespera::jni` (= `vespera_jni`) + implies `inprocess` | RUNTIME, jni_app!, JNI symbol |
 
 ## JNI ARCHITECTURE
 
 ```
-Java (Spring Boot) Rust (cdylib) vespera framework
+Java (Spring Boot) Rust (cdylib) vespera crates
 ───────────────── ────────────── ─────────────────
-VesperaBridge.init() → JNI_OnLoad register_app(create_app)
+VesperaBridge.init() → JNI_OnLoad vespera_inprocess::register_app()
  ↓ ↓
-VesperaBridge.dispatch() → JNI symbol → inprocess::dispatch()
+VesperaBridge.dispatch() → JNI symbol vespera_inprocess::dispatch_from_json()
  ↓ ↓ ↓
 VesperaProxyController catch_unwind router.oneshot(request)
  ↓ ↓ ↓
@@ -131,6 +173,8 @@ Generate request/response types from existing structs with powerful transformati
 - **Workspace dependencies**: Internal crates use `{ workspace = true }`
 - **Test frameworks**: `rstest` for unit tests, `insta` for snapshots
 - **No `build.rs`**: All code gen via proc-macros at compile time
+- **No direct axum dep in examples**: Use `vespera::axum` re-export
+- **No direct vespera_jni/vespera_inprocess dep**: Use `vespera` features
 - **Java package**: `com.devfive.vespera.bridge` (fixed for JNI symbol stability)
 - **Java build**: Gradle (Kotlin DSL), published to GitHub Packages
 
@@ -141,6 +185,9 @@ Generate request/response types from existing structs with powerful transformati
 - **NEVER** write OpenAPI JSON by hand - generated from code
 - **NEVER** write JNI boilerplate in examples - use `vespera::jni_app!` macro
 - **NEVER** parse domain JSON in Java - Spring is a proxy, Rust owns business logic
+- **NEVER** depend on axum directly in examples - use `vespera::axum`
+- **NEVER** depend on `vespera_jni` or `vespera_inprocess` directly - use `vespera` features
+- **NEVER** put transport logic in vespera core - use `vespera_inprocess` / `vespera_jni`
 - Route functions **MUST** be `pub async fn`
 
 ## COMMANDS

Cargo.lock

@@ -13,6 +13,8 @@ readme = "README.md"
 [workspace.dependencies]
 vespera_core = { path = "crates/vespera_core", version = "0.1.44" }
 vespera_macro = { path = "crates/vespera_macro", version = "0.1.44" }
+vespera_inprocess = { path = "crates/vespera_inprocess", version = "0.1.44" }
+vespera_jni = { path = "crates/vespera_jni", version = "0.1.44" }
 
 [workspace.lints.clippy]
 all = { level = "warn", priority = -1 }

Cargo.toml

@@ -9,8 +9,8 @@ repository.workspace = true
 [features]
 default = ["axum-extra/typed-header", "axum-extra/form", "axum-extra/query", "axum-extra/multipart", "axum-extra/cookie"]
 cron = ["dep:tokio-cron-scheduler", "dep:tokio"]
-inprocess = ["dep:http", "dep:http-body-util", "dep:tower", "dep:serde"]
-jni = ["inprocess", "dep:jni", "dep:tokio"]
+inprocess = ["dep:vespera_inprocess"]
+jni = ["inprocess", "dep:vespera_jni"]
 
 [dependencies]
 vespera_core = { workspace = true }
@@ -23,14 +23,9 @@ serde_json = "1"
 tower-layer = "0.3"
 tower-service = "0.3"
 tokio-cron-scheduler = { version = "0.13", optional = true }
-tokio = { version = "1", features = ["rt-multi-thread"], optional = true }
-# inprocess feature
-http = { version = "1", optional = true }
-http-body-util = { version = "0.1", optional = true }
-tower = { version = "0.5", features = ["util"], optional = true }
-serde = { version = "1", features = ["derive"], optional = true }
-# jni feature
-jni = { version = "0.21", optional = true }
+tokio = { version = "1", features = ["rt"], optional = true }
+vespera_inprocess = { workspace = true, optional = true }
+vespera_jni = { workspace = true, optional = true }
 
 [lints]
 workspace = true