English | 简体中文
A composable network application framework for Go: server/client bootstrap, TCP/UDP/TLS/WebSocket transports, handler pipeline, framing codecs and a protocol codec kit.
The goal is high ease of use and reusable protocol foundations — not just raw sockets. Wire-format codecs live in gnety; protocol state machines live in the protocol libraries built on top.
Status: development snapshot (untagged) — TCP/UDP/TLS/WS/WSS/DTLS servers and clients, pipeline middleware, frame + MQTT/CoAP/Modbus (MBAP+RTU) codecs, sessions, request/response correlation, heartbeats, metrics hooks and bounded write queues; the HTTP/WebSocket codec packages are placeholders. No tags are published until a stable release; use commit pseudo-versions. License: MIT. Design notes: docs/DESIGN.md.
gnety is a framework, positioned by ease of use and protocol foundations:
| gnety provides | Protocol libraries provide |
|---|---|
| server/client bootstrap and lifecycle | MQTT QoS/retained/session state machine |
| handler pipeline + middleware | CoAP observe/block-wise state machine |
| TCP/UDP/TLS/WebSocket/DTLS transports | LwM2M registration/observe state machine |
| framing codecs (length, delimiter, line, fixed, custom) | device auth, TSL, business rules |
| protocol codec kit (wire format: HTTP/1.1, WebSocket, MQTT, CoAP, ... roadmap) | product semantics |
| sessions, heartbeat/idle, request/response correlation | — |
| metrics hooks, broadcast, test utilities | — |
Rules:
- Wire-format codecs belong to gnety (reusable across applications).
- Protocol state machines and business semantics belong to protocol libraries built on gnety.
- gnety must never import a protocol library.
Planned / in progress
- limits/timeouts:
MaxSessions,MaxPendingRequests,WriteTimeout,ShutdownTimeout; explicit DTLSInsecureSkipVerify - server bootstrap (done); client connector (TCP/UDP/TCP-TLS/WS/WSS/DTLS, done); reconnect/backpressure (roadmap)
- composable pipeline/middleware (
Chain,Recover, ...) - TLS / WebSocket / WSS / DTLS (server + client), from files or an in-memory
*tls.Config/*dtls.Config - protocol codec kit (
codec/): shared byte primitives (codec/wire), HTTP/1.1, WebSocket, MQTT, CoAP, Modbus MBAP+RTU+PDU (with a vendor function-code registry), LwM2M TLV (wire format only) - metrics hooks, event-loop backend option
- broadcast and test utilities
Out of scope
- protocol state machines and business semantics (MQTT broker logic, LwM2M registry, CoAP observe)
- annotation/reflection magic; Go-idiomatic explicit pipelines
srv, _ := gnety.New(gnety.Config{
Network: "tcp",
Addr: ":9000",
Codec: gnety.LengthFieldCodec{},
Handler: gnety.HandlerFuncs{
Message: func(s *gnety.Session, msg any) { _ = s.Send(msg) },
},
})
_ = srv.Start(context.Background())
defer srv.Stop(context.Background())UDP:
srv, _ := gnety.New(gnety.Config{
Network: "udp",
Addr: ":9001",
DatagramCodec: gnety.BytesDatagramCodec{},
Handler: gnety.HandlerFuncs{Message: func(s *gnety.Session, msg any) { _ = s.Send(msg) }},
})TLS / WebSocket:
// TLS
srv, _ := gnety.New(gnety.Config{
Network: "tcp-tls", Addr: ":9443", Codec: codec,
TLS: gnety.TLSConfig{CertFile: "cert.pem", KeyFile: "key.pem"},
})
// WebSocket
srv, _ = gnety.New(gnety.Config{
Network: "ws", Addr: ":9002", Path: "/echo", Subprotocol: "gnety", Codec: codec,
})Config.Socket and ClientConfig.Socket expose channel-style socket options for
the listener, accepted connections and client dial:
| Option | Kernel setting |
|---|---|
ReuseAddr |
SO_REUSEADDR |
ReusePort |
SO_REUSEPORT (Linux/macOS/BSD; Windows rejects it) |
KeepAlive |
SO_KEEPALIVE; >0 sets the period, <0 disables |
NoDelay |
TCP_NODELAY (nil keeps Go's default) |
Linger |
SO_LINGER; <0 disables, >0 seconds |
ReadBuffer / WriteBuffer |
SO_RCVBUF / SO_SNDBUF |
Control |
arbitrary syscall.RawConn options, e.g. TCP_FASTOPEN |
noDelay := false
srv, _ := gnety.New(gnety.Config{
Network: "tcp", Addr: ":9000", Codec: gnety.LengthFieldCodec{},
Socket: gnety.SocketOptions{
ReuseAddr: true,
ReusePort: true,
KeepAlive: 30 * time.Second,
NoDelay: &noDelay,
Linger: -1,
ReadBuffer: 64 << 10,
WriteBuffer: 64 << 10,
},
})
client, _ := gnety.Dial(ctx, gnety.ClientConfig{
Network: "tcp", Addr: "127.0.0.1:9000", Codec: gnety.LengthFieldCodec{},
LocalAddr: &net.TCPAddr{IP: net.ParseIP("127.0.0.1")},
Socket: gnety.SocketOptions{KeepAlive: 30 * time.Second},
})SO_REUSEPORT is opt-in; every listener sharing the port must enable it.
SO_REUSEADDR is already set by Go for many Unix listeners, so it is mainly
useful for explicit restarts and Windows. TCP-only options are rejected on UDP;
DTLS does not expose socket options in this version.
Pass an already-bound socket when an application owns the transport or needs a socket type gnety cannot create:
ln, _ := net.Listen("tcp", ":9000")
srv, _ := gnety.New(gnety.Config{
Network: "tcp",
Listener: ln, // gnety closes it in Stop
Codec: gnety.LengthFieldCodec{},
})
packet, _ := net.ListenPacket("udp", ":9001")
udp, _ := gnety.New(gnety.Config{
Network: "udp", PacketConn: packet, DatagramCodec: gnety.BytesDatagramCodec{},
})Listener is transport-ready: for tcp-tls/wss it must already be a TLS
listener (gnety does not wrap it); for ws it is the raw TCP listener. This
lets an application own Unix sockets, SO_REUSEPORT listeners or a custom
net.Listener. PacketConn is only valid for udp.
For the client side, NewClient wraps any net.Conn:
conn, _ := net.Dial("unix", "/tmp/app.sock")
client, _ := gnety.NewClient(conn, gnety.ClientConfig{
Network: "tcp", Codec: gnety.LengthFieldCodec{},
})NewClient does not dial; the caller owns the connection until Client.Close.
Bind-probe helpers answer "is this port free?" and "what is the next free port?":
if gnety.TCPPortInUse(1883) {
port, err := gnety.AvailablePort(1883) // first free TCP port >= 1883
}
if gnety.UDPPortInUse(1883) {
port, err := gnety.AvailableUDPPort(1883)
}
// A service that binds the same numeric port for TCP and UDP:
both, err := gnety.AvailablePortBoth(1883)Use the On variants to probe a specific host, and a shared allocated map
when several ports belong to one service (otherwise two adjacent defaults can
both shift onto the same free port):
allocated := map[int]struct{}{}
mqtt, _ := gnety.AvailablePortOn("0.0.0.0", 1883, allocated)
mqttTLS, _ := gnety.AvailablePortOn("0.0.0.0", 8883, allocated)AvailablePortFor(PortTCPAndUDP, host, start, allocated) is the general form;
PortInUse(PortTCPAndUDP, ...) is true when either protocol is occupied.
A probe is inherently racy between the bind check and the real listen; the
caller must still handle the bind error. Port 0 means "let the OS choose" and
is returned as 0; negative or out-of-range ports return ErrInvalidPort, and
an exhausted range returns ErrNoAvailablePort.
Request/response:
policy := gnety.RequestKeyPolicyFuncs{
Request: func(msg any) (string, bool) { return keyOf(msg), true },
Response: func(msg any) (string, bool) { return keyOf(msg), true },
}
srv, _ := gnety.New(gnety.Config{Network: "tcp", Addr: ":9000", Codec: codec,
RequestKeyPolicy: policy, Handler: handler})
// inside a handler:
resp, err := session.Request(ctx, request)Pipeline:
handler := gnety.Chain(baseHandler,
gnety.Recover(logger),
myAuthMiddleware,
myMetricsMiddleware,
)
srv, _ := gnety.New(gnety.Config{Network: "tcp", Addr: ":9000", Codec: codec, Handler: handler})Broadcast:
n := srv.Broadcast([]byte("{\"type\":\"ping\"}"))The observability contract lives in hook: Metrics, NoopMetrics and the coarse
session labels (ReasonClosed, ReasonReadError, ReasonBackpressure, ...). The root
package re-exports every one of them as an alias, so the two import paths are the same types
and existing code needs no change:
var m gnety.Metrics = hook.MetricsFuncs{} // literally the same typehook.MetricsFuncs implements the six methods with optional function fields — set only the
events you care about, and nil fields are skipped. hook.NoopMetrics is the default and
drops everything.
To make extensions switchable at run time — start, stop, inspect — wrap the server in a
plugin registry: gplugin.NewRegistry(server) from
gplugin gives named plugins, a three-state lifecycle,
an observer and per-plugin start/stop; this package only defines what a plugin can plug
into.
Two runnable echo servers live under examples/, using the length-prefixed TCP
codec and the datagram codec from the quick start above:
go run ./examples/tcp-echo # listens on :9000
go run ./examples/udp-echo # listens on :9001Both bind the documented ports and log the actual listen address; stop them with Ctrl-C.
| Decision | Why |
|---|---|
Stdlib net backend first (goroutine per TCP connection) |
correct, portable, low dependency; IoT hubs commonly need tens of thousands of connections, which Go handles well |
| Standard-library-only RFC 6455 WebSocket | no external or legacy WebSocket dependency; separate handshake, frame codec and message/stream stages support fragmentation, control frames and bounded reads |
Optional gnet backend (roadmap) |
event-loop performance for 100k+ connections without changing the public API |
Explicit Codec / DatagramCodec |
Go has no annotation reflection pipeline; explicit codecs are testable and fast |
Session + Handler (OnOpen/OnMessage/OnClose) |
explicit lifecycle without a framework-specific pipeline |
IdleTimeout + Touch() |
covers heartbeat/keepalive at the transport layer |
- panjf2000/gnet — high-performance event-loop networking (Apache-2.0); planned optional backend.
See VERSIONING.md.
MIT. See LICENSE.