mach

README

mach

Silicon-Speed Protocol Engines & Transport Layers for Go 1.27+

«Aerodynamic protocol mechanics at Mach speed — where zero heap allocation meets wire throughput»

mach is the low-level, zero-allocation protocol engine powering the aoni client ecosystem and sein server frameworks. It provides raw, silicon-optimized bytes-to-frames mechanics: SIMD header delimiter scanning, sub-nanosecond binary frame overlays, stream multiplexing, HPACK/QPACK table compression, and RFC-conforming protocol state machines.

Architecture: The Zero-Drag Manifesto

Named after the Mach number and aerodynamic concept of Zero Drag, mach eliminates computational friction from network pipelines:

• Agnostic Wire Core: The engine accepts raw bytes from a socket, enforces RFC constraints, and emits protocol frames. It contains zero application routing, middleware, or business logic.
• Forever-Frozen Standard: Mechanics strictly implement IETF RFCs (HTTP/1.1 RFC 9112, HTTP/2 RFC 9113, HPACK RFC 7541, HTTP/3 RFC 9114, QPACK RFC 9204).
• Symmetric Isolation: Client and server architectures require fundamentally distinct memory layouts, buffer reuse patterns, and concurrency lifecycles. mach isolates them into distinct packages (mach/client vs mach/server).
• Zero Heap Allocation on Hot Path: Every frame, header slice, and URI component is read and recycled using multi-tiered arenas, Per-P pools, and scoped borrow semantics.

Protocol Index

mach/
├── client/                   # Client protocol engines (optimized for `aoni`)
│   ├── h1/                   # HTTP/1.1 Client Engine. Connection reuse, chunked transfers
│   ├── h2/                   # HTTP/2 Client Engine. Concurrent stream multiplexing
│   └── h3/                   # HTTP/3 Client Engine. QUIC stream lifecycle, 0-RTT transactions
├── fsm/                      # Finite State Machines
│   └── h2/                   # Strict RFC 9113 §5.1 HTTP/2 stream transition verifier
├── hpack/                    # HPACK (RFC 7541) header compression codec
├── proto/                    # RFC-conforming wire mechanics (client/server agnostic)
│   ├── compress/             # Streaming Brotli, Gzip, Deflate, Zstd decompressors
│   ├── h2/                   # HTTP/2 framing (RFC 9113), priority trees, flow control
│   │   └── overlay/          # Sub-nanosecond In-Situ binary frame overlay
│   ├── h3/                   # HTTP/3 framing (RFC 9114), datagrams, capsules
│   ├── http/                 # HTTP/1.1 wire parser, SIMD scanner, zero-alloc Request/Response
│   │   └── stackless/        # Goroutine-free async I/O dispatch
│   ├── packet/               # L3/L4 packet parsers (ICMP, TCP)
│   └── raptor/               # Ultra-low-latency layer-7 proxy and tunneling core
├── qpack/                    # QPACK (RFC 9204) header compression codec
├── scripts/                  # CI & Fuzzing suites
│   └── fuzz_all.go           # Heavy automated fuzz harness
├── server/                   # Server protocol engines (optimized for `sein`)
│   ├── h1/                   # HTTP/1.1 Server Engine. High-throughput edge listener
│   ├── h2/                   # HTTP/2 Server Engine. Prioritized stream dispatch
│   └── h3/                   # HTTP/3 Server Engine. Connection ID routing
└── tests/                    # Integration and E2E tests

Honest Benchmarks

All benchmarks measured on bare-metal hardware (12th Gen Intel Core i5-12400F @ 4.40 GHz, Go 1.27, Windows x86_64).

1. HTTP/2 In-Situ Binary Overlay vs Legacy Decode

Instead of allocating and copying wire bytes into Go structs, proto/h2/overlay casts raw frame buffers into zero-copy in-situ memory views:

Implementation	Speed	Throughput / Overhead	Allocations
Legacy Struct Heap Decode	17.17 ns/op	48 B/op	1 allocs/op
mach/proto/h2/overlay	0.49 ns/op	0 B/op	0 allocs/op
Improvement	35.0x faster	100% memory eliminated	Zero garbage created

2. HTTP/1.1 SIMD Wire Scanning & Header Parsing

Accelerated vector scanners scan \r\n and colon delimiters using hardware SIMD registers:

Operation	Latency	Throughput	Allocations
SIMD Header Wire Scan	323.6 ns/op	2,042.61 MB/s (~2.04 GB/s)	3 allocs/op
Response Header Full SIMD Parse	1,481.0 ns/op	446.28 MB/s	25 allocs/op
Scoped Borrow Pipeline	106.0 ns/op	Wire decoding + Header mapping	0 allocs/op
Legacy Copy Pipeline	121.0 ns/op	80 B/op	1 allocs/op

3. Multi-Tiered Memory Pool Latency

Comparison of object recycling strategies across parallel execution threads:

Pool Strategy	Latency	Memory Overhead	Allocations
Per-Goroutine Ring Pool	1.889 ns/op	0 B/op	0 allocs/op
Per-P Storage (foundation/pool)	4.390 ns/op	0 B/op	0 allocs/op
Standard sync.Pool	4.574 ns/op	0 B/op	0 allocs/op
Connection-Bound Frame Pool (Ping/WU/Rst)	10.510 ns/op	0 B/op	0 allocs/op

4. HTTP/3 & QPACK Wire Performance

Component	Operation	Latency	Memory	Allocations
HTTP/3 Frame Header Pack	Pack varint header	2.812 ns/op	0 B/op	0 allocs/op
QPACK Response Decode	Decode headers into map	943.8 ns/op	693 B/op	13 allocs/op
QPACK Request Decode	Decode headers into map	1,056.0 ns/op	696 B/op	9 allocs/op
QPACK Request Encode	Encode dynamic headers	1,962.0 ns/op	2,208 B/op	34 allocs/op

Engineering Invariants

1. Strict Zero-Allocation Hot Path: Connection handshakes, stream processing, frame serialization, and URI parsing recycling must produce zero heap allocations during steady-state traffic.
2. Cache-Line Alignment (64 Bytes): Core data-in-motion structs (Request, Response, FrameHeader) are packed and padded to 64-byte boundaries to prevent cross-core false sharing on symmetric multi-processor (SMP) architectures.
3. No Hidden Background Goroutines: State transitions are driven synchronously by the caller's thread or explicit external reactors. No unmonitored goroutine leaks.
4. RFC Invariant Integrity: No non-standard extensions or framework-specific compromises in mach/proto.

Continuous Fuzzing & Verification

The protocol mechanics in mach are continuously verified against malformed frame injections and protocol corruption using Go native fuzzing:

# Run the complete multi-protocol fuzzing suite across all 8 targets
go run ./scripts/fuzz_all.go -fuzztime=5s

Run test suite with the race detector enabled:

go test -v -race ./...

Run micro-benchmarks with memory profiling:

go test -bench=. -benchmem ./...

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.

Copyright (c) 2026 Lemon4ksan. All rights reserved.

Documentation

Overview

Package mach provides silicon-speed protocol engines and transport layers for Go.

Index

• type Conn
• type Engine
• type Frame
• type Stream

Types

type Conn

type Conn interface {
	io.Closer

	// OpenStream creates a new request-response stream (Zero-alloc where possible).
	OpenStream(ctx context.Context) (Stream, error)
}

Conn represents an active protocol connection. For multiplexed protocols (H2, H3), it manages multiple Streams. For H1, it acts as a single-stream carrier.

type Engine

type Engine interface {
	// Dial establishes a connection or yields a protocol-specific multiplexer.
	Dial(ctx context.Context, addr string) (Conn, error)
}

Engine defines the universal contract for protocol engines (H1/H2/H3/QUIC). It acts as a factory for protocol connections.

type Frame

type Frame interface {
	// Type returns the protocol-specific frame type identifier.
	Type() uint8
	// Payload yields the zero-copy slice of the frame body.
	Payload() []byte
}

Frame represents a Data-In-Motion abstraction of a protocol frame (H2/H3/QUIC).

type Stream

type Stream interface {
	io.Reader
	io.Writer
	io.Closer

	// ReadFrame parses the next protocol-specific frame without heap allocations.
	ReadFrame() (Frame, error)
}

Stream represents an isolated request/response lifecycle. It bypasses standard io.Reader/io.Writer allocations by using Zero-copy methods or integrating directly with the foundation/bufkit arenas.