# Tako

> Tako is a multi-transport Rust web framework: HTTP/1.1, HTTP/2, HTTP/3, WebTransport, WebSocket, SSE, gRPC, TCP, UDP and Unix sockets behind one router, on Tokio or Compio.

Key facts for writing Tako code:

- The crates.io package is `tako-rs`; the library is imported as `tako` (`use tako::...`). The crate named `tako` on crates.io is an unrelated project, so never depend on it.
- Install with `cargo add tako-rs` (`tako-rs = "2.4"`). Tako requires Rust 1.95 or newer and edition 2024.
- Default features give Tokio with HTTP/1.1, raw TCP, Unix sockets, static files, and the core extractors and middleware. HTTP/2, HTTP/3, TLS, WebSocket (`ws`), SSE (`sse`), UDP, gRPC, and the bundled plugins are opt-in Cargo features.
- Start servers with `Server::builder().build().try_spawn_http(listener, router)?`; the `serve_*` free functions are deprecated. The `compio` feature switches to `CompioServer`; every transport runs on both runtimes.
- Tako has no outbound HTTP client (`tako::client` was removed in 2.3.0); use `reqwest` or `ureq`.
- Every docs page is available as Markdown by appending `.mdx` to its URL.

## Overview

- [Introduction](https://tako.rust-dd.com/docs.mdx): A multi-transport Rust framework for HTTP, WebSocket, SSE, gRPC, HTTP/3, and raw sockets behind one routing, middleware, and observability model.

## Start here

- Getting started
  - [Installation](https://tako.rust-dd.com/docs/getting-started/installation.mdx): Add tako-rs to a Cargo project, pick the Tokio or Compio runtime, and opt into the feature flags your service needs.
  - [Quickstart](https://tako.rust-dd.com/docs/getting-started/quickstart.mdx): Add the tako-rs dependency, write a handler, register a GET route on Router, and start it with Server::builder and a TcpListener.
  - [Coming from Axum](https://tako.rust-dd.com/docs/getting-started/coming-from-axum.mdx): Map Axum routers, extractors, state, middleware, serving, and tests to their Tako equivalents, with the differences that matter when porting.
  - [Using Tako with AI assistants](https://tako.rust-dd.com/docs/getting-started/ai-assistants.mdx): Point coding agents at Tako's llms.txt, Markdown docs, and Context7 index, and give them project rules so they write current Tako 2.x code.
  - [Project layout](https://tako.rust-dd.com/docs/getting-started/project-layout.mdx): The eight-crate tako workspace — what the tako-rs umbrella re-exports and which sub-crate owns each part of the framework.
- Concepts
  - [Architecture](https://tako.rust-dd.com/docs/concepts/architecture.mdx): The big picture of tako — Router, handlers, extractors, middleware, and responders in the core, with the server crate driving transports.
  - [Request lifecycle](https://tako.rust-dd.com/docs/concepts/request-lifecycle.mdx): Trace a request through tako end to end — listener, server, Router match, middleware chain, extractors, handler, and Responder.
  - [Runtimes](https://tako.rust-dd.com/docs/concepts/runtimes.mdx): Tako's dual-runtime model — Tokio vs Compio, which transports each supports, TLS and HTTP/2 coverage, and how to switch.
  - [Design philosophy](https://tako.rust-dd.com/docs/concepts/design-philosophy.mdx): The principles behind tako — one service many transports, one model two runtimes, primitives included, and performance knobs when they matter.
  - [Tako vs Axum vs Actix Web](https://tako.rust-dd.com/docs/concepts/comparison.mdx): How Tako compares with Axum and Actix Web on transports, runtimes, bundled middleware, ecosystem, and throughput, and when to pick each one.

## Transports

- [Transports](https://tako.rust-dd.com/docs/transports.mdx): Every Tako transport — HTTP, HTTP/3, WebSocket, WebTransport, SSE, gRPC, raw sockets, and PROXY protocol — with runtime and feature-flag support.
- [HTTP](https://tako.rust-dd.com/docs/transports/http.mdx): Serve HTTP/1.1, HTTP/2 cleartext (h2c), and HTTP/2 over TLS with ALPN negotiation on either runtime.
- [HTTP/3](https://tako.rust-dd.com/docs/transports/http3.mdx): Serve HTTP/3 over QUIC on Tokio (quinn) or Compio (compio-quic) with mandatory TLS, congestion control, and stream caps.
- [WebSocket](https://tako.rust-dd.com/docs/transports/websocket.mdx): Upgrade an HTTP request to a WebSocket inside a handler, then run the send/receive message loop on either runtime.
- [WebTransport](https://tako.rust-dd.com/docs/transports/webtransport.mdx): Browser-compatible W3C WebTransport over HTTP/3 on Tokio or Compio, routed through the Router, plus a raw QUIC session helper on Tokio.
- [Server-Sent Events](https://tako.rust-dd.com/docs/transports/sse.mdx): Stream text/event-stream responses from any HTTP handler with the Sse responder, structured events, and proxy-safe keep-alive.
- [gRPC](https://tako.rust-dd.com/docs/transports/grpc.mdx): Serve unary, server-streaming, client-streaming, and bidirectional gRPC over HTTP/2 on ordinary Tako routes, on Tokio or Compio.
- [TCP, UDP & Unix sockets](https://tako.rust-dd.com/docs/transports/tcp-udp-unix.mdx): Drop below HTTP to handle raw TCP streams, UDP datagrams, and Unix-domain-socket connections with a per-connection async handler.
- [PROXY protocol](https://tako.rust-dd.com/docs/transports/proxy-protocol.mdx): Recover the real client address behind an L4 load balancer by parsing PROXY protocol v1/v2 headers into request extensions.

## Request handling

- [Routing](https://tako.rust-dd.com/docs/routing.mdx): Map (method, path) pairs to handlers, run middleware, nest sub-routers, and emit method-aware responses with Tako's Router.
- [State](https://tako.rust-dd.com/docs/state.mdx): Share database pools, configuration, and handles with handlers via per-router State<T> or process-global state in Tako.
- Extractors
  - [Extractors](https://tako.rust-dd.com/docs/extractors.mdx): Typed handler arguments that read shape out of a request — JSON, form, query, path, headers, cookies, JWT, and more.
  - [Body extractors](https://tako.rust-dd.com/docs/extractors/body.mdx): Read and deserialize request bodies — Json, Form, raw Bytes, Protobuf, SIMD JSON, and multipart uploads.
  - [Request metadata extractors](https://tako.rust-dd.com/docs/extractors/request-meta.mdx): Read URL, path, header, and connection metadata — Query, Path, Params, HeaderMap, Accept, AcceptLanguage, Range, and IpAddr.
  - [Auth extractors](https://tako.rust-dd.com/docs/extractors/auth.mdx): Pull credentials and identity from a request — Basic, Bearer, ApiKey, and unverified vs verified JWT claims.
  - [Cookie extractors](https://tako.rust-dd.com/docs/extractors/cookies.mdx): Read and write request cookies — plain CookieJar, HMAC-signed CookieSigned, and encrypted CookiePrivate, with key rotation.
- Middleware
  - [Middleware](https://tako.rust-dd.com/docs/middleware.mdx): How Tako's middleware model works — registering the chain, ordering, and the full catalog of bundled middleware.
  - [Authentication](https://tako.rust-dd.com/docs/middleware/auth.mdx): JWT, Basic, Bearer, and API-key authentication middleware for Tako routes.
  - [Security](https://tako.rust-dd.com/docs/middleware/security.mdx): CSRF protection, security response headers, body-size limits, and cookie sessions for Tako.
  - [Traffic](https://tako.rust-dd.com/docs/middleware/traffic.mdx): Rate limiting, CORS, response compression, and idempotency-key de-duplication for Tako.
  - [Metrics & Observability](https://tako.rust-dd.com/docs/middleware/metrics.mdx): Prometheus / OpenTelemetry metrics export, request-ID propagation, and upload-progress callbacks.
- [Plugins](https://tako.rust-dd.com/docs/plugins.mdx): The tako-rs-plugins crate — bundled middleware and plugins, the plugins feature flag, and how plugins differ from middleware.

## Primitives

- [Streams](https://tako.rust-dd.com/docs/streams.mdx): Server-Sent Events, WebSocket, ranged file streaming, and WebTransport over HTTP/3 in tako.
- [Queue](https://tako.rust-dd.com/docs/queue.mdx): In-process background job queue with retry, dead-lettering, deduplication, and delayed execution.
- [Signals](https://tako.rust-dd.com/docs/signals.mdx): Subscribe to application, router, and route events, observe listener shutdown, and use typed RPC with the in-process signal arbiter.
- [Observability](https://tako.rust-dd.com/docs/observability.mdx): Logs, metrics, traces, and health checks with swappable defaults for production deployments.

## Guides

- Tutorials
  - [Tutorials](https://tako.rust-dd.com/docs/tutorials.mdx): End-to-end, copy-along guides that build a complete tako service from a single example crate in the repository.
  - [Building a REST API](https://tako.rust-dd.com/docs/tutorials/rest-api.mdx): Build a small JSON REST API with path, query, and body extractors, shared state, a custom error type, and a middleware layer.
  - [Realtime over WebSocket](https://tako.rust-dd.com/docs/tutorials/realtime-chat.mdx): Build a full-duplex WebSocket feature with an echo handler and a server-push ticker, then compare it to the SSE alternative.
- [Deployment](https://tako.rust-dd.com/docs/deployment.mdx): The three tako deployment shapes — single binary, thread-per-core, and behind a load balancer — plus socket activation and graceful shutdown.
- [Benchmarks](https://tako.rust-dd.com/docs/benchmarks.mdx): Hello-world throughput of tako's two serving models against Axum, Actix Web, and ntex under loopback, server-bound, and pipelined load.

## Reference

- [Migrating to 2.4](https://tako.rust-dd.com/docs/reference/migration-2-4.mdx): Tako 2.4 needs no code changes; review the core pinning default, the coarser HTTP/1 header deadline, and the extractor ENTRIES list.
- [Migrating to 2.3](https://tako.rust-dd.com/docs/reference/migration-2-3.mdx): Replace the removed outbound HTTP client, review the WebTransport and gRPC changes, and use the Compio transports added in Tako 2.3.
- [Migrating to 2.2](https://tako.rust-dd.com/docs/reference/migration-2-2.mdx): Update PerThreadConfig literals for connection balancing and review the Tako 2.2 server performance changes.
- [Migrating to 2.1](https://tako.rust-dd.com/docs/reference/migration-2-1.mdx): Update handlers, middleware stores, transport features, cookies, static files, and server startup for the Tako 2.1 API.
- [Migrating from 1.x to 2.0](https://tako.rust-dd.com/docs/reference/migration.mdx): Every breaking change between the tako 1.x line on crates.io and the 2.0.0 release, with before/after code for each.
- [Cargo feature graph](https://tako.rust-dd.com/docs/reference/features.mdx): Every cargo feature on the tako-rs umbrella crate — transports, runtimes, plugins, extractors, observability, and runtime selection.
- [API reference](https://tako.rust-dd.com/docs/reference/api.mdx): The in-source rustdoc on docs.rs is the canonical per-item API reference for tako — here is the per-crate link list.
- [Contributing](https://tako.rust-dd.com/docs/contributing.mdx): How to build and test the tako workspace, the rustfmt/MSRV/edition conventions, the crate layout, and the crates.io publish flow.

## Optional

- [Full documentation](https://tako.rust-dd.com/llms-full.txt): every page above in one Markdown file
- [API reference](https://docs.rs/tako-rs/latest/tako/): rustdoc for the `tako` crate
- [Examples](https://github.com/rust-dd/tako/tree/main/examples): runnable example crates for every transport
- [Releases](https://github.com/rust-dd/tako/releases): changelog and migration notes