examples

简体中文 | Documentation

Runnable examples, smoke clients, and stress clients for the Gnalloy modular networking stack.

This module contains runnable examples, smoke clients, and stress clients. It demonstrates supported assembly patterns and should not be imported as a production library.

Status

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

Install

go get gnalloy.org/examples@dev
go doc gnalloy.org/examples
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: Runnable examples, smoke clients, and stress clients for the Gnalloy modular networking stack.

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/examples/bench-client (main)
• gnalloy.org/examples/custom-ip-proto (main)
• gnalloy.org/examples/doq-query (main)
• gnalloy.org/examples/echo (main)
• gnalloy.org/examples/fixed-length (main)
• gnalloy.org/examples/http1 (main)
• gnalloy.org/examples/icmp-ping (main)
• gnalloy.org/examples/internal/benchclient (benchclient)
• gnalloy.org/examples/internal/exampleconfig (exampleconfig)
• gnalloy.org/examples/internal/smokeclient (smokeclient)
• gnalloy.org/examples/internal/stresscheck (stresscheck)
• gnalloy.org/examples/internal/stressclient (stressclient)
• gnalloy.org/examples/length-field (main)
• gnalloy.org/examples/line-frame (main)
• gnalloy.org/examples/mqtt-frame (main)
• gnalloy.org/examples/parity-bench (main)
• gnalloy.org/examples/protobuf-varint (main)
• gnalloy.org/examples/protocol-exchange (main)
• gnalloy.org/examples/raw-ip-dump (main)
• gnalloy.org/examples/redis-resp (main)
• gnalloy.org/examples/smoke-client (main)
• gnalloy.org/examples/stress-check (main)
• gnalloy.org/examples/stress-client (main)
• gnalloy.org/examples/udp-echo (main)
• gnalloy.org/examples/websocket (main)

Gnalloy Dependencies

• gnalloy.org/benchmarks
• gnalloy.org/codec-dns
• gnalloy.org/codec-http1
• gnalloy.org/codec-icmp
• gnalloy.org/codec-ip
• gnalloy.org/codec-mqtt
• gnalloy.org/codec-protobuf
• gnalloy.org/codec-redis
• gnalloy.org/codec-websocket
• gnalloy.org/gnalloy
• gnalloy.org/protocol
• gnalloy.org/resolver-dns-quic
• gnalloy.org/transport-l2
• gnalloy.org/transport-quic
• gnalloy.org/transport-raw
• gnalloy.org/transport-tcp
• gnalloy.org/transport-udp

Common Integration Pattern

• Configure bind addresses, target addresses, payload sizes, duration, concurrency, and protocol options from command-line flags or environment-specific wrappers.
• Treat examples as executable documentation; production services should own their own configuration schema.

Current Public Entry Points

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

• var ErrInvalidProtocol = errors.New("gnalloy/examples: invalid bench protocol") ...
• type Config struct{ ... }
• var ErrInvalidBackend = errors.New("gnalloy/examples: invalid backend") ...
• type Options struct{ ... }
• var ErrInvalidProtocol = errors.New("gnalloy/examples: invalid smoke protocol") ...
• type Config struct{ ... }
• const ProtocolBoth stressclient.Protocol = "both"
• var ErrLeakDetected = errors.New("gnalloy/examples: stress leak detected") ...
• type Config struct{ ... }
• var ErrInvalidProtocol = errors.New("gnalloy/examples: invalid stress protocol") ...
• type Config struct{ ... }

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.