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/smallnest/rpcx 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 — Mixed signals — read the receipts

• Last commit 5w ago
• 19 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ Non-standard license (Other) — review terms

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "smallnest/rpcx(\\.git)?\\b" \\
  && ok "origin remote is smallnest/rpcx" \\
  || miss "origin remote is not smallnest/rpcx (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 "server/server.go" \\
  && ok "server/server.go" \\
  || miss "missing critical file: server/server.go"
test -f "client/xclient.go" \\
  && ok "client/xclient.go" \\
  || miss "missing critical file: client/xclient.go"
test -f "protocol/message.go" \\
  && ok "protocol/message.go" \\
  || miss "missing critical file: protocol/message.go"
test -f "server/router.go" \\
  && ok "server/router.go" \\
  || miss "missing critical file: server/router.go"
test -f "client/selector.go" \\
  && ok "client/selector.go" \\
  || miss "missing critical file: client/selector.go"

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

rpcx is a high-performance microservices RPC framework for Go that provides service registration, discovery, load balancing, and protocol serialization — similar to Java's Dubbo but with cloud-native features like QUIC, KCP, and io_uring support. It allows Go developers to build distributed systems by exposing methods as RPC services with automatic client-side service discovery and failover. Monorepo structure: client/ contains the RPC client with service discovery (dns_discovery.go, mdns_discovery.go, peer2peer_discovery.go) and load balancing (selector.go, smooth_weighted_round_robin.go); server/ handles RPC servers; codec/ provides serialization; _testutils/ contains shared test fixtures (arith_service.go) with both protobuf and thrift definitions.

Go backend engineers building microservices architectures who need cross-service communication with built-in service discovery, load balancing, and support for multiple transport protocols (TCP, QUIC, KCP, RDMA). Also used by teams migrating from Java Dubbo or needing polyglot RPC via rpcx-gateway.

Production-ready with active development: Go 1.24 support, stable v1.7.x branch, comprehensive test coverage (client_test.go, circuit_breaker_test.go, xclient_test.go present), GitHub Actions CI/CD configured (.github/workflows/go.yml), and recent dependency updates (Redis client v9.7.3, quic-go v0.57.0). Master branch represents current development while v1.7.x is the stable release line.

Moderate risk from plugin ecosystem fragmentation: etcd, zookeeper, consul, and redis plugins were extracted to separate repos (rpcx-etcd, rpcx-zookeeper, etc.) as of v1.7.6, increasing external dependency management. Single maintainer (smallnest) visible in repo ownership. High code complexity in client/connection_*.go variants (TCP, QUIC, KCP, RDMA, io_uring) increases maintenance surface.

Active development on Go 1.24 compatibility, io_uring integration (connection_iouring.go), circuit breaker patterns (circuit_breaker.go), and rate limiting plugins. README indicates recent stability in core features with plugin ecosystem refactoring toward independent packages for maintainability.

git clone https://github.com/smallnest/rpcx.git && cd rpcx && go get -v github.com/smallnest/rpcx/... && go get -v -tags "quic kcp" github.com/smallnest/rpcx/... (to include QUIC and KCP transport support)

Daily commands: No single 'dev server' — rpcx is a library. Run examples: go run examples/server.go to start an RPC server, then go run examples/client.go to invoke it. Or run tests: go test ./client ./server ./codec (requires Go 1.24+ and optional -tags quic kcp for advanced transports).

• server/server.go — Core RPC server implementation handling listener setup, request routing, and service registration—entry point for all server-side operations.
• client/xclient.go — Primary client implementation providing load balancing, failover, and service discovery—essential for understanding RPC call flow.
• protocol/message.go — Message protocol definition and serialization logic—fundamental to all RPC communication between client and server.
• server/router.go — Request routing and service method dispatch mechanism—critical for mapping incoming calls to handler functions.
• client/selector.go — Server selection strategy implementation (round-robin, weighted, geo-aware)—controls how load balancing decisions are made.
• codec/codec.go — Codec abstraction supporting protobuf, thrift, and custom serialization—key for extending RPC protocol support.
• client/discovery.go — Service discovery interface and implementations (peer-to-peer, DNS, mDNS)—enables dynamic service locating.

Add a new RPC Service

1. Define your service struct and exported methods in a new file following the convention: methods must have signature func (s *YourService) MethodName(ctx context.Context, args *ArgsType, reply *ReplyType) error. (server/service.go (reference) + your_service.go (create))
2. Register the service with the server using server.RegisterName() in your main function, passing the service instance and optional metadata. (server/server.go (see Server.RegisterName method))
3. Update your protobuf or thrift definitions if using code generation, and regenerate service stubs. (_testutils/arith_service.proto (reference example))
4. Test the service using either xclient (multi-server) or oneclient (single-server) with the service name and method name you registered. (client/xclient_test.go (reference) or client/oneclient.go)

Add a Custom Discovery Provider

1. Implement the Discover interface defined in client/discovery.go: define the struct and implement GetServices(), Watch(), and Close() methods. (client/discovery.go (see Discover interface))
2. Integrate with the client by passing your discovery instance to xclient initialization: client := &client.XClient{...}. (client/xclient.go (see NewXClient constructor))
3. Reference existing implementations (peer2peer, DNS, mDNS) for patterns on error handling and event propagation. (client/peer2peer_discovery.go, client/dns_discovery.go, client/mdns_discovery.go (reference examples))

Add a Custom Load Balancing Strategy

1. Create a new struct implementing the Selector interface from client/selector.go: implement Select(), UpdateServer(), RemoveServer(), and Close() methods. (client/selector.go (see Selector interface))
2. Implement your selection logic (e.g., based on latency, request counts, or custom metrics). Reference smooth_weighted_round_robin.go for a production example. (client/smooth_weighted_round_robin.go (reference advanced example) or client/selector.go (see SelectMode implementations))
3. Configure the client to use your selector by setting the SelectMode option or passing your selector directly when creating xclient. (client/xclient.go (see NewXClient function and selector integration))

Add Support for a New Transport Protocol

1. Create a new connection implementation file (e.g., connection_your_protocol.go) that implements network dialing and connection setup. (client/connection_quic.go or client/connection_kcp.go (reference implementations))
2. Implement protocol-specific listener on the server side in a new server file, handling the protocol-specific accept loop and message read/write. (server/quic.go or server/kcp.go (reference implementations))
3. Register your protocol in the connection factory logic and ensure the router in server/router.go can handle incoming requests from your new transport. (client/connection.go (factory patterns) and server/server.go (listener registration))

• Go — High concurrency support via goroutines, fast compilation, excellent networking libraries (net, io), and strong gRPC ecosystem compatibility.
• Protobuf & Thrift — Language-agnostic serialization formats enabling cross-language RPC integration; pluggable codec support allows protocol flexibility.
• QUIC (quic-go) — Multiplexed, lower-latency alternative to TCP with built-in congestion control; reduces connection overhead for bursty workloads.
• KCP & io_uring — KCP provides reliable UDP for game/streaming use cases; io_uring enables high-throughput polling on Linux without syscall

1. Plugin separation: Registry plugins (etcd, zookeeper, consul, redis) are now external packages — importing old code with embedded plugins will break post-v1.7.6. 2. Build tags required: QUIC and KCP support require -tags "quic kcp" during go get/build or they silently compile as no-ops. 3. Thrift code generation: _testutils/thrift_arith_service.thrift requires thrift compiler to regenerate .go files — not auto-generated by go generate. 4. Service discovery dependency: XClient requires a Discovery implementation (e.g., BasePeer, DNS) or it will panic on Call() — no default fallback. 5. Connection pooling semantics: oneclient_pool vs xclient_pool have different semantics — pools are per-service not per-server.

• Service Discovery — rpcx abstracts multiple discovery backends (DNS, mDNS, etcd, Consul) behind a Discovery interface — understanding how XClient resolves service names to server addresses is critical for deployment architecture decisions
• Load Balancing Selectors — rpcx provides multiple SelectMode implementations (random, round-robin, weighted, consistent hash, geo-aware) — choosing the right selector directly impacts request distribution and latency across server instances
• Circuit Breaker Pattern — client/circuit_breaker.go implements fault tolerance by failing fast on cascading failures — essential for preventing thundering herd problems in microservices
• Connection Pooling — oneclient_pool.go and xclient_pool.go manage reusable connection pools per service/server — connection pooling directly affects throughput and prevents connection exhaustion under load
• RPC Serialization Codecs — codec/ directory supports protobuf, msgpack, thrift, and others — different codecs trade off serialization speed, payload size, and schema evolution — critical for choosing between framework features
• Transport Protocol Abstraction — connection_*.go files abstract TCP, QUIC, KCP, RDMA, and io_uring into pluggable transports — rpcx achieves cloud-native scalability by supporting modern high-performance transports beyond standard TCP
• Token Bucket Rate Limiting — clientplugin/req_rate_limiting_redis.go uses token bucket algorithm for distributed rate limiting across client instances — prevents overloading downstream services

• rpcxio/rpcx-etcd — Official service registry backend extracted from main rpcx repo — required if you want etcd-based service discovery (post-v1.7.6)
• rpcxio/rpcx-gateway — HTTP/REST gateway for accessing rpcx services from any language — enables polyglot clients and browser access
• smallnest/rpcx-java — Java implementation of rpcx protocol — allows Java services to communicate with Go rpcx services using the same wire format
• grpc/grpc-go — Alternative RPC framework with similar goals (service discovery, load balancing, multiple transports) but uses HTTP/2 and protobuf exclusively
• hashicorp/consul — Service mesh & registry platform that rpcx integrates with via rpcx-consul plugin for dynamic service discovery in production

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 connection_iouring.go and connection_rdma.go

The client directory shows specialized connection implementations for io_uring and RDMA protocols (connection_iouring.go, connection_iouring_test.go, connection_rdma.go), but connection_rdma.go lacks a corresponding test file. Given the complexity and platform-specific nature of these transports, comprehensive tests are critical for reliability. This would improve test coverage for advanced network transport options that differentiate rpcx from competitors.

• [ ] Create client/connection_rdma_test.go with unit tests for RDMA connection initialization, read/write operations, and error handling
• [ ] Add tests for edge cases: connection timeout, buffer overflow, network interruptions specific to RDMA
• [ ] Ensure tests can run on CI (may need platform-specific build tags like +build linux)
• [ ] Add benchmarks comparing RDMA vs standard TCP connections in connection_rdma_test.go

Implement GitHub Actions workflows for protocol-specific codec testing

The repo supports multiple serialization formats (protobuf, thrift, msgpack) as seen in codec/testdata and dependencies, but .github/workflows/go.yml likely only runs basic tests. Creating protocol-specific test workflows would ensure codec compatibility across version updates. This is critical since codec bugs can silently break client-server communication.

• [ ] Create .github/workflows/codec-tests.yml to run codec/codec_test.go with different protobuf/thrift versions
• [ ] Add a matrix strategy testing against google.golang.org/protobuf versions (1.28, 1.30, 1.36)
• [ ] Add thrift compatibility testing using apache/thrift versions specified in go.mod
• [ ] Include a test validating serialization round-trips for codec/testdata/protobuf.proto and codec/testdata/thrift_colorgroup.thrift

Add integration tests for discovery mechanisms across different backends

The client directory contains multiple discovery implementations (dns_discovery.go, mdns_discovery.go, peer2peer_discovery.go, multiple_servers_discovery.go) but lacks comprehensive integration tests validating they work correctly with the rest of the system. The stub "etcd notice" in README suggests etcd discovery may be incomplete. Integration tests would prevent regressions in service discovery—a critical component for microservices.

• [ ] Create client/discovery_integration_test.go with docker-compose setup for testing each discovery type
• [ ] Add tests validating dns_discovery.go against a test DNS server (e.g., miekg/dns mock)
• [ ] Add tests for mdns_discovery.go using grandcat/zeroconf (already in deps) to simulate mDNS service registration/discovery
• [ ] Test failover scenarios in multiple_servers_discovery.go when servers become unavailable
• [ ] Document expected behavior for each discovery mechanism in _documents/ for future contributors

• Add comprehensive integration tests for smooth_weighted_round_robin.go selector comparing load distribution fairness across different weight ratios — currently selector_test.go only covers basic SelectMode functionality
• Document and add examples for cross-language service calls via rpcx-gateway (gateway examples exist but are not in this repo) — create examples/gateway_client_http.go showing HTTP invocation of rpcx services
• Implement geo_utils.go usage in selector — the file exists but SelectMode geographic selection in selector.go is incomplete; add GeoSelectMode with concrete geo-location based routing tests

• High · Outdated Go Version Dependency — go.mod. The go.mod specifies 'go 1.24.0' which is not a released Go version as of the analysis date. This indicates either a configuration error or use of an unstable/future version. This could lead to unexpected behavior, missing security patches, and incompatibility with production environments. Fix: Update to a stable, released Go version (e.g., 1.22.x or 1.23.x). Verify compatibility with all dependencies and conduct thorough testing before deployment.
• High · Known Vulnerable Dependency: quic-go — go.mod - github.com/quic-go/quic-go v0.57.0. The dependency 'github.com/quic-go/quic-go v0.57.0' may contain known vulnerabilities. QUIC protocol implementations have historically had security issues related to connection handling and state management. Fix: Run 'go list -json -m all | nancy sleuth' or use 'gosec' to check for CVEs. Update to the latest patched version and verify security advisories from the quic-go project.
• High · Deprecated Dependency: gogo/protobuf — go.mod - github.com/gogo/protobuf v1.3.2. The project depends on 'github.com/gogo/protobuf v1.3.2', which is a deprecated package. The gogo/protobuf project is no longer actively maintained and has been superseded by google.golang.org/protobuf. Using deprecated packages risks missing critical security updates. Fix: Migrate to 'google.golang.org/protobuf' (already in go.mod). Remove gogo/protobuf dependency and update all related imports and code.
• Medium · Network Services Exposure Risk — client/connection_quic.go, client/connection_kcp.go, client/connection_rdma.go, server/gateway.go, client/mdns_discovery.go. The codebase implements multiple network protocol handlers (QUIC, KCP, RDMA, mDNS, standard TCP/UDP) and includes gateway functionality. Without proper network segmentation and authentication, this could expose services to unauthorized access or network-based attacks. Fix: Implement strict network segmentation, use TLS/mTLS for all connections, validate all incoming requests, implement rate limiting, and restrict mDNS discovery to trusted networks only.
• Medium · Potential Deserialization Vulnerability — codec/codec.go, server/jsonrpc2.go, server/converter.go. The codebase supports multiple serialization formats (protobuf, thrift, msgpack, JSON-RPC2) without explicit validation of deserialized data. Deserialization vulnerabilities can lead to remote code execution or denial of service attacks. Fix: Implement strict input validation for all deserialized objects, use safe deserialization libraries, validate schema compliance, and implement size limits on deserialized data to prevent DoS attacks.
• Medium · Insufficient Error Handling in File Transfer — server/file_transfer.go. The file transfer functionality in server/file_transfer.go may not properly validate file paths or handle symlink attacks. This could allow attackers to read arbitrary files or write to unexpected locations. Fix: Implement strict path validation, reject path traversal attempts (../, /etc/passwd patterns), validate file sizes before transfer, use a whitelist of allowed directories, and check for symlinks.
• Medium · Redis Dependency Security — clientplugin/req_rate_limiting_redis.go, go.mod. The project integrates with Redis (github.com/redis/go-redis and go-redis/redis_rate) without evidence of connection encryption validation in the visible code. Redis connections should always use TLS in production. Fix: Enforce TLS for all Redis connections, validate certificates, use Redis AUTH with strong credentials, implement network segmentation, and never expose Redis ports to untrusted networks.
• Low · Missing Security Headers in HTTP Gateway — undefined. The gateway and HTTP router components may not enforce security headers. This could allow clickjacking, XSS, or MIME-type sniffing attacks in scenarios where the RPC service is exposed 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.