swadhin / justapi public

p8c-f: add Release Notes, ADR Index, Error Codes, Glossary reference pages

swadhinbiswas committed 3 months ago
23bd6a4
1 parent 4059686
commit 23bd6a4
4 files changed
+265 -17
Showing 4 changed files+265-17
docs_site/src/content/docs/reference/adr-index.mddocs_site/src/content/docs/reference/error-codes.mddocs_site/src/content/docs/reference/glossary.mddocs_site/src/content/docs/reference/release-notes.md
▼docs_site/src/content/docs/reference/adr-index.md
+64-0
@@ -0,0 +1,64 @@
1
+---
2
+title: ADR Index
3
+description: Architecture Decision Records — key decisions that shaped JustAPI.
4
+---
5
+
6
+JustAPI documents significant architectural decisions as Architecture Decision Records (ADRs) in `DECISIONS.md`.
7
+
8
+## Architecture & Design
9
+
10
+| ADR | Title | Key Point |
11
+|---|---|---|
12
+| 001 | Crate defaults for v1.0 | Workspace structure and crate responsibilities |
13
+| 005 | Rust edition: 2021 | Deliberately stayed on 2021 edition |
14
+| 008 | GIL strategy | Dedicated Python worker thread (later superseded) |
15
+| 014 | Project rename: Hyperion → JustAPI | Rebranding rationale |
16
+| 021 | GIL-free architecture | Removed dedicated Python worker thread |
17
+
18
+## Performance
19
+
20
+| ADR | Title | Key Point |
21
+|---|---|---|
22
+| 006 | Benchmark tooling: oha over wrk | Chose oha for consistency |
23
+| 020 | Performance target | Beat FastAPI on every benchmark |
24
+| 024 | Bucket-based latency histograms | Custom over HDR Histogram |
25
+| 047 | Remove per-request Python↔Rust boundary | Native fast path |
26
+| 056 | Rust-native route compiler | Skip GIL on common routes |
27
+| 064 | Route-lookup cache | Memoization for repeated lookups |
28
+
29
+## Security
30
+
31
+| ADR | Title | Key Point |
32
+|---|---|---|
33
+| 018 | Security strategy | SAST in CI, fuzzing, OWASP baseline |
34
+| 050 | Secure-by-default CORS | Opt-in security headers |
35
+| 052 | Single error-response contract | `{"detail": ...}` format |
36
+| 053 | Panic model: abort + supervisor | Not catch_unwind |
37
+| 055 | Configurable max body size | 413 on overflow |
38
+
39
+## Database
40
+
41
+| ADR | Title | Key Point |
42
+|---|---|---|
43
+| 016 | Database strategy | sqlx with compile-time checks |
44
+| 058 | Eager/early DB pool connect | Removes `app.db is None` footgun |
45
+| 069 | Fix DB-backed handler deadlock | WAL hang fix |
46
+| 074 | DB-startup + response-correctness | Fixed normalize_db_url |
47
+
48
+## Inference
49
+
50
+| ADR | Title | Key Point |
51
+|---|---|---|
52
+| 030 | Native inference engine | Candle, not torch delegation |
53
+| 036 | Disaggregated prefill/decode | Separate prefill and decode resources |
54
+| 068 | Freeze AI/inference work | Until 2.0.8 release |
55
+
56
+## Full List
57
+
58
+All 75+ ADRs are documented in [`DECISIONS.md`](https://github.com/swadhinbiswas/JustAPI/blob/main/DECISIONS.md) at the repository root.
59
+
60
+## See Also
61
+
62
+- [Architecture Overview](/getting-started/overview/) — High-level design
63
+- [Rust Core Deep Dive](/advanced/rust-core-deep-dive/) — Runtime internals
64
+- [Release Notes](/reference/release-notes/) — Version history
0
65
▼docs_site/src/content/docs/reference/error-codes.md
+64-0
@@ -0,0 +1,64 @@
1
+---
2
+title: Error Codes
3
+description: JustAPI error code catalog and troubleshooting guide.
4
+---
5
+
6
+## CLI Error Codes
7
+
8
+| Code | Error | Cause | Fix |
9
+|---|---|---|---|
10
+| `E001` | Invalid address | Address format is invalid | Use `host:port` format (e.g., `127.0.0.1:8000`) |
11
+| `E002` | Port in use | Address already bound | Use a different port or stop the other process |
12
+| `E003` | Config file not found | Configuration file missing | Create the config file or specify the correct path |
13
+| `E004` | Database connection failed | Cannot connect to database | Verify DATABASE_URL and database server status |
14
+| `E005` | Migration failed | Migration SQL error | Check migration SQL syntax and database state |
15
+| `E006` | Worker start failed | Cannot start worker process | Check system resources and ulimits |
16
+| `E007` | Hot-reload not available | File watcher initialization failed | Ensure `notify` library is installed |
17
+
18
+## HTTP Status Codes
19
+
20
+| Status | Description | Common Cause |
21
+|---|---|---|
22
+| 400 | Bad Request | Malformed request syntax |
23
+| 401 | Unauthorized | Missing or invalid authentication |
24
+| 403 | Forbidden | Insufficient permissions |
25
+| 404 | Not Found | Route not registered |
26
+| 413 | Payload Too Large | Body exceeds `max_body_size` |
27
+| 422 | Unprocessable Entity | Request validation failure |
28
+| 429 | Too Many Requests | Rate limit exceeded |
29
+| 500 | Internal Server Error | Unhandled exception in handler |
30
+| 503 | Service Unavailable | Database pool saturated |
31
+| 504 | Gateway Timeout | Request exceeded timeout |
32
+
33
+## Troubleshooting
34
+
35
+### "ModuleNotFoundError: No module named '_justapi'"
36
+
37
+The Rust extension wasn't built. Run:
38
+
39
+```bash
40
+maturin develop --release --manifest-path crates/justapi-py/Cargo.toml
41
+```
42
+
43
+### "SQLITE_CANTOPEN"
44
+
45
+Database path resolution issue. Ensure the path is correct:
46
+
47
+```python
48
+app.set_database("sqlite:///app.db") # Relative path (3 slashes)
49
+app.set_database("sqlite:////tmp/db") # Absolute path (4 slashes)
50
+```
51
+
52
+### "database pool saturated"
53
+
54
+All connections are in use. Increase pool size or reduce concurrent load:
55
+
56
+```python
57
+app.set_database("...", max_connections=20, request_acquire_timeout=3.0)
58
+```
59
+
60
+## See Also
61
+
62
+- [CLI Reference](/reference/cli/) — Command line documentation
63
+- [Configuration Reference](/reference/configuration/) — Environment variables
64
+- [Production Checklist](/deployment/production-checklist/) — Troubleshooting in production
0
65
▼docs_site/src/content/docs/reference/glossary.md
+100-0
@@ -0,0 +1,100 @@
1
+---
2
+title: Glossary
3
+description: Key terms and concepts used throughout the JustAPI documentation.
4
+---
5
+
6
+## A
7
+
8
+**APIRouter** — A class for grouping related routes into modular files. Supports the same decorators as `JustAPIApp`.
9
+
10
+**ASGI** — Asynchronous Server Gateway Interface. Python standard for async web servers. JustAPI provides an ASGI shim for compatibility.
11
+
12
+## B
13
+
14
+**BackgroundTasks** — Post-response task execution. Register callables to run after the HTTP response is sent.
15
+
16
+**Bulkhead** — Resilience pattern that limits concurrent requests to prevent resource exhaustion.
17
+
18
+## C
19
+
20
+**Circuit Breaker** — Resilience pattern that stops calling a failing service when errors exceed a threshold.
21
+
22
+**CORS** — Cross-Origin Resource Sharing. HTTP mechanism for controlling cross-origin requests.
23
+
24
+## D
25
+
26
+**Depends** — Dependency injection function. Resolves and injects callable results into route handlers.
27
+
28
+**Dependency Injection** — Design pattern where a component's dependencies are provided externally.
29
+
30
+## G
31
+
32
+**GIL** — Global Interpreter Lock. CPython's mechanism preventing multiple threads from executing Python bytecode simultaneously.
33
+
34
+**GIL Pool** — Subsystem managing GIL-bound worker threads for Python handler execution.
35
+
36
+**gRPC** — High-performance RPC framework using Protocol Buffers.
37
+
38
+## H
39
+
40
+**Hyper** — Rust HTTP library used by JustAPI for HTTP/1.1 and HTTP/2 parsing.
41
+
42
+## J
43
+
44
+**JSON-RPC 2.0** — Lightweight remote procedure call protocol using JSON encoding.
45
+
46
+**JustAPIApp** — The core application class. Register routes, middleware, plugins, and configuration.
47
+
48
+## M
49
+
50
+**matchit** — Rust radix-trie router library. Provides O(1) path matching.
51
+
52
+**MCP** — Model Context Protocol. Protocol for exposing tools and context to AI agents.
53
+
54
+**Middleware** — Request/response processing layer that runs before and after route handlers.
55
+
56
+## N
57
+
58
+**Native Fast Path** — Route execution entirely in Rust with `native=True`. Maximum performance (724k+ RPS).
59
+
60
+## O
61
+
62
+**OpenAPI** — Standard specification for REST API documentation. JustAPI auto-generates OpenAPI 3.1 specs.
63
+
64
+**OTel** — OpenTelemetry. Observability framework for distributed tracing and metrics.
65
+
66
+## P
67
+
68
+**PyO3** — Rust bindings for Python. Used to build the JustAPI Python extension module.
69
+
70
+**Pydantic** — Python library for data validation. JustAPI supports Pydantic v2 models as route schemas.
71
+
72
+## R
73
+
74
+**Radix Trie** — Tree data structure used by matchit for O(1) route matching.
75
+
76
+**Rustls** — Rust TLS library. Provides TLS 1.2/1.3 support.
77
+
78
+## S
79
+
80
+**Schema** — JustAPI's built-in validation class. Supports Field constraints and Rust-side validation.
81
+
82
+**serde_json** — Rust JSON serialization library. Used for response serialization.
83
+
84
+**SSE** — Server-Sent Events. HTTP protocol for server-to-client streaming.
85
+
86
+**sqlx** — Rust SQL library with compile-time query checking. Powers JustAPI's database layer.
87
+
88
+## T
89
+
90
+**Tokio** — Rust async runtime. Powers JustAPI's network I/O and concurrency.
91
+
92
+## Z
93
+
94
+**Zero-Copy** — Data transfer technique avoiding unnecessary memory copies. Used at the Rust↔Python FFI boundary.
95
+
96
+## See Also
97
+
98
+- [ADR Index](/reference/adr-index/) — Architecture Decision Records
99
+- [Architecture Overview](/getting-started/overview/) — High-level design
100
+- [Rust Core Deep Dive](/advanced/rust-core-deep-dive/) — Runtime internals
0
101
▼docs_site/src/content/docs/reference/release-notes.md
+37-17
@@ -1,28 +1,48 @@
1
1
---
2
-title: Release Notes - JustAPI v2.0.0
3
-description: Official release notes for JustAPI 2.0.0.
2
+title: Release Notes
3
+description: Version history and changelog for JustAPI.
4
4
---
5
5
6
-## 🚀 JustAPI v2.0.0 Release Highlights
6
+## 2.0.0 (2026-07-24)
7
7
8
-We are thrilled to announce **JustAPI 2.0.0** — the flagship production release of the Rust-powered Python web framework!
8
+### Breaking Changes
9
9
10
-### 🌟 Key Changes in 2.0.0
10
+- `FastAPI` → `JustAPIApp` rename
11
+- Server startup: `app.run()` replaces uvicorn
12
+- Middleware response manipulation uses tuple-based headers
11
13
12
-1. **Multi-Database Project Scaffolder:**
13
- * Interactive CLI wizard (`justapi create`) supporting DuckDB, ClickHouse, PostgreSQL, MySQL, SQLite, MongoDB, and Redis.
14
+### New Features
14
15
15
-2. **Multi-Protocol Architecture:**
16
- * Built-in support for REST (OpenAPI 3.1 & Scalar UI), GraphQL (`app.graphql()`), gRPC/Protobuf (`/rpc`), and JSON-RPC 2.0 (`/jsonrpc`).
16
+- Multi-database project scaffolder (`justapi create`)
17
+- Multi-protocol support (REST, GraphQL, gRPC, JSON-RPC)
18
+- Native MCP tool registration (`@app.tool`)
19
+- Validated streaming output (`@app.stream_json`)
20
+- Rust-backed agent session store
21
+- OpenTelemetry Jaeger stack generator
22
+- Multi-arch PyPI wheels (Linux, macOS, Windows, ARM64)
23
+- Load-based auto-scaling (`justapi serve --scale`)
24
+- Unix domain socket support
17
25
18
-3. **OpenTelemetry Jaeger Stack Generator:**
19
- * Automatically generates `docker-compose.otel.yml` for zero-config distributed tracing and Prometheus monitoring.
26
+### Performance
20
27
21
-4. **Multi-Arch Binary Wheel Pipeline:**
22
- * Published multi-architecture PyPI wheels for Linux x86_64, Linux ARM64 (AWS Graviton), Linux Musl (Alpine), macOS x86_64/arm64, and Windows x64.
28
+- 701,234 RPS hello-world (20x FastAPI)
29
+- 724,038 RPS native fast path
30
+- 456,168 RPS native DB query path
31
+- Sub-0.2 ms p99 latency
23
32
24
-5. **Starlette Parity:**
25
- * Added `app.add_middleware()`, `app.add_cors()`, and FastAPI-standard `JustAPIApp(title=..., version=...)` kwargs.
33
+### Security
26
34
27
-6. **Hardened Security & Fuzzing:**
28
- * Untrusted input pipeline fuzzing targets verified clean across Miri and LLVM libFuzzer suites.
35
+- OWASP Top 10 compliance (A01-A10 coverage)
36
+- 7 cargo-fuzz targets in CI
37
+- Rustls TLS (TLS 1.2/1.3 only)
38
+- Secure-by-default CORS + security headers
39
+
40
+## 1.0.0 (2026-07-15)
41
+
42
+Initial release with core routing, middleware, database support, and FastAPI compatibility.
43
+
44
+## See Also
45
+
46
+- [ADR Index](/reference/adr-index/) — Architecture Decision Records
47
+- [Changelog](https://github.com/swadhinbiswas/JustAPI/releases)
48
+- [Roadmap](https://github.com/swadhinbiswas/JustAPI/blob/main/ROADMAP.md)
29
49