protocol

简体中文 | Documentation

Transport-neutral request-response protocol assembly over stream, datagram, raw packet, and L2 frame channels for Gnalloy.

This module assembles transport-neutral request-response behavior over stream, datagram, raw packet, and L2 frame Channels. It does not replace concrete codecs or transports.

Status

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

Install

go get gnalloy.org/protocol@dev
go doc gnalloy.org/protocol
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: Transport-neutral request-response protocol assembly over stream, datagram, raw packet, and L2 frame channels for Gnalloy.

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/protocol (protocol)

Gnalloy Dependencies

• gnalloy.org/gnalloy
• gnalloy.org/transport-l2
• gnalloy.org/transport-raw
• gnalloy.org/transport-udp

Common Integration Pattern

• Configuration is passed through explicit constructors and option structs rather than package-level mutable state.
• Keep hot-path defaults conservative, bounded, and allocation-aware.

Current Public Entry Points

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

• var ErrInvalidConfig = errors.New("gnalloy/protocol: invalid config") ...
• func NewServerHandler(adapter ServerAdapter, handler Handler) channel.Handler

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.