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/TooTallNate/Java-WebSocket 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 4mo ago
• 14 active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago

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

What it runs against: a local clone of TooTallNate/Java-WebSocket — 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 TooTallNate/Java-WebSocket | 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 ≤ 144 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TooTallNate/Java-WebSocket(\\.git)?\\b" \\
  && ok "origin remote is TooTallNate/Java-WebSocket" \\
  || miss "origin remote is not TooTallNate/Java-WebSocket (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 "src/main/java/org/java_websocket/WebSocketImpl.java" \\
  && ok "src/main/java/org/java_websocket/WebSocketImpl.java" \\
  || miss "missing critical file: src/main/java/org/java_websocket/WebSocketImpl.java"
test -f "src/main/java/org/java_websocket/client/WebSocketClient.java" \\
  && ok "src/main/java/org/java_websocket/client/WebSocketClient.java" \\
  || miss "missing critical file: src/main/java/org/java_websocket/client/WebSocketClient.java"
test -f "src/main/java/org/java_websocket/server/WebSocketServer.java" \\
  && ok "src/main/java/org/java_websocket/server/WebSocketServer.java" \\
  || miss "missing critical file: src/main/java/org/java_websocket/server/WebSocketServer.java"
test -f "src/main/java/org/java_websocket/drafts/Draft_6455.java" \\
  && ok "src/main/java/org/java_websocket/drafts/Draft_6455.java" \\
  || miss "missing critical file: src/main/java/org/java_websocket/drafts/Draft_6455.java"
test -f "src/main/java/org/java_websocket/framing/FramedataImpl1.java" \\
  && ok "src/main/java/org/java_websocket/framing/FramedataImpl1.java" \\
  || miss "missing critical file: src/main/java/org/java_websocket/framing/FramedataImpl1.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 144 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~114d)"
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/TooTallNate/Java-WebSocket"
  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).

A pure-Java WebSocket server and client library implementing RFC 6455 and RFC 7692 (PerMessageDeflate compression) using non-blocking NIO for high-concurrency, event-driven communication. It eliminates the need for external WebSocket dependencies, providing a lightweight alternative to heavier frameworks for bidirectional socket communication in 100% Java without native code. Monolithic Java library: src/main/java/org/java_websocket/ contains core server/client classes and protocol handlers; src/main/example/ holds 20+ runnable example implementations (ChatServer, SSLServerExample, PerMessageDeflateExample); src/test/ contains BDD-style Gherkin tests and JUnit 5 tests; Gradle build.gradle orchestrates compilation and Maven publishing.

Java backend developers and DevOps engineers building real-time applications (chat servers, live dashboards, monitoring systems) who need embedded WebSocket support without running a separate Node.js or Go server, and want fine-grained control over SSL/TLS, custom headers, and protocol negotiation.

Production-ready and actively maintained: version 1.6.1-SNAPSHOT with Maven Central distribution, comprehensive CI/CD (checkstyle.yml, ci.yml, sonar.yml workflows), 855KB of Java code, and extensive Autobahn conformance test reports. Last commit activity and test infrastructure (JUnit 5) indicate active development and stability.

Low risk for most use cases—single maintainer (TooTallNate) is a potential concern for critical infrastructure, but the library is well-established with no unusual dependencies (only SLF4J logging facade). Verify compatibility with your target Java version (1.8+) and test SSL/TLS certificate setup if using HTTPS, as there are multiple SSLServerExample variants suggesting configuration complexity.

Active development on version 1.6.1-SNAPSHOT with SLF4J 2.0.15 and JUnit 5.11.4 integration. CI workflows validate checkstyle compliance and code quality via Sonar. Autobahn test reports indicate ongoing protocol conformance validation. No breaking changes visible in recent snapshots.

git clone https://github.com/TooTallNate/Java-WebSocket.git && cd Java-WebSocket && gradle build && java -cp build/libs/Java-WebSocket-1.6.1-SNAPSHOT.jar org.java_websocket.server.WebSocketServer

Daily commands: Run examples directly: gradle run -PmainClass=org.java_websocket.examples.ChatServer, or gradle build && java -cp build/libs/Java-WebSocket-1.6.1-SNAPSHOT.jar org.java_websocket.examples.ChatServer. Server listens on localhost:8887 by default.

• src/main/java/org/java_websocket/WebSocketImpl.java — Core WebSocket implementation handling frame parsing, message routing, and state management—all connection logic flows through here.
• src/main/java/org/java_websocket/client/WebSocketClient.java — Client-side entry point managing connection lifecycle, handshake, and message dispatch to listeners.
• src/main/java/org/java_websocket/server/WebSocketServer.java — Server-side entry point managing socket acceptance, client registration, and multi-client message broadcasting.
• src/main/java/org/java_websocket/drafts/Draft_6455.java — RFC 6455 protocol implementation defining frame encoding/decoding and handshake validation—the specification backbone.
• src/main/java/org/java_websocket/framing/FramedataImpl1.java — Frame-level serialization and deserialization logic for all WebSocket message types.
• src/main/java/org/java_websocket/AbstractWebSocket.java — Base class providing shared state management, listeners, and socket operations for both client and server.
• build.gradle — Defines Java 1.8+ compatibility, slf4j logging, and JUnit testing dependencies required for builds.

Create a Custom WebSocket Server

1. Extend WebSocketServer and implement abstract methods. (src/main/java/org/java_websocket/server/WebSocketServer.java)
2. Override onOpen(WebSocket conn, ClientHandshake handshake) to register new clients. (src/main/java/org/java_websocket/server/WebSocketServer.java)
3. Override onMessage(WebSocket conn, String message) to handle text frames. (src/main/java/org/java_websocket/server/WebSocketServer.java)
4. Call broadcast(String text) to send to all connected clients. (src/main/java/org/java_websocket/server/WebSocketServer.java)
5. In main, instantiate your server, set port/address, and call start(). (src/main/example/ChatServer.java)

Create a Custom WebSocket Client

1. Extend WebSocketClient and pass a URI to the constructor. (src/main/java/org/java_websocket/client/WebSocketClient.java)
2. Override onOpen(ServerHandshake handshakedata) to confirm connection. (src/main/java/org/java_websocket/client/WebSocketClient.java)
3. Override onMessage(String message) to handle received text frames. (src/main/java/org/java_websocket/client/WebSocketClient.java)
4. Call send(String text) or send(ByteBuffer data) to send messages. (src/main/java/org/java_websocket/client/WebSocketClient.java)
5. Call connectBlocking() or use connect() with async listener. (src/main/example/ChatClient.java)

Enable SSL/TLS (wss://) for Secure Connections

1. Create an SSLContext from a KeyStore with certificate. (src/main/example/SSLServerExample.java)
2. Pass SSLContext to WebSocketServer via constructor or setter. (src/main/java/org/java_websocket/server/WebSocketServer.java)
3. For clients, set SSLContext on the WebSocketClient before connect(). (src/main/example/SSLClientExample.java)
4. Use wss:// URI scheme instead of ws://. (src/main/example/SSLClientExample.java)

Add Message Compression (RFC 7692 permessage-deflate)

1. Enable deflate draft on server or client via setWebsocketFactory() or constructor draft list. (src/main/java/org/java_websocket/drafts/Draft_6455.java)
2. Create PerMessageDeflateExtension and add to draft extension list. (src/main/java/org/java_websocket/extensions/permessage_deflate/PerMessageDeflateExtension.java)
3. Send and receive messages normally; compression/decompression is automatic. (src/main/example/PerMessageDeflateExample.java)

1. No default logging implementation shipped—you must add an SLF4J binding (e.g., slf4j-simple in tests) or logging will silently fail; see src/main/example/simplelogger.properties. 2) SSL/TLS examples show multiple SSLSocketChannel variants (SSLSocketChannel.java vs SSLSocketChannel2.java)—verify which is appropriate for your JDK version and keystore setup. 3) WebSocket handshake customization (custom headers, subprotocol negotiation) requires overriding specific methods in WebSocketServer/WebSocketClient; the handshake is strict and protocol-version-sensitive. 4) PerMessageDeflate compression requires explicit opt-in via Draft negotiation; not enabled by default.

• RFC 6455 WebSocket Protocol — The core specification this library implements; understanding the handshake (HTTP Upgrade header), frame structure (opcodes, FIN bit, masking), and close semantics is essential to using the library correctly
• Non-blocking I/O (NIO) and SocketChannels — This library's entire performance model depends on java.nio.channels.SocketChannel and Selectors; understanding how non-blocking reads/writes and event multiplexing work is critical to diagnosing hangs or high CPU usage
• RFC 7692 PerMessageDeflate Compression — Optional but commonly-used extension for reducing bandwidth on text/JSON payloads; understanding compression context, LZ77 dictionary, and negotiation is important for production deployments
• TLS/SSL Certificate Handling and SSLEngine — Production deployments require WSS (WebSocket Secure); understanding KeyStore/TrustStore setup, certificate validation chains, and SSLEngine state machines avoids security misconfigurations
• Frame Fragmentation and Continuation Opcodes — WebSocket allows splitting large messages across multiple frames using FIN bits and opcode 0x0 (continuation); misunderstanding this breaks streaming/chunked message handling
• WebSocket Masking and XOR Operations — Client-to-server frames must be XOR-masked per RFC 6455; this library handles masking automatically but understanding why (cache-poisoning attack prevention) is important for security context
• SLF4J Logging Facade Pattern — The library uses SLF4J but ships no implementation; understanding how to bind slf4j-simple, logback, or log4j2 prevents debugging blindness and is a common integration pain point

• eclipse/jetty.project — Heavy-duty WebSocket server alternative with full servlet container; use this if you need HTTP/2, security realms, or clustering
• netty/netty — Lower-level NIO framework that this library builds on; if you need more fine-grained control over networking layers or other protocols
• javalin/javalin — Lightweight web framework with built-in WebSocket support; simpler than Jetty if you want HTTP + WebSocket in one package
• remkop/picocli — No direct relation but example projects (ChatServer, ServerStressTest) could benefit from CLI argument parsing instead of hardcoded defaults

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 SSLSocketChannel and SSLSocketChannel2

The repo has multiple SSL implementation files (SSLSocketChannel.java and SSLSocketChannel2.java) but there are no visible test files for these critical security components. Given that SSL/TLS is fundamental to secure WebSocket connections, these classes deserve dedicated unit tests covering certificate validation, handshake failures, and edge cases. This is a high-value PR as it improves test coverage for security-sensitive code.

• [ ] Create src/test/java/org/java_websocket/SSLSocketChannelTest.java with tests for certificate validation
• [ ] Create src/test/java/org/java_websocket/SSLSocketChannel2Test.java with tests for the alternative SSL implementation
• [ ] Add tests for SSL handshake failures, expired certificates, and hostname verification
• [ ] Verify tests run with the existing JUnit 5 setup in the build.gradle

Add integration tests for client reconnection and proxy handling examples

The repo contains example files ReconnectClientExample.java and ProxyClientExample.java that demonstrate important features, but there are no corresponding test cases validating these behaviors work correctly. Adding integration tests would ensure these features remain functional across releases and provide a template for users implementing similar functionality.

• [ ] Create src/test/java/org/java_websocket/client/ReconnectClientIntegrationTest.java testing exponential backoff and reconnection logic
• [ ] Create src/test/java/org/java_websocket/client/ProxyClientIntegrationTest.java testing proxy connections (HTTP CONNECT tunneling)
• [ ] Use embedded server approach to test client behavior without external dependencies
• [ ] Verify tests integrate with existing CI workflows in .github/workflows/ci.yml

Add unit tests for Draft_6455 frame parsing edge cases and RFC 6455 compliance

The Draft_6455.java class implements the RFC 6455 WebSocket protocol specification. While the repo has autobahn test reports in /autobahn-reports, there are no visible unit tests for the frame parsing logic, masking validation, fragmentation handling, or protocol edge cases. This is critical since frame parsing is the core of the protocol implementation.

• [ ] Create src/test/java/org/java_websocket/drafts/Draft_6455Test.java
• [ ] Add tests for frame parsing: payload length encoding (7-bit, 16-bit, 64-bit variants)
• [ ] Add tests for masking/unmasking validation per RFC 6455 Section 5.3
• [ ] Add tests for fragmented message reconstruction and opcode validation
• [ ] Add tests for close frame status codes and control frame handling
• [ ] Reference the autobahn reports to ensure compliance with known test cases

• Add comprehensive JavaDoc comments to src/main/java/org/java_websocket/SocketChannelIOHelper.java—currently missing method-level docs explaining NIO buffer management semantics, blocking behavior, and when to use read() vs write()
• Create a missing src/main/example/ProxyClientExample.java that demonstrates proxy authentication (seen in file list but likely minimal)—add complete CONNECT tunnel handshake, BASIC auth, and SOCKS5 support with working test case
• Write integration test in src/test/java/ validating SSL handshake failure scenarios (expired cert, mismatched hostname, untrusted CA)—currently unclear from file list if exception paths are fully covered

The Java-WebSocket codebase demonstrates generally good security practices with minimal dependencies and active use of code quality and security scanning tools (SonarQube, Checkstyle). However, the project targets Java 1.8, which is significantly outdated and lacks modern security improvements. The lack of visible automated dependency vulnerability scanning in CI/CD and the presence of multiple SSL/TLS example files that could contain insecure defaults are moderate concerns. The main recommendations are to upgrade the Java target version to 11+, add explicit dependency vulnerability scanning to the build pipeline, and audit example code for security issues. Overall security posture is reasonable for a mature library, but modernization is needed.

• Medium · Permissive Source Compatibility Target — build.gradle (sourceCompatibility and targetCompatibility settings). The project targets Java 1.8 (sourceCompatibility = 1.8, targetCompatibility = 1.8) which is significantly outdated. Java 8 reached end-of-life in December 2030 for Oracle JDK but many critical security patches have been released. Modern Java versions (17+) include substantial security improvements including stronger cryptography, better memory safety protections, and removal of deprecated insecure APIs. Fix: Upgrade to Java 11 (LTS minimum) or preferably Java 17+ (current LTS). Update sourceCompatibility and targetCompatibility to at least 11. Review and test code compatibility with newer versions. This is especially critical for WebSocket implementations that handle network I/O and SSL/TLS.
• Medium · Limited Dependency Oversight — build.gradle, CI/CD workflows (.github/workflows/). The project has minimal dependencies (only SLF4J and JUnit), which is positive, but there is no evidence of dependency vulnerability scanning in the CI/CD pipeline. The gradle/pom.xml files do not show explicit security plugins like OWASP DependencyCheck or Gradle Security vulnerability scanning configured. Fix: Add OWASP DependencyCheck plugin to build.gradle: 'org.owasp.dependencycheck' plugin. Alternatively, integrate Snyk or GitHub Dependabot for automated vulnerability scanning. Add to CI/CD pipeline to catch vulnerable transitive dependencies early.
• Medium · Sonar Analysis Configuration Present But Rigor Unknown — sonar-project.properties, .github/workflows/sonar.yml. The presence of sonar-project.properties indicates code quality scanning is in place, but without access to the actual configuration and reports, the security rules enforced are unknown. WebSocket implementations are security-sensitive and may benefit from stricter SAST rules. Fix: Review and enhance sonar-project.properties to include security-specific rules. Enable SonarQube quality gates for security issues with 'BLOCKER' severity. Configure to fail builds on security hotspots. Ensure rules cover cryptography, authentication, and data validation.
• Low · Example Files May Contain Hardcoded Configurations — src/main/example/ (multiple SSL and server example files). Multiple example files exist (SSLServerExample.java, SSLClientExample.java, TwoWaySSLServerExample.java, etc.) which could potentially contain hardcoded credentials, default passwords, or insecure default configurations used for demonstration purposes. These could be copied into production code. Fix: Audit all example files to ensure they do not contain hardcoded secrets, default credentials, or insecure default configurations. Add clear warnings in documentation about never using example code directly in production. Consider using environment variables or property files for sensitive configuration in examples.
• Low · Missing SECURITY.md File — Repository root. There is no visible SECURITY.md or security policy file in the root directory. This makes it unclear how security vulnerabilities should be reported and what the project's security response procedures are. Fix: Create a SECURITY.md file that includes: security reporting procedures, contact information for security issues, disclosure timeline expectations, and supported versions for security patches. Reference RFC 9116 for standard format.

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.