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/panjf2000/gnet 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 all four use cases

• Last commit 5w ago
• 6 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 94% of recent commits

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

What it runs against: a local clone of panjf2000/gnet — 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 panjf2000/gnet | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | Last commit ≤ 67 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev 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 67 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~37d)"
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/panjf2000/gnet"
  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).

gnet is a high-performance, event-driven networking framework written in pure Go that uses epoll (Linux) and kqueue (BSD/macOS) to handle thousands of concurrent connections with minimal memory overhead. It achieves significantly better throughput and lower latency than Go's standard net package by leveraging non-blocking I/O and avoiding goroutine-per-connection overhead. Flat architecture with platform-specific build tags: core event loop logic in eventloop_unix.go/eventloop_windows.go, connection lifecycle in connection_.go files, acceptor patterns in acceptor_.go, and utilities in conn_map.go (connection tracking), load_balancer.go (round-robin balancing), and internal/gfd (file descriptor wrapper). Tests live alongside implementation files.

Go developers building high-concurrency network services (game servers, message brokers, real-time systems, load balancers) who need sub-millisecond latencies and can handle the callback-based event loop programming model instead of the familiar goroutine-per-connection pattern.

Production-ready and actively maintained. The project has comprehensive CI/CD across multiple platforms (Linux, macOS, BSD, Windows via separate codepaths), extensive test coverage (gnet_test.go, eventloop_unix_test.go, conn_matrix_test.go), and uses semantic versioning (v2 module). Last activity is recent and visible through GitHub Actions workflows.

Low-to-moderate risk: single maintainer (panjf2000) is a concentration point, but the codebase is stable with infrequent breaking changes (v2 is mature). OS-specific code paths (acceptor_unix.go, connection_linux.go, engine_windows.go) add maintenance burden. Dependencies are minimal (ants worker pool, zap logging, valyala bytebuffer) and well-established.

Active maintenance with focused effort on performance optimization (workflows test_gc_opt.yml, test_poll_opt.yml indicate GC and polling tuning), cross-platform stability (cross-compile-bsd.yml), and security scanning (codeql.yml). No major breaking changes planned for v2—work is incremental hardening.

Clone the repository and run tests to verify setup:

git clone https://github.com/panjf2000/gnet.git
cd gnet
go mod download
go test -v ./...

No external services required; minimal dependencies auto-fetched via go mod.

Daily commands: No dev server in traditional sense—gnet is a library. Test the example server pattern by examining gnet_test.go, then write your own using the Serve() API with custom handlers. Run unit tests: go test -race -v ./... to catch data races.

• gnet.go: Public API surface—defines Engine interface, Serve function, and Conn interface that users interact with
• eventloop_unix.go: Core event loop for Linux/Unix using epoll; handles connection accept, read, write, and callback dispatch
• eventloop_windows.go: Windows-specific event loop using IOCP instead of epoll; parallel to Unix loop
• connection_linux.go: Linux-specific connection state and syscall optimization (TCP_NODELAY, SO_REUSEADDR)
• options.go: Configuration options and callback handler interface definitions (OnOpen, OnData, OnClose, OnTick)
• conn_matrix.go: Lock-free connection tracking matrix for rapid lookups; critical for scaling to thousands of connections
• load_balancer.go: Distributes connections across multiple eventloops; implements round-robin or least-loaded policies
• internal/gfd/gfd.go: File descriptor wrapper for tracking and cleanup; prevents FD exhaustion

Adding protocol support: Extend eventloop_unix.go and eventloop_windows.go OnData handlers. Adding platform: Create connection_os.go, acceptor_os.go, engine_os.go using syscall constants from golang.org/x/sys/os. Optimizing memory: Edit conn_map.go or conn_matrix.go for connection tracking. Adding handlers: See options.go for the full callback interface (OnOpen, OnData, OnClose, OnTick, OnShutdown). Most changes require platform-specific code, so check build tags carefully.

OS-specific behavior: Code builds differently on Linux (epoll), macOS/BSD (kqueue), and Windows (IOCP)—test your changes on target platform. Callback blocking: OnData/OnClose handlers are synchronous in the event loop; long operations block all connections in that loop. Memory pooling: bytebufferpool reuses buffers—never hold references after returning from OnData. Build tags: Files like connection_linux.go only compile on Linux; read build constraints. Goroutine limits: Default is NumCPU event loops; tuning via NumLoops option is required for high concurrency on weak hardware.

• epoll / kqueue — These are the OS syscalls gnet wraps—understanding how they multiplex I/O is critical to diagnosing performance issues and avoiding common blocking mistakes
• Reactor Pattern (event-driven) — gnet is a Reactor—a single thread dispatches callbacks instead of spawning goroutines per connection; you must avoid blocking in callbacks
• Lock-free ring buffers / matrix indexing — conn_matrix.go uses clever lock-free data structures for connection tracking; understanding this is key to safe concurrent access without mutexes
• TCP_NODELAY and SO_REUSEADDR socket options — gnet sets these automatically in connection_linux.go / connection_unix.go; knowing why (Nagle disable, port reuse on restart) helps optimize latency-sensitive apps
• Object pooling / buffer reuse — gnet reuses buffers via valyala/bytebufferpool to reduce GC pressure; critical for sustained high throughput
• IOCP (I/O Completion Ports) — Windows-specific alternative to epoll/kqueue; engine_windows.go and eventloop_windows.go implement this—understand it to port features across platforms
• Goroutine-per-connection vs. event loop tradeoff — gnet abandons Go's typical goroutine model for lower memory and fewer context switches; requires callback-based code which is a paradigm shift from net package

• valyala/fasthttp — HTTP-specific event-driven server also optimized for high throughput; complementary if you want HTTP on top of gnet
• eycorsican/go-tun2socks — Another high-performance Go networking project using syscalls directly; similar performance-first philosophy
• panjf2000/ants — Worker goroutine pool by same author, often paired with gnet to safely dispatch OnData callbacks to background jobs
• xtaci/kcptun — UDP-based protocol transport in pure Go; complementary transport layer alternative to gnet's TCP focus
• google/gvisor — Userspace network stack in Go; alternative architecture for network isolation (heavier than gnet, different use case)

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_linux.go and connection_bsd.go

The repo has platform-specific connection implementations (connection_linux.go, connection_bsd.go, connection_unix.go, connection_windows.go) but only basic test files exist (os_unix_test.go, os_windows_test.go). Linux and BSD connection handling deserves dedicated test coverage for edge cases like TCP_NODELAY, SO_REUSEADDR, and platform-specific socket options that differ between systems.

• [ ] Create connection_linux_test.go with tests for Linux-specific socket options and epoll integration
• [ ] Create connection_bsd_test.go with tests for BSD-specific socket options and kqueue integration
• [ ] Test edge cases like connection shutdown, option setting failures, and platform capability detection
• [ ] Reference existing connection_unix.go implementation to identify untested code paths

Add load balancer strategy tests and documentation in load_balancer.go

The load_balancer.go file exists but there are no corresponding unit tests (no load_balancer_test.go file visible). Given gnet's focus on high-performance event-driven networking, the load balancing strategy for distributing connections across event loops is critical. This needs thorough testing for fairness, correctness, and performance under various scenarios.

• [ ] Create load_balancer_test.go with tests for different balancing strategies (round-robin, least-loaded, etc.)
• [ ] Test load distribution correctness under uneven connection patterns and connection churn
• [ ] Add benchmarks comparing different load balancer implementations
• [ ] Document the load balancing algorithm choice and trade-offs in a dedicated section of README.md

Implement cross-platform buffer tests for pkg/buffer implementations

The repo has multiple buffer implementations (elastic_ring_buffer, elastic_ring_list_buffer, linked_list_buffer, ring_buffer) with some unit tests, but they appear platform-agnostic and lack integrated stress tests. Add comprehensive cross-platform buffer tests to verify correctness under concurrent access patterns that gnet's event loops would create.

• [ ] Create pkg/buffer/buffer_stress_test.go testing all buffer types under concurrent read/write patterns
• [ ] Add benchmarks comparing buffer types (elastic vs ring vs linked list) for gnet's use cases
• [ ] Test buffer behavior with the actual event loop in eventloop_unix_test.go and eventloop_windows.go patterns
• [ ] Verify memory usage and GC pressure across buffer implementations under sustained traffic

• idea: Add cross-platform benchmarks in a new examples/benchmarks/ directory comparing gnet vs net package on Windows (os_windows_test.go exists but has no comprehensive throughput benchmarks)
• idea: Write integration tests for conn_matrix_test.go covering edge cases like connection ID wraparound and matrix resizing under concurrent load (current tests only check basic ops)
• idea: Document the callback handler blocking behavior and add a NonBlockingOnData example in pkg/ showing how to safely dispatch to a worker pool (ants v2 is already imported but no example exists)

The gnet networking framework demonstrates generally good security practices with a focus on performance-critical, platform-specific implementations. Primary concerns include: (1) Outdated minimum Go version (1.20 is EOL), which should be updated to receive security patches; (2) Custom buffer and connection management code that requires careful verification to prevent race conditions and buffer misuse; (3) Platform-specific implementations across multiple operating systems that each require individual security auditing; (4) Lack of visible input validation patterns, though the library is low-level and may delegate this to consumers. The codebase lacks obvious secrets or injection vulnerabilities, and dependencies are relatively minimal and well-maintained. Recommendation: Update Go version, run comprehensive race condition testing, conduct platform-specific security audits, and integrate static analysis tools (gosec, staticcheck) into CI/CD.

• Medium · Outdated Go Version Requirement — go.mod (go 1.20). The project specifies Go 1.20 as the minimum version. Go 1.20 reached end-of-life in August 2024. Using outdated Go versions may expose the codebase to known security vulnerabilities that have been patched in newer releases. Fix: Update the minimum Go version to 1.23 or later. Ensure all dependencies are compatible with the newer version and run full test suite.
• Low · Potential Race Condition in Connection Handling — conn_map.go, conn_matrix.go, connection_*.go files. The codebase contains multiple platform-specific implementations (conn_matrix.go, conn_map.go, connection_*.go) for handling concurrent connections. Without reviewing the actual implementation details, concurrent map access or non-atomic operations could lead to race conditions in high-concurrency scenarios. Fix: Run the codebase with '-race' flag during testing: go test -race ./.... Ensure all shared state access is properly synchronized using mutexes or atomic operations.
• Low · Platform-Specific Code Paths Not Fully Visible — acceptor_*.go, connection_*.go, engine_*.go, eventloop_*.go, listener_*.go, client_*.go files. The project has multiple platform-specific implementations (Unix, Windows, BSD, Linux). Without visibility into the actual code content, potential platform-specific vulnerabilities in syscall usage, file descriptor handling, or networking primitives cannot be fully assessed. Fix: Conduct thorough code review of all platform-specific syscall usage. Use tools like 'gosec' to identify unsafe patterns. Test on each supported platform with network fuzzing tools.
• Low · Buffer Management Security — pkg/buffer/ directory. The project implements custom buffer management (pkg/buffer/elastic, pkg/buffer/ring, pkg/buffer/linkedlist). Custom memory management can introduce vulnerabilities such as buffer overflows, use-after-free, or improper bounds checking if not carefully implemented. Fix: Review buffer implementation for bounds checking. Use fuzzing tools to test buffer operations with various input sizes. Consider using proven third-party buffer libraries where applicable.
• Low · External Dependency: github.com/valyala/bytebufferpool — go.mod (github.com/valyala/bytebufferpool v1.0.0). The bytebufferpool package is a convenience dependency that reuses buffers. While generally safe, ensure its usage pattern doesn't lead to buffer reuse vulnerabilities where sensitive data might persist across requests. Fix: Verify that buffers containing sensitive data are explicitly cleared before being returned to the pool. Consider implementing a custom buffer clearing mechanism.

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.