handler-proxy

简体中文 | Documentation

HTTP CONNECT, SOCKS4, SOCKS5, and HAProxy negotiation handlers for Gnalloy pipelines.

This module provides Pipeline handlers. A handler observes, transforms, rejects, delays, records, or protects messages after a Channel already exists. It does not own listening sockets or application protocols unless explicitly named.

Status

• Import path: gnalloy.org/handler-proxy
• Repository: github.com/gnalloy/handler-proxy
• Default branch: dev
• Preview install: go get gnalloy.org/handler-proxy@dev
• License: Apache-2.0

Install

go get gnalloy.org/handler-proxy@dev
go doc gnalloy.org/handler-proxy
GOWORK=off GOTOOLCHAIN=local go test ./... -count=1

Documentation

• Overview (中文)
• Usage (中文)
• Examples (中文)
• Configuration (中文)
• Testing and Performance (中文)
• API Reference (中文)
• Notes and Caveats (中文)
• ADR-001 Module Boundary (中文)

Module Boundary

This repository owns: HTTP CONNECT, SOCKS4, SOCKS5, and HAProxy negotiation handlers for Gnalloy pipelines.

It does not absorb neighboring module responsibilities. Core primitives stay in gnalloy.org/gnalloy; protocol codecs, transports, handlers, resolvers, examples, and benchmarks stay in their own repositories.

Packages

• gnalloy.org/handler-proxy (proxy)

Gnalloy Dependencies

• gnalloy.org/gnalloy

Common Integration Pattern

• Handler constructors usually carry the policy: limits, timeouts, match rules, logging level, recorder, or traffic budget.
• Handler order matters. Place protocol decoders before handlers that inspect protocol objects, and place outbound encoders after handlers that write protocol objects.
• Handlers must keep backpressure and message ownership explicit; never retain ByteBuf values without clear lifetime control.

Current Public Entry Points

The generated API reference lists the full public surface. Common constructors or option types currently include:

• const SOCKS4Version byte = 0x04 ...
• const SOCKS5Version byte = 0x05 ...
• var ErrNeedMore = errors.New("gnalloy/handler/proxy: need more bytes") ...

Verification

GOWORK=off GOTOOLCHAIN=local go test ./... -count=1
GOWORK=off GOTOOLCHAIN=local go vet ./...
GOWORK=off GOTOOLCHAIN=local go test ./... -run '^$' -bench . -benchmem -count=1

For pressure tests, assemble this module with the relevant transport, codec, and handler stack and run the scenario from gnalloy.org/benchmarks or gnalloy.org/examples. Keep host, operating system, payload, concurrency, warmup, and repetitions in the report.

Caveats

• This repository is intentionally narrow. Cross-module behavior should be assembled in applications, recipes, examples, or benchmark harnesses.
• Public APIs should remain Go-native and explicit; avoid runtime scanning, hidden global registries, and reflection-heavy behavior in hot paths.
• Treat network input as untrusted. Configure parser limits and return typed errors instead of panics.
• Keep benchmark claims tied to a concrete host, operating system, protocol, payload, concurrency, warmup, and repetition count.
• Handler modules are reusable only when their position in the pipeline is correct for the messages they observe.