release: OxyRoute 0.5.0

.github/workflows/perf-smoke.yml

@@ -0,0 +1,52 @@
+name: perf-smoke
+
+# Opt-in smoke for Criterion + short wrk (issue #110). Not part of default PR CI.
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+
+jobs:
+  criterion:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Sync + Criterion smoke
+        run: |
+          uv sync --frozen --extra dev
+          # Quiet, short Criterion run (still builds the bench binary).
+          cargo bench --bench hot_path -- --sample-size 10 --warm-up-time 1 --measurement-time 2
+
+  wrk-scenarios:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+      - name: Install wrk
+        run: sudo apt-get update && sudo apt-get install -y wrk
+      - name: Build oxyroute and run short scenarios
+        run: |
+          set -euo pipefail
+          uv sync --frozen --extra dev --extra bench
+          rm -f target/wheels/oxyroute-*.whl
+          uv run maturin build --release
+          shopt -s nullglob
+          wheels=(target/wheels/oxyroute-*.whl)
+          shopt -u nullglob
+          uv pip install --force-reinstall "${wheels[0]}"
+          chmod +x perf-test/bench_scenarios.sh
+          OXYROUTE_BENCH_DURATION=1s OXYROUTE_BENCH_CONNECTIONS=8 OXYROUTE_BENCH_THREADS=1 \
+            ./perf-test/bench_scenarios.sh

.gitignore

@@ -45,6 +45,7 @@ env/
 
 # --- IDE / editor ---
 .idea/
+.cursor/
 *.swp
 *~
 

AGENTS.md

@@ -1,4 +1,4 @@
 # Notes for AI agents (OxyRoute)
 
-- **Git / branches / PRs / validation** — [`.cursor/rules/git-workflow.mdc`](.cursor/rules/git-workflow.mdc) (`alwaysApply`).
+- **Git / branches / PRs / validation** — [docs/development-workflow.md](docs/development-workflow.md) (integration branch `dev`, issue branches, atomic commits, PR to `dev`).
 - **Validation (ruff, cargo, `make test`, pytest, maturin):** the **maintainer runs these** before push. **Do not** run that full pipeline in the agent unless the user explicitly asks (e.g. “run `make test`”, “fix the failing test”). If something failed in CI or locally, the user will say so — then fix what they report.

CHANGELOG.md

@@ -7,6 +7,66 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-20
+
+### Added
+
+- First-class OpenAPI docs UI: `App(..., docs_ui="scalar"|"swagger")` and
+  `app.mount_docs(...)` serve CDN-backed Scalar / Swagger UI at `/docs` against
+  `/openapi.json` ([#130](https://github.com/QueryaHub/OxyRoute/issues/130)).
+- OpenAPI enrichment for interactive explorers: matchit `:param` / `*rest` → `{param}` /
+  `{rest}` with path `parameters`; JWT `bearerAuth` when `require_jwt=True`; operation
+  `tags=` / `include_router(..., tags=[...])`; `set_openapi_info` and constructor
+  `openapi_description` / `openapi_contact` / `openapi_servers`.
+- Granian-compatible lifespan: sync `__rsgi_init__(loop)` / `__rsgi_del__(loop)` run
+  `on_startup` / `on_shutdown` via `loop.run_until_complete`. Prefer overriding
+  `on_startup` / `on_shutdown` instead of `async def __rsgi_init__`.
+- `oxyroute.testing.TestClient` for in-process HTTP tests ([#102](https://github.com/QueryaHub/OxyRoute/issues/102)).
+- Typed `Request` with lazy headers ([#101](https://github.com/QueryaHub/OxyRoute/issues/101)).
+- Runtime `body_model` validation with HTTP 422 ([#100](https://github.com/QueryaHub/OxyRoute/issues/100)).
+- Global exception handlers for sync and async routes
+  ([#99](https://github.com/QueryaHub/OxyRoute/issues/99)).
+- Optional request / response middleware chain
+  ([#98](https://github.com/QueryaHub/OxyRoute/issues/98)).
+- `StaticFiles` and `App.mount` ([#104](https://github.com/QueryaHub/OxyRoute/issues/104)).
+- Generic streaming responses (non-SSE chunked generators)
+  ([#103](https://github.com/QueryaHub/OxyRoute/issues/103)).
+- Observability hooks: request id, access log, metrics
+  ([#127](https://github.com/QueryaHub/OxyRoute/pull/127)).
+- SQLx / Postgres pool helpers on `AppState` and dynamic query execution from Python
+  dependencies ([#116](https://github.com/QueryaHub/OxyRoute/issues/116),
+  [#118](https://github.com/QueryaHub/OxyRoute/issues/118)).
+- Criterion microbenchmarks (`cargo bench --bench hot_path`) and expanded wrk scenarios
+  (`perf-test/bench_scenarios.sh`); optional `perf-smoke` workflow
+  ([#110](https://github.com/QueryaHub/OxyRoute/issues/110)).
+
+### Changed
+
+- OpenAPI path keys use `{param}` form (breaking for consumers that asserted matchit
+  `:param` strings in `openapi_json()`).
+- JWT hot path reuses prebuilt `DecodingKey` and `Validation` per route
+  ([#109](https://github.com/QueryaHub/OxyRoute/issues/109)).
+- CORS response merge skips the Python `response_header_pairs` call when the request has
+  no `Origin` header ([#108](https://github.com/QueryaHub/OxyRoute/issues/108)).
+- OpenAPI document string is cached until the next registration change
+  ([#129](https://github.com/QueryaHub/OxyRoute/pull/129)).
+- Router / dispatch hot-path improvements: fewer path-param allocations, sync short-circuit
+  for trivial routes, direct `json_to_py`, cheaper str/bytes responses, env-flag caching
+  ([#94](https://github.com/QueryaHub/OxyRoute/issues/94)–[#97](https://github.com/QueryaHub/OxyRoute/issues/97),
+  [#128](https://github.com/QueryaHub/OxyRoute/pull/128)).
+
+### Migration
+
+- Prefer `async def on_startup` / `on_shutdown` for worker lifecycle under Granian. Do not
+  override `__rsgi_init__` as `async def` (the coroutine is never awaited).
+- Update any tooling that expected OpenAPI paths with matchit `:param` syntax to `{param}`.
+- Interactive docs: `App(..., docs_ui="scalar")` (or `mount_docs`) instead of app-local HTML.
+
+## [0.4.0] - 2026-05
+
+RSGI-only line with native WebSockets, forms, CORS/CSRF/security headers, and related
+hardening after the v0.3.0 ASGI removal. See `git log v0.3.0..v0.4.0` for the full list.
+
 ## [0.3.0] - 2026-04-27
 
 ### Added