examples

简体中文 | Documentation

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

This module contains runnable examples and smoke 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 and smoke 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/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/exampleconfig (exampleconfig)
• gnalloy.org/examples/internal/smokeclient (smokeclient)
• gnalloy.org/examples/length-field (main)
• gnalloy.org/examples/line-frame (main)
• gnalloy.org/examples/mqtt-frame (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/udp-echo (main)
• gnalloy.org/examples/websocket (main)

Gnalloy Dependencies

• 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 ./...

Run pressure tests from gnalloy.org/benchmarks, which owns the benchmark clients and reports. Keep host, operating system, payload, concurrency, warmup, and repetitions in the report.

Caveats

• This repository is intentionally narrow. Applications assemble cross-module behavior; examples and benchmark harnesses demonstrate and validate it.
• 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.