Core Capabilities
Understand the access, messaging, cluster, state, and operations capabilities currently provided by WuKongIM v3.
WuKongIM is Channel-oriented realtime communication infrastructure. It combines client access, per-Channel ordered messaging, distributed metadata, online routing, and operations under one cluster model.
Capabilities are not capacity promises
v3 is still Beta. Hardware, storage, replica count, Channel distribution, online fanout, and latency objectives all change effective capacity. This page documents semantics rather than a context-free maximum QPS.
Capability map
| Area | Current capability | Important boundary |
|---|---|---|
| Client access | TCP WKProto, WKProto/JSON-RPC over WebSocket, connection lifecycle, and bounded async dispatch | Gateway owns protocol and Session mechanics, not business permission or Channel authority |
| Messaging | Person, group, and custom Channels; ordered append, durable replication, idempotency, offline sync, and message-event projections | Ordering is per Channel; commit and online delivery are separate |
| Channel policy | Subscribers, denylist, allowlist, ban, disband, stranger policy, and system users | The business service still owns product relationships and content governance |
| User state | UID, device metadata, multi-device Sessions, distributed presence, and online routing | Concrete Sessions exist only on the connection-owner node |
| Conversations | Membership-backed recent views, badge floor, and delete visibility | A conversation is built at sync time, not persisted as a row |
| Cluster | Controller, 256 physical hash slots, logical Slot Raft Groups, Channel replicas, and failover | Every deployment is a cluster; a single-node cluster uses the same paths |
| Extensions | HTTP webhooks, node-local .wkp plugins, Send/Receive/PersistAfter hooks, and host RPC | Webhooks and post-commit hooks are not durable message queues |
| Operations | Manager, readiness, Prometheus, diagnostics, wkcli, wkdb, and wkbench | Mutations must respect authoritative state and safety fences |
Messaging semantics
A durable SEND appends at the Channel authority and waits for quorum durable commit before acknowledgement. Online delivery, webhooks, and post-commit plugins run later; their failure cannot roll back an already committed Channel log. Conversation views are constructed later from membership and Channel state.
client -> Gateway -> message usecase -> Channel authority
-> durable commit -> SENDACK
-> post-commit effectsApplications should retain a stable client_msg_no and make retry decisions from the returned outcome. Server message ID, per-Channel message_seq, and client message number are different concepts.
Designed for scale
- Ordering is per Channel, not global across all Channels.
- A 100,000-member group pages members and creates bounded delivery plans instead of loading the complete membership into one hot-path request.
- Gateway, Channel, delivery, and plugin work use bounded queues and backpressure. A larger queue increases worst-case wait; it does not replace capacity planning.
- High Channel cardinality is controlled through on-demand activation and idle eviction; durable messages do not depend on a runtime staying loaded.
- Performance conclusions should record throughput, P99, errors, queues, CPU, memory, disk, and network together.
What the application must provide
WuKongIM does not replace account login, product authorization, friendship or group business rules, content moderation, mobile platform push, the business database, or analytics. A typical business service issues identity credentials, maintains product relationships, calls protected server APIs, and consumes asynchronous events idempotently.
Continue with Use Cases to choose an architecture pattern, or enter Core Concepts for the shared vocabulary.