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/Snailclimb/guide-rpc-framework 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 7mo ago

• Last commit 7mo ago
• 22+ active contributors
• Other licensed
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 66% 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 Snailclimb/guide-rpc-framework repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Snailclimb/guide-rpc-framework.

What it runs against: a local clone of Snailclimb/guide-rpc-framework — 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 Snailclimb/guide-rpc-framework | 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 | Last commit ≤ 250 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Snailclimb/guide-rpc-framework(\\.git)?\\b" \\
  && ok "origin remote is Snailclimb/guide-rpc-framework" \\
  || miss "origin remote is not Snailclimb/guide-rpc-framework (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"

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

guide-rpc-framework is a lightweight RPC (Remote Procedure Call) framework built on Netty, Kryo, and Zookeeper that lets you invoke remote service methods as if they were local. It provides service registration/discovery via Zookeeper, high-performance async networking through Netty, multiple serialization strategies (Kryo, Protostuff, Hessian), and load balancing—designed as an educational implementation of production RPC concepts used by frameworks like Dubbo. Maven monorepo with three core modules: rpc-framework-simple/ (the engine with Netty handlers, serialization, and service registration), rpc-framework-common/ (shared utilities), and hello-service-api/ (interface definitions), plus example-server/ and example-client/ as runnable samples showing provider and consumer roles. Both Socket and Netty transport options are implemented.

Java developers learning RPC internals, computer science students building capstone projects, and engineers wanting to understand how frameworks like Dubbo work under the hood. The detailed code comments and docs in docs/ make it ideal for self-study or interview preparation.

Early-stage educational project, not production-ready. The codebase is well-commented and runnable (example-server/ and example-client/ prove functionality), but it's a teaching tool with acknowledged limitations. No CI/CD pipelines visible, no automated tests mentioned, and the single maintainer explicitly notes it as a 'simple wheel' with many optimization opportunities.

This is a reference implementation, not battle-tested. Single maintainer (Snailclimb/JavaGuide), no visible test suite or CI setup, and it depends on external services (Zookeeper must be running). The core insight is solid but production use would require hardening—error handling, connection pooling, and retry logic likely need work. Last activity and issue backlog are not visible in the provided data.

Documentation exists in docs/ covering CompletableFuture optimization for async responses, service annotation design, and framework philosophy. The repo appears stable rather than actively developed—focus was on adding detailed comments and docs to support learning, not on new features.

git clone https://github.com/Snailclimb/guide-rpc-framework.git
cd guide-rpc-framework
mvn clean install
# Start Zookeeper (required, not included in repo)
# Then in one terminal:
cd example-server && mvn exec:java -Dexec.mainClass='NettyServerMain'
# In another terminal:
cd example-client && mvn exec:java -Dexec.mainClass='NettyClientMain'

Daily commands: Start Zookeeper first, then: cd example-server && mvn exec:java -Dexec.mainClass='NettyServerMain' and in parallel cd example-client && mvn exec:java -Dexec.mainClass='NettyClientMain'. Both SocketServerMain and NettyServerMain variants exist—Netty is preferred for high performance.

• example-server/src/main/java/NettyServerMain.java: Entry point showing how to register services with Zookeeper and start the Netty server
• example-client/src/main/java/github/javaguide/HelloController.java: Consumer side—demonstrates service discovery and remote method invocation via dynamic proxy
• hello-service-api/src/main/java/github/javaguide/HelloService.java: Service interface contract that both server implementation and client proxy conform to
• docs/使用CompletableFuture优化接受服务提供端返回结果.md: Core design doc explaining async response handling and the unprocessed request tracking mechanism
• docs/造个轮子：自定义注解实现服务注册和消费（RPC框架）.md: Tutorial on Spring annotation-based service registration—key for understanding the framework's ease-of-use approach

1. Add new services: Create interface in hello-service-api/src/main/java/github/javaguide/, implement in example-server/src/main/java/github/javaguide/serviceimpl/. 2. Modify serialization: Edit rpc-framework-simple/ serialization module. 3. Add load balancing strategy: Extend strategy classes in rpc-framework-simple/. 4. Test client/server integration: Modify HelloController.java or NettyClientMain.java entry points.

Zookeeper must be running before starting server or client—the framework has hard dependency on it for service registration; no in-memory fallback exists. Configuration files: example-server/src/main/resources/rpc.properties and example-client/src/main/resources/rpc.properties must be correctly set for Zookeeper address and port discovery. Serialization mismatch: If client and server use different serialization frameworks (Kryo vs. Protostuff), deserialization will fail silently or throw ClassCastException. Netty channel lifecycle: If you modify the Netty handlers, be aware that channel.write() is asynchronous—writes must be followed by flush() to guarantee delivery.

• Service Registry Pattern — Central to how clients discover service endpoints; Zookeeper holds the source of truth, and the framework demonstrates how to publish and query it at runtime
• Dynamic Proxy (JDK Proxy / CGLIB) — On the client side, proxy objects intercept method calls and translate them into RPC network requests; this abstraction is what makes remote calls feel local
• Serialization Frameworks (Kryo, Protostuff, Hessian) — Network transmission requires object→bytes→object conversion; choosing the right serializer affects performance (throughput) and compatibility (security, version evolution)
• Netty Channel and ChannelHandler Pipeline — Netty's async I/O model allows thousands of concurrent RPC calls without thread-per-connection; understanding handlers (encoding, decoding, logic) is essential to modify transport behavior
• CompletableFuture for Async Request-Response Matching — RPC calls are async in Netty, but Java method calls appear synchronous to the caller; CompletableFuture bridges this gap by holding request ID → response promise mappings (see UnprocessedRequests.png)
• Load Balancing Strategies (Round-Robin, Random, Weighted) — When a service has multiple provider instances registered in Zookeeper, the client must pick one; different strategies trade simplicity for fairness under varying load
• Heartbeat Detection / Health Checking — Clients must detect when a service instance becomes unhealthy; periodic heartbeats allow the framework to remove stale entries from the local service cache and retry on live instances

• apache/dubbo — Production-grade RPC framework that inspired this repo's architecture; study this to see how guide-rpc-framework concepts scale to millions of transactions
• grpc/grpc-java — Alternative RPC approach using Protocol Buffers and HTTP/2; useful for comparing serialization and transport strategies
• motan-docs/motan — Meituan's RPC framework with similar Netty+Zookeeper stack but more mature failover and cluster management
• alibaba/nacos — Modern alternative to Zookeeper for service registration; if building on guide-rpc-framework, Nacos is a drop-in replacement
• Snailclimb/JavaGuide — Main repository by the same author containing interview guides and system design articles that contextualize this RPC framework project

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 rpc-framework-common enums and utilities

The rpc-framework-common module contains critical enums (CompressTypeEnum, LoadBalanceEnum, SerializationTypeEnum, RpcResponseCodeEnum, etc.) but there are no visible test files. These enums are foundational to the entire RPC framework and should have unit tests covering enum value parsing, validation, and edge cases. This improves code reliability and serves as documentation for enum usage.

• [ ] Create rpc-framework-common/src/test/java/github/javaguide/enums/ directory structure
• [ ] Add CompressTypeEnumTest.java covering codec type validation and parsing
• [ ] Add LoadBalanceEnumTest.java testing load balance strategy enum operations
• [ ] Add SerializationTypeEnumTest.java validating serialization type conversions
• [ ] Add RpcResponseCodeEnumTest.java for response code enum tests
• [ ] Add test for RpcConfigEnum.java covering configuration key mapping

Add integration tests for example-client and example-server communication

The example-client and example-server modules demonstrate both Socket and Netty-based RPC communication, but there are no visible integration tests verifying that client-server communication works end-to-end. Adding integration tests (e.g., HelloServiceImpl invocation from HelloController) will catch regressions and validate the framework actually works as documented.

• [ ] Create example-server/src/test/java/github/javaguide/ directory
• [ ] Add ServerStartupTest.java to verify NettyServerMain and SocketServerMain start correctly
• [ ] Create example-client/src/test/java/github/javaguide/ directory
• [ ] Add ClientServerIntegrationTest.java that starts an example server and makes RPC calls from HelloController
• [ ] Add test cases for HelloServiceImpl.hello() and HelloServiceImpl2 invocations
• [ ] Add test validating both Netty and Socket transport mechanisms work

Add GitHub Actions CI workflow for automated testing and build validation

The repo lacks any visible CI/CD configuration (.github/workflows/ directory is absent). Adding a GitHub Actions workflow ensures every PR is automatically tested across Maven builds, all three modules compile, tests pass, and prevents broken code from being merged. This is especially critical for a framework where downstream example projects depend on stability.

• [ ] Create .github/workflows/maven-build.yml with Maven clean install, test, and package goals
• [ ] Configure workflow to trigger on push to main/master and all PRs
• [ ] Add test coverage reporting (JaCoCo or Codecov) to enforce minimum coverage for critical modules
• [ ] Add linting check for hello-service-api (requires interfaces be properly Serializable)
• [ ] Configure build matrix for Java 8, 11, 17 to validate backward compatibility
• [ ] Add step to verify all three example modules (hello-service-api, example-client, example-server) build without errors

• Add comprehensive unit tests for the serialization layer (rpc-framework-simple/) covering Kryo, Protostuff, and Hessian edge cases (null values, nested objects, large payloads)—currently no test directory exists.
• Implement a retry mechanism with exponential backoff in NettyClientTransport when RPC calls fail due to network timeouts; the current code likely fails fast without retries.
• Add metrics/logging integration (e.g., via Micrometer or SLF4J) to track request latency, failure rates, and Zookeeper connection status; helps diagnose production issues in deployments.

• High · Use of Kyro Serialization Framework — rpc-framework-simple (inferred from pom.xml and README). The RPC framework uses Kyro for serialization. Kyro has known deserialization vulnerabilities (CVE-2018-1000058) that can lead to arbitrary code execution if untrusted data is deserialized. Kyro's default configuration is not secure for untrusted input. Fix: Consider using safer serialization mechanisms like Protocol Buffers or JSON. If Kyro must be used, implement strict deserialization filters and validate all incoming RPC messages. Keep Kyro updated to the latest version and configure it with explicit class registration only.
• High · Potential Unsafe RPC Method Invocation — rpc-framework-simple (service invocation logic). The framework appears to use reflection-based RPC invocation to call remote methods dynamically. Without proper validation and restrictions, this could allow attackers to invoke arbitrary methods on the server, including dangerous system operations or internal utility methods not intended for RPC exposure. Fix: Implement strict method whitelisting. Only allow invocation of methods explicitly marked with a security annotation. Validate method signatures and parameters. Implement authorization checks before method invocation. Consider using an Interface-based approach to restrict callable methods.
• High · Zookeeper Integration Without Authentication — rpc-framework-simple (Zookeeper integration). The framework integrates with Zookeeper for service discovery and registration. If Zookeeper is not properly secured with authentication and ACLs, attackers could modify service registration information, poison the service registry, or discover internal service topology. Fix: Enable Zookeeper SASL authentication and ACLs. Restrict access to Zookeeper to authorized clients only. Use SSL/TLS for Zookeeper client connections. Implement proper credential management and rotate credentials regularly.
• Medium · Missing Input Validation and Sanitization — rpc-framework-simple (RPC request handling). The framework processes RPC requests containing method names, parameter types, and parameter values. Without proper input validation, this could be vulnerable to injection attacks or exploitation of unexpected input formats. Fix: Implement comprehensive input validation for all RPC request parameters. Validate method names against whitelists, validate parameter types match declared types, and sanitize all string inputs. Implement size limits on request payloads.
• Medium · Unencrypted Network Communication — example-client/src/main/resources/rpc.properties, example-server/src/main/resources/rpc.properties. The RPC framework uses Netty for network communication, but the provided documentation and structure suggest that TLS/SSL might not be enforced by default. This exposes RPC messages to network eavesdropping and man-in-the-middle attacks. Fix: Enforce TLS 1.2+ for all network communication. Configure Netty to use SslContext with proper certificate management. Make TLS the default and only supported transport mechanism. Implement certificate pinning if applicable.
• Medium · Hardcoded Configuration in Properties Files — example-client/src/main/resources/rpc.properties, example-server/src/main/resources/rpc.properties. Configuration files (rpc.properties) may contain sensitive information like service registry addresses, port numbers, and connection parameters. These files may be committed to version control or exposed in deployments. Fix: Move sensitive configuration to environment variables or secure configuration management systems (e.g., Vault, AWS Secrets Manager). Use .gitignore to prevent properties files from being committed. Implement configuration encryption for sensitive values.
• Medium · Insufficient Logging and Monitoring — rpc-framework-simple (all components). The framework structure suggests minimal security logging. Without proper logging of RPC invocations, authentication attempts, and errors, it would be difficult to detect attacks or investigate security incidents. Fix: Implement comprehensive security logging for: all RPC method invocations with caller information, failed authentication/authorization attempts, deserialization errors, unexpected input validation failures. Use centralized logging and implement alerting for suspicious patterns.
• Low · Missing Rate Limiting and DoS Protection — undefined. The RPC framework does not appear to implement rate limiting or connection throttling. This makes it vulnerable to denial-of-service attacks where an attacker floods the service with Fix: undefined

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.