Beta 3.0.0 release

[Danny-Dasilva]

What Changed in v3.0.0

CycleTLS v3.0.0 moves to a streaming-first API with built-in backpressure, so big downloads no longer blow up memory. It also brings full WebSocket V2 support, native SSE, and a modern response API. This doc focuses on user-impacting changes and high-level fixes.

At a Glance

• ⚠️ Breaking: new default export is CycleTLS class (legacy initCycleTLS still works).
• ⚠️ Breaking: responses stream by default for large files.
• WebSocket V2 is fully bidirectional (send/receive/close/ping/pong).
• SSE is built in with async iteration.
• Fetch-like helpers: json(), text(), buffer(), arrayBuffer(), blob().
• Stability and performance fixes across the stack.

The Problem (Before)

Client requests large file
Server reads entire file into memory
Server sends all data over WebSocket
Client tries to buffer everything
Out of memory

The Solution (After)

Client: "I can handle 64KB right now"
Server: sends 64KB, then waits
Client: processes data, "Send 32KB more"
Server: sends next 32KB
Continues until complete

Instead of dumping the entire response at once, the client and server agree on a small credit window so data only flows as fast as the client can handle it.

User-Impacting API Changes

1) ⚠️ Default Export Changed (Breaking)

initCycleTLS is no longer the default export. The new default is the CycleTLS class.

// New default (recommended)
import CycleTLS from 'cycletls';
const client = new CycleTLS();

If you want zero code changes, use the legacy named export:

// Legacy (still works)
import { initCycleTLS } from 'cycletls';
const client = await initCycleTLS();

2) ⚠️ Response Handling Is Streaming-First (Breaking)

Responses now stream by default. For small payloads, use helper methods. For large payloads, stream the body.

const response = await client.get(url);

// Small responses
const json = await response.json();
const text = await response.text();

// Large responses
for await (const chunk of response.body) {
  processChunk(chunk);
}

3) ⚠️ Headers Can Have Multiple Values

Header values are returned as arrays to reflect multiple values (e.g., repeated set-cookie). If you previously assumed a single string, update your handling.

4) ❗ HTTP Methods Are Now First-Class

Instead of passing a method string into a generic function, use dedicated methods like get, post, put, delete, patch, head, options, trace, and connect.

5) ❗ WebSocket V2 Is a Full Client

WebSockets now support the full event and send API (open/message/close/error, ping/pong, binary messages). If you relied on partial behavior, you can now use the full surface.

6) ❗ SSE Is Built In

Server-Sent Events are available via client.sse() with async iteration or callbacks for real-time feeds.

7) ❗ Response Helpers Match Fetch

The response now includes json(), text(), buffer(), arrayBuffer(), and blob() for convenience.

Bug Fixes (User Impact)

Connection Reuse and Concurrency

• Connection reuse is stable under concurrency (Issue #407): safe channel writes and panic recovery prevent "send on closed channel" crashes and keep the process alive.
• Cached-transport races no longer panic when a transport already exists; per-address locking serializes transport creation under load.
• Connection/transport caches are now bounded with LRU eviction and periodic cleanup, preventing unbounded growth and idle-connection leaks.

WebSocket Reliability

• WebSocket .ws() no longer hangs and now resolves reliably (Issue #408).
• WebSocket writes are serialized with a write mutex, preventing concurrent-write panics and frame corruption.
• WebSocket read/write loops now honor shutdown signals and read deadlines, so connections close cleanly without goroutine leaks.
• Binary ws_send correctly decodes base64 payloads (with fallback), fixing corrupted binary message delivery.

Request Lifecycle and Safety

• Invalid URL input no longer crashes the server; it returns a clean 400 error.
• Requests can be canceled by request ID without killing the process, avoiding stuck in-flight work.
• Client-side request timeouts now reject stalled calls, and server-side timeouts return 408 instead of hanging forever.
• Concurrent initCycleTLS() calls no longer spawn duplicate processes or trigger EADDRINUSE.
• Proxy TLS verification now respects InsecureSkipVerify for HTTPS proxies (no forced skip of cert checks).

Data Integrity

• Large payloads now parse correctly with 64-bit length handling, fixing corruption for responses larger than 4GB.
• HTTP/3 pre-dialed connections are closed when unusable, preventing goroutine and connection leaks.

Regression Tests Added

• Issue Performance Issue in CycleTLS with Node.js Compared to Go #407 connection reuse crash: cycletls/tests/integration/issue_407_connection_reuse_test.go, cycletls/tests/integration/panic_regression_test.go, cycletls/roundtripper_concurrency_test.go, tests/connectionReuse.test.ts.
• Read-timeout hangs: tests/read-timeout.test.ts, cycletls/tests/unit/timeout_do_test.go, cycletls/tests/integration/custom_timeout_test.go.
• WebSocket cleanup and binary send: cycletls/tests/integration/legacy_ws_goroutine_leak_test.go, cycletls/tests/unit/ws_send_base64_test.go, tests/websocket.test.ts.
• HTTP/3 leak prevention: cycletls/tests/integration/http3_leak_test.go.
• LRU eviction correctness: cycletls/roundtripper_lru_test.go.
• Protocol framing and state tracking safety: cycletls/tests/unit/protocol_encoder_test.go, cycletls/tests/unit/state_request_tracker_test.go, cycletls/tests/unit/state_websocket_tracker_test.go, cycletls/tests/unit/state_globals_test.go.

Performance Improvements

Transport Reuse and Connection Pooling

• HTTP/3 transports are cached and reused, avoiding a fresh QUIC handshake on every request.
• HTTP/1.1 keep-alives are enabled with sensible idle limits to reuse TCP/TLS connections.
• Connection/transport caches use LRU eviction with age-based cleanup to stay fast and bounded.
• Connection reuse fixes address the Node vs Go slowdown reported in Issue #407, so repeat requests are no longer penalized by constant setup costs.

Hot-Path Efficiency

• Shared buffer pooling reduces allocations in dispatchers and streaming paths, lowering GC pressure.
• Client pooling uses fast FNV-1a hashing for cache keys, reducing overhead when reusing clients.
• Per-address transport locking prevents duplicate transport creation work during high concurrency.

Migration Checklist

• ⚠️ If you use the default import, switch to CycleTLS or import { initCycleTLS }.
• ⚠️ If you read response.body directly, move to streaming or helper methods.
• ⚠️ If you rely on headers as single strings, handle multiple values.
• If you use WebSockets, you can adopt the full V2 feature set.