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/crossoverJie/cim 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.

GO — Healthy across the board

• Last commit 5w ago
• 8 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{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 crossoverJie/cim repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/crossoverJie/cim.

What it runs against: a local clone of crossoverJie/cim — 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 crossoverJie/cim | 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 ≤ 63 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "crossoverJie/cim(\\.git)?\\b" \\
  && ok "origin remote is crossoverJie/cim" \\
  || miss "origin remote is not crossoverJie/cim (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 "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/Client.java" \\
  && ok "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/Client.java" \\
  || miss "missing critical file: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/Client.java"
test -f "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientImpl.java" \\
  && ok "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientImpl.java" \\
  || miss "missing critical file: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientImpl.java"
test -f "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/CIMClientHandle.java" \\
  && ok "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/CIMClientHandle.java" \\
  || miss "missing critical file: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/CIMClientHandle.java"
test -f "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/RouteManager.java" \\
  && ok "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/RouteManager.java" \\
  || miss "missing critical file: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/RouteManager.java"
test -f "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/ReConnectManager.java" \\
  && ok "cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/ReConnectManager.java" \\
  || miss "missing critical file: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/ReConnectManager.java"

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

CIM (Cross-IM) is a distributed instant messaging system built on Netty and Spring Boot 3.0 (Java 17+) that enables developers to build scalable IM platforms, message push middleware, and IoT massive-connection scenarios. It provides a client SDK (cim-client-sdk), server components, and a CLI client with features like group/private chat, offline message handling, automatic reconnection, and Protocol Buffer encoding. Multi-module Maven monorepo: cim-client-sdk/ contains the client library with core classes (Client, ClientBuilder, ClientImpl) and I/O handlers (CIMClientHandle, CIMClientHandleInitializer); cim-common and cim-rout-api are shared dependencies; cim-client provides a CLI shell; .github/workflows/ orchestrates CI (Maven tests, Docker builds); Makefile and Dockerfile support container deployment.

Backend engineers and distributed systems developers who need to build or integrate real-time messaging capabilities into applications; DevOps teams deploying containerized microservices; IoT platform developers managing thousands of concurrent connections.

Actively developed and modernized (V2.0 upgraded to JDK17/Spring Boot 3.0); has CI/CD setup (Maven, Docker, GitHub Actions workflows in .github/workflows/); includes integration tests (cim-integration-test module) and checkstyle enforcement; demonstrates production-readiness with client SDK packaging and multiple deployment options, though some V2.0 features remain in-progress (picocli migration, OpenTelemetry, Kubernetes support).

Single-maintainer project (crossoverJie) with moderate complexity spanning Netty I/O, distributed routing, and Spring Boot microservices; V2.0 is still stabilizing (several TODO items incomplete); dependency on external components (Redis, Zookeeper) not yet made pluggable; no visible recent commit dates in provided data limits assessment of maintenance cadence.

V2.0 modernization in active progress: JDK17 & Spring Boot 3.0 upgrade complete; client SDK packaged and released; picocli CLI migration, OpenTelemetry integration, single-node startup mode, and component pluggability (Redis/Zookeeper) remain on TODO; web client (WebSocket) and Kubernetes support are planned but not yet implemented.

git clone https://github.com/crossoverJie/cim.git && cd cim && mvn clean install && make build-docker (or mvn spring-boot:run from individual modules). See Makefile for orchestration commands; cim-client-sdk/README.md contains SDK-specific setup.

Daily commands: Individual modules: mvn -f cim-client-sdk/pom.xml spring-boot:run OR mvn -f cim-client/pom.xml spring-boot:run; Docker: docker build -f Dockerfile . && docker run ...; Makefile targets: make build, make docker, make test. See .github/workflows/maven.yml for test execution (mvn test -B).

• cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/Client.java — Core client interface defining the public API for SDK consumers; all messaging operations flow through this abstraction.
• cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientImpl.java — Primary client implementation managing connection lifecycle, message routing, and reconnection logic—the heaviest runtime component.
• cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/CIMClientHandle.java — Netty channel handler orchestrating inbound/outbound message serialization and protocol handling—critical I/O boundary.
• cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/RouteManager.java — Manages server routing and discovery; essential for multi-server deployments and failover logic.
• cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/ReConnectManager.java — Handles reconnection attempts with backoff strategy; critical for resilience in unreliable networks.
• cim-client-sdk/pom.xml — SDK module dependencies and build configuration; defines Netty, Spring, and testing framework versions.
• cim-client/src/main/java/com/crossoverjie/cim/client/service/impl/MsgHandler.java — Main message handler in the client application; implements core command processing and event routing.

Add a New Built-in Command

1. Create a new command class implementing InnerCommand interface in cim-client/src/main/java/com/crossoverjie/cim/client/service/impl/command/ (cim-client/src/main/java/com/crossoverjie/cim/client/service/impl/command/YourNewCommand.java)
2. Implement execute(String s, MsgHandle msgHandle) method; parse incoming message and invoke appropriate msgHandle methods. (cim-client/src/main/java/com/crossoverjie/cim/client/service/impl/command/YourNewCommand.java)
3. Register command in InnerCommandContext by adding entry to the command map in the initialization method. (cim-client/src/main/java/com/crossoverjie/cim/client/service/InnerCommandContext.java)
4. Add test case in cim-client/src/test/java/com/crossoverjie/cim/client/service/ to verify command parsing and execution. (cim-client/src/test/java/com/crossoverjie/cim/client/service/InnerCommandContextTest.java)

Integrate the SDK into a New Project

1. Add cim-client-sdk and cim-common modules to your project pom.xml as dependencies. (cim-client-sdk/pom.xml)
2. Build a Client instance using ClientBuilder with connection parameters (host, port, userId). (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientBuilderImpl.java)
3. Implement MessageListener interface to handle incoming messages and route them to your application logic. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/MessageListener.java)
4. Call client.send(msg) to transmit messages; reconnection and routing are handled transparently by ReConnectManager and RouteManager. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientImpl.java)

Customize Reconnection Behavior

1. Implement BackoffStrategy interface to define custom retry delay logic (e.g., fixed, exponential, or adaptive backoff). (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/backoff/BackoffStrategy.java)
2. Inject your BackoffStrategy into ReConnectManager constructor via ClientConfigurationData. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/impl/ClientConfigurationData.java)
3. Test reconnection under network failure conditions using ReconnectCheck utility or custom test scenarios. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/ReconnectCheck.java)

Add Offline Message Retrieval

1. Implement FetchOfflineMsgJob to query the route service (typically Redis/DB) for messages missed during disconnection. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/FetchOfflineMsgJob.java)
2. Trigger FetchOfflineMsgJob from ReConnectManager after successful reconnection to sync missed messages. (cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/ReConnectManager.java)
3. undefined

RouteManager requires external routing service (Redis or Zookeeper integration not yet fully abstracted — see 'Third-party components support replacement' in V2.0 TODO); FetchOfflineMsgJob depends on Redis for message persistence; Client state transitions (ClientState enum) have implicit ordering assumptions in ReConnectManager.reconnect() — calling connect() twice without explicit disconnect() can cause race conditions; test resources in cim-client-sdk/src/test/resources/ reference application-route.yaml which must be configured for integration tests to pass; no explicit thread-safety guarantees documented for ClientImpl — concurrent sends from multiple threads may require external synchronization.

• Netty ChannelPipeline and ChannelHandler — CIM's entire client-server I/O model (CIMClientHandleInitializer, CIMClientHandle) depends on composable handlers in a pipeline for encoding/decoding, TLS, and protocol processing.
• Protocol Buffers (protobuf) — CIM uses Protocol Buffers for efficient message serialization mentioned in README TODO ('Efficient encoding/decoding with Google Protocol Buffer'); enables compact binary protocol over Netty.
• Exponential Backoff with Jitter — ReConnectManager and BackoffStrategy implementations handle client reconnection; RandomBackoff prevents thundering herd when many clients reconnect simultaneously after server restart.
• Spring Boot ComponentScan and Lifecycle Events — CIM modules use Spring Boot's @SpringBootApplication, dependency injection, and lifecycle events (ContextClosedEvent in ClientImpl) to orchestrate component startup/shutdown across distributed nodes.
• Client-side Service Discovery and Load Balancing — RouteManager abstracts server discovery and failover; essential for horizontal scaling across multiple CIM server instances without requiring a dedicated load balancer.
• Offline Message Storage and Eventual Delivery — FetchOfflineMsgJob and Redis integration handle message persistence for disconnected clients; critical for reliability in IoT/mobile scenarios where transient disconnections are common.
• Docker Multi-stage Builds and Container Orchestration — CIM's Dockerfile and make targets support containerized deployment; V2.0 roadmap includes Kubernetes operator support for managing distributed IM clusters at scale.

• alibaba/nacos — Distributed service discovery and config management; CIM uses similar patterns for client-server routing and can integrate with Nacos for enhanced service registration.
• netty/netty — Underlying async I/O framework; CIM builds its client-server communication on Netty's ChannelPipeline and codec architecture.
• grpc/grpc-java — Alternative RPC framework for distributed messaging; shares Netty foundation but adds gRPC streaming semantics that could complement CIM for bidirectional messaging.
• apache/kafka — Message broker for event streaming; CIM could use Kafka as persistent message storage backend instead of Redis for scaling offline message delivery.
• opentelemetry/opentelemetry-java — Observability framework for distributed tracing; CIM V2.0 TODO explicitly lists OpenTelemetry integration for monitoring message latency and client connection health.

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 ReConnectManager and BackoffStrategy implementations

The cim-client-sdk has reconnection logic (ReConnectManager.java, BackoffStrategy.java, RandomBackoff.java) but there are only 2 test files (ClientTest.java, OfflineMsgTest.java) visible in the repo. The backoff/reconnection strategies lack dedicated unit tests, which is critical for a distributed IM system where connection reliability is paramount. This would improve test coverage and prevent regression in reconnection behavior.

• [ ] Create cim-client-sdk/src/test/java/com/crossoverjie/cim/client/sdk/io/backoff/BackoffStrategyTest.java with tests for RandomBackoff implementation
• [ ] Create cim-client-sdk/src/test/java/com/crossoverjie/cim/client/sdk/ReConnectManagerTest.java testing reconnection scenarios (success, failure, max retries)
• [ ] Create cim-client-sdk/src/test/java/com/crossoverjie/cim/client/sdk/io/ReconnectCheckTest.java for reconnect detection logic
• [ ] Add mock Netty channel tests to verify backoff timing between reconnection attempts

Add GitHub Actions workflow for client SDK integration tests

While there are docker.yml and maven.yml workflows in .github/workflows/, there's a reusable_run_tests.yml that suggests test orchestration exists but isn't fully documented. The cim-client-sdk has integration tests (cim-integration-test dependency) and SQL init files (init.sql) but no dedicated workflow to run them in CI/CD. This gap means integration test failures might not be caught before merge.

• [ ] Create .github/workflows/client-sdk-integration-tests.yml that starts required services (database, route server) using docker-compose or testcontainers
• [ ] Configure the workflow to run cim-client-sdk tests against application-route.yaml test configuration
• [ ] Add test result reporting and coverage upload to codecov for cim-client-sdk module specifically
• [ ] Document the integration test setup in cim-client-sdk/README.md with prerequisites and local execution instructions

Implement comprehensive error handling documentation and tests for ClientBuilder and RouteManager

The ClientBuilder.java and RouteManager.java are core SDK components but have minimal test coverage. RouteManager is critical for service discovery in a distributed system, and ClientBuilder needs robust error scenarios (network timeouts, invalid route responses, missing configuration). The repo README lacks specific troubleshooting guidance for SDK users encountering these failures.

• [ ] Create cim-client-sdk/src/test/java/com/crossoverjie/cim/client/sdk/ClientBuilderTest.java testing validation logic and failure scenarios (null configs, invalid ports, missing hosts)
• [ ] Create cim-client-sdk/src/test/java/com/crossoverjie/cim/client/sdk/RouteManagerTest.java with tests for route resolution failures, stale routes, and fallback behavior
• [ ] Add error handling documentation to cim-client-sdk/README.md with a troubleshooting section covering common SDK initialization failures
• [ ] Create cim-client-sdk/src/test/resources/application-route-invalid.yaml and application-route-empty.yaml to test edge cases

• Add unit tests for BackoffStrategy implementations: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/backoff/ has RandomBackoff but no test coverage in cim-client-sdk/src/test/; contribute tests validating backoff timing and exponential growth.
• Implement pluggable RouteManager: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/RouteManager.java currently has no documented abstraction for swapping Redis/Zookeeper backends; refactor to interface-based design and add factory pattern (aligns with V2.0 TODO: 'Third-party components support replacement').
• Add async message listener documentation: cim-client-sdk/src/main/java/com/crossoverjie/cim/client/sdk/io/MessageListener.java lacks Javadoc on thread-safety guarantees and execution model; contribute detailed documentation with code examples showing safe concurrent usage patterns.

The codebase shows moderate security posture. While no critical vulnerabilities were immediately evident, there are several areas requiring attention: potential SQL injection risks in data access, missing security controls on API documentation, insecure deserialization risks in network communication, and lack of encryption for network transport. The application handles instant messaging which inherently deals with sensitive user communication, making

• Medium · Potential SQL Injection Risk in Test Resources — cim-client-sdk/src/test/resources/init.sql. The presence of 'init.sql' in test resources (cim-client-sdk/src/test/resources/init.sql) suggests direct SQL query execution. If similar patterns exist in production code, there could be SQL injection vulnerabilities if user input is not properly parameterized. Fix: Ensure all SQL queries use prepared statements or parameterized queries. Review codebase for any raw SQL concatenation with user input. Use ORM frameworks or query builders that prevent SQL injection by default.
• Medium · Missing Security Headers in Swagger Configuration — cim-client/src/main/java/com/crossoverjie/cim/client/config/SwaggerConfig.java. Swagger/OpenAPI configuration file (SwaggerConfig.java) is present but may expose API documentation without authentication. This could leak API structure and internal endpoints to unauthorized users. Fix: Implement authentication/authorization for Swagger UI in production. Consider disabling Swagger documentation in production environments. Add security schemes to Swagger configuration.
• Medium · Insecure Deserialization Risk — cim-common (dependency), cim-client-sdk network handlers. The project uses Netty for network communication and handles message serialization/deserialization. Without explicit secure serialization mechanisms, there's a risk of insecure deserialization attacks if untrusted data is deserialized. Fix: Use safe serialization libraries (e.g., Protocol Buffers, JSON with Jackson configured securely). Never deserialize untrusted data using Java serialization. Implement strict input validation and use object input stream filters.
• Low · Potential Information Disclosure via Logging — cim-client/src/main/java/com/crossoverjie/cim/client/service/MsgLogger.java, cim-client/src/main/java/com/crossoverjie/cim/client/service/impl/AsyncMsgLogger.java. MsgLogger and AsyncMsgLogger classes exist which may log sensitive message contents. If debug/verbose logging is enabled in production, this could leak confidential communication data. Fix: Ensure sensitive data (passwords, tokens, message contents) are never logged. Implement log filtering for production. Use appropriate log levels (INFO/WARN instead of DEBUG) in production configurations.
• Low · Missing Dependency Version Pinning — cim-client-sdk/pom.xml. The pom.xml uses parent version inheritance without explicit version declarations for some dependencies. This could lead to unexpected version updates and potential introduction of vulnerable transitive dependencies. Fix: Explicitly declare dependency versions in properties. Use dependency management sections. Regularly scan dependencies with tools like OWASP Dependency-Check or Snyk for known vulnerabilities.
• Low · Potential Command Injection via InnerCommand Pattern — cim-client/src/main/java/com/crossoverjie/cim/client/service/InnerCommand.java, command implementations directory. The application implements a command pattern (InnerCommand, InnerCommandContext) with multiple command implementations. If user input is used to construct or execute commands, this could lead to command injection. Fix: Implement strict whitelist validation for command inputs. Use enums or predefined command sets. Never construct command strings from user input. Apply principle of least privilege to command execution.
• Low · Unencrypted Network Communication — cim-client/src/main/resources/application.yaml, cim-client-sdk configuration. No evidence of TLS/SSL configuration in visible configuration files. Netty-based instant messaging systems should use encrypted communication channels to protect message privacy. Fix: Implement TLS/SSL encryption for all network communications. Use SslContext in Netty channel initializers. Enforce HTTPS/TLS for all connections. Consider mutual TLS (mTLS) for server-to-server communication.

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.