Zinx: Lightweight TCP Server Framework for Go

Concurrent TCP server framework with message routing and worker pools

Zinx is a concurrent TCP server framework written in Go. It is designed for developers who want to learn how server frameworks work internally and for teams building long-lived socket connections, such as game server backends or message forwarding systems. The framework handles connection management, worker pools, and message routing. Unlike general-purpose web frameworks, Zinx focuses purely on TCP connections and message dispatch. It has been used in enterprise systems for message forwarding in backend modules, game servers, and as a plugin handler for web frameworks.

Core architecture: connections, routers, and workers

A Zinx server manages incoming TCP connections and routes messages to handler code. You define a router by subclassing BaseRouter and implementing a Handle method that processes requests. The server assigns a message ID to each request type, and the router matches IDs to handler code via AddRouter(messageID, router). For concurrency, Zinx runs a worker pool: you set WorkerPoolSize in the config file to define how many goroutines process tasks concurrently. Each connection sends messages to the work queue, which executes handlers asynchronously. The server exposes lifecycle hooks via IConnection: onClientStart fires when a connection opens, allowing you to initialize per-connection state or start background tasks for that client, and onClientStop fires when the connection closes. You access the connection object from within a router's Handle method to send messages back to the client via conn.SendMsg(msgID, data). This pattern keeps application code simple and lets the framework manage goroutine lifecycle and resource cleanup.

Installing Zinx and your first server

Zinx requires Go 1.17 or later, though the current codebase uses Go 1.24.0. Install the package with go get:

go get github.com/aceld/zinx

Create a server by instantiating znet.NewServer and adding routers. Here is a minimal echo server:

package main

import (
	"fmt"
	"github.com/aceld/zinx/ziface"
	"github.com/aceld/zinx/znet"
)

type PingRouter struct {
	znet.BaseRouter
}

func (r *PingRouter) Handle(request ziface.IRequest) {
	fmt.Println("recv from client : msgId=", request.GetMsgID(), ", data=", string(request.GetData()))
}

func main() {
	s := znet.NewServer()
	s.AddRouter(1, &PingRouter{})
	s.Serve()
}

Run it with go run server.go, then connect a client to port 8999 (the default). The server prints each message it receives. The znet.BaseRouter base type provides default behavior, and your Handle method receives the request and can call request.GetMsgID() and request.GetData() to inspect the message. The framework is positioned with concise code that helps developers quickly understand the internal details of server frameworks and customize them for enterprise scenarios.

Configuration and deployment tuning

Zinx reads a JSON configuration file (usually from the working directory) that controls server behavior. The key fields are Name (application name), Host (bind address), TCPPort (listening port), MaxConn (maximum concurrent connections), and WorkerPoolSize (number of goroutines in the work queue). LogDir, LogFile, LogSaveDays, and LogIsolationLevel control logging. Setting MaxConn to 3 limits concurrent connections; WorkerPoolSize to 10 means up to 10 handler goroutines run in parallel. LogIsolationLevel controls verbosity: 0 logs everything, 1 suppresses debug, 2 suppresses debug and info, 3 suppresses debug, info, and warnings. The framework logs startup state and connection events, which you can silence or redirect by adjusting these fields.

Built-in features for production servers

Zinx includes websocket support via gorilla/websocket, KCP protocol support via xtaci/kcp-go for unreliable connection scenarios, and TLS encryption through Go's standard crypto library. Protobuf serialization is available through google.golang.org/protobuf if you import it. The framework provides interceptors for cross-cutting concerns like logging or authentication, and dynamic binding to attach handlers at runtime. Metrics collection is built in via examples in the repository. Async operations let you defer work outside the request handler. The architecture supports request-poll mode for flexible message processing patterns, connection lifecycle hooks (onClientStart and onClientStop), and message routing by integer message IDs. The framework logs connection events and startup state, which you can control through configuration. The examples directory includes working code for each of these: examples/zinx_websocket, examples/zinx_kcp, examples/zinx_tls, examples/zinx_protobuf, examples/zinx_interceptor, examples/zinx_metrics, examples/zinx_async_op, examples/zinx_RequestPollMode, examples/zinx_mutiport, and examples/zinx_heartbeat. The framework is positioned to help developers understand server internals and learn TCP server patterns through concise, readable code.

Limits and constraints

Zinx is a TCP framework and does not include HTTP routing, REST endpoints, or request-response patterns. If your protocol is synchronous request-reply over HTTP, reach for net/http or a framework like Gin or Chi. The framework has no built-in clustering or load balancing; each Zinx instance is independent. If you need multiple servers behind a load balancer, you must handle session affinity yourself. The worker pool is local and per-process; you cannot distribute work across machines. The framework works on a single machine per instance, so scaling requires running multiple processes and routing clients to them externally.

Comparison with raw Go networking

Go's standard library includes net.Listen for TCP servers and net.Dial for clients. Writing a server from scratch requires managing connections, parsing binary protocols, and dispatching to handler code. Zinx provides a router pattern, connection lifecycle hooks, and a worker pool out of the box, saving you from writing boilerplate. However, you trade flexibility for structure: routers must inherit BaseRouter and implement Handle, and messages must have an integer ID. If you need complete control over the connection loop or a custom concurrency model, the standard library may be simpler. Zinx assumes a message-ID-based protocol, which is not universal. The framework is designed for developers who want to learn server internals and understand how frameworks work internally, making it well-suited for educational purposes and custom long-linked applications where a message-ID protocol makes sense.

Recent releases and community support via Discord and Gitter

The last push to the master branch was on 2026-06-06, showing recent activity. Releases are published regularly: v1.2.8 in May 2026, v1.2.7 in June 2025, and v1.2.6 in August 2024. The project has documentation on the GitHub wiki and detailed tutorials in Chinese on Yuque. Developers can access online tutorials, video tutorials on Bilibili and YouTube, and documentation at zinx.me. Discord and Gitter channels provide community support. The MIT license permits commercial use without restriction. Zinx has been adopted in many enterprises for message forwarding, game backends, and web framework plugins.

Editorial conclusion

Choose Zinx if you are building a TCP server from scratch and want to understand every piece of the stack, or if you need a thin routing layer without the weight of enterprise frameworks. It is not for you if you need HTTP/REST or if you depend on features like load balancing or clustering built in. Before committing, verify that message routing via IRequest and the router pattern fit your protocol design.

Frequently asked questions

Official sources

1. aceld/zinx on GitHub
2. License: MIT
3. Project website
4. README
5. Releases