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/Tencent/mars 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.

WAIT — Slowing — last commit 8mo ago

• Last commit 8mo ago
• 7 active contributors
• Other licensed
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

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

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

What it runs against: a local clone of Tencent/mars — 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 Tencent/mars | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 270 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/mars. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/mars.git
#   cd mars
#
# 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 Tencent/mars and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "mars/CMakeLists.txt" \\
  && ok "mars/CMakeLists.txt" \\
  || miss "missing critical file: mars/CMakeLists.txt"
test -f "mars/app/app_manager.h" \\
  && ok "mars/app/app_manager.h" \\
  || miss "missing critical file: mars/app/app_manager.h"
test -f "mars/app/app_logic.cc" \\
  && ok "mars/app/app_logic.cc" \\
  || miss "missing critical file: mars/app/app_logic.cc"
test -f "mars/baseevent/baseevent.h" \\
  && ok "mars/baseevent/baseevent.h" \\
  || miss "missing critical file: mars/baseevent/baseevent.h"
test -f "mars/app/src/traffic_statistics.h" \\
  && ok "mars/app/src/traffic_statistics.h" \\
  || miss "missing critical file: mars/app/src/traffic_statistics.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 270 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~240d)"
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/Tencent/mars"
  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).

Mars is a production-grade cross-platform network infrastructure component developed by WeChat that handles billions of user connections. It provides low-level primitives (socket, thread, message queue, coroutine) plus high-level components: Xlog (reliable high-performance logging), SDT (network detection), and STN (signaling network)—optimized for mobile with minimal power and traffic consumption. Monorepo with four core modules under mars/: comm/ (sockets, threads, queues, coroutines), baseevent/ (event loop abstraction with JNI bridge), app/ (application lifecycle and traffic stats with Android JNI wrappers), boost/ (vendored Boost headers). Each module has parallel src/, jni/, and CMakeLists.txt structure. Platform-specific code isolated in subdirs like mars/app/src/wp/ (Windows Phone legacy).

Mobile app developers (iOS, Android, Windows, macOS) building messaging, push, or real-time systems who need battle-tested network infrastructure. WeChat Mobile Team contributors and enterprises deploying cross-platform communication stacks at scale.

Highly mature production code. Actively maintained (v1.2.5 current release), proven in billions of WeChat deployments. Strong multi-platform CMake/Meson build system, JNI bindings for Android, and modular architecture (comm, xlog, sdt, stn). Last major platform target was Android NDK r20 and VS2015—slightly aged but stable.

Complexity risk: 24MB of C++, 7.5MB of C, low-level socket/thread/IPC code requires careful review. Heavy platform-specific code (JNI wrappers, Objective-C++ for iOS, Windows platform_logic) increases maintenance surface. Build system maturity varies (CMake vs legacy Meson/M4 config). No obvious recent activity data shown in file structure.

File structure shows completed Android/iOS/Windows support and legacy Windows Phone code. No active development metadata visible in provided data, but repo is stable release v1.2.3–1.2.5. Suggests maintenance mode with focus on production reliability rather than new features.

git clone https://github.com/Tencent/mars.git
cd mars
# Requires Python 3.10+
python3 --version
# Build with CMake (primary, cross-platform)
mkdir build && cd build
cmake ..
make
# Or platform-specific: iOS/macOS, Android NDK r20+, Windows VS2015+

Daily commands:

# Android (NDK r20+): use Android.mk or CMakeLists.txt
cd mars/android
# iOS/macOS: Xcode integration via CMake
cmake -G Xcode -DCMAKE_SYSTEM_NAME=iOS
# Windows (VS2015+): Visual Studio project generation
cmake -G "Visual Studio 14 2015" .
# Linux/native build
make -C build

• mars/CMakeLists.txt — Root CMake configuration that orchestrates the entire cross-platform build system for iOS, Android, macOS, and Windows.
• mars/app/app_manager.h — Core application manager interface; entry point for all app lifecycle and initialization logic across platforms.
• mars/app/app_logic.cc — Main application logic implementation containing startup, shutdown, and platform-specific initialization routines.
• mars/baseevent/baseevent.h — Foundation event system abstraction; all networking and messaging components depend on this event interface.
• mars/app/src/traffic_statistics.h — Traffic and resource monitoring interface critical for mobile optimization and diagnostics.
• mars/boost/CMakeLists.txt — Boost library bundling strategy that Mars relies on for cross-platform compatibility and utility functions.
• README.md — Defines Mars as WeChat's proven cross-platform infrastructure for low-power, low-traffic mobile networking.

• AppManager (C++, JNI (Android)) — Orchestrates lifecycle (init, start, stop, deinit) and delegates platform initialization; public API entry point.
  • Failure mode: If AppManager fails to initialize, entire Mars subsystem is unav

Add a New Event Type

1. Define the event structure in mars/baseevent/baseprjevent.h by extending the base event class and adding your event fields (mars/baseevent/baseprjevent.h)
2. Implement event handling logic in mars/baseevent/src/baseprjevent.cc, registering the event handler and dispatch mechanism (mars/baseevent/src/baseprjevent.cc)
3. If platform-specific handling needed, add JNI wrapper in mars/baseevent/jni/com_tencent_mars_BaseEvent.cc for Android integration (mars/baseevent/jni/com_tencent_mars_BaseEvent.cc)

Add Traffic Monitoring for a New Component

1. Extend mars/app/src/traffic_statistics.h with new statistics fields and accessor methods (mars/app/src/traffic_statistics.h)
2. Implement statistics collection in mars/app/src/traffic_statistics.cc by hooking into network/resource calls (mars/app/src/traffic_statistics.cc)
3. Expose metrics via JNI in mars/app/jni/app_manager_callback_wrapper.cc if Android integration required (mars/app/jni/app_manager_callback_wrapper.cc)

Port Mars to a New Platform

1. Create platform-specific logic file (e.g., mars/app/src/wp/platform_logic_newos.cpp) following the pattern in platform_logic.cpp (mars/app/src/wp/platform_logic.cpp)
2. Add platform initialization hooks to mars/app/app_logic.cc within conditional compilation blocks (mars/app/app_logic.cc)
3. Update mars/CMakeLists.txt and mars/app/CMakeLists.txt to conditionally compile and link platform-specific code (mars/CMakeLists.txt)
4. If the target platform is Java-based, implement JNI wrappers in mars/app/jni/ following existing Android patterns (mars/app/jni/app_manager_wrapper.cc)

• CMake (cross-platform build) — Enables single codebase deployment across iOS, Android, macOS, and Windows without platform-specific build scripts; Mars serves billions of WeChat users across all major mobile/desktop platforms.
• C/C++ core + JNI bridges — C/C++ provides low-level network control and minimal power overhead critical for mobile; JNI enables Android app integration without rewriting in Java.
• Event-driven async architecture — Non-blocking event dispatch is essential for mobile where threads and power budgets are limited; WeChat's billions of users require scalable concurrent message handling.
• Bundled Boost (selective) — Provides proven cross-platform algorithms and utilities (string, algorithm, atomic ops) while minimizing binary size through selective compilation.
• Traffic monitoring as first-class concern — Mobile apps are bandwidth and power constrained; Mars bakes in statistics collection from the ground up to help developers optimize.

• Bare C/C++ implementation rather than Swift/Kotlin abstractions

  • Why: Enables single codebase across all platforms; avoids rewriting core logic per language.
  • Consequence: Higher barrier to entry for pure mobile developers; requires JNI expertise for Android integration; but ensures consistency and minimal overhead across platforms.

• Event-based async model rather than synchronous request/response

  • Why: Non-blocking dispatch prevents thread starvation and reduces power draw on mobile.
  • Consequence: Higher complexity for call sites (async callbacks instead of blocking calls); but required for billions of concurrent users with limited device resources.

• Bundle Boost rather than rely on system libraries

  • Why: Guarantees consistent algorithms across platforms; avoids platform version fragmentation.
  • Consequence: Larger library footprint; must manually update Boost versions; but ensures deterministic behavior on WeChat's heterogeneous global userbase.

• Does not provide application-layer protocol definition (e.g., message serialization formats); Mars is transport infrastructure only.
• Does not implement HTTP client—Mars predates and complements HTTP; suitable for small-packet, high-frequency messaging.
• Does not handle TLS/crypto directly; assumes integration with OS-level security; Mars focuses on transport efficiency.
• Not a replacement for native platform APIs; Mars is a thin, low-level networking layer for WeChat's use case, not a general-purpose mobile framework.

Build requires Python 3.10+ (enforced by build scripts). Android builds require NDK r20 specifically (noted in README—version constraints can break older setups). JNI code has tight coupling between C++ and Java—modifying signatures requires synchronized updates in .cc and Java wrapper files (mars/app/jni/ and corresponding Java classes). Boost headers are vendored; updates require manual sync. Platform-specific code paths (Windows Phone legacy in mars/app/src/wp/) still present but unmaintained—avoid modifying unless necessary. No visible package.json or requirements.txt—pure CMake/Make, so IDE integration needs manual toolchain setup.

• Signal Network (STN) Protocol — Core feature of Mars—custom reliable transport layer for mobile messaging; understanding its design helps explain why custom implementation beats HTTP for WeChat's use case
• Memory-mapped I/O (in Xlog) — Xlog uses mmap for high-performance logging without blocking—critical for understanding why Mars can log billions of events efficiently
• Coroutine-based Async (in comm/) — Mars implements coroutine abstractions (likely stackful) to hide async complexity; essential for understanding how STN achieves low power consumption
• JNI (Java Native Interface) Bridge Pattern — Android integration relies on careful JNI callback marshaling (mars/app/jni/); improper binding can crash the app or leak resources
• Traffic Statistics & Quota Management — mars/app/src/traffic_statistics.cc implements metered network usage tracking—core for mobile where data plans are expensive
• Event Loop & Lifecycle Integration — Mars's baseevent module integrates into app lifecycle (app_manager.h); understanding this integration prevents initialization races and dangling sockets
• Platform-Abstraction Layer (PAL) — Mars achieves cross-platform with ifdef guards and platform-specific subdirectories (mars/app/src/wp/); critical pattern for understanding how to add new platforms

• grpc/grpc — High-performance RPC framework for mobile/cloud; similar use case for reliable cross-platform communication but uses HTTP/2 instead of custom signaling protocol
• facebook/Fizz — Facebook's TLS library; Mars uses custom encryption in STN; Fizz offers alternative for TLS layer but doesn't replace full stack
• Tencent/wcdb — Tencent's companion project for efficient mobile database; often used alongside Mars for local persistence of network state
• skywind3000/kcp — Alternative UDP-based reliable transport protocol; Mars's STN uses TCP/custom protocol; KCP shares similar low-latency mobile goals
• asyncio/boost.asio — Boost.Asio is Mars's async I/O inspiration for cross-platform socket handling; Mars vendored parts and implements similar patterns

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 unit tests for mars/app/src/traffic_statistics module

The traffic_statistics.cc/h files handle critical network metrics for WeChat's billions of users, but there are no visible test files in the repo structure. Given Mars' cross-platform nature and the importance of accurate traffic monitoring, this module needs comprehensive unit tests covering Linux/Windows/iOS/Android platforms to prevent regressions.

• [ ] Create mars/app/test/traffic_statistics_test.cc with tests for traffic data collection across platforms
• [ ] Add platform-specific test cases for Linux, Windows, iOS, and Android (reference mars/app/src/wp/platform_logic.cpp for platform abstractions)
• [ ] Integrate tests into mars/CMakeLists.txt build system
• [ ] Test edge cases: network state transitions, overflow handling, and concurrent access patterns

Implement CMake cross-platform CI/CD workflow for supported platforms

The README lists support for iOS, OS X, Android(ndk-r20), and Windows(vs2015), but there's no visible GitHub Actions workflow file. This is a critical gap since Mars is a production network component used by billions - CI/CD ensures builds don't break across platforms before releases.

• [ ] Create .github/workflows/cmake-multiplatform.yml with matrix builds for iOS (xcode), macOS (clang), Android (ndk-r20), and Windows (vs2015/MSVC)
• [ ] Reference mars/CMakeLists.txt and existing build configuration
• [ ] Add build validation step that compiles all modules (app, baseevent, boost)
• [ ] Add optional ccache caching and artifact upload for release binaries

Add comprehensive JNI bridge tests for Java-C++ interop

Mars has multiple JNI wrapper files (mars/app/jni/app_manager_wrapper.cc, mars/baseevent/jni/com_tencent_mars_BaseEvent.cc) but no visible Android JNI test suite. These are critical integration points between the native networking layer and Android applications - missing tests risk silent failures in production.

• [ ] Create mars/app/test/android/jni_app_manager_test.cc for testing app_manager JNI bindings (reference mars/app/jni/app_manager_callback_wrapper.h for callback patterns)
• [ ] Create mars/baseevent/test/android/jni_baseevent_test.cc for event JNI interop testing
• [ ] Add Android instrumentation test configuration in mars/CMakeLists.txt for running tests on actual Android devices/emulators
• [ ] Test critical paths: callback invocation, memory management, exception handling, and thread safety across Java-C++ boundary

• Add comprehensive unit tests for mars/comm/socket_wrapper — currently no test file visible in structure; critical for cross-platform reliability. Start by creating a test file that exercises connection, send/recv, and platform-specific error handling.
• Document JNI function signatures in mars/app/jni/app_manager_wrapper.cc with JavaDoc and native signatures side-by-side. Currently only .cc files exist; adding paired .h documentation would help new contributors understand the Java↔C++ contract.
• Migrate mars/app/src/wp/ (Windows Phone) platform code to deprecation stubs or remove entirely. File structure shows legacy dead code; either document why it's kept or clean it up with proper deprecation warnings.

The Mars codebase is a mature, cross-platform network component with generally acceptable security posture, but several areas require attention. Primary concerns include: (1) lack of visible dependency management and security tracking, (2) JNI bridge security without visible validation mechanisms, (3) C/C++ memory safety risks inherent to the language, and (4) missing security documentation and processes. The project is open-source and well-established (used by WeChat), suggesting community scrutiny, but explicit security practices should be formalized. Implementation of automated security scanning, dependency tracking, and comprehensive testing across

• Medium · Boost Library Version Management — mars/boost/. The codebase includes embedded Boost libraries (mars/boost directory). Without explicit version pinning and regular updates, these dependencies may contain known vulnerabilities. The file structure shows multiple Boost components (accumulators, algorithm, align, etc.) that need maintenance. Fix: Implement a dependency management system to track and update Boost library versions. Use a package manager (e.g., Conan, vcpkg) or maintain a dependency manifest with version constraints and security audit schedules.
• Medium · JNI Bridge Security Exposure — mars/app/jni/, mars/baseevent/jni/. Multiple JNI wrapper files are present (app_manager_wrapper.cc, app_manager_callback_wrapper.cc, com_tencent_mars_app_AppLogic_C2Java.cc, com_tencent_mars_BaseEvent.cc). JNI bridges can be attack vectors if not properly validated. The current file structure doesn't reveal input validation mechanisms. Fix: Implement strict input validation for all JNI callbacks and return values. Add bounds checking, type validation, and sanitization for data crossing the JNI boundary. Document and review the contract between Java and native code.
• Medium · Missing Dependency Information — Repository root. The 'Dependencies/Package file content' section is empty. There is no visible package manager configuration (package.json, requirements.txt, Gemfile, conanfile.txt, etc.), making it impossible to track third-party dependencies and their security status. Fix: Create and maintain a dependency manifest file (e.g., CMakeLists.txt dependencies, vcpkg.json, or Conan configuration) with explicit version constraints. Implement automated dependency scanning tools (e.g., OWASP Dependency-Check, Snyk) in CI/CD pipeline.
• Low · Potential Memory Safety Issues in C/C++ Components — mars/app/app_logic.cc, mars/app/app_manager.cc, mars/baseevent/src/active_logic.cc, mars/baseevent/src/baseprj.cc. The codebase is predominantly C/C++ (mars/app/.cc, mars/baseevent/src/.cc). C/C++ are prone to memory safety vulnerabilities (buffer overflows, use-after-free, double-free) if not carefully managed. No visible use of memory-safe abstractions or modern C++ practices. Fix: Adopt static analysis tools (clang-analyzer, cppcheck, Valgrind). Implement AddressSanitizer and MemorySanitizer in CI/CD. Use RAII principles, smart pointers, and modern C++ standards (C++17/20). Conduct regular code reviews focused on memory management.
• Low · Missing Security Configuration Files — Repository root. No visible security configuration files such as .editorconfig with security rules, security.md, or SECURITY.md file describing the vulnerability disclosure process. The codecc.sh script is present but its security scanning capabilities are unclear. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process. Add security guidelines to CONTRIBUTING.md. Implement pre-commit hooks with security checks. Document the purpose and configuration of codecc.sh.
• Low · Cross-Platform Code Complexity — mars/app/src/wp/platform_logic.cpp, mars/. The codebase targets multiple platforms (iOS, OS X, Android, Windows) as indicated in the README. Cross-platform implementations often have platform-specific vulnerabilities that may be missed during testing on primary development platform. Fix: Implement platform-specific security tests in CI/CD for each target platform. Use conditional compilation guards (#ifdef, #if defined) carefully. Maintain separate security test suites for each platform. Document platform-specific security considerations.

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

• 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.