Onboarding: NetEase/pomelo

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/NetEase/pomelo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 23+ active contributors
• Distributed ownership (top contributor 33% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live NetEase/pomelo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/NetEase/pomelo.

What it runs against: a local clone of NetEase/pomelo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in NetEase/pomelo | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1030 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>NetEase/pomelo</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of NetEase/pomelo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/NetEase/pomelo.git
#   cd pomelo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of NetEase/pomelo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "NetEase/pomelo(\\.git)?\\b" \\
  && ok "origin remote is NetEase/pomelo" \\
  || miss "origin remote is not NetEase/pomelo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "lib/pomelo.js" \\
  && ok "lib/pomelo.js" \\
  || miss "missing critical file: lib/pomelo.js"
test -f "lib/application.js" \\
  && ok "lib/application.js" \\
  || miss "missing critical file: lib/application.js"
test -f "lib/components/connector.js" \\
  && ok "lib/components/connector.js" \\
  || miss "missing critical file: lib/components/connector.js"
test -f "lib/common/service/handlerService.js" \\
  && ok "lib/common/service/handlerService.js" \\
  || miss "missing critical file: lib/common/service/handlerService.js"
test -f "lib/components/remote.js" \\
  && ok "lib/components/remote.js" \\
  || miss "missing critical file: lib/components/remote.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1030 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1000d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/NetEase/pomelo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Pomelo is a distributed, multi-process game server framework for Node.js that enables fast, scalable real-time multiplayer game backends and live web applications. It provides a complete architecture (connectors, session management, RPC, message routing) to handle multiple player communication, state synchronization, and backend scaling across server clusters without boilerplate. Monolithic Node.js framework structured as lib/components/ (core subsystems: connector, session, channel, master, monitor, proxy, remote), lib/services/ (business logic: sessionService, channelService, handlerService, filterService), lib/connectors/ (protocol handlers: hybrid TCP/WebSocket switcher), and lib/common/ for shared utilities. Entry point is index.js wrapping lib/application.js which orchestrates server startup.

Who it's for

Game developers and backend engineers building mobile MMOs, social games, or real-time web apps who need a production-ready distributed server framework with built-in clustering, hot reload, and support for multiple client platforms (JavaScript, Android, iOS, Cocos2d-x, C, Flash).

Maturity & risk

Actively maintained but mature: version 2.2.7 with solid CI/CD (.travis.yml present), comprehensive test coverage via Grunt/Mocha, full npm ecosystem integration with pomelo-* satellite packages (pomelo-admin, pomelo-rpc, pomelo-protocol, pomelo-logger). This is production-grade software used in shipped games by NetEase.

Moderate risks: Socket.io 1.7.2 (released 2016) and some other dependencies are stale; no recent commit visibility in provided data so activity status unclear. ~414KB JavaScript codebase is non-trivial; single-maintainer (NetEase) risk typical for game frameworks. Breaking changes between v1 and v2 were significant per History.md.

Active areas of work

Based on repo structure, active areas include: hybrid connector improvements (tcpsocket.js, wsprocessor.js, switcher.js for TCP/WebSocket fallback), distributed session sync (backendSessionService.js, sessionService.js), channel broadcast optimization (channelRemote.js, channelService.js), and admin tooling integration (pomelo-admin dependency).

Get running

git clone https://github.com/NetEase/pomelo.git
cd pomelo
npm install
npm test

Daily commands:

node bin/pomelo

OR in development: npm test runs Grunt test suite. Actual game server startup depends on user-created app instance calling app.start() (see lib/application.js) with configured servers in config/servers.json.

Map of the codebase

• lib/pomelo.js — Main entry point and Application factory; initializes the entire framework and exposes core APIs like start(), configure(), and component loading
• lib/application.js — Core Application class managing server lifecycle, component registration, RPC routing, and configuration; every server instance uses this
• lib/components/connector.js — Base connector component handling client connections; critical for understanding how external clients communicate with game servers
• lib/common/service/handlerService.js — Routes incoming requests to appropriate handlers; essential for understanding request flow and handler dispatch
• lib/components/remote.js — RPC proxy for inter-server communication; enables distributed architecture and server-to-server calls
• lib/connectors/common/handler.js — Base handler for processing protocol messages and routing them through the filter pipeline
• lib/components/master.js — Master process component coordinating cluster topology, server registration, and lifecycle management

How to make changes

Add a Custom Game Handler

1. Create a new handler file in your game server handlers directory (e.g., template/game-server/app/servers/connector/handler/gameHandler.js) (template/game-server/app/servers/connector/handler/entryHandler.js)
2. Implement handler method (e.g., handle() and/or action methods) following the signature in lib/connectors/common/handler.js (lib/connectors/common/handler.js)
3. Register handler in your game server's app.js by requiring and mounting it in the handlerService (template/game-server/app.js)
4. Client requests will be routed by handlerService to your handler based on route pattern (e.g., 'game.battle.attack') (lib/common/service/handlerService.js)

Add a Custom Filter

1. Create a new filter in lib/filters/handler/ (e.g., myFilter.js) implementing before() and/or after() callbacks (lib/filters/handler/timeout.js)
2. Export filter with handle(msg, session, next) signature to intercept and process requests (lib/filters/handler/serial.js)
3. Register filter in your app by calling app.filter() during initialization, optionally specifying server type constraints (lib/application.js)
4. FilterService will execute all registered filters in order before/after handler execution (lib/common/service/filterService.js)

Enable Inter-Server RPC

1. In your handler, call app.rpc.<serverType>.<serviceName>.<methodName>(args, callback) to invoke remote server methods (lib/common/service/handlerService.js)
2. Remote component exposes RPC proxy dynamically; method calls are serialized and routed by pomelo-rpc (lib/components/remote.js)
3. Define RPC service methods in remote directory (lib/common/remote/backend/ or frontend/) matching your architecture (lib/common/remote/backend/msgRemote.js)
4. Master coordinates routing based on server type and server-id; if target not found, request fails to callback (lib/components/master.js)

Add Channel Broadcasting

1. In handler, get or create a channel via app.get('channelService').getChannel(channelName, true) (lib/common/service/channelService.js)
2. Add players to channel using channel.add(uid, sid) where uid is player ID and sid is session/connector server (lib/components/channel.js)
3. Broadcast message via channel.push(route, msg, opts) or channel.broadcast(route, msg) to all members (lib/components/channel.js)
4. Message is pushed through pushScheduler (direct or buffered) and delivered to all connected sessions (lib/components/pushScheduler.js)

Why these technologies

• Node.js + async — Single-threaded event loop provides high concurrency for I/O-bound game servers without thread overhead; async library manages callback chains
• Socket.IO + hybrid TCP/WebSocket — Provides fallback connectivity across browsers and mobile clients; hybrid connector enables native game clients to use efficient TCP while web uses WebSocket
• pomelo-rpc library — Custom lightweight RPC for inter-server communication; integrated service discovery and routing within Pomelo's cluster topology
• pomelo-protocol — Binary protocol compression reduces bandwidth for game messages; custom codec optimized for game server traffic patterns
• Multi-process master-worker — Bypasses Node.js single-thread limit; master coordinates cluster, workers handle specific server types (connector, game, chat)

Trade-offs already made

• Synchronous callback-based RPC instead of promises/async-await

  • Why: Codebase predates modern async patterns; compatible with older Node versions and existing plugin ecosystem
  • Consequence: Callback hell in complex request chains; difficult error handling; new code should use wrapper utilities

• In-memory session storage with optional backend sync

  • Why: Minimizes latency for game state queries; fast local access for hot data
  • Consequence: Session loss on connector crash; requires external persistence layer (Redis) for redundancy; not suitable for stateless scaling

• Master-worker singleton master process

  • Why: Simplifies cluster coordination and avoids split-brain; single source of truth for server topology
  • Consequence: Master is SPOF; if master dies, servers orphan; mitigation requires external watchdog or manual restart

• Filters execute sequentially (serial) by default

  • Why: Predictable execution order; easier debugging; prevents race conditions in shared state
  • Consequence: Filter overhead scales linearly with count; parallel filters require explicit opt-in

Non-goals (don't propose these)

• Database ORM or query layer (developers must use external db drivers)
• Built-in authentication or authorization (framework provides session container only)
• Horizontal session replication across regions (single-cluster only; no geo-distribution)
• Real-time file system persistence (state must be explicitly saved to external store)
• WebRTC or peer-to-peer connections (server-brokered only)

Traps & gotchas

Multi-process coordination via pomelo-admin: relies on master server component (lib/components/master.js) listening on admin port (default 3005); if not configured, clustering fails silently. Session serialization: backendSessionService.js expects session data to be JSON-serializable; circular references will break distributed session sync. Protocol version mismatch: pomelo-protocol 0.1.6 is hardcoded; client libraries must match exact version or handshake fails. No hot-reload by default: requires explicit reload() calls or plugin integration; naive code edits don't auto-restart. Sequential message processing: seq-queue enforces order; can cause bottleneck if handler functions block. WebSocket upgrade handshake is fragile: hybrid connector handshake.js protocol differs from Socket.io v1.7; custom clients must implement exact packet format.

Architecture

Concepts to learn

• Multi-process, single-thread architecture — Pomelo's core design trade-off: each process runs Node's single-threaded event loop independently, avoiding GIL issues but requiring explicit IPC/RPC for state sync across processes. Understanding this explains why session.push() and channel.broadcast() are async and why the proxy/RPC layer exists.
• Hybrid protocol switching (TCP fallback to WebSocket) — Pomelo's hybrid connector (lib/connectors/hybrid/switcher.js) attempts TCP first for low-latency games, falls back to WebSocket for browser/firewall compatibility. This is why tcpsocket.js and wsprocessor.js coexist and why handshake.js is critical — failures here break client connections.
• Frontend/Backend server role separation — Pomelo splits servers into 'frontend' (handles client connections) and 'backend' (runs game logic). Messages route through proxy.js RPC to backends; session state syncs via backendSessionService.js. This separation enables horizontal scaling of game logic independent of client count.
• Channel-based broadcast (pub/sub pattern) — Pomelo's channel component (lib/components/channel.js) groups players for efficient multicast. Instead of iterating player lists, messages target a channel; this is how 'all players in area' or 'raid group' broadcasts avoid O(n) iterations and reduce message overhead.
• Sequential queue for message processing — Pomelo uses seq-queue (dependency 0.0.5) to enforce ordered message handling per session/connection. Without this, race conditions would occur in game state (e.g., two movement commands reordered would cause position inconsistency). This is why handlers must not block — blocking stalls the entire queue.
• Protocol buffer (protobuf) encoding — Pomelo uses pomelo-protobuf 0.4.0 for compact binary message encoding between clients and servers. This reduces bandwidth vs JSON, critical for mobile games. The .proto file definitions define message structure; mismatches between client and server versions cause silent deserialization failures.
• Admin server and remote monitoring — Pomelo's master component and pomelo-admin dependency provide a separate admin server (distinct from game servers) for cluster inspection, code reloading, and metrics. This allows runtime updates without stopping game servers, but requires careful firewall isolation since admin port (3005) should not be exposed publicly.

Related repos

• colyseus/colyseus — Modern multiplayer framework alternative for Node.js; uses different RPC/state sync patterns (WebSocket + binary state diff) vs Pomelo's hybrid protocol, but serves same MMO/real-time game use case.
• gamesparks/GameSparks — AWS cloud-hosted alternative to self-hosted Pomelo for game backends; Pomelo is for on-premise or custom-cloud deployment where you control the full server architecture.
• NetEase/pomelo-admin — Official admin/monitoring companion to Pomelo; provides web UI for cluster inspection, hot-reloading, and metrics that depend on pomelo-admin 1.0.1 dependency in package.json.
• NetEase/pomelo-protobuf — Official binary serialization library for Pomelo (dependency pomelo-protobuf 0.4.0); handles protocol buffer encoding/decoding used by hybrid connector and message compression.
• NetEase/pomelo-rpc — Official RPC library (dependency pomelo-rpc 1.0.7); implements inter-server communication protocol used by lib/components/proxy.js and remote handlers.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for connector protocols (hybrid, MQTT, Socket.io)

The repo has multiple connector implementations (hybridconnector.js, mqttconnector.js, sioconnector.js, udpconnector.js) with complex protocol handling, but the test coverage appears minimal based on the gruntfile setup. These are critical for stability since connectors are the entry point for all client connections. Adding protocol-level tests would catch regressions early and improve confidence in protocol changes.

• [ ] Create test/connectors/ directory with separate test files for each connector type
• [ ] Add tests for lib/connectors/hybrid/tcpprocessor.js and lib/connectors/hybrid/wsprocessor.js message encoding/decoding
• [ ] Add tests for lib/connectors/common/coder.js and lib/connectors/common/handler.js with various message formats
• [ ] Test MQTT protocol generation in lib/connectors/mqtt/generate.js and lib/connectors/mqtt/protocol.js
• [ ] Update gruntfile.js to include new test suite in mochaTest configuration

Add unit tests for RPC filter pipeline and message routing (lib/filters/rpc/)

The lib/filters/rpc/ directory contains critical RPC filters (rpcLog.js, toobusy.js) and there are handler filters (serial.js, time.js, timeout.js, toobusy.js) that intercept requests. These filters form the backbone of message handling and routing but lack visible test coverage. Inadequate testing here can lead to silent failures in distributed RPC calls across server nodes.

• [ ] Create test/filters/rpc/ with tests for lib/filters/rpc/rpcLog.js filter chain behavior
• [ ] Create test/filters/handler/ with tests for lib/filters/handler/serial.js ensuring sequential execution
• [ ] Add timeout tests for lib/filters/handler/timeout.js to verify timeout enforcement
• [ ] Add tests for lib/filters/handler/toobusy.js load-shedding behavior under stress
• [ ] Add integration test for filter chain execution order in lib/common/service/filterService.js

Add integration tests for backend session and channel management across distributed nodes

The backend session (lib/components/backendSession.js) and channel (lib/components/channel.js) components are central to multi-node communication and state management. The corresponding remote handlers (lib/common/remote/backend/msgRemote.js, lib/common/remote/frontend/channelRemote.js, lib/common/remote/frontend/sessionRemote.js) likely lack integration tests. This is high-risk because session/channel desynchronization across nodes would be difficult to debug in production.

• [ ] Create test/integration/session-channel/ directory for distributed scenario tests
• [ ] Add tests simulating backend session push to verify lib/common/service/backendSessionService.js handles remote updates
• [ ] Add tests for channel broadcasts across multiple nodes using lib/common/remote/frontend/channelRemote.js
• [ ] Add tests for session binding/unbinding across nodes (lib/components/session.js state consistency)
• [ ] Test session cleanup and timeout propagation in distributed scenario

Good first issues

• Add unit tests for lib/connectors/common/coder.js (encoder/decoder). Current codebase has Mocha setup via Grunt but coder.js lacks dedicated test file — encoding/decoding bugs in protocol handling would be silent.
• Document the RPC contract: lib/common/remote/backend/ and /frontend/ have no JSDoc for which RPC methods are callable from which server types. Add explicit @rpc decorators and a docs/RPC_API.md file mapping remote methods to their arguments.
• Implement missing error handler in lib/components/pushScheduler.js: no test or example shows graceful degradation when push queue overflows under high load; add retry logic and backpressure handling.
• Add Connection object pooling documentation: lib/components/connection.js and lib/connectors/common/handler.js create connection objects per message; no visible object reuse or GC hints — investigate if object pooling would reduce GC pauses for large player counts.

Top contributors

• @fantasyni — 33 commits
• @py8765 — 27 commits
• @cynron — 12 commits
• @impcyber — 4 commits
• @ljhsai — 2 commits

Recent commits

• e1615c1 — update to 2.2.7 (fantasyni)
• e0de00a — Merge pull request #1150 from whtiehack/patch-1 (fantasyni)
• 5b999c5 — temporary fix #1149 (whtiehack)
• c534727 — update to 2.2.6 (fantasyni)
• defcf01 — Merge pull request #1128 from neuqzxy/zhouxinyu (fantasyni)
• d2b04a4 — Merge pull request #1133 from ljhsai/patch-9 (fantasyni)
• 0ff717b — Update .travis.yml (ljhsai)
• 2641d15 — fix: fix the bug while creating log dir (neuqzxy)
• 5f7bec1 — review some log messages (fantasyni)
• c808640 — resolve socket.io options error (fantasyni)

Security observations

• Critical · Severely Outdated Dependencies with Known Vulnerabilities — package.json - all dependency declarations. Multiple dependencies are several years old and contain known security vulnerabilities. Specifically: socket.io@1.7.2 (released 2017), ws@1.1.1 (2016), mqtt@0.3.9 (2013), async@0.2.5 (2011), and others. These versions have documented CVEs for XSS, DoS, authentication bypass, and protocol handling issues. Fix: Update all dependencies to their latest stable versions. Run 'npm audit' to identify specific CVEs. Priority updates: socket.io (to 4.x), ws (to 8.x+), mqtt (to 4.x+), async (to 3.x+). Implement automated dependency scanning in CI/CD pipeline.
• High · No Input Validation Framework Visible — lib/common/service/handlerService.js, lib/common/service/filterService.js, lib/connectors/common/handler.js. The codebase shows handler and filter services (handlerService.js, filterService.js) but no clear input validation or sanitization mechanisms. Game server frameworks handling user input are susceptible to injection attacks if validation is insufficient. Fix: Implement comprehensive input validation middleware. Use libraries like joi, yup, or validator.js. Validate all user inputs at connector/handler level. Implement whitelist-based validation rather than blacklist.
• High · MQTT Protocol Handler with Outdated Dependencies — lib/connectors/mqttconnector.js, lib/connectors/mqtt/. MQTT connector (lib/connectors/mqttconnector.js) uses mqtt@0.3.9, an extremely outdated library from 2013 with multiple security issues including authentication bypass and injection vulnerabilities. MQTT protocol handling is critical for IoT/realtime systems. Fix: Upgrade mqtt dependency to 4.x or 5.x. Review MQTT authentication implementation. Test against mqtt-specific security vulnerabilities. Consider using mqttjs or other actively maintained alternatives.
• High · Potential Unvalidated RPC/IPC Communication — lib/common/remote/, lib/components/remote.js, lib/common/remote/backend/msgRemote.js. Remote procedure call infrastructure (lib/common/remote/, lib/components/remote.js, pomelo-rpc dependency) and inter-process messaging lack visible authentication or message signing. Game servers with multiple distributed components are vulnerable to unauthorized RPC calls if not properly validated. Fix: Implement message signing/verification for all RPC calls. Add authentication tokens to inter-process communication. Use TLS for remote connections. Validate RPC caller identity before executing commands.
• High · WebSocket Implementation Using Outdated socket.io — lib/connectors/sioconnector.js, lib/connectors/siosocket.js, package.json. socket.io@1.7.2 (2017) has multiple documented security vulnerabilities including XSS issues, authentication bypasses, and protocol vulnerabilities. This is a critical attack surface for realtime game servers. Fix: Upgrade socket.io to 4.x or latest. Review security advisories for 1.7.2. Implement Origin validation for WebSocket connections. Add CSRF protection. Enable secure WebSocket (WSS) in production.
• Medium · Session Management Without Visible Token Validation — lib/common/service/sessionService.js, lib/components/session.js, lib/common/service/backendSessionService.js. Session services (lib/common/service/sessionService.js, lib/components/session.js, lib/components/backendSession.js) handle user sessions but no visible token expiration, validation, or secure storage mechanisms are evident in the structure. Fix: Implement secure session token generation using crypto. Add token expiration/rotation. Implement session invalidation on logout. Use secure cookie flags (HttpOnly, Secure, SameSite). Store session data server-side, not client-side.
• Medium · No Visible Rate Limiting on Handlers — lib/common/service/handlerService.js, lib/. Handler service and filters show timeout handling (lib/filters/handler/timeout.js) but no obvious rate limiting. Game servers need rate limiting to prevent DoS/brute force attacks on handlers. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.