aoni

The Unified Internet Protocol Stack for Go

«In networks chaos is the default — let aoni be your ice cold anchor»

aoni is a network protocol stack and HTTP client for Go. It implements modern IETF RFC standards, W3C specifications, and Chromium network resilience mechanisms in a zero-allocation architecture.

English • Русский • Architecture Specification • Vortex Guide

Installation

aoni requires Go version 1.27 or higher.

go get github.com/lemon4ksan/aoni

Quickstart

Type-safe HTTP request with generic response deserialization:

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/lemon4ksan/aoni"
	"github.com/lemon4ksan/aoni/mod"
	"github.com/lemon4ksan/aoni/option"
)

type User struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
}

func main() {
	ctx := context.Background()

	// 1. Initialize client
	client := aoni.NewClient(nil,
		option.WithBaseURL("https://api.example.com"),
		option.WithTimeout(10*time.Second),
		option.WithMaxConnsPerHost(100),
	)

	// 2. Direct generic GET request
	user, err := client.GetTo[User](ctx, "/users/{id}",
		mod.WithVar("id", 42),
		mod.WithHeader("Accept", "application/json"),
	)
	if err != nil {
		panic(err)
	}

	fmt.Printf("User: %s (ID: %d)\n", user.Name, user.ID)
}

Client Usage Patterns

1. Generic Methods (`client.GetTo[T]`, `client.PostTo[T]`, etc.)

Request payloads and responses are serialized and deserialized automatically:

// GET request decoded into *User
user, err := client.GetTo[User](ctx, "/users/42")

// POST with request body
created, err := client.PostTo[User](ctx, "/users", User{Name: "Alice"})

// PUT, PATCH, DELETE
updated, err := client.PutTo[User](ctx, "/users/42", User{Name: "Alice Cooper"})
deleted, err := client.DeleteTo[User](ctx, "/users/42")

// Custom HTTP method
res, err := client.FetchTo[User](ctx, "CUSTOM", "/endpoint", payload)

2. Raw Response Access & Binding to Existing Struct

// Raw GET request returning (*http.Response, error)
rawResp, err := client.Get(ctx, "/raw-data")
if err == nil {
    defer rawResp.Body.Close()
}

// GetEx returns both the typed result and raw *http.Response
user, resp, err := client.GetEx[User](ctx, "/users/42")
fmt.Printf("Status: %d, Server: %s\n", resp.StatusCode, resp.Header.Get("Server"))

// GetInto unmarshals directly into a pre-allocated struct
var existing User
err := client.GetInto(ctx, "/users/42", &existing)

3. Request Builder (`client.R()`)

For composite requests requiring path parameters, query parameters, or custom headers:

var user User

resp, err := client.R().
	SetContext(ctx).
	SetPathParam("userId", "42").
	SetQueryParam("fields", "id,name,email").
	SetHeader("X-Trace-ID", "trace-12345").
	SetBody(map[string]any{"active": true}).
	SetResult(&user).
	Post("/users/{userId}/update")

4. Top-Level Package Functions (`aoni.GetTo[T]`, `aoni.PostTo[T]`)

For quick requests without managing a client instance:

user, err := aoni.GetTo[User](ctx, "https://api.example.com/users/42")

5. High-Throughput Engine (`fast.Client`)

fasthttp-based engine for high-throughput workloads:

import "github.com/lemon4ksan/aoni/fast"

fastClient := fast.NewClient(
	option.WithBaseURL("https://api.example.com"),
	option.WithTimeout(5*time.Second),
)

user, err := fastClient.GetTo[User](ctx, "/users/42")

⚡ Performance Profile

Tested under parallel load across 12 CPU cores (b.RunParallel, PGO-Optimized):

HTTP Client / Engine	RPS (12 Cores)	Allocations	Memory / op	HTTP/2 & HTTP/3	Post-Quantum TLS 1.3	Zero-Alloc Pipeline
`aoni/fast` (`io_uring`)	2,480,000+	0 allocs/op	0 B/op	✓ (H2/H3/QUIC)	✓ (ML-KEM 768)	✓
`aoni/fast` (PGO / Sockets)	2,126,000+	0 allocs/op	0 B/op	✓ (H2/H3/QUIC)	✓ (ML-KEM 768)	✓
`aoni.Client` (Stdlib)	640,000+	1 alloc/op	24 B/op	✓ (H2/H3/QUIC)	✓ (ML-KEM 768)	✓
`fasthttp`	1,910,000	0 allocs/op	0 B/op	✗ (No H2/H3)	✗	✗
`net/http` (Stdlib)	165,000	78 allocs/op	6,800 B/op	⚠️ (H2 only)	✗	✗
`go-resty/resty`	142,000	86 allocs/op	8,940 B/op	✗	✗	✗

Architecture

1. Public API & Transport

Stable Public Surface: RFC 9110 methods (client.GetTo[T], client.PostTo[T], client.Get, client.R(), option.With..., mod.With...) are maintained across v1.x releases.
Transport: Handles protocol negotiation (HTTP/1.1, HTTP/2, HTTP/3, TLS 1.3 with ML-KEM, MASQUE), Happy Eyeballs connection racing, and buffer management.
Ecosystem Modularization: Third-party integrations live in aoni-contrib, while browser evasion and TLS fingerprinting live in aoni-browser.

2. Memory Safety & Static Verification

When pooling buffers (sync.Pool), escaping borrowed slices can lead to data races. The companion vortex static analyzer provides compile-time verification:

Verifies borrowed buffers do not escape into unsynchronized goroutines (vortex borrow).
Checks non-overlapping slice mutations.
Enforces explicit resource acquisition and release lifecycles.

# Verify invariants in CI/CD via vortex:
vortex borrow ./...

3. CPU & Memory Optimizations

Per-P Storage (pool.PerPStorage): Core-local buffers minimize mutex and channel contention.
Off-Heap Slabs (offheap.SlabAllocator): Protocol framing structures allocated outside the Go heap to reduce GC overhead.
64-Byte Cache Line Alignment (_ cpu.CacheLinePad): Prevents False Sharing across multi-threaded socket loops.
SIMD Header Scanning: Delimiter scanning (\r\n) uses AVX2 / SWAR vector instructions.
Monotonic Clocks: Reduces system call overhead on hot timestamp paths.
Linux io_uring Support (netutil/iouring): Submission (SQ) and completion (CQ) rings for asynchronous socket I/O.

Vortex Toolchain

The aoni ecosystem relies on vortex, a standalone static analysis CLI tool and schema-driven code generator for OpenAPI 3.1, AsyncAPI 2.x/3.x, and Protobuf schemas:

package userapi

import (
	"context"
	"github.com/lemon4ksan/aoni/mod"
)

// @aoni:service
// @base_url "https://api.example.com"
type UserAPI interface {
	// @get /users/{id}
	// @header "Accept: application/json"
	GetUser(ctx context.Context, id int, mods ...aoni.RequestModifier) (*User, error)

	// @post /users
	CreateUser(ctx context.Context, req CreateUserRequest, mods ...aoni.RequestModifier) (*User, error)
}

# Verify zero-allocation borrowing and memory safety in CI/CD:
vortex borrow ./...

# Generate client code from schemas:
vortex gen

# Generate in-memory mock servers for test suites:
vortex mock

See the Vortex Repository, Toolchain Guide, and Specification.

Protocols & Features

1. Protobuf & gRPC-Web (Unary & Streaming)

// Direct gRPC-Web call with 5-byte framing and trailer validation
userResp, resp, err := aoni.PostGRPCWebTo[pb.UserResponse](ctx, client, "/UserService/GetUser", &pb.UserRequest{
	UserId: 42,
})

2. WebSockets over HTTP/2 Extended CONNECT (RFC 8441)

import "github.com/lemon4ksan/aoni/realtime/ws"

conn, resp, err := ws.Dial(ctx, "wss://stream.example.com/feed",
	ws.WithH2ExtendedConnect(),
	ws.WithSubprotocols("graphql-transport-ws"),
)
if err != nil {
	panic(err)
}
defer conn.Close()

_ = conn.WriteText("{\"type\":\"subscribe\"}")

3. Post-Quantum TLS 1.3 & Encrypted Client Hello (ECH / RFC 9460)

client := aoni.NewClient(nil,
	option.WithPostQuantumKyber(),        // Hybrid key exchange X25519MLKEM768
	option.WithECH(option.ECHModeStrict), // Encrypted Client Hello via DoH/DoQ
)

4. Happy Eyeballs v3 & Early Hints (RFC 8297)

// Proactively resolves DNS and establishes TLS pipelines before first request
_ = client.Preconnect(ctx, "https://api.example.com")
_ = client.Preresolve(ctx, "api.example.com")

5. Credential Privacy & 0-RTT Anti-Replay (RFC 8470)

import "github.com/lemon4ksan/aoni/netutil/secret"

// Values inside secret.Secret are masked in logs, JSON, and stack traces
token := secret.New("super-secret-api-token")

client := aoni.NewClient(nil,
	option.WithSecretBearer(token),
)

Microbenchmarks

Detailed Subsystem Microbenchmarks (Click to Expand)

1. Subsystem Microbenchmarks

Subsystem / Operation	Go Standard / `x/...`	`aoni`	Latency Delta	Memory (`B / op`)
URL Parsing (`net/url.Parse`)	295.1 ns	85.2 ns (`net/url`)	3.5x Faster	L1 CRC32 Cache
Public Suffix (`eTLD+1`)	146.3 ns	78.8 ns (`aoni-browser/psl`)	1.9x Faster	0 B / 0 allocs
QPACK RFC 9204 Block Codec	2,500+ ns (`quic-go/qpack`)	461.3 ns (`internal/fast/h3engine`)	5.4x Faster	0 B / 0 allocs
HPACK Field Decoder	391.9 ns (`x/net/http2/hpack`)	329.2 ns (`internal/fast/h2engine`)	1.19x Faster	0 B / 0 allocs
HPACK Huffman Encoder	18.5 ns	13.99 ns (`internal/fast/h2engine`)	1.32x Faster	0 B / 0 allocs
Timestamping (`vDSO` Bypass)	3.15 ns (`time.Now`)	0.28 ns (`silicon/clock`)	11.2x Faster	0 B / 0 allocs
Token Bucket Limiter	85+ ns (`x/time`)	23.8 ns (`async/rate`)	3.6x Faster	0 B / 0 allocs
SWAR UTF-8 Scan (1KB)	280+ ns (`bytes.Index`)	5.88 ns (`silicon/simd`)	12.4 GB/s	0 B / 0 allocs
SWAR `\r\n` Header Scan (1KB)	280+ ns (`bytes.Index`)	114.4 ns (`silicon/simd`)	2.5x Faster	0 B / 0 allocs
Zstd Decompression (1KB)	1.8+ µs (`klauspost/zstd`)	251.6 ns / 0 B (`compress/zstd`)	7.2x Faster	0 B / 0 allocs
Brotli Decompression (1KB)	2.1+ µs (`google/brotli`)	282.6 ns / 0 B (`compress/brotli`)	7.4x Faster	0 B / 0 allocs
WebSocket Stream Throughput	800 MB/s (`gorilla/websocket`)	1,789 MB/s (`realtime/ws`)	2.23x Faster	0 B / 0 allocs

2. Gollvm (LLVM 20.1.8 -O3) Vectorization

Subsystem / Workload	Standard Go (`gc`)	Gollvm (`LLVM 20.1.8 -O3`)	Speedup	Mechanism
ASCII Header Case-Folding & Match	8.47 ns/match	1.71 ns/match	⚡ 4.95x Faster	Vectorized bitwise unrolling & branch elimination
HPACK / QPACK Huffman Bitstream Pack	324.32 MB/s (464.6 ns)	697.84 MB/s (215.9 ns)	⚡ 2.15x Faster	64-bit barrel-shifter & register packing
QUIC / Protobuf Varint Codec	22.41 ns/op	1.55 ns/op	⚡ 14.4x Faster	Unrolled bitmask extraction & branch prediction
EWMA Latency & Jitter Filter	2.74 ns/sample	1.92 ns/sample	⚡ 1.43x Faster	Fused multiply-accumulate & float register pipelining

Feature & Protocol Matrix

Feature / Capability	Go `net/http`	Wrappers (e.g. Resty)	`aoni` Engine
Static Buffer Verification (`vortex lint`)	✗	✗	✓ (CFG & Escape Analysis)
Multi-Core Allocator Contention	⚠️ (`sync.Pool`)	⚠️ (High contention)	✓ (`pool.PerPStorage` core-pinned)
Linux `io_uring`	✗	✗	✓ (Shared SQ/CQ Ring Buffers)
Reduced GC Overhead on Framing	✗ (Heap allocation)	✗ (Heap allocation)	✓ (`offheap.SlabAllocator`)
Native HTTP/2 Multiplexer	⚠️ (`x/net/http2`)	✗	✓ (Native Engine & LUT)
Native HTTP/3 / QUIC / QPACK	✗	✗	✓ (RFC 9000 & RFC 9204)
Post-Quantum TLS 1.3 Key Exchange	✗	✗	✓ (X25519MLKEM768 & Zstd Cert Compression)
RFC 8297 `103 Early Hints`	✗	✗	✓ (Link Parsing & Socket Preconnect)
Network Isolation (NIK)	✗	✗	✓ (TopFrame/FrameSite Keys & CHIPS)
RFC 9218 Extensible Priorities	✗	✗	✓ (Stream Priorities `u=0..7, i`)
RFC 8767 Stale-While-Revalidate DNS	✗	✗	✓ (Stale DNS with Background Refresh)
RFC 9651 Compression Dictionaries	✗	✗	✓ (`dcb`, `dcz` & `Sec-Available-Dictionary`)
Generics-First Codecs	✗ (Manual)	✗ (Interface reflection)	✓ (Compile-time `[T]`)
gRPC & gRPC-Web (4 Streaming Modes)	✗	✗	✓ (Unary, Server, Client & Bidi)
Chromium Happy Eyeballs v3	⚠️ (IPv4/v6 only)	✗	✓ (H3 vs H2/H1 Protocol Racing)
Auto-Recovery Pipeline	✗	✗	✓ (HTTP 421, 408, 425 & Alt-Svc Backoff)
W3C `No-Vary-Search` Cache	✗	✗	✓ (Query Normalization)
TLS 1.3 Encrypted Client Hello	✗	✗	✓ (ECH / RFC 9460 via DoH/DoQ)
Credential Privacy & Anti-Replay	✗	✗	✓ (`Secret[T]` & RFC 8470)
Sandboxed PAC / WPAD Engine	✗	✗	✓ (PAC Rule Engine)
OS Sleep / Wake Recovery	✗	✗	✓ (Socket Pool Cleanup on Network Change)
Active Circuit Breaking	✗	✗	✓ (EWMA & Error Ratio Tripping)
`Retry-After` Parsing	✗	✗	✓ (Delta-sec & RFC 1123 datetime)
Non-UTF8 Charset Decoding	✗	✗	✓ (WhatWG Encoding Engine)
TLS Evasion (JA3/JA4/JA4H/p0f)	✗	✗	✓ (via `aoni-browser`)
Unix Domain Socket Support	⚠️ (Manual)	✗	✓ (Native `unix://`)
L3/L4 & MASQUE Tunnels	✗	✗	✓ (Wintun, utun, /dev/net/tun, MASQUE RFC 9298)
OpenTelemetry & W3C Tracing	✗	✗	✓ (via `aoni-contrib/otel`)
Socket.IO / Engine.IO v4 Client	✗	✗	✓ (via `aoni-contrib/socketio`)
Proxy & Session Isolation	✗	✗	✓ (`ProxyIsolatedJar` RFC 6265)

📦 Repository Layout

aoni/
├── option/       // Client initialization options (option.WithBaseURL, option.WithH2...)
├── mod/          // Per-request modifiers (mod.WithVar, mod.WithHeader, mod.WithJSON...)
├── fast/         // High-performance fasthttp engine (2.12M+ RPS zero-alloc pipeline)
├── middleware/   // Composable request/response interceptors (Retry, RateLimit, Recover...)
├── cookie/       // Proxy-isolated cookie jars, Netscape format, RFC 6265 path sorting
├── netutil/      // Proxy rotators, DoH/DoT/DoQ resolvers, PAC engine, NIK, Early Hints
├── codec/        // Response decoders (JSON, Proto, gRPC-Web, XML) and url.Values encoders
├── realtime/     // WebSocket over H2 CONNECT (RFC 8441), SSE & NDJSON streams
├── resiliency/   // Response caching, Circuit Breakers, Load Balancers, Backoff
└── telemetry/    // HAR generators, EWMA latency trackers, tracing hooks & cURL exporters

🪐 Ecosystem & Satellite Projects

The aoni project follows a micro-kernel philosophy: the core engine is permanently locked to IETF RFC and W3C standards with zero business logic, while specialized domain layers reside in companion repositories:

aoni-browser: The Stealth Shield — pure-Go uTLS ClientHello spoofing, JA3/JA4/JA4H fingerprinting, p0f TCP/IP stack emulation, CDN padding, and full browser impersonation (Chrome, Firefox, Safari).
aoni-contrib: Ecosystem Extensions — specialized protocol adapters including OS TUN & MASQUE tunnels (aoni-contrib/tunnel), OpenTelemetry (aoni-contrib/otel), Socket.IO v5 / Engine.IO v4 (aoni-contrib/socketio), OAuth2/PKCE/DPoP, and GeoIP MMDB.
vortex: Static Analysis & Code Generator — AST borrow checking, memory safety verifier, and schema-driven client generation for OpenAPI 3.1, AsyncAPI, and Protobuf schemas.
ao: High-performance curl fork powered by libaoni (lib/aoni_bridge.c), delivering 9,145+ RPS across 100 concurrent threads.
discordgo-aoni: High-efficiency fork of discordgo with network transport replaced by aoni and aoni/realtime/ws.

📚 Technical Documentation

Security & Protocol Invariants: Defense model, SSRF protection, DNS rebinding, and decompression bomb guards.
Vortex Toolchain Guide: Declarative syntax, OpenAPI/AsyncAPI ingestion, mock servers, and CI/CD integration.
Vortex Specification: EBNF grammar and static linter rules.
Network Stack Specification: Happy Eyeballs v3, HTTP 421/408/425 recovery, ECH, and connection pool management.
CPU & Memory Optimization: SIMD assembly, slab allocation, and memory layouts.
Low-Level Mechanics: HPACK state manipulation, socket system calls, and framing.
Cookbook: Practical recipes for REST, WebSockets, gRPC-Web, and streaming workflows.
Code Examples: Usage examples for the library.

🧾 License

Licensed under the BSD 3-Clause License. See LICENSE for details.

Name		Name	Last commit message	Last commit date
.agents		.agents
.github		.github
.vscode		.vscode
codec		codec
cookie		cookie
dns		dns
docs		docs
examples		examples
fast		fast
fragment		fragment
internal		internal
ipc		ipc
middleware		middleware
mod		mod
netutil		netutil
nik		nik
option		option
pipeline		pipeline
proxy		proxy
realtime		realtime
resiliency		resiliency
scripts		scripts
telemetry		telemetry
tests		tests
testutil		testutil
tls		tls
trie		trie
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_RU.md		README_RU.md
SECURITY.md		SECURITY.md
bridge.go		bridge.go
builder.go		builder.go
builder_test.go		builder_test.go
client.go		client.go
config.go		config.go
context.go		context.go
contract.go		contract.go
default.pgo		default.pgo
dial.go		dial.go
doc.go		doc.go
engine.go		engine.go
errors.go		errors.go
errors_test.go		errors_test.go
facade.go		facade.go
go.mod		go.mod
go.sum		go.sum
h3_engine.go		h3_engine.go
lifecycle_test.go		lifecycle_test.go
release-please-config.json		release-please-config.json
security_test.go		security_test.go
std.go		std.go
typed.go		typed.go
version.go		version.go

Navigation Menu

Repository navigation

About

Repository files navigation

aoni

The Unified Internet Protocol Stack for Go

English • Русский • Architecture Specification • Vortex Guide

Installation

Quickstart

Client Usage Patterns

1. Generic Methods (`client.GetTo[T]`, `client.PostTo[T]`, etc.)

2. Raw Response Access & Binding to Existing Struct

3. Request Builder (`client.R()`)

4. Top-Level Package Functions (`aoni.GetTo[T]`, `aoni.PostTo[T]`)

5. High-Throughput Engine (`fast.Client`)

⚡ Performance Profile

Architecture

1. Public API & Transport

2. Memory Safety & Static Verification

3. CPU & Memory Optimizations

Vortex Toolchain

Protocols & Features

Microbenchmarks

1. Subsystem Microbenchmarks

2. Gollvm (LLVM 20.1.8 -O3) Vectorization

Feature & Protocol Matrix

📦 Repository Layout

🪐 Ecosystem & Satellite Projects

📚 Technical Documentation

🧾 License

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

aoni

The Unified Internet Protocol Stack for Go

English • Русский • Architecture Specification • Vortex Guide

Installation

Quickstart

Client Usage Patterns

1. Generic Methods (client.GetTo[T], client.PostTo[T], etc.)

2. Raw Response Access & Binding to Existing Struct

3. Request Builder (client.R())

4. Top-Level Package Functions (aoni.GetTo[T], aoni.PostTo[T])

5. High-Throughput Engine (fast.Client)

⚡ Performance Profile

Architecture

1. Public API & Transport

2. Memory Safety & Static Verification

3. CPU & Memory Optimizations

Vortex Toolchain

Protocols & Features

Microbenchmarks

1. Subsystem Microbenchmarks

2. Gollvm (LLVM 20.1.8 -O3) Vectorization

Feature & Protocol Matrix

📦 Repository Layout

🪐 Ecosystem & Satellite Projects

📚 Technical Documentation

🧾 License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Contributors

Languages

1. Generic Methods (`client.GetTo[T]`, `client.PostTo[T]`, etc.)

3. Request Builder (`client.R()`)

4. Top-Level Package Functions (`aoni.GetTo[T]`, `aoni.PostTo[T]`)

5. High-Throughput Engine (`fast.Client`)