Merge pull request #93 from QueryaHub/chore-readme-positioning-main-pr

docs: update README positioning and 0.3.0 changelog heading

Author: ZhuchkaTriplesix

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to OxyRoute are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-04-27
+
+### Added
+
+- Native RSGI WebSocket support: `@app.websocket(path)` and `oxyroute.WebSocket` are
+  exported from the package and dispatched directly inside the Rust extension. No ASGI
+  shim is involved; the helper class wraps Granian's `RSGIWebsocketProtocol` and exposes
+  `accept`, `receive` / `receive_text` / `receive_bytes`, `send_text` / `send_bytes` /
+  `send_json`, and `close`. Path matching uses the same `matchit` syntax as HTTP routes
+  and lives in its own router. Unknown paths produce a polite `close(1000)`; handler
+  errors trigger `close(1011)`.
+
+### Removed (breaking)
+
+- The optional ASGI 3.0 compatibility bridge (`oxyroute.asgi`) was removed. `App` is no
+  longer an ASGI callable; `App.__call__`, `App._asgi3`, the `asgi_to_rsgi` helper and the
+  `WebSocket` helper class are gone. Run OxyRoute exclusively under
+  ``granian --interface rsgi``.
+- The ASGI-based `@app.websocket(path)` decorator and the
+  `App._handle_asgi_websocket` plumbing were removed alongside the bridge. Native RSGI
+  WebSocket support is reintroduced in this release (see *Added*).
+
+### Migration
+
+- If you ran `uvicorn` or `granian --interface asgi` against an OxyRoute app, switch to
+  `granian --interface rsgi`. RSGI is now the only supported transport.
+- For unit tests that drove the app via `httpx.ASGITransport(app=app)`, import the
+  test-only shim from the test tree:
+
+  ```python
+  from tests._rsgi_test_transport import asgi_test_app
+  transport = httpx.ASGITransport(app=asgi_test_app(app))
+  ```
+
+  The shim is **only** built for the test suite; production code must not import it.
+
+## [0.2.0] - 2026-04
+
+Initial public release. See `git log v0.2.0` for details.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "oxyroute"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 description = "RSGI web framework: Rust hot path, Python handlers"
 license = "MIT"

Cargo.toml

@@ -1,21 +1,22 @@
 # OxyRoute
 
-**RSGI-first** web toolkit: HTTP routing, JSON handling, and HS\* JWT validation on a **Rust** hot path ([PyO3](https://pyo3.rs/) + [Maturin](https://www.maturin.rs/)), with your business logic in ordinary **Python** handlers. Pair it with **[Granian](https://github.com/emmett-framework/granian)** using `--interface rsgi` for the intended stack.
+High-performance web framework for **Granian RSGI**, tuned for high **single-worker** throughput: routing, JSON/form parsing, JWT checks, response mapping, and native WebSockets run on a **Rust** hot path ([PyO3](https://pyo3.rs/) + [Maturin](https://www.maturin.rs/)), while business logic stays in plain **Python** handlers.
 
 [![CI](https://github.com/QueryaHub/OxyRoute/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/QueryaHub/OxyRoute/actions)
 
 ## Features
 
 - **RSGI** entrypoint (`async def __rsgi__(scope, protocol)`) compatible with Granian’s RSGI implementation
 - **Routing** via [matchit](https://crates.io/crates/matchit) (path parameters like `/users/:id`)
-- **JSON bodies** parsed in Rust; successful values passed to handlers as kwargs
-- **JWT (HMAC)** verification on the Rust path before your handler runs (`require_jwt`, HS256/384/512)
+- **JSON, form, and multipart bodies** parsed on the native path; successful values passed to handlers as kwargs
+- **JWT** verification on the Rust path before your handler runs (`require_jwt`, HS*, RSA, EC, EdDSA public-key verification)
 - **Optional** `GET /openapi.json` with a minimal OpenAPI-style document
 - **Dependencies**: linear list of named factories (`Depends`, sync or async) passed as kwargs
-- **Optional ASGI 3** bridge: `async def __call__(scope, receive, send)` for servers that speak ASGI (see [docs/asgi.md](docs/asgi.md))
+- **Optional middleware layers** for pre-route decisions, CORS, CSRF, and browser security headers
+- **Native RSGI WebSockets** via `@app.websocket(path)` and `oxyroute.WebSocket`
 - Native extension wheel (abi3) for **Python ≥ 3.10**
 
-Full documentation: **[docs/index.md](docs/index.md)**
+Start with the full **[Usage guide](docs/usage.md)**, or use **[docs/index.md](docs/index.md)** for topic-specific pages.
 
 ## Requirements
 
@@ -61,8 +62,8 @@ def root() -> str:
 
 
 @app.get("/hello/:name")
-def hello_name(**kwargs) -> str:
-    return f"Hello, {kwargs.get('name', '')}"
+def hello_name(name: str) -> dict:
+    return {"message": f"Hello, {name}"}
 ```
 
 Run (from the repo, after `maturin develop` or an editable install):
@@ -73,11 +74,24 @@ granian --interface rsgi examples.rsgi_app:app
 
 Per-worker setup (`__rsgi_init__`) is shown in [examples/rsgi_lifespan_app.py](examples/rsgi_lifespan_app.py) and [docs/rsgi.md](docs/rsgi.md#lifespan-optional).
 
-ASGI and other servers are covered in [docs/asgi.md](docs/asgi.md).
+OxyRoute v0.3.0 supports **only** Granian RSGI; the legacy ASGI bridge (`uvicorn` / `granian --interface asgi`) was removed.
+
+## Usage docs
+
+- [Usage guide](docs/usage.md) — install, run, routing, bodies, responses, middleware, CORS, CSRF, JWT, WebSockets, deployment notes, limitations
+- [RSGI and Granian](docs/rsgi.md) — app entrypoint, lifespan hooks, worker process model
+- [Handlers](docs/handlers.md) — injected parameters and response mapping details
+- [Routing](docs/routing.md) — methods, path syntax, `APIRouter`, `freeze()`
+- [JWT](docs/jwt.md), [CORS](docs/cors.md), [CSRF](docs/csrf.md), [Security headers](docs/security-headers.md)
+- [WebSockets](docs/websocket.md) and [SSE](docs/sse.md)
+
+## Production notes
+
+OxyRoute is designed for Granian RSGI deployments. For public traffic, place it behind a normal production boundary (TLS, request-size limits, timeouts, logging, process supervision) and keep `OXYROUTE_DEBUG` disabled. Request bodies and multipart files are currently buffered in memory before parsing, so enforce limits both at the edge and with `OXYROUTE_MAX_BODY_BYTES`.
 
 ## Project layout
 
-- `oxyroute/` — Python package (`App`, `Depends`, optional ASGI bridge)
+- `oxyroute/` — Python package (`App`, `Depends`)
 - `src/` — Rust extension (`_oxyroute`, routing, dispatch, JWT helpers)
 - `docs/` — detailed English documentation
 - `tests/` — pytest suite (run from a temp directory or an installed wheel so the source tree does not shadow the package; see [docs/development.md](docs/development.md))

README.md

@@ -6,7 +6,7 @@ OxyRoute supports a **linear** list of **named** dependency factories. At reques
 
 ### Request context (optional)
 
-If a factory’s signature includes a parameter named `request`, the extension passes a **dict** (once per request, shared) with string keys: `method`, `path`, `query_string`, and `headers` (a flat `str` → `str` map, when the underlying RSGI scope exposes headers—see the ASGI bridge in `oxyroute.asgi`). Factories that do **not** declare `request` are still called with **no** extra arguments when they have no prior dependencies, preserving older behavior.
+If a factory’s signature includes a parameter named `request`, the extension passes a **dict** (once per request, shared) with string keys: `method`, `path`, `query_string`, and `headers` (a flat `str` → `str` map, when the underlying RSGI scope exposes headers). Factories that do **not** declare `request` are still called with **no** extra arguments when they have no prior dependencies, preserving older behavior.
 
 ## Declaring on a route
 

docs/asgi.md

@@ -42,7 +42,7 @@ pip install "oxyroute[dev]"  # in your dev env, from source after maturin develo
 
 ## Granian RSGI (end-to-end)
 
-`tests/test_granian_e2e.py` starts a real **Granian** subprocess with `--interface rsgi`, sends HTTP requests with **httpx**, then stops the server. It is part of the normal **pytest** run when `granian` is installed (`oxyroute[dev]` includes it). The same file runs in **CI** on every matrix combination (Linux, macOS, Windows), so the native RSGI path is exercised against a real server, not only the ASGI in-process transport.
+`tests/test_granian_e2e.py` starts a real **Granian** subprocess with `--interface rsgi`, sends HTTP requests with **httpx**, then stops the server. It is part of the normal **pytest** run when `granian` is installed (`oxyroute[dev]` includes it). The same file runs in **CI** on every matrix combination (Linux, macOS, Windows), so the native RSGI path is exercised against a real server, not only the in-process httpx test transport.
 
 ## Continuous integration
 
@@ -53,11 +53,11 @@ The workflow at `.github/workflows/ci.yml` (job name: **ci**):
 
 ## Releasing to PyPI
 
-Tag a release with a **`v`-prefixed** semver tag (example: **`v0.2.0`**). That triggers `.github/workflows/release-pypi.yml`, which builds an **sdist**, **manylinux** x86_64 wheels, **Windows** x64, and **macOS** arm64 + x86_64 wheels, then uploads to **PyPI** using a **project-scoped API token** stored in GitHub as **`PYPI_API_TOKEN`** (Secret or Environment variable) on the **`pypi`** environment. The publish step uses `secrets` first, then `vars` (so you can start with a variable and move the value to a **Secret** later).
+Tag a release with a **`v`-prefixed** semver tag (example: **`v0.3.0`**). That triggers `.github/workflows/release-pypi.yml`, which builds an **sdist**, **manylinux** x86_64 wheels, **Windows** x64, and **macOS** arm64 + x86_64 wheels, then uploads to **PyPI** using a **project-scoped API token** stored in GitHub as **`PYPI_API_TOKEN`** (Secret or Environment variable) on the **`pypi`** environment. The publish step uses `secrets` first, then `vars` (so you can start with a variable and move the value to a **Secret** later).
 
 **Before the first upload:**
 
-1. Keep **`pyproject.toml`**, **`Cargo.toml`**, and **`oxyroute/__init__.py`** `__version__` in sync with the version you are releasing, and with the tag (e.g. `0.2.0` → tag `v0.2.0`).
+1. Keep **`pyproject.toml`**, **`Cargo.toml`**, and **`oxyroute/__init__.py`** `__version__` in sync with the version you are releasing, and with the tag (e.g. `0.3.0` → tag `v0.3.0`).
 2. On [PyPI](https://pypi.org), create a **scoped API token** for this project, then in GitHub → **Settings → Environments** create the **`pypi`** environment and add **`PYPI_API_TOKEN`** (strongly prefer an **Environment secret** over a **Variable**; tokens in Variables are visible to people with access to the environment).
 3. Optional alternative to API tokens: [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) — no long-lived token; then the workflow’s publish job should omit `with.password` and set `id-token: write` (see the PyPA action README).