How WeChat’s Mars Library Unified Mobile Networking Across Platforms

Background

In mid‑2012 WeChat supported Android, iOS and Symbian, but each platform had its own network implementation, causing incompatibilities and extra server‑side work. A unified network library was needed to ensure high availability, performance and load balancing across millions of users.

Unified component facilitated network research and optimization.

It accelerated multi‑platform development.

Design Principles

The component is built on the premises of cross‑platform and cross‑business use, following the principles of high availability, high performance and load balancing.

Network availability : weak‑network conditions, packet loss, limited bandwidth, latency fluctuations, third‑party influences are addressed by the STN module.

App availability : stability and runtime performance, as discussed in the high‑performance logging module xlog.

System availability : server‑side disaster recovery combined with client‑side local failover, enabling >95% user migration within 15 minutes.

High availability must not sacrifice performance; the library balances resource usage, especially for a heavily used app.

Load balancing also considers server load; IP selection uses random functions to avoid thundering‑herd problems.

Simple and balanced design is emphasized; for example, long‑link connection frequency is tuned for power, traffic, availability and user behavior.

Mars Evolution

Phase 1: Getting WeChat Running

The goal was to provide a stateless signaling channel between client and server, simplifying interfaces to encoding/decoding and auth queries. Example interface definitions are in stn_logic.h.

void StartTask(...);
int OnTaskEnd(...);
void OnPush(...);
bool Req2Buf(...);
int Buf2Resp(...);
bool MakeSureAuthed();

Initially a multithreaded model caused deadlocks; the solution moved to a message‑queue architecture with non‑blocking calls and a single‑direction API.

Phase 2: Refining the Core

Network metrics monitoring (SMC) was added, focusing on DNS anti‑hijacking, dynamic IP allocation, proximity access, disaster recovery, and fine‑grained socket optimizations such as connection strategies and multi‑level timeouts.

Platform‑specific optimizations: smart heartbeat for Android (alarm alignment) and iOS network handling.

Mobile‑specific tweaks: leveraging radio resource controller states for early activation of latency‑sensitive requests.

Phase 3: Tackling Edge Cases

Real‑world issues such as Wi‑Fi MTU limits, vendor‑specific crashes, and obscure network blocks were identified and resolved through code changes (e.g., forcing MSS = 1400, adjusting ANR detection, disabling client‑side gating when no network is present).

One long‑standing problem involved TCP timestamp manipulation during the three‑way handshake; the fix was to disable timestamps on the server.

Images illustrating debugging steps are shown below.

Mars Overview

The project was named “Mars” after the movie “The Martian”. The codebase was reorganized into three repositories: mars-open (public), mars-private (potentially open), and mars-wechat (WeChat‑specific).

Code Refactoring

Adopted Google style with lowercase, underscore‑separated identifiers; private functions prefixed with “__”, parameters with “_”. Business‑specific code such as newdns was extracted.

Build Options

For Android both dynamic (.so) and static (.a) libraries are provided; iOS builds a framework. Developers can customize logging, packet headers, and other interfaces.

Comparison with Other Libraries

Mars offers cross‑platform socket‑level networking, high‑performance logging, DNS extensions, and mobile‑centric optimizations, unlike HTTP‑based solutions such as Retrofit or OkHttp.

Conclusion

After years of iteration, Mars provides a robust, mobile‑focused networking stack that handles weak networks, platform quirks and large‑scale availability requirements. The code is now open‑sourced on GitHub, and further improvements will continue.

https://github.com/Tencent/mars