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/kerryjiang/SuperSocket 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
• 3 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% 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 kerryjiang/SuperSocket repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kerryjiang/SuperSocket.

What it runs against: a local clone of kerryjiang/SuperSocket — 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 kerryjiang/SuperSocket | 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 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 kerryjiang/SuperSocket. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kerryjiang/SuperSocket.git
#   cd SuperSocket
#
# 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 kerryjiang/SuperSocket and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kerryjiang/SuperSocket(\\.git)?\\b" \\
  && ok "origin remote is kerryjiang/SuperSocket" \\
  || miss "origin remote is not kerryjiang/SuperSocket (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "SuperSocket.sln" \\
  && ok "SuperSocket.sln" \\
  || miss "missing critical file: SuperSocket.sln"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "samples/ConsoleEchoServer/Program.cs" \\
  && ok "samples/ConsoleEchoServer/Program.cs" \\
  || miss "missing critical file: samples/ConsoleEchoServer/Program.cs"
test -f "samples/CommandServer/Program.cs" \\
  && ok "samples/CommandServer/Program.cs" \\
  || miss "missing critical file: samples/CommandServer/Program.cs"
test -f "samples/LiveChat/ChatSession.cs" \\
  && ok "samples/LiveChat/ChatSession.cs" \\
  || miss "missing critical file: samples/LiveChat/ChatSession.cs"

# 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/kerryjiang/SuperSocket"
  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).

SuperSocket is a high-performance, extensible socket server framework for .NET that abstracts low-level socket operations and provides a pipeline-based processing model for building custom network applications. It handles TCP, UDP, and WebSocket protocols out-of-the-box with built-in session management, middleware support, and command handling, eliminating boilerplate for real-time communication systems. Monorepo structure: core transport logic in root src/ (likely SuperSocket.Server, SuperSocket.ProtoBase), samples/ contain runnable reference implementations (CommandServer with ADD/SUB/MULT command files, AspNetSample with ASP.NET Core integration), and legacy/ holds v1.x artifacts. GitHub Actions workflows in .github/workflows/ drive CI and NuGet packaging.

.NET backend developers building real-time applications (game servers, IoT platforms, chat systems) who need to implement custom network protocols without managing raw sockets, buffer management, or protocol state machines manually.

Production-ready and actively maintained: the project has NuGet releases (v2.1.0+), CI/CD pipelines via GitHub Actions (build, myget, benchmark workflows), and organized release notes through v2.1.0. Recent updates include sample projects (AspNetSample, CommandServer, ConfigSample) and Docker support, indicating active development.

Standard open source risks apply.

Recent work includes ASP.NET Core integration (AspNetSample/Program.cs), configuration system expansion (samples/ConfigSample/appsettings.json), and cross-platform support verification (build.yml, benchmark.yml workflows). Release pipeline stabilization evident from myget_release.yml workflow.

git clone https://github.com/kerryjiang/SuperSocket.git
cd SuperSocket
dotnet restore SuperSocket.sln
dotnet build SuperSocket.sln
dotnet run --project samples/CommandServer/CommandServer.csproj

Daily commands: For CommandServer sample: dotnet run --project samples/CommandServer/CommandServer.csproj. For AspNetSample: dotnet run --project samples/AspNetSample/AspNetSample.csproj (runs on launchSettings.json configured port). For client: dotnet run --project samples/BasicClient/BasicClient.csproj.

• SuperSocket.sln — Solution file defining the entire project structure and all buildable projects; essential starting point for understanding the codebase organization.
• Directory.Build.props — Global build properties and version definitions shared across all projects; governs compilation, packaging, and framework targets.
• samples/ConsoleEchoServer/Program.cs — Canonical example demonstrating the minimal setup required to build a SuperSocket server; essential reference for API patterns.
• samples/CommandServer/Program.cs — Shows command-based protocol implementation and request routing patterns central to SuperSocket's extensibility model.
• samples/LiveChat/ChatSession.cs — Complex sample demonstrating session management, WebSocket integration, and real-time bidirectional communication patterns.
• .github/workflows/build.yml — CI/CD pipeline defining build, test, and release processes; critical for understanding deployment and quality gates.
• pkg/SuperSocket.csproj — Main NuGet package definition aggregating core components for distribution; shows public API surface area.

Create a Custom Protocol Handler

1. Create a new project or add to existing samples directory mirroring CustomProtocol structure (samples/CustomProtocol/CustomProtocol.csproj)
2. Define custom package class by implementing SuperSocket's package interface (samples/CustomProtocol/MyPackage.cs)
3. Implement package filter to parse raw bytes into structured packets (samples/CustomProtocol/MyPackageFilter.cs)
4. Configure server with custom protocol in Program.cs using UsePackageHandler<T> (samples/CustomProtocol/Program.cs)

Add a New Command to Command-Based Server

1. Create new command class inheriting from SuperSocket.Command<T>, following CommandServer pattern (samples/CommandServer/ADD.cs)
2. Implement Execute method to handle command logic and session response (samples/CommandServer/ADD.cs)
3. Register command in Program.cs via command handler configuration (samples/CommandServer/Program.cs)

Configure TLS/SSL Security

1. Create or reference certificate file (PFX format) in assets directory (assets/supersocket.pfx)
2. Define SSL settings in appsettings configuration with certificate path and password (samples/ConfigSample/appsettings.tls.json)
3. Apply configuration to server builder using UseSSL() in Program.cs (samples/ConfigSample/Program.cs)

Integrate SuperSocket into ASP.NET Core Application

1. Reference SuperSocket NuGet package in your ASP.NET project (samples/AspNetSample/AspNetSample.csproj)
2. Configure SuperSocket server instance as hosted service in Program.cs (samples/AspNetSample/Program.cs)
3. Define server options via appsettings.json configuration file (samples/AspNetSample/appsettings.json)

• .NET 5+ / C# — High-performance async/await support, strong type system, and native Windows/Linux deployment targets enable low-latency socket operations at scale.
• Async pipeline architecture — Enables non-blocking I/O multiplexing allowing thousands of concurrent connections without thread exhaustion; critical for high-concurrency socket servers.
• Protocol-agnostic handler system — Pluggable package filters and command handlers decouple protocol parsing from business logic, allowing reuse across TCP/UDP/WebSocket transports.
• Angular 11 + Material UI — Provides real-time bidirectional WebSocket communication in LiveChat sample with responsive material design components.
• Docker containerization — Enables reproducible deployment and horizontal scaling of SuperSocket applications in cloud-native environments.

• Pipeline-based request processing over traditional thread-per-connection

  • Why: Async pipelines scale to 10,000+ concurrent connections vs. thread pools limited to ~1,000 threads on typical hardware.
  • Consequence: Increased complexity in error handling and debugging; requires async-aware code patterns throughout.

• Protocol handlers as pluggable components rather than builtin support

  • Why: Allows framework to remain lightweight and support arbitrary custom protocols without bloat.
  • Consequence: Users must implement protocol filtering logic; framework provides less out-of-box protocol support vs. enterprise frameworks.

• .NET Framework dependency over cross-platform alternatives

  • Why: Maximizes performance on Windows production servers and provides tight OS-level socket optimizations.
  • Consequence: Limits addressability to .NET ecosystem; not suitable for non-.NET infrastructure.

• Configuration-driven server setup (appsettings.json) over programmatic API only

  • Why: Allows operational teams to adjust ports, TLS, and connection limits without recompilation.
  • Consequence: Adds complexity to bootstrap code; runtime configuration parsing can fail at startup if malformed.

• Does not provide built-in HTTP/REST API framework—use ASP.NET Core for HTTP protocols
• Does not handle application-level authentication or authorization—integrators must implement
• Does not provide persistent message queuing or replication—is not a message broker
• Does not include ORM or database drivers—application responsibility to integrate data access
• Not Linux-specific—requires .NET runtime but targets Windows as primary deployment platform

1. Pipeline filters must handle partial packets and buffer management correctly—incomplete frames cause silent hangs. 2) Session lifecycle: sessions expire if not properly heartbeat'd in CommandServer; check idle timeout in appsettings.json. 3) No built-in TLS/SSL—secure protocols require custom IPacketFilter wrapping or external reverse proxy. 4) WebSocket support is in separate packages (not visible in this file list); main NuGet may not include it—check SuperSocket.WebSocket NuGet dependency. 5) Docker image requires dotnet runtime compatible with target framework in global.json.

• Pipeline Filter Architecture — Core abstraction in SuperSocket—filters form a chain processing incoming bytes into structured packets; understanding this is mandatory to implement custom protocols
• Session Management (Stateful Connection Lifecycle) — SuperSocket tracks session identity, timeout, and state; you must understand session lifecycle to implement authentication, heartbeats, and graceful disconnects
• Middleware (Connection/Packet Hooks) — SuperSocket's middleware system is where you intercept connection events and packets before/after processing; critical for logging, rate-limiting, and cross-cutting concerns
• Buffer Pooling (ArrayPool<T>) — SuperSocket uses System.Buffers.ArrayPool to reduce GC pressure; you must respect buffer lifetime and return semantics to avoid memory corruption
• Async/Await I/O (ValueTask, IAsyncEnumerable) — SuperSocket is fully async-first; all network operations use ValueTask<> to minimize allocations; you must write async filters and handlers
• Dependency Injection Container (Microsoft.Extensions.DependencyInjection) — SuperSocket integrates with .NET's DI container; commands, filters, and middleware are registered and resolved via IServiceProvider
• WebSocket Protocol (RFC 6455 + Handshake) — SuperSocket includes WebSocket support; understanding frame types, masking, and upgrade handshakes is needed for real-time browser communication

• dotnet/runtime — Core .NET runtime and System.Net.Sockets; SuperSocket depends on its async socket APIs and buffer pooling primitives
• Microsoft/AspNetCore — Dependency injection and configuration abstractions (Microsoft.Extensions.*) that SuperSocket integrates with; also shows middleware patterns SuperSocket adopts
• Salaros/Toxy — Alternative .NET socket abstraction layer; shows competing approach to protocol-agnostic server frameworks
• NLua/NLua — Not directly related, but SuperSocket often paired with scripting for dynamic command handlers and protocol extensions in game/IoT use cases
• grpc/grpc-dotnet — Modern alternative for RPC-style communication; complements SuperSocket for when gRPC semantics (request-response, streaming) fit better than custom protocols

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 SuperSocket.Channel and SuperSocket.Connection core modules

The repo contains multiple protocol handlers (TCP, UDP, WebSocket) and session management logic, but there's no visible test project structure in the file listing. Channel and connection management are critical paths that handle protocol handshakes, packet routing, and session lifecycle. Adding unit tests here would catch regressions early and provide examples for contributors testing custom protocol implementations.

• [ ] Create SuperSocket.Tests project alongside existing src modules
• [ ] Write unit tests for Channel abstraction (connection establishment, packet buffering, protocol switching)
• [ ] Write unit tests for IPackageHandler implementations across TCP/UDP/WebSocket protocols
• [ ] Add integration tests validating session lifecycle (connect → authenticate → receive → disconnect)
• [ ] Reference existing samples (EchoServer, CommandServer) as test fixtures

Add GitHub Actions workflow for dependency security scanning and NuGet package auditing

The repo has build.yml and myget.yml workflows, but no automated security scanning. Given that SuperSocket is a networking framework used in production systems, and the LiveChat sample has outdated Angular 11 dependencies (from 2020), a security audit workflow would prevent vulnerable dependencies from being packaged and released. This follows common practices for libraries handling network I/O.

• [ ] Create .github/workflows/security-audit.yml with dependabot or Snyk integration
• [ ] Add step to run 'dotnet list package --vulnerable' on SuperSocket.sln to catch .NET CVEs
• [ ] Add npm audit scanning for samples/LiveChat/ClientApp package.json and flag outdated major versions
• [ ] Configure workflow to fail CI if high/critical vulnerabilities are found
• [ ] Document findings in SECURITY.md (if missing) with update guidance for samples

Refactor LiveChat sample to use a current Angular LTS version and document full-stack extensibility

The LiveChat sample is a valuable real-world reference for how to use SuperSocket with ASP.NET Core + WebSocket + Angular client, but it uses Angular 11 (EOL since 2021). Modernizing it to Angular 16+ LTS and adding a README documenting the protocol flow, session management, and how to extend authentication would make it a better learning resource. This addresses a gap: while ConsoleEchoServer has a README, LiveChat doesn't.

• [ ] Update samples/LiveChat/ClientApp to Angular 16+ LTS (run ng update @angular/cli @angular/core)
• [ ] Resolve npm audit issues (update bootstrap, jquery, oidc-client to secure versions)
• [ ] Create samples/LiveChat/README.md documenting: (1) WebSocket protocol handshake between server/client, (2) ChatSession lifecycle, (3) how to add custom authentication middleware
• [ ] Add diagram showing message flow: Client → Browser WebSocket → ASP.NET Core → SuperSocket SessionHandler → Broadcast
• [ ] Include instructions for deploying LiveChat sample with samples/EchoServer/Dockerfile as reference

• Add integration tests for samples/CommandServer/ command handlers (ADD.cs, SUB.cs, MULT.cs)—currently no visible test projects; create SuperSocket.Tests.Commands with xUnit cases for arithmetic edge cases (overflow, negative numbers).
• Document the pipeline filter contract: BasicClient/MyPackageFilter.cs lacks XML comments on IPacketFilter.Filter() method signature; add examples for stateful protocol parsing (multi-frame messages).
• Create a minimal UDP example in samples/: current samples focus on TCP/WebSocket; add samples/UdpEchoServer/ with connectionless packet handling to show protocol flexibility.

The SuperSocket repository demonstrates moderate security concerns, primarily stemming from significantly outdated dependencies in the LiveChat sample application. The Angular 11, Bootstrap 4.3.1, and jQuery

• High · Outdated Angular Dependencies with Known Vulnerabilities — samples/LiveChat/ClientApp/package.json. The LiveChat sample application uses Angular 11.0.2 and related packages from 2020-2021. Multiple security vulnerabilities have been identified in these versions, including XSS, prototype pollution, and other attack vectors. Angular 11 reached end-of-life in November 2021. Fix: Upgrade to the latest stable Angular version (v17+). Update all @angular packages, rxjs, and related dependencies to their latest versions. Run 'npm audit fix' to address known vulnerabilities.
• High · Vulnerable Bootstrap Version — samples/LiveChat/ClientApp/package.json. Bootstrap 4.3.1 contains known XSS and CSS vulnerability (CVE-2019-8331). This version was released in January 2019 and has multiple documented security issues. Fix: Upgrade Bootstrap to version 5.x or later. Update the package.json dependency to 'bootstrap': '^5.3.0' and test compatibility with the application.
• High · Outdated jQuery Version — samples/LiveChat/ClientApp/package.json. jQuery 3.5.1 is outdated and contains known vulnerabilities. Current versions of jQuery (3.6.x and 3.7.x) contain security patches for prototype pollution and other attack vectors. Fix: Upgrade jQuery to version 3.6.4 or later. Run 'npm audit' to verify the update resolves security issues.
• Medium · OIDC Client Library Version — samples/LiveChat/ClientApp/package.json. oidc-client version 1.9.1 is outdated. The project has been superseded by oidc-client-ts which includes security improvements and active maintenance. Fix: Migrate to 'oidc-client-ts' package instead. Update authentication implementation to use the new library with its enhanced security features.
• Medium · Potential Hardcoded Certificate Asset — assets/supersocket.pfx. The file 'assets/supersocket.pfx' appears to be a certificate file stored in the repository. If this contains a private key for development/testing, it could expose cryptographic material if the repository is compromised. Fix: Verify that this certificate does not contain production keys. Move certificate files to secure secret management systems. Add *.pfx to .gitignore if not already present. Document certificate generation procedures for local development.
• Medium · Outdated TypeScript Version — samples/LiveChat/ClientApp/package.json. TypeScript 4.0.5 is from September 2020 and contains known type safety issues. Current versions (5.x) provide improved security type checking and vulnerability fixes. Fix: Upgrade TypeScript to version 5.x. Update package.json to 'typescript': '^5.2.0' and verify type compatibility across the codebase.
• Low · Missing Security Headers Configuration — samples/AspNetSample/Program.cs. The AspNetSample and other samples do not appear to have documented security header configurations (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in their setup. Fix: Implement security headers middleware in the ASP.NET application. Add Content Security Policy (CSP), X-Frame-Options, X-Content-Type-Options, and other protective headers to all HTTP responses.
• Low · Dependency Version Flexibility — samples/LiveChat/ClientApp/package.json. Some dependencies use loose version specifiers (^, ~) which may pull in minor/patch versions with vulnerabilities. For example, 'core-js': '^3.3.3' could install any version from 3.3.3 to 4.0.0. Fix: Use package-lock.json to lock exact versions in production. Review and test dependency updates regularly. Consider using more restrictive version specifications for critical security libraries.

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.