Framework
aceld/zinx avatar
aceld/zinx

aceld/zinx: a lightweight Go TCP server framework you can read end to end

A lightweight concurrent server framework based on Golang.

7,767 stars1,262 forksGoMIT

At a glance

What is it?
Zinx is a Go framework for long-lived TCP connections, built so that the whole request path stays small enough to read and modify. It fits game backends and message forwarding; it does not replace a full RPC or HTTP stack.
Who is it for?
Adopt zinx when you need a TCP or long-connection server whose routing, worker pool and packet framing you can read in an afternoon and change without fighting an abstraction layer. Skip it if your service is request-response HTTP or gRPC.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 24 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • aceld/zinx7,767 ★ · +2
Star history
Repository2026-09-222026-11-15
aceld/zinx7.8k7.8k

2 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What zinx is for, and who ends up using it

The README is explicit about the gap zinx was written to fill: there are many Golang server frameworks, but few lightweight ones aimed at gaming and other long-linked fields. The stated purpose is to give a complete outline of how to write a TCP server in Go, so that developers can learn the area directly. That framing matters when you decide whether to adopt it. Zinx is not positioned as a general application framework. It is positioned as a framework whose code you can read in full, and the README says this is deliberate: the project is developed alongside a tutorial series, with each version adding a small increment of functionality so a beginner is not handed a finished framework all at once.

The README also lists where the project says it is already used in production: message forwarding for backend modules, long-linked game servers, and message handling plugins for web frameworks. Those three uses share a shape. A client holds a connection open, sends framed messages, and expects a handler to run per message. If that is your shape, the framework's vocabulary (connection, request, router, message ID) will match your problem. If your service is a REST API, a gRPC service or a batch job, the vocabulary will not match, and you will spend your time working around the framework rather than with it.

The request path: connection, message ID, router

The unit of work in zinx is the request. The quick start example registers a router against an integer message ID and implements a Handle method that receives a ziface.IRequest. Inside that method, request.GetMsgID() returns the ID and request.GetData() returns the payload bytes. Routing is therefore a map lookup from message ID to handler, not path or method matching.

The README's configuration file example shows the settings the server builds around that map: Name, Host, TCPPort, MaxConn, WorkerPoolSize, LogDir, LogFile, LogSaveDays, LogCons and LogIsolationLevel. WorkerPoolSize, set to 10 in that example, is the maximum number of working goroutines in the work task pool, and MaxConn is the maximum number of client links allowed.

The repository layout confirms the split of concerns: ziface holds interfaces, znet holds the networking implementation, zpack handles packet packing, zdecoder handles decoding, zconf holds configuration, zlog holds logging, ztimer holds timers, and zinterceptor holds interceptors. There is also a zasync_op package and an examples/zinx_async_op directory, plus examples/zinx_RequestPollMode, which suggests more than one way to dispatch requests. Read the example code before assuming the default dispatch is what you want.

Installing zinx and running a first server

The README gives the install step as a go get against the module path, with a note that Golang 1.17 or later is required. The repository's go.mod declares go 1.24.0, so the module itself is built against a newer toolchain than the README's stated floor.

bash
go get github.com/aceld/zinx

After that, the quick start defines a server in three steps: create the service, register a router for message ID 1, and call Serve. The router embeds znet.BaseRouter and overrides Handle.

go
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()
}

Running it with go run server.go prints the ASCII banner. In the README's client example the client connects to 127.0.0.1 on port 8999, and the server prints a recv from client line with msgId= 1 for each ping. The README also links a separate TCP debugging tool, tcptest, for sending test frames. Ports and limits come from the configuration file; the README's example file sets TCPPort 9090, MaxConn 3 and WorkerPoolSize 10.

Where zinx stops being the right tool

The clearest limitation is the one the project states about itself. The README describes zinx as positioned for concise code that lets developers understand the framework internals and customize it for their own enterprise scenarios. That is an invitation to fork and adapt, and it is also a warning: the framework expects you to reach into it. If your team wants a dependency that stays behind a stable interface and never needs reading, zinx is the wrong shape.

The second limitation is transport scope. The README's quick start is a TCP server, and the examples directory contains separate directories for KCP (examples/zinx_kcp), WebSocket (examples/zinx_websocket), TLS (examples/zinx_tls) and protobuf (examples/zinx_protobuf). The go.mod pulls in github.com/gorilla/websocket and github.com/xtaci/kcp-go, which confirms those transports exist in the module. Treat each transport as its own integration until the example says otherwise.

The third is operational. The configuration file exposes LogDir, LogFile and LogIsolationLevel, so logging is configurable, and there is a zlog package. There is also an examples/zinx_metrics directory.

How zinx differs from a general Go server framework

A framework like Gin or Echo solves HTTP: the transport is fixed, the routing key is a method plus path, and the framework owns the request lifecycle from accept to response. Zinx inverts that. The transport is a parameter you choose (TCP by default, with KCP, WebSocket and TLS examples in the tree), the routing key is an integer message ID you define, and the framework hands you a request object and expects you to decide what happens next. There is no response writer, no middleware chain in the HTTP sense, and no status code convention.

The closer comparison is net/http's bare server loop, or a hand-rolled accept loop with a worker pool. Zinx packages exactly that: an accept path, a connection abstraction, a packet codec in zpack and zdecoder, a fixed worker pool, and a router registry. The difference from writing it yourself is that the pieces are already separated into packages with interfaces in ziface, so you can replace the codec or the logger without rewriting the accept loop. The difference from a heavier game server framework is that zinx does not appear to ship a scene graph, a matchmaker, a persistence layer or an entity replication model. It is the connection and dispatch layer, and the README's list of enterprise uses (message forwarding, long-linked game servers, web framework plugins) is consistent with that narrower scope.

Maintenance, licence and what an upgrade costs

The repository is not archived, and the last push was on 2026-10-22. Releases are spaced unevenly: v1.2.6 on 2024-08-09, v1.2.7 on 2025-06-30, and v1.2.8 on 2026-05-04. That is roughly one release a year, so plan for a slow cadence and do not expect a fix to land on your schedule. The go.mod requires Go 1.24.0 while the README states Go 1.17 or later, which is the kind of drift that bites when you build in an older CI image: your toolchain, not the framework's API, will be what fails first.

The licence is MIT, and the LICENSE file is at the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. It also means there is no patent grant clause and no trademark grant, which matters if you plan to ship zinx inside a product under your own name. That is a description of what the licence text does, not legal advice; have your own counsel review it if the distinction affects your distribution.

Upgrade cost is driven by the same property that makes zinx readable. Because the framework is meant to be customized, a local fork will diverge. Before upgrading across a minor version, diff the ziface package and the znet package against your fork.

Editorial conclusion

Adopt zinx when you need a TCP or long-connection server whose routing, worker pool and packet framing you can read in an afternoon and change without fighting an abstraction layer. Skip it if your service is request-response HTTP or gRPC. Before committing, check the last push date of 2026-10-22 against your own release cadence, and read the examples directory for the transport you actually plan to use: zinx_kcp, zinx_websocket and zinx_tls each have their own example.

Frequently asked questions

What Go version does zinx require?

The README states Golang Version 1.17 or later for the go get step, while the repository's go.mod declares go 1.24.0. Building the module as published therefore needs a newer toolchain than the README's stated floor.

How do I register a handler for a message type in zinx?

You define a router that embeds znet.BaseRouter and overrides Handle, then call AddRouter with an integer message ID and an instance of that router. Inside Handle, request.GetMsgID() gives the ID and request.GetData() gives the payload bytes.

Does zinx support WebSocket or KCP instead of plain TCP?

The examples directory contains zinx_websocket, zinx_kcp and zinx_tls, and go.mod depends on gorilla/websocket and kcp-go. Read the example for the transport you plan to use.

Official sources

  1. aceld/zinx on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/aceld-zinx.svg)](https://hysenlabs.com/projects/aceld-zinx)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/aceld-zinx.svg)](https://hysenlabs.com/projects/aceld-zinx)

Was this useful?