8000 GitHub - maxid/gnety: TCP/UDP transport framework for custom protocols in Go · GitHub
[go: up one dir, main page]

Skip to content
maxidPublic

About

TCP/UDP transport framework for custom protocols in Go

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

53 Commits

Folders and files

 
NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

English | 简体中文

gnety

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.

Positioning

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.

Scope

Planned / in progress

  • limits/timeouts: MaxSessions, MaxPendingRequests, WriteTimeout, ShutdownTimeout; explicit DTLS InsecureSkipVerify
  • 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

Quick start (TCP echo)

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,
})

Socket options

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.

Custom sockets

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.

Port helpers

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\"}"))

Extension points

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 type

hook.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.

Examples

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 :9001

Both bind the documented ports and log the actual listen address; stop them with Ctrl-C.

Design choices

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

References

  • panjf2000/gnet — high-performance event-loop networking (Apache-2.0); planned optional backend.

Versioning

See VERSIONING.md.

License

MIT. See LICENSE.

About

TCP/UDP transport framework for custom protocols in Go

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0