{"id":42216757,"url":"https://github.com/goceleris/celeris","last_synced_at":"2026-05-24T15:01:34.328Z","repository":{"id":331785173,"uuid":"1126711787","full_name":"goceleris/celeris","owner":"goceleris","description":"Ultra-low latency Go HTTP engine. A protocol-aware dual-architecture (io_uring \u0026 epoll) designed for high-throughput infrastructure and zero-allocation microservices.","archived":false,"fork":false,"pushed_at":"2026-05-19T23:20:01.000Z","size":2047,"stargazers_count":1,"open_issues_count":9,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-20T02:34:30.316Z","etag":null,"topics":["epoll","go","http-server","io-uring","linux","performance","zero-copy"],"latest_commit_sha":null,"homepage":"https://goceleris.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goceleris.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T12:48:35.000Z","updated_at":"2026-05-19T23:19:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/goceleris/celeris","commit_stats":null,"previous_names":["goceleris/celeris"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/goceleris/celeris","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goceleris%2Fceleris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goceleris%2Fceleris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goceleris%2Fceleris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goceleris%2Fceleris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goceleris","download_url":"https://codeload.github.com/goceleris/celeris/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goceleris%2Fceleris/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33438518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T13:13:05.286Z","status":"ssl_error","status_checked_at":"2026-05-24T13:13:03.728Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["epoll","go","http-server","io-uring","linux","performance","zero-copy"],"created_at":"2026-01-27T01:15:47.133Z","updated_at":"2026-05-24T15:01:34.307Z","avatar_url":"https://github.com/goceleris.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# celeris\n\n[![CI](https://github.com/goceleris/celeris/actions/workflows/ci.yml/badge.svg)](https://github.com/goceleris/celeris/actions/workflows/ci.yml)\n[![Nightly Validation](https://github.com/goceleris/probatorium/actions/workflows/matrix-nightly-tier.yml/badge.svg?branch=main)](https://github.com/goceleris/probatorium/actions/workflows/matrix-nightly-tier.yml?query=branch%3Amain)\n[![Weekend Soak](https://github.com/goceleris/probatorium/actions/workflows/matrix-weekend-tier.yml/badge.svg?branch=main)](https://github.com/goceleris/probatorium/actions/workflows/matrix-weekend-tier.yml?query=branch%3Amain)\n[![Go Reference](https://pkg.go.dev/badge/github.com/goceleris/celeris.svg)](https://pkg.go.dev/github.com/goceleris/celeris)\n[![Go Report Card](https://goreportcard.com/badge/github.com/goceleris/celeris)](https://goreportcard.com/report/github.com/goceleris/celeris)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\nUltra-low latency Go HTTP engine with a protocol-aware dual-architecture (io_uring \u0026 epoll) designed for high-throughput infrastructure and zero-allocation microservices. It provides a familiar route-group and middleware API similar to Gin and Echo, so teams can adopt it without learning a new programming model.\n\n## Highlights\n\n- **io_uring and epoll at parity** — both engines deliver equivalent throughput\n- **Zero hot-path allocations** for both H1 and H2\n- **Designed for throughput** — see [benchmarks](https://goceleris.dev/benchmarks) for current numbers\n\n## Features\n\n- **Tiered io_uring** — auto-selects the best io_uring feature set (multishot accept/recv, provided buffers, SQ poll, fixed files) for your kernel\n- **Edge-triggered epoll** — per-core event loops with CPU pinning\n- **Adaptive meta-engine** — dynamically switches between io_uring and epoll based on runtime telemetry\n- **SIMD HTTP parser** — SSE2 (amd64) and NEON (arm64) with generic SWAR fallback\n- **HTTP/2 cleartext (h2c)** — full stream multiplexing, flow control, HPACK, inline handler execution, zero-alloc HEADERS fast path\n- **Auto-detect** — protocol negotiation from the first bytes on the wire\n- **Error-returning handlers** — `HandlerFunc` returns `error`; structured `HTTPError` for status codes\n- **Pre-routing middleware** — `Server.Pre()` runs middleware before route matching (method override, URL rewrite)\n- **Serialization** — JSON and XML response methods; `Bind` auto-detects request format from Content-Type\n- **net/http compatibility** — wrap existing `http.Handler` via `celeris.Adapt()`\n- **Streaming responses** — `Detach()` + `StreamWriter` for SSE and chunked responses on native engines\n- **Connection hijacking** — `Hijack()` for WebSocket and custom protocol upgrades (H1 only)\n- **Response buffering** — `BufferResponse`/`FlushResponse` for transform middleware (compress, ETag, cache)\n- **File serving** — `File()` from OS, `FileFromFS()` from `embed.FS` / `fs.FS`\n- **Content negotiation** — `Negotiate`, `Respond`, `AcceptsEncodings`, `AcceptsLanguages`\n- **Configurable body limits** — `MaxRequestBodySize` enforced across H1, H2, and the bridge\n- **100-continue control** — `OnExpectContinue` callback for upload validation before body transfer\n- **Accept control** — `PauseAccept()`/`ResumeAccept()` for graceful load shedding\n- **Zero-downtime restart** — `InheritListener` + `StartWithListener` for socket inheritance\n- **Built-in metrics** — atomic counters, CPU utilization sampling, always-on `Server.Collector().Snapshot()`\n\n## Quick Start\n\n```\ngo get github.com/goceleris/celeris@latest\n```\n\nRequires **Go 1.26.3+**. Linux for io_uring/epoll engines; any OS for the std engine.\n\n## Hello World\n\n```go\npackage main\n\nimport (\n\t\"log\"\n\n\t\"github.com/goceleris/celeris\"\n)\n\nfunc main() {\n\ts := celeris.New(celeris.Config{Addr: \":8080\"})\n\ts.GET(\"/hello\", func(c *celeris.Context) error {\n\t\treturn c.String(200, \"Hello, World!\")\n\t})\n\tlog.Fatal(s.Start())\n}\n```\n\n## Routing\n\n```go\ns := celeris.New(celeris.Config{Addr: \":8080\"})\n\n// Static routes\ns.GET(\"/health\", healthHandler)\n\n// Named parameters\ns.GET(\"/users/:id\", func(c *celeris.Context) error {\n\tid := c.Param(\"id\")\n\treturn c.JSON(200, map[string]string{\"id\": id})\n})\n\n// Catch-all wildcards\ns.GET(\"/files/*path\", staticFileHandler)\n\n// Route groups with middleware\napi := s.Group(\"/api\")\napi.Use(authMiddleware)\napi.GET(\"/items\", listItems)\napi.POST(\"/items\", createItem)\n\n// Named routes + reverse URL generation\ns.GET(\"/users/:id\", showUser).Name(\"user\")\nurl, _ := s.URL(\"user\", \"42\") // \"/users/42\"\n\n// Pre-routing middleware (runs before route matching)\ns.Pre(methodOverride, urlRewrite)\n```\n\n## Middleware\n\nAll middleware is in-tree under [`middleware/`](middleware/):\n\n| Package | Description |\n|---------|-------------|\n| [`adapters`](middleware/adapters) | Bidirectional stdlib ↔ celeris middleware/handler conversion |\n| [`basicauth`](middleware/basicauth) | HTTP Basic authentication with hashed password support |\n| [`bodylimit`](middleware/bodylimit) | Request body size enforcement |\n| [`cache`](middleware/cache) | HTTP response cache with singleflight + Cache-Control honoring |\n| [`circuitbreaker`](middleware/circuitbreaker) | Circuit breaker (3-state, sliding window error rate, 503 + Retry-After) |\n| [`compress`](middleware/compress) | Response compression (zstd, brotli, gzip; separate go.mod) |\n| [`cors`](middleware/cors) | Cross-Origin Resource Sharing (zero-alloc) |\n| [`csrf`](middleware/csrf) | CSRF protection (double-submit cookie + origin validation) |\n| [`debug`](middleware/debug) | Debug/introspection endpoints (loopback-only by default) |\n| [`etag`](middleware/etag) | Automatic ETag generation and conditional 304 responses |\n| [`healthcheck`](middleware/healthcheck) | Kubernetes-style liveness/readiness/startup probes |\n| [`idempotency`](middleware/idempotency) | Idempotency-Key replay protection (state machine: in-flight 409 + cached replay) |\n| [`jwt`](middleware/jwt) | JWT authentication (HMAC/RSA/ECDSA/EdDSA, JWKS auto-refresh) |\n| [`keyauth`](middleware/keyauth) | API key authentication with constant-time comparison |\n| [`logger`](middleware/logger) | Structured request logging (slog, zero-alloc FastHandler) |\n| [`methodoverride`](middleware/methodoverride) | HTTP method override via header or form field |\n| [`metrics`](middleware/metrics) | Prometheus metrics (separate go.mod) |\n| [`otel`](middleware/otel) | OpenTelemetry tracing + metrics (separate go.mod) |\n| [`overload`](middleware/overload) | 5-stage CPU + queue-depth + tail-latency-EMA overload control (503 + Retry-After) |\n| [`pprof`](middleware/pprof) | Go profiling endpoints (loopback-only by default) |\n| [`protobuf`](middleware/protobuf) | Protobuf serialization with content negotiation (separate go.mod) |\n| [`proxy`](middleware/proxy) | Trusted proxy header extraction (X-Forwarded-For, X-Real-IP) |\n| [`ratelimit`](middleware/ratelimit) | Sharded token bucket / sliding window rate limiter (Redis store adapter) |\n| [`recovery`](middleware/recovery) | Panic recovery with broken pipe detection |\n| [`redirect`](middleware/redirect) | URL redirect/rewrite (HTTPS, www, trailing slash) |\n| [`requestid`](middleware/requestid) | Request ID generation (buffered UUID v4) |\n| [`rewrite`](middleware/rewrite) | Regex-based URL rewriting with capture group support |\n| [`secure`](middleware/secure) | Security headers (HSTS, CSP, COOP/CORP/COEP, OWASP defaults) |\n| [`session`](middleware/session) | Cookie-based sessions on the unified [`store.KV`](middleware/store) (memory / Redis / Postgres / memcached adapters) |\n| [`singleflight`](middleware/singleflight) | Request coalescing (collapse identical in-flight requests) |\n| [`sse`](middleware/sse) | Server-Sent Events: heartbeat, Last-Event-ID resumption with pluggable replay store (in-memory ring buffer or KV-backed for cross-restart durability), per-client `MaxQueueDepth` + `OnSlowClient` policy (Drop/Close/Block), and a `Broker` for fan-out to N subscribers with per-subscriber bounded queues + `OnSlowSubscriber` policy (Drop/Remove/Close) |\n| [`static`](middleware/static) | Static file serving with directory browse, ETag/Last-Modified caching |\n| [`store`](middleware/store) | Unified `KV` interface + adapters (memory LRU, Redis, Postgres, memcached) shared by session / csrf / ratelimit / cache / idempotency / jwt JWKS |\n| [`swagger`](middleware/swagger) | OpenAPI spec + Swagger UI/Scalar (CDN-loaded) |\n| [`timeout`](middleware/timeout) | Request timeout with cooperative and preemptive modes |\n| [`websocket`](middleware/websocket) | RFC 6455 WebSocket: permessage-deflate, engine-integrated backpressure, plus a `Hub` for fan-out broadcast to N connections (via cached `PreparedMessage` for O(1) per-message wire-encoding cost) with `OnSlowConn` policy (Drop/Remove/Close) and per-Conn filter via `BroadcastFilter` |\n\n```go\nimport (\n\t\"github.com/goceleris/celeris/middleware/cors\"\n\t\"github.com/goceleris/celeris/middleware/logger\"\n\t\"github.com/goceleris/celeris/middleware/recovery\"\n)\n\ns := celeris.New(celeris.Config{Addr: \":8080\"})\ns.Use(recovery.New())\ns.Use(logger.New())\ns.Use(cors.New())\n```\n\nFor middleware with external dependencies, use separate imports:\n\n```go\nimport \"github.com/goceleris/celeris/middleware/metrics\" // requires prometheus\nimport \"github.com/goceleris/celeris/middleware/otel\"    // requires opentelemetry\n```\n\n## Error Handling\n\n`HandlerFunc` has the signature `func(*Context) error`. Returning a non-nil error propagates it up through the middleware chain. If no middleware handles the error, the router's safety net converts it to an HTTP response:\n\n- `*HTTPError` — responds with `Code` and `Message` from the error.\n- Any other `error` — responds with `500 Internal Server Error`.\n\n```go\n// Return a structured HTTP error\ns.GET(\"/item/:id\", func(c *celeris.Context) error {\n\titem, err := store.Find(c.Param(\"id\"))\n\tif err != nil {\n\t\treturn celeris.NewHTTPError(404, \"item not found\").WithError(err)\n\t}\n\treturn c.JSON(200, item)\n})\n\n// Use Status() + StatusJSON() for fluent responses\ns.POST(\"/items\", func(c *celeris.Context) error {\n\tvar item Item\n\tif err := c.Bind(\u0026item); err != nil {\n\t\treturn celeris.NewHTTPError(400, \"invalid body\").WithError(err)\n\t}\n\tcreated := store.Create(item)\n\treturn c.Status(201).StatusJSON(created)\n})\n```\n\n## Configuration\n\n```go\ns := celeris.New(celeris.Config{\n\tAddr:               \":8080\",\n\tProtocol:           celeris.Auto,       // HTTP1, H2C, or Auto\n\tEngine:             celeris.Adaptive,    // IOUring, Epoll, Adaptive, or Std\n\tWorkers:            8,\n\tReadTimeout:        30 * time.Second,\n\tWriteTimeout:       30 * time.Second,\n\tIdleTimeout:        120 * time.Second,\n\tShutdownTimeout:    10 * time.Second,    // max wait for in-flight requests (default 30s)\n\tMaxRequestBodySize: 50 \u003c\u003c 20,            // 50 MB (default 100 MB, -1 for unlimited)\n\tLogger:             slog.Default(),\n})\n```\n\n## net/http Compatibility\n\nWrap existing `net/http` handlers and middleware:\n\n```go\n// Wrap http.Handler\ns.GET(\"/legacy\", celeris.Adapt(legacyHandler))\n\n// Wrap http.HandlerFunc\ns.GET(\"/func\", celeris.AdaptFunc(func(w http.ResponseWriter, r *http.Request) {\n\tw.Write([]byte(\"from stdlib\"))\n}))\n```\n\nThe bridge buffers the adapted handler's response in memory, capped at `MaxRequestBodySize` (default 100 MB). Responses exceeding this limit return an error.\n\n## Engine Selection\n\n| Engine | Platform | Use Case |\n|--------|----------|----------|\n| `IOUring` | Linux 5.10+ | Lowest latency, highest throughput |\n| `Epoll` | Linux | Broad kernel support, proven stability |\n| `Adaptive` | Linux | Auto-switch based on telemetry |\n| `Std` | Any OS | Development, compatibility, non-Linux deploys |\n\nUse Adaptive (the default on Linux) unless you have a specific reason to pin an engine. On non-Linux platforms, only Std is available.\n\n## Graceful Shutdown\n\nUse `StartWithContext` for production deployments. When the context is canceled, the server drains in-flight requests up to `ShutdownTimeout` (default 30s).\n\n```go\nctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)\ndefer stop()\n\ns := celeris.New(celeris.Config{\n\tAddr:            \":8080\",\n\tShutdownTimeout: 15 * time.Second,\n})\ns.GET(\"/hello\", helloHandler)\n\nif err := s.StartWithContext(ctx); err != nil {\n\tlog.Fatal(err)\n}\n```\n\n## Observability\n\nThe core provides a lightweight metrics collector accessible via `Server.Collector()`:\n\n```go\nsnap := server.Collector().Snapshot()\nfmt.Println(snap.RequestsTotal, snap.ErrorsTotal, snap.ActiveConns, snap.CPUUtilization)\n```\n\nFor Prometheus exposition and debug endpoints, use the [`middleware/metrics`](middleware/metrics) and [`middleware/debug`](middleware/debug) packages. For OpenTelemetry, use [`middleware/otel`](middleware/otel).\n\n## Feature Matrix\n\n| Feature | io_uring | epoll | std |\n|---------|----------|-------|-----|\n| HTTP/1.1 | yes | yes | yes |\n| H2C | yes | yes | yes |\n| Auto-detect | yes | yes | yes |\n| CPU pinning | yes | yes | no |\n| Provided buffers | yes (5.19+) | no | no |\n| Multishot accept | yes (5.19+) | no | no |\n| Multishot recv | yes (6.0+) | no | no |\n| Zero-alloc HEADERS | yes | yes | no |\n| Inline H2 handlers | yes | yes | no |\n| Detach / StreamWriter | yes | yes | yes |\n| Connection hijack | yes | yes | yes |\n\n## Benchmarks\n\nFor current benchmark results and methodology, see [goceleris.dev/benchmarks](https://goceleris.dev/benchmarks).\n\nCross-framework performance benchmarks live in [`test/perfmatrix/`](test/perfmatrix/) — a (scenario × server × protocol) matrix driven by `loadgen`. Run the full sweep with `mage matrixBench` or the dev-loop subset with `mage matrixBenchQuick`. Driver-isolation benchmarks remain in [`test/drivercmp/`](test/drivercmp/) and WebSocket comparisons in [`test/benchcmp_ws/`](test/benchcmp_ws/).\n\n\u003e **Note:** In-tree middleware benchmarks (e.g., `middleware/compress/bench_test.go`) use `celeristest` which provides pool-based contexts with no HTTP overhead. These numbers measure pure middleware logic and should not be compared directly with `httptest`-based competitor benchmarks. Use `test/perfmatrix/` for fair cross-framework comparisons.\n\n## Project Structure\n\n```\nadaptive/       Adaptive meta-engine (Linux)\nceleristest/    Test helpers (NewContext, ResponseRecorder)\nengine/         Engine interface + implementations (iouring, epoll, std)\ninternal/       Shared internals (conn, cpumon, ctxkit, negotiate, platform, sockopts)\nmiddleware/     In-tree middleware ecosystem (29 packages)\nobserve/        Metrics collector, CPUMonitor, Snapshot\nprobe/          System capability detection\nprotocol/       Protocol parsers (h1, h2, detect)\nresource/       Configuration, presets, defaults\ntest/           Conformance, spec compliance, integration, benchmarks\n```\n\n## Requirements\n\n- **Go 1.26.3+**\n- **Linux** for io_uring and epoll engines\n- **Any OS** for the std engine\n- Dependencies: `golang.org/x/sys`, `golang.org/x/net`\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull request guidelines.\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoceleris%2Fceleris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoceleris%2Fceleris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoceleris%2Fceleris/lists"}