celeris

module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 9, 2026 License: Apache-2.0

README

celeris

CI Go Reference Go Report Card License

Ultra-low latency Go HTTP engine with a protocol-aware dual-architecture (io_uring & epoll) designed for high-throughput infrastructure and zero-allocation microservices.

Features

  • Tiered io_uring — auto-selects the best io_uring feature set (multishot accept, provided buffers, SQ poll) for your kernel
  • Edge-triggered epoll — per-core event loops with CPU pinning
  • Adaptive meta-engine — dynamically switches between io_uring and epoll based on runtime telemetry
  • Overload manager — 5-stage degradation ladder (expand → reap → reorder → backpressure → reject)
  • SIMD HTTP parser — SSE2 (amd64) and NEON (arm64) with generic SWAR fallback
  • HTTP/2 cleartext (h2c) — full stream multiplexing, flow control, HPACK
  • Auto-detect — protocol negotiation from the first bytes on the wire

Architecture

block-beta
  columns 3
  A["celeris (public API)"]:3
  B["adaptive"]:1 C["overload"]:1 D["observe"]:1
  E["engine/iouring"]:1 F["engine/epoll"]:1 G["engine/std"]:1
  H["protocol/h1"]:1 I["protocol/h2"]:1 J["protocol/detect"]:1
  K["probe"]:1 L["resource"]:1 M["internal"]:1

Quick Start

go get github.com/goceleris/celeris@latest

Requires Go 1.26+. Linux for io_uring/epoll engines; any OS for the std engine.

Hello World

package main

import (
	"context"
	"log"
	"os/signal"
	"syscall"

	"github.com/goceleris/celeris/engine/std"
	"github.com/goceleris/celeris/protocol/h2/stream"
	"github.com/goceleris/celeris/resource"
)

func main() {
	handler := stream.HandlerFunc(func(ctx context.Context, s *stream.Stream) error {
		return s.ResponseWriter.WriteResponse(s, 200, [][2]string{
			{"content-type", "text/plain"},
		}, []byte("Hello, World!"))
	})

	cfg := resource.Config{Addr: ":8080"}
	e, err := std.New(cfg, handler)
	if err != nil {
		log.Fatal(err)
	}

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()

	if err := e.Listen(ctx); err != nil {
		log.Fatal(err)
	}
}

Engine Selection

Engine Platform Use Case
io_uring Linux 5.10+ Lowest latency, highest throughput
epoll Linux Broad kernel support, proven stability
adaptive Linux Auto-switch based on telemetry
std Any OS Development, compatibility, non-Linux deploys

Performance Profiles

Profile Optimizes For Key Tuning
LatencyOptimized P99 tail latency TCP_NODELAY, small batches, SO_BUSY_POLL
ThroughputOptimized Max RPS Large CQ batches, write batching
Balanced Mixed workloads Default settings

Feature Matrix

Feature io_uring epoll std
HTTP/1.1 yes yes yes
H2C yes yes yes
Auto-detect yes yes yes
CPU pinning yes yes no
Provided buffers yes (5.19+) no no
Multishot accept yes (5.19+) no no
Overload shedding yes yes partial

Requirements

  • Go 1.26+
  • Linux for io_uring and epoll engines
  • Any OS for the std engine
  • Dependencies: golang.org/x/sys, golang.org/x/net

Project Structure

adaptive/       Adaptive meta-engine (Linux)
engine/         Engine interface + implementations (iouring, epoll, std)
internal/       Shared internals (conn, cpumon, platform, sockopts)
observe/        Observability (planned)
overload/       Overload manager with 5-stage degradation
probe/          System capability detection
protocol/       Protocol parsers (h1, h2, detect)
resource/       Configuration, presets, objectives
test/           Conformance, spec compliance, integration, benchmarks

Contributing

go run mage.go build   # build all targets
go run mage.go test    # run tests
go run mage.go lint    # run linters
go run mage.go bench   # run benchmarks

Pull requests should target main.

License

Apache License 2.0

Directories

Path Synopsis
Package adaptive implements a dual-engine controller that dynamically switches between io_uring and epoll based on runtime telemetry.
 Package adaptive implements a dual-engine controller that dynamically switches between io_uring and epoll based on runtime telemetry.
Package engine defines the core Engine interface and types.
 Package engine defines the core Engine interface and types.
epoll
Package epoll implements the epoll-based I/O engine for Linux.
 Package epoll implements the epoll-based I/O engine for Linux.
iouring
Package iouring implements an engine backed by Linux io_uring.
 Package iouring implements an engine backed by Linux io_uring.
std
Package std provides an engine implementation backed by net/http.
 Package std provides an engine implementation backed by net/http.
Package internal contains shared utilities.
 Package internal contains shared utilities.
conn
Package conn provides shared HTTP/1.1 and HTTP/2 connection handling.
 Package conn provides shared HTTP/1.1 and HTTP/2 connection handling.
cpumon
Package cpumon provides CPU utilization monitoring with platform-specific implementations.
 Package cpumon provides CPU utilization monitoring with platform-specific implementations.
platform
Package platform provides OS-level helpers for CPU pinning and NUMA distribution.
 Package platform provides OS-level helpers for CPU pinning and NUMA distribution.
sockopts
Package sockopts provides socket option helpers for TCP tuning across platforms.
 Package sockopts provides socket option helpers for TCP tuning across platforms.
middleware
compress module
metrics module
otel module
Package observe provides metrics collection and diagnostics.
 Package observe provides metrics collection and diagnostics.
Package overload implements a 5-stage degradation ladder for backpressure and load shedding.
 Package overload implements a 5-stage degradation ladder for backpressure and load shedding.
Package probe provides capability detection for io_uring and epoll.
 Package probe provides capability detection for io_uring and epoll.
protocol
detect
Package detect provides HTTP protocol detection from initial connection bytes.
 Package detect provides HTTP protocol detection from initial connection bytes.
h1
Package h1 implements a zero-copy HTTP/1.1 parser.
 Package h1 implements a zero-copy HTTP/1.1 parser.
h2
Package h2 provides HTTP/2 frame handling and stream management.
 Package h2 provides HTTP/2 frame handling and stream management.
h2/frame
Package frame provides HTTP/2 frame type definitions, parsing, writing, and HPACK integration.
 Package frame provides HTTP/2 frame type definitions, parsing, writing, and HPACK integration.
h2/stream
Package stream manages HTTP/2 stream lifecycle, state transitions, flow control, and frame processing.
 Package stream manages HTTP/2 stream lifecycle, state transitions, flow control, and frame processing.
Package resource defines configuration presets and performance profiles.
 Package resource defines configuration presets and performance profiles.
test
benchmark
conformance

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.