Skip to content

index.md

Latest commit

 

History

History
59 lines (50 loc) · 2.99 KB

index.md

File metadata and controls

59 lines (50 loc) · 2.99 KB

OxyRoute documentation

OxyRoute is a small RSGI-oriented framework: the native Rust extension handles HTTP matching, JSON parsing, optional JWT checks, and response construction, while your code stays in Python functions or coroutines.

The primary integration is Granian with --interface rsgi, which calls your application’s async def __rsgi__(scope, protocol) on each connection. OxyRoute’s App type implements that contract and delegates to a PyO3 App that runs the async run_rsgi pipeline in Rust.

Architecture (high level)

flowchart LR
  subgraph server [Server]
    G[Granian RSGI]
  end
  subgraph py [Python]
    A[App class]
  end
  subgraph rust [Rust _oxyroute]
    R[run_rsgi]
    RT[matchit router]
    J[JWT and JSON]
    S[Response helpers]
  end
  G --> A
  A -->|handle_rsgi| R
  R --> RT
  R --> J
  R --> S
  R -->|handler kwargs| A
  S --> G
Loading

Granian still invokes a Python App object; the “win” is doing routing, body parsing, and JWT in one native layer before your handler runs, instead of a heavier pure-Python stack.

Note: A full “zero GIL at the process boundary” is not claimed—OxyRoute reduces Python work on the request path, not the server’s own scheduling.

Table of contents

Topic Description
Usage guide End-to-end reference: install, run, routing, bodies, responses, middleware, CORS/CSRF/JWT, WebSockets, production notes
Installation pip, oxyroute[dev], building with Cargo/maturin, troubleshooting
RSGI and Granian Why RSGI, __rsgi__, lifespan hooks, spec link
Routing Path patterns, methods, 404s
Handlers Injected parameters, return types, JSON encoding
CORS CORSConfig, preflight, apply_cors
Security headers SecurityHeadersConfig, HSTS, CSP
CSRF Double-submit, apply_csrf, csrf_layer + CORS
JWT require_jwt, HS* / RSA / EC PEM, decode_jwt_hs (HS* tests)
SSE send_sse, event framing, streaming caveats
WebSockets Native RSGI @app.websocket(path) and oxyroute.WebSocket
HTTP/2 with Granian Transport guarantees vs server/proxy responsibilities
Dependencies Depends, dependencies=[...], freeze
OpenAPI openapi.json route, title, openapi_json()
Development Tests, CI, PyPI releases (tag v*), clippy, pytest
Branching and PRs dev as base, issue branches, Closes #N, no mixing code with ISSUE_BACKLOG in one commit
Feature gaps (research) What is missing vs a “full” HTTP framework and what has been implemented — Russian
Contributing Local setup, issue backlog, GitHub gh workflow

← Back to project README