Toron Documentation Wiki (v1.5.32 Milestone)

Welcome to the Toron Web Server documentation wiki. Toron is an event-driven, high-performance, zero-dependency web server, reverse proxy gateway, and edge security engine written in pure Go.

Toron at a Glance

তোরণ (to-ron) means gateway in Bengali.

Toron is an event-driven, high-performance web server, reverse proxy, API gateway, and edge security engine written in Go.

• Project: GitHub repository
• Benchmarks: Comparative benchmark suite
• Comparisons: Toron vs NGINX, HAProxy, Traefik and Caddy
• Contact: sayantan.somu@gmail.com

Wiki Navigation

🚀 Getting Started & Operations

• Getting Started – Quickstart guide for building and running Toron.
• Universal Installer & Service Manager – Auto-installer script (install.sh), systemd (Linux) & launchd (macOS) service setup.
• Docker Containerization Guide – Multi-stage Dockerfile packaging, image creation, and Docker Compose configuration.
• Configuration Guide – Dual-file YAML configuration guide (config.yaml & routes.yaml).

⚙️ Core Architecture & Protocols

• Inbound Chunked Ingestion & Edge Normalization – Native HTTP/1.1 chunked request ingestion, zero-tolerance wire decoding (RFC 9112 §7.1), Active Ingress Smuggling Firewall, and upstream Content-Length re-framing.
• Event Reactor Core – Event-driven concurrency, explicit TCP_NODELAY tuning, adaptive deadline amortization, and worker pool.
• HTTP/2 Engine – Cleartext h2c prior-knowledge and stream multiplexing.
• HTTP/3 QUIC Protocol Engine – HTTP/3 over QUIC (UDP), concurrent listener, and Alt-Svc upgrade advertising.
• HTTPS TLS & Auto Dev Certs – TLS 1.2/1.3 encryption and ECDSA dev certificate generation.
• ACME Zero-Touch Production SSL & Protocol Hardening – Automated Let’s Encrypt SSL issuance, HTTP-01 & TLS-ALPN-01 challenge responders, and RFC 8555 token validation.
• WebSocket Tunneling – RFC 6455 and RFC 8441 Extended CONNECT bi-directional stream tunneling.
• Static File Serving – Hosting web apps, MIME resolution, and directory index handling.

🌐 Routing, Proxying & Resilience

• Layer 4 TCP & UDP Transport Proxies – Raw stream and datagram proxying with bounded concurrency, buffer recycling, and Slowloris idle deadline protection.
• REST-to-gRPC Transcoding Engine – Direct JSON REST to binary Protobuf gRPC RPC transcoding, bounded request limits (HTTP 413), hop-by-hop header sanitization, and direct parameterized subpath dispatch.
• Service Mesh Sidecar Mode – Lightweight pod-to-pod mTLS, bounded request body limits (HTTP 413), and weighted traffic splitting.
• Native Kubernetes Ingress Controller – Zero-dependency Kubernetes networking.k8s.io/v1 Ingress Controller.
• OCI Container Auto-Discovery – Vendor-agnostic Docker & Podman Unix socket container auto-discovery.
• Reverse Proxy & Gateway Routing – Upstream request forwarding, zero-allocation response serialization, proxy headers, configurable transport, and distributed tracing (REQ-123, REQ-127).
• gRPC Edge Gateway & Health Probing – Native grpc.health.v1 probing and HTTP/2 trailers preservation.
• Advanced Load Balancing Engine – 8 strategies: round-robin, weighted, least conn, least latency, sticky cookie, and IP hash.
• Circuit Breaker & Health Checks – 3-state circuit breaker and active upstream health probing.
• Header-Based HTTP Routing – API versioning and conditional header routing.
• Domain-Based Virtual Host Routing – Multi-tenant host header dispatching.

🛡️ Traffic Control, Performance & Security

• Layered Path Traversal Defense – Route-aware prefix boundary protection, WAF raw wire URI inspection, and fail-fast transport socket teardown (CWE-22).
• Web Application Firewall (WAF) & Injection Protection – OWASP Top 10 SQLi, XSS, Path Traversal, and RCE threat mitigation.
• CORS Policies & Enterprise Security Headers – Preflight OPTIONS handling, origin matching, and OWASP security headers.
• Transparent Response Compression – Streaming Zstd, Brotli, Gzip & Deflate response compression.
• In-Memory Response Caching – RFC 9111 HTTP response caching, Shared Cache Session Boundary Isolation, Host:Port authority derivation, cross-port cache isolation (CWE-524), dual-stage Set-Cookie purging (CWE-384), and Web Cache Deception Shared Responsibility Model (REQ-134 / TASK-157).
• Multi-Scheme Authentication – JWT (HS256), API Key, and HTTP Basic authentication.
• Native Go Benchmarking – Performance benchmarks and allocation metrics.
• High-Concurrency Saturation Stress Benchmark & Status Classification – Dual-stream saturation testing, four-tier status classification taxonomy, and Table 6 metrics (BMK-04, HARN-01).
• Heterogeneous Multi-Hop Origin Testbed – Dual-mode (standalone & Docker Compose) evaluation across Node.js (llhttp), Python (uvicorn/h11), and Go (net/http) origins, wire-level protocol adapters, and zero-desync canary validation (BMK-03, REQ-120).
• Multi-Proxy Differential Docker Benchmark – Automated comparative benchmarking comparing Toron against NGINX, Traefik, Caddy, and HAProxy fronting identical heterogeneous upstreams (REQ-121, REQ-122).
• Protocol Invariant Regression Suite & Generative Fuzzing Engine – Wire-level rejection latency profiling (Equation 7, K=1,000) and coverage-guided generative differential fuzzing against Go standard library (REQ-118, REQ-132).
• Dummy Microservices Suite – Cluster of 10 test microservices.

📖 References

• CLI Reference – Command-line interface options and usage flags.
• Configuration Options Reference – Complete reference for YAML configuration settings.
• HTTP API Reference – Built-in health, metrics, and internal management endpoints.

💡 Help & Support

• Troubleshooting Guide – Common runtime issues and solutions.
• Frequently Asked Questions (FAQ) – Common questions about Toron.
• Release Notes – Changelog and release milestones (v1.0.0–v1.5.32).