Networking & Client Access
Use a connection diagram to separate listeners, published addresses, and private management access.
Listen address: where this node accepts connections. Published address: where others connect. Match domains, ports, and TLS to the actual network path.
This example terminates WSS at a TLS proxy and forwards WS upstream. Route the external /ws path correctly. The trusted backend accesses the WuKongIM HTTP API to obtain client routing.
Traffic planes
| Who connects | Entry to use |
|---|---|
| Clients | Controlled TCP / WS / WSS edge; reachable from client networks |
| Business backend | WuKongIM HTTP API on a trusted network or behind external auth |
| Peer nodes | Private Transport with bidirectional reachability |
| Admins and collectors | SSH / private Manager access; metrics and diagnostics restricted |
Complete traffic, field, and production-boundary reference
| Traffic | Primary configuration | Consumer | Production boundary |
|---|---|---|---|
| Inter-node Transport | cluster.listen_addr, static nodes[].addr, or cluster.advertise_addr | Other WuKongIM nodes | Restrict to the cluster network and require bidirectional reachability |
| WuKongIM HTTP API | api.listen_addr | Business backends, health checks, observability collectors | Place on a trusted network or behind external authentication |
| Client Gateway | gateway.listeners | TCP and WebSocket clients | Expose through a controlled edge and enforce connection capacity |
| Client discovery | api.external_tcp_addr, external_ws_addr, external_wss_addr | Callers of /route | Reachable from every target client network |
| Manager | manager.listen_addr | Administrators and automation | Loopback or management network only; use SSH tunneling or a private HTTPS proxy and keep authentication enabled |
| Prometheus | prometheus.listen_addr or an external service | Manager and collectors | Never expose directly to the Internet |
Listen is not advertise
| Address purpose | Value in this example |
|---|---|
| Node WS listener | 0.0.0.0:5200 |
| Client WSS address | wss://im.example.com/ws |
| Peer address | Real private host and port; never wildcard or loopback |
Static peers use nodes[].addr; seed joining uses cluster.advertise_addr. Client fields api.external_* may point to a proxy; configure its reachable ports and TLS separately.
Complete TOML example and TLS forwarding notes
0.0.0.0 and [::] are useful wildcard listeners, but they are not routable peer or client destinations. Static clusters use nodes[].addr for peer connections; seed joining uses cluster.advertise_addr. Those values need stable, resolvable, reachable hosts and ports.
Client-advertised fields describe the address clients ultimately use, which may be a load balancer or edge proxy:
[api]
listen_addr = "0.0.0.0:5001"
external_tcp_addr = "im.example.com:5100"
external_wss_addr = "wss://im.example.com/ws"
[gateway]
listeners = [
{ name = "tcp", network = "tcp", address = "0.0.0.0:5100", transport = "gnet", protocol = "wkproto" },
{ name = "ws", network = "websocket", address = "0.0.0.0:5200", transport = "gnet", protocol = "wsmux" }
]The names and ports are structural examples. If a load balancer, reverse proxy, or service mesh terminates TLS, still verify the external WSS address, certificate, host and path forwarding, and upstream protocol together.
Exposure policy
WuKongIM HTTP API needs an external trust boundary
WuKongIM HTTP API routes do not validate general business identity. Use a trusted network or external auth. Public ingress contains only required client ports and a protected API. Keep Manager auth on; use loopback, private networking, or SSH.
Restrict Transport, metrics, debug, benchmark, and diagnostics separately. A shared HTTP listener does not imply equal trust.
Full exposure policy and health-check distinction
- Public ingress should contain only required client ports and a protected WuKongIM HTTP API.
- Give node Transport, Manager,
/metrics,/top/v1/*,/debug/pprof/*, Benchmark, and diagnostics separate network policies. Sharing an HTTP listener does not give them the same trust level. - WuKongIM HTTP API routes do not provide general business identity validation. Establish that boundary with a trusted network, API gateway, or external authentication proxy.
- Load balancers must use
/readyzfor traffic admission./healthzonly proves process liveness and cannot prove the node is ready to serve.
Validate before publishing
| Check | Required result |
|---|---|
| Peer network | Every peer-advertised address is reachable both ways |
| Backend and client networks | Backend reaches the API; clients reach every /route result |
| Handshake and proxy | TCP / WS / WSS, TLS chain, host / path, and idle timeouts work |
| Unauthorized networks | Manager, metrics, debug, benchmark, and diagnostics stay unreachable |
| Each node | /readyz returns 200 with ready: true before pool admission |
/healthz proves only process liveness; it cannot replace readiness checks.
Full validation steps before publishing
- Test bidirectional Transport connections from each node to every peer-advertised address.
- Reach the HTTP API from the business network and every
/routeresult from the target client network. - Verify TCP, WS/WSS handshakes, the TLS chain, timeouts, and proxy idle-connection policy.
- Confirm Manager, metrics, debug, benchmark, and diagnostic endpoints are unreachable from unauthorized networks.
- Check
/readyzper node and admit only nodes returning200withready: true.
Once paths are explicit, use Security & Access to constrain credentials and administrative surfaces.