fix: docs

dancixx · dancixx · commit b2164ac1c703 · 2026-06-06T15:26:51.000+02:00
diff --git a/README.md b/README.md
@@ -7,181 +7,34 @@
 > **Tako** (*"octopus"* in Japanese) is a pragmatic, ergonomic and extensible Rust framework for services that go beyond plain HTTP.
 > Build one cohesive application across HTTP/1.1, HTTP/2, HTTP/3, WebSocket, SSE, gRPC, TCP, UDP, Unix sockets, and WebTransport with a single routing, middleware, and observability model.
 
+📖 **Full documentation → [tako.rust-dd.com](https://tako.rust-dd.com)** &nbsp;·&nbsp; [API docs (docs.rs)](https://docs.rs/tako-rs/latest/tako/)
+
 ## Why Tako
 
-Tako is built for teams that want fewer moving parts in production:
-
-* **One service, many transports** — Serve REST, WebSockets, SSE, gRPC, raw TCP/UDP, Unix sockets, and QUIC-based workloads without switching frameworks.
-* **One mental model, two runtimes** — Use the same framework style on **Tokio** or **Compio** depending on the deployment constraints.
-* **Application primitives included** — Middleware, auth, metrics, signals, queues, graceful shutdown, and streaming are part of the framework story, not an afterthought.
-* **Performance knobs when they matter** — SIMD JSON, optional zero-copy extractors, compression, jemalloc, and HTTP/3 support are available without fragmenting the API.
-* **Strong fit for real systems** — API backends, realtime apps, protocol gateways, internal platforms, and edge-facing services.
-
-## ✨ Highlights
-
-* **Multi-transport by design** — HTTP/1.1, HTTP/2, HTTP/3 (QUIC), WebSocket, WebTransport, SSE, gRPC, TCP, UDP, Unix sockets, and PROXY protocol.
-* **Dual runtime support** — First-class support for both **Tokio** and **Compio**, including TLS and HTTP/2 on both sides where supported.
-* **Built-in platform primitives** — Background job queue, in-process signals, metrics hooks, graceful shutdown, static files, and stream helpers.
-* **Rich middleware and auth** — JWT, Basic, Bearer, API key, CSRF, sessions, body limits, request IDs, security headers, upload progress, rate limiting, CORS, idempotency, and compression.
-* **Strongly typed extraction** — 22+ extractors for JSON, form, query, path, headers, cookies, JWT claims, API keys, Accept, Range, protobuf, multipart, and more.
-* **Performance paths included** — SIMD JSON (`sonic-rs` / `simd-json`), optional zero-copy extractors, brotli/gzip/deflate/zstd, and jemalloc support.
-* **Realtime-ready** — Streaming responses, SSE, WebSockets, GraphQL subscriptions, HTTP/3, and WebTransport under one crate.
-* **Docs and API surface included** — OpenAPI via `utoipa` or `vespera`, GraphiQL support, and a growing example suite for common deployment patterns.
-
-## Best Fit
-
-Choose Tako when your service needs one or more of these:
-
-* **More than REST** — You need HTTP APIs plus WebSockets, SSE, gRPC, TCP, UDP, or QUIC in the same application.
-* **Realtime coordination** — You want built-in signals, queues, and streaming primitives instead of composing everything manually.
-* **Framework consolidation** — You would rather depend on one coherent crate than glue together several partially overlapping libraries.
-* **Protocol-heavy infrastructure** — Gateways, internal platforms, telemetry collectors, control planes, or edge services are a particularly strong fit.
-
-## Feature Matrix
-
-### Transports & Protocols
-
-| Protocol | Tokio | Compio | Feature flag |
-|---|---|---|---|
-| HTTP/1.1 | ✅ | ✅ | *default* |
-| HTTP/2 | ✅ | ✅ | `http2` |
-| HTTP/3 (QUIC) | ✅ | — | `http3` |
-| TLS (rustls) | ✅ | ✅ | `tls` / `compio-tls` |
-| WebSocket | ✅ | ✅ | *default* / `compio-ws` |
-| WebTransport | ✅ | — | `webtransport` |
-| SSE | ✅ | ✅ | *default* |
-| gRPC (unary) | ✅ | — | `grpc` |
-| Raw TCP | ✅ | — | *default* |
-| Raw UDP | ✅ | — | *default* |
-| Unix sockets | ✅ | — | *default* (unix only) |
-| PROXY protocol v1/v2 | ✅ | — | *default* |
-
-### Extractors (22+)
-
-| Extractor | Description |
-|---|---|
-| `Json<T>` | JSON body (with optional SIMD acceleration) |
-| `Form<T>` | URL-encoded form body |
-| `Query<T>` | URL query parameters |
-| `Path<T>` | Route path parameters |
-| `Params` | Dynamic path params map |
-| `HeaderMap` | Full request headers |
-| `Bytes` | Raw request body |
-| `State<T>` | Shared application state |
-| `CookieJar` | Cookie reading/writing |
-| `SignedCookieJar` | HMAC-signed cookies |
-| `PrivateCookieJar` | Encrypted cookies |
-| `BasicAuth` | HTTP Basic authentication |
-| `BearerAuth` | Bearer token extraction |
-| `JwtClaimsUnverified<T>` | Unverified JWT claims decode (signature **not** checked) |
-| `JwtClaimsVerified<T>` | Signature-verified JWT claims (via `tako-plugins::JwtAuth`) |
-| `ApiKey` | API key from header/query |
-| `Accept` | Content negotiation |
-| `AcceptLanguage` | Language negotiation |
-| `Range` | HTTP Range header |
-| `IpAddr` | Client IP address |
-| `Protobuf<T>` | Protocol Buffers body |
-| `SimdJson<T>` | Force SIMD JSON parsing |
-| `Multipart` | Multipart form data |
-
-### Middleware
-
-| Middleware | Description |
-|---|---|
-| JWT Auth | Validate JWT tokens on routes |
-| Basic Auth | HTTP Basic authentication |
-| Bearer Auth | Bearer token validation |
-| API Key Auth | Header or query-based API key |
-| CSRF | Double-submit cookie CSRF protection |
-| Session | Cookie-based sessions (in-memory store) |
-| Security Headers | HSTS, X-Frame-Options, CSP, etc. |
-| Request ID | Generate/propagate `X-Request-ID` |
-| Body Limit | Enforce max request body size |
-| Upload Progress | Track upload progress callbacks |
-| CORS | Cross-Origin Resource Sharing |
-| Rate Limiter | Token-bucket rate limiting |
-| Compression | Brotli / gzip / deflate / zstd |
-| Idempotency | Idempotency key deduplication |
-| Metrics | Prometheus / OpenTelemetry export |
-
-### Feature Flags
-
-| Flag | Description |
-|---|---|
-| `http2` | HTTP/2 support (ALPN h2) |
-| `http3` | HTTP/3 over QUIC (enables `webtransport`) |
-| `tls` | HTTPS via rustls |
-| `compio` | Compio async runtime (alternative to tokio) |
-| `compio-tls` | TLS on compio |
-| `compio-ws` | WebSocket on compio |
-| `grpc` | gRPC unary RPCs with protobuf |
-| `protobuf` | Protobuf extractor (prost) |
-| `plugins` | CORS, compression, rate limiting |
-| `simd` | SIMD JSON parsing (sonic-rs + simd-json) |
-| `multipart` | Multipart form-data extractors |
-| `file-stream` | File streaming & range requests |
-| `async-graphql` | GraphQL integration |
-| `graphiql` | GraphiQL IDE endpoint |
-| `signals` | In-process pub/sub signal system |
-| `jemalloc` | jemalloc global allocator |
-| `zstd` | Zstandard compression (in plugins) |
-| `tako-tracing` | Distributed tracing subscriber |
-| `utoipa` | OpenAPI docs via utoipa |
-| `vespera` | OpenAPI docs via vespera |
-| `metrics-prometheus` | Prometheus metrics export |
-| `metrics-opentelemetry` | OpenTelemetry metrics export |
-| `zero-copy-extractors` | Zero-copy body extraction |
-| `client` | Outbound HTTP client |
-
-## Documentation
-
-- **Guide & reference:** [tako.rust-dd.com](https://tako.rust-dd.com) — the full handbook: getting started, transports, extractors, middleware, concepts, and reference.
-- **API docs:** [docs.rs/tako-rs](https://docs.rs/tako-rs/latest/tako/)
-
-The documentation site lives in [`website/`](./website) (Fumadocs + Next.js + MDX).
-
-MSRV 1.95 | Edition 2024
-
-See [`STABILITY.md`](./STABILITY.md) for the full semver and MSRV policy,
-[`MIGRATION_1_TO_2.md`](./MIGRATION_1_TO_2.md) for upgrading from 1.x, and
-[`CHANGELOG.md`](./CHANGELOG.md) for release notes.
-
-## Tako in Production
-
-Tako already powers real-world services in production:
-
-- `stochastic-api`: https://stochasticlab.cloud/
-- `shrtn.ink`: https://app.shrtn.ink/
-
-## Baseline Hello World Benchmark
-
-Hello world throughput is not the whole story, but the current branch lands in this range on a clean local run:
-
-| Framework | Requests/sec | Avg Latency | Note |
-| --- | ---: | ---: | --- |
-| Tako | ~187,288 | ~505 us | latest local `30s` rerun |
-| Tako + `jemalloc` | ~187,638 | ~502 us | latest local `30s` rerun |
-| Axum | ~186,194 | ~498 us | latest local `30s` rerun |
-| Actix | ~155,307 | ~635 us | latest local `30s` rerun |
-
-Command used: `wrk -t4 -c100 -d30s http://127.0.0.1:8080/`
-
-Benchmarks are machine- and thermal-state-dependent, so treat these as local baselines, not universal claims. Axum and Actix were rerun with minimal temporary hello-world servers using the same `wrk` command.
-
-
-## 📦 Installation
-
-Add **Tako** to your `Cargo.toml`:
+- **One service, many transports** — REST, WebSockets, SSE, gRPC, raw TCP/UDP, Unix sockets, and QUIC without switching frameworks.
+- **One model, two runtimes** — the same framework style on **Tokio** or **Compio**, TLS and HTTP/2 on both.
+- **Batteries included** — middleware, auth, metrics, signals, queues, graceful shutdown, and streaming are part of the framework, not an afterthought.
+- **Performance when it matters** — SIMD JSON, optional zero-copy extractors, brotli/gzip/deflate/zstd, jemalloc, and HTTP/3 — without fragmenting the API.
+
+## At a glance
+
+- **Transports** — HTTP/1.1, HTTP/2, HTTP/3 (QUIC), WebSocket, WebTransport, SSE, gRPC, TCP, UDP, Unix sockets, PROXY protocol.
+- **Extraction** — 22+ typed extractors: JSON (SIMD optional), form, query, path, headers, cookies, JWT claims, API keys, Accept, Range, protobuf, multipart.
+- **Middleware** — JWT/Basic/Bearer/API-key auth, CSRF, sessions, security headers, request IDs, body limits, rate limiting, CORS, idempotency, compression, metrics.
+
+The full transport matrix, extractor catalog, middleware reference, and cargo
+feature graph live in the [documentation](https://tako.rust-dd.com).
+
+## Installation
 
 ```toml
 [dependencies]
 tako-rs = "2"
 ```
 
+MSRV 1.95 · Edition 2024
 
-## 🚀 Quick Start
-
-Spin up a "Hello, World!" server in a handful of lines:
+## Quick Start
 
 ```rust
 use anyhow::Result;
@@ -199,23 +52,41 @@ async fn hello_world(_: Request) -> impl Responder {
 
 #[tokio::main]
 async fn main() -> Result<()> {
-    // Bind a local TCP listener
     let listener = TcpListener::bind("127.0.0.1:8080").await?;
 
-    // Declare routes
     let mut router = Router::new();
     router.route(Method::GET, "/", hello_world);
 
-    // Launch the server
     tako::serve(listener, router).await;
-
     Ok(())
 }
 ```
 
-## 📜 License
+Keep going with the [Quickstart guide](https://tako.rust-dd.com/docs/getting-started/quickstart).
+
+## In Production
+
+Tako already powers real-world services:
+
+- `stochastic-api` — https://stochasticlab.cloud/
+- `shrtn.ink` — https://app.shrtn.ink/
+
+## Benchmark
+
+Hello-world throughput on a clean local run (`wrk -t4 -c100 -d30s`):
+
+| Framework | Requests/sec | Avg Latency |
+| --- | ---: | ---: |
+| Tako | ~187,288 | ~505 µs |
+| Tako + `jemalloc` | ~187,638 | ~502 µs |
+| Axum | ~186,194 | ~498 µs |
+| Actix | ~155,307 | ~635 µs |
+
+Machine- and thermal-state-dependent — treat as local baselines, not universal
+claims. Details on the [benchmarks page](https://tako.rust-dd.com/docs/benchmarks).
 
-`MIT` — see [LICENSE](./LICENSE) for details.
+## License
 
+`MIT` — see [LICENSE](./LICENSE).
 
 Made with ❤️ & 🦀 by the Tako contributors.
diff --git a/website/content/docs/middleware/metrics.mdx b/website/content/docs/middleware/metrics.mdx
@@ -66,7 +66,7 @@ meter_provider.shutdown()?;
 
 `with_meter_name(name)` sets the meter name (default `"tako"`).
 
-<RustExample path="examples/metrics-opentelemetry" />
+<RustExample path="examples/metrics-opentelemetry/src/main.rs" />
 
 <Callout type="info">
   Both backends depend on the signal system, so the metrics features enable
@@ -140,7 +140,7 @@ let pct = req
   .unwrap_or(0);
 ```
 
-<RustExample path="examples/upload-progress" />
+<RustExample path="examples/upload-progress/src/main.rs" />
 
 See the [middleware model](/docs/middleware) for chain ordering and
 [Observability](/docs/observability) for signals, tracing, and the broader
diff --git a/website/content/docs/streams.mdx b/website/content/docs/streams.mdx
@@ -97,7 +97,7 @@ precompressed sidecars (`<file>.br`, `<file>.gz`) when present.
 `tako::r#static::ServeDirBuilder` mounts a directory with SPA
 fallback (`fallback("/index.html")`) and traversal hardening.
 
-<RustExample path="examples/file-stream" />
+<RustExample path="examples/file-stream/src/main.rs" />
 
 ## WebTransport
 
diff --git a/website/scripts/docs-audit.ts b/website/scripts/docs-audit.ts
@@ -93,11 +93,15 @@ for (const file of walk(ROOT)) {
   let m: RegExpExecArray | null;
   while ((m = rustExampleRe.exec(src)) !== null) {
     const target = join(WORKSPACE, m[1]);
+    let isFile = false;
     try {
-      statSync(target);
+      isFile = statSync(target).isFile();
     } catch {
+      isFile = false;
+    }
+    if (!isFile) {
       errors++;
-      console.error(`✘ ${rel}: RustExample path "${m[1]}" does not exist`);
+      console.error(`✘ ${rel}: RustExample path "${m[1]}" is not a file`);
     }
   }
   rustExampleRe.lastIndex = 0;
