Socket.IO for Go: a server and client implementation in a multi-module repository

What this repository is, and what it is not

The project description is direct: Socket.IO for Go, a high-performance, feature-complete implementation supporting Socket.IO v4 and later, for real-time bidirectional communication over WebSockets and other transports. The README calls it a modern, idiomatic Go implementation.

The distinction that matters for an adopter is that this is not the JavaScript Socket.IO server. It is a second implementation of the same wire protocol, written in Go, maintained by zishang520. If your team writes its backend in Go and your frontend already uses the JavaScript client, this library is how the two talk to each other. If your backend is Node, the official JavaScript implementation is the straightforward choice and this repository solves a problem you do not have.

The language is Go, the licence is MIT, and the repository topics are `go`, `golang`, `socket-io`, `socket-io-server` and `websocket`. The last push to the default branch was on 2026-10-05, and the recent release tags are v3.0.6 on 2026-09-22, v3.0.5 on 2026-09-16 and v3.0.4 on 2026-06-11.

The project also has a clear support policy. The README says the Issues section is only for confirmed bugs or feature requests, and directs general help and implementation questions to the documentation and to a Discussions Q&A category. Vulnerabilities have their own path, with a Security Policy file and an explicit instruction not to file a public issue for a security problem. For a library that sits between a browser and your business logic, that separation between bug reports, questions and disclosure is the right shape.

Why the repository is split into eleven Go modules

The repository is a monorepo, and the README is explicit about it. The Makefile confirms the scope by listing the modules it iterates over: `parsers/engine`, `parsers/socket`, `servers/engine`, `servers/socket`, `adapters/adapter`, `adapters/mongo`, `adapters/postgres`, `adapters/redis`, `adapters/unix`, `adapters/valkey`, `clients/engine` and `clients/socket`.

Each is a separate Go module with its own import path, and the README describes what each one is.

The layering follows the protocol. The Engine.IO server is the low-level transport handling module, and the Socket.IO server is built on top of it. The client side mirrors that exactly, with an Engine.IO client and a Socket.IO client built on top. Above the servers sit the parsers, one for the Engine.IO protocol and one for the Socket.IO protocol.

The root module, `github.com/zishang520/socket.io/v3`, holds shared interfaces, types and base definitions. The adapter base module, `adapters/adapter`, is described as the base adapter interface for implementing broadcast mechanisms, and the concrete adapters for mongo, postgres, redis, unix and valkey sit next to it.

The practical effect of this layout is dependency control. A Go service that only serves Socket.IO does not need the client modules, and a Go test harness that only drives the client does not need the server. The `/v3` segment in every path is the Go module major version suffix, and it is the thing to look for when you are following an import path.

Two things in the tree suggest a larger structure than the README shows. There is a `pkg/` directory, and the Makefile points at `pkg/version/version.go` as the version file for the project, so version information is a first-class part of the build rather than a tag only.

Installing the server module and the adapter you need

The README points at the official documentation for examples, API references and guides, and then gives the module install commands directly.

For the server:

go get github.com/zishang520/socket.io/servers/socket/v3

The adapters are separate modules, each with its own command. The PostgreSQL adapter:

go get github.com/zishang520/socket.io/adapters/postgres/v3

The Valkey adapter:

go get github.com/zishang520/socket.io/adapters/valkey/v3

And the MongoDB adapter:

go get github.com/zishang520/socket.io/adapters/mongo/v3

The Makefile's module list adds two more that the README's install section does not show explicitly, `adapters/redis` and `adapters/unix`, so the full set of stores you can back a cluster with is larger than the four in the getting started commands.

There is a version-specific warning at the top of the README for anyone arriving from earlier code. If you are upgrading from v1 or v2 of the library, the README points to an Upgrade Guide in `docs/UPGRADE.md` for detailed instructions, including package replacements and migration steps. In a major version bump of a Go library, the package paths change and the import lines in your code change with them, so that document is the first thing to read, not an afterthought.

The repository also has a `docs/` directory at the top level and an `examples` entry, so the working code lives alongside the modules.

What the dependency list says about the transports

The root `go.mod` is short and specific, and it is the best evidence of what this implementation actually speaks.

It declares Go 1.26.0 as the language requirement, which is a high floor and worth checking against your build environment before anything else.

The direct dependencies are `github.com/gorilla/websocket` at v1.5.3 for the WebSocket transport, `github.com/quic-go/quic-go` at v0.62.0 and `github.com/quic-go/webtransport-go` at v0.13.0 for QUIC and WebTransport, `github.com/andybalholm/brotli` and `github.com/klauspost/compress` for compression, `github.com/vmihailenco/msgpack/v5` at v5.4.1 for the MessagePack binary protocol, `resty.dev/v3` at v3.0.0-rc.4 as an HTTP client, and `github.com/gookit/color` for terminal output.

Three things follow from that list. First, the implementation is not WebSocket-only, which matches the description mentioning WebSockets and other transports; the QUIC and WebTransport dependencies show modern transports are supported alongside the classic one. Second, the MessagePack dependency means binary protocol encoding is a first-class path, not an afterthought, which matters for throughput-sensitive clients. Third, the compression libraries indicate payload size is treated as a real cost rather than left to the network.

The `resty.dev/v3` dependency is pinned to a release candidate, `v3.0.0-rc.4`, and it is used for outgoing HTTP requests, which is how a server-side component would talk to an external service such as a push provider or a webhook target. Depending on a release candidate in a production path is a choice you should make consciously rather than inherit by accident.

The indirect dependencies are the usual supporting cast, including `golang.org/x/crypto` at v0.57.0, `golang.org/x/net` at v0.59.0 and `go.uber.org/mock` at v0.6.0 for testing.

Adapters are how a multi-instance deployment works

Socket.IO's server holds connection state in memory, which is fine for one process and a problem for several. The adapter layer is the answer, and this repository treats it as a first-class extension point rather than a plugin bolted on.

The base module `github.com/zishang520/socket.io/adapters/adapter/v3` is described as the base adapter interface for implementing broadcast mechanisms. That is the contract: a store-backed implementation of the interface lets a node tell the other nodes that a room, a namespace or a single socket has something to receive. The concrete adapters for mongo, postgres, redis, unix and valkey implement it against stores you are likely to already run.

The `unix` adapter is the interesting one, because it does not need a separate service. A Unix domain socket between processes on the same machine is a plausible way to share broadcast state across several instances of a Go service without adding a Redis or Postgres dependency, and the presence of that module in the Makefile list suggests the project treats local multi-process as a case worth supporting.

There is a further signal in the dependency list: the `github.com/gorilla/websocket` and `github.com/quic-go/quic-go` combination plus the presence of a `pkg/` directory suggest the transport layer is factored so that different transports can be plugged beneath the Socket.IO protocol. The README's own description of the server module as built atop the Engine.IO server matches that picture.

The practical question for a team running more than one instance is which store you will use. The adapter choice is a deployment decision with a cost: a shared store becomes part of your availability story, and the Redis or Valkey adapter means your real-time layer now depends on that service being up.

The build system and the module iteration pattern

The Makefile is unusual enough to be worth describing, because it shows how a monorepo of eleven modules is kept consistent.

It sets `SHELL := /bin/bash` and silences make's directory printing with `MAKEFLAGS += --no-print-directory`, and the default goal is `help` rather than a build, so a bare `make` gives you the target list. The GOPROXY is exported as `https://proxy.golang.org,direct`, which pins the module proxy the build uses.

The module list is defined once as the `MODULES` variable, and the scope logic sets `SCOPE` to a single module if you pass one in, otherwise to the root plus all modules. Everything then runs through a macro named `EXECUTE`, described in a comment as safe iteration with fail-fast logic, which takes a label and a command and loops over the scope, skipping directories that do not exist with a warning and aborting with a non-zero exit if any module fails.

That fail-fast behaviour is the point. A monorepo where one module passes its checks while another silently does not is worse than no check at all, and the macro makes the whole set a single unit of verification.

The file also uses ANSI colour codes for its output, with named variables for reset, cyan, green, red and yellow, and the project version is read from `pkg/version/version.go` rather than being written in two places.

For contributors, the README asks that changes be well tested and formatted with `make fmt`, and that you open an issue or discussion before starting major changes. The repository also carries `make.bat` alongside the Makefile, so the same targets are reachable on Windows.

Where a Go implementation of Socket.IO is the wrong choice

The clearest wrong-tool case is a Node backend. If your server is JavaScript or TypeScript, the official Socket.IO implementation is the one with the deepest integration with the JavaScript client, the first-party ecosystem around it, and the documentation that everyone else has read. Reimplementing the protocol in Go to then interoperate with a JavaScript client adds a second source of protocol behaviour to reason about, and the interoperability bugs you will hit will be in the layer you cannot read.

The second case is a protocol mismatch rather than a language one. This implementation supports Socket.IO v4 and later. If the clients you must serve are pinned to an earlier protocol generation, or if you need features outside the v4 protocol as this implementation covers it, you need to check the compatibility notes rather than assume it.

The third is operational. The dependency list includes a release candidate of an HTTP client library, and the module requires Go 1.26.0. A conservative production environment pins its dependencies and its toolchain, and a release candidate plus a very new Go release are two moving parts at once.

The fourth is the cost of writing and running your own Socket.IO client, if your Go services need to talk to each other. The client modules exist, and the protocol is documented, so it is possible. But a Go service talking to another Go service has better options, such as gRPC, where both ends share one generated contract rather than a protocol implemented twice.

The alternative worth naming, then, is a plain WebSocket or Server-Sent Events server written directly in Go. The difference in approach is real: Socket.IO gives you rooms and namespaces, connection recovery and acknowledgements, and a client that ships with the browser ecosystem, at the cost of a protocol layer, its adapter machinery and its dependency surface. A raw WebSocket server gives you a duplex byte stream and nothing else, which is all you need if your messages are point to point and you are willing to write the reconnect and heartbeat logic yourself.

Editorial conclusion

Adopt this repository when your backend is Go and your browser clients are Socket.IO, when you want the protocol handled in Go rather than through a Node sidecar, and when you need horizontal scaling, because the adapter modules are the reason a multi-instance deployment works. Do not adopt it if you are building a Node or TypeScript service, since the official JavaScript implementation already covers that case, and do not adopt it without reading the upgrade guide if you are moving from v1 or v2, since the module paths carry a `/v3` segment. Before you start, check that your Go toolchain is 1.26.0 or later as the root module requires, confirm that your chosen adapter matches the store you already run, and read `docs/UPGRADE.md` if you are carrying code from an earlier major version.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zishang520/socket.io on GitHub