Merge remote-tracking branch 'origin/main' into version/2.0.6

Author: Danny-Dasilva

README.md

@@ -111,7 +111,11 @@ const CycleTLS = require('cycletls').default;
 ```
 
 ## JA4R (Raw) TLS Fingerprinting
+## JA4R (Raw) TLS Fingerprinting
+
+> **Important:** Pass `ja4r` to configure the TLS ClientHello. JA4 (hash) is a report-only value; configuring with a JA4 hash will not change your fingerprint.
 
+JA4R is the raw format of JA4 fingerprinting that allows explicit configuration of cipher suites, extensions, and signature algorithms:
 > **Important:** Pass `ja4r` to configure the TLS ClientHello. JA4 (hash) is a report-only value; configuring with a JA4 hash will not change your fingerprint.
 
 JA4R is the raw format of JA4 fingerprinting that allows explicit configuration of cipher suites, extensions, and signature algorithms:
@@ -140,6 +144,7 @@ const CycleTLS = require('cycletls').default;
 })();
 ```
 
+### Golang JA4R Example
 ### Golang JA4R Example
 ```go
 package main
@@ -150,11 +155,14 @@ import (
 )
 
 func main() {
+	client := cycletls.Init(cycletls.WithRawBytes())
 	client := cycletls.Init(cycletls.WithRawBytes())
 	defer client.Close()
 
+	// Chrome JA4R fingerprint (raw format)
 	// Chrome JA4R fingerprint (raw format)
 	response, err := client.Do("https://tls.peet.ws/api/all", cycletls.Options{
+		Ja4r: "t13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601",
 		Ja4r: "t13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601",
 		UserAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/138.0.0.0 Safari/537.36",
 	}, "GET")
@@ -163,6 +171,7 @@ func main() {
 		log.Fatal(err)
 	}
 	log.Println("Response with JA4R:", response.Status)
+	log.Println("Response with JA4R:", response.Status)
 }
 ```
 
@@ -547,6 +556,49 @@ func main() {
 
 **Note:** Use `Init()` for standard compatibility with `chan Response`. Use `Init(cycletls.WithRawBytes())` when you need the performance benefits of handling raw `[]byte` responses directly.
 
+#### Performance Enhancement: Raw Bytes Option
+
+The default `Init()` method provides the standard v1 API with `chan Response`. For performance-critical applications that can handle raw bytes, use the `WithRawBytes()` option:
+
+```go
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"github.com/Danny-Dasilva/CycleTLS/cycletls"
+)
+
+func main() {
+	// Use WithRawBytes() option for performance enhancement
+	client := cycletls.Init(cycletls.WithRawBytes())
+	defer client.Close()
+	
+	// Queue a request
+	go func() {
+		client.Queue("https://ja3er.com/json", cycletls.Options{
+			Ja3: "771,4865-4867-4866-49195-49199-52393-52392-49196-49200-49162-49161-49171-49172-51-57-47-53-10,0-23-65281-10-11-35-16-5-51-43-13-45-28-21,29-23-24-25-256-257,0",
+			UserAgent: "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:87.0) Gecko/20100101 Firefox/87.0",
+		}, "GET")
+	}()
+	
+	// Performance pattern: receive raw bytes from RespChanV2
+	select {
+	case responseBytes := <-client.RespChanV2:
+		var response cycletls.Response
+		json.Unmarshal(responseBytes, &response)
+		fmt.Printf("Status: %d\n", response.Status)
+		fmt.Printf("Body: %s\n", response.Body)
+	// Alternative: still supports v1 pattern via RespChan
+	case response := <-client.RespChan:
+		fmt.Printf("Status: %d\n", response.Status)
+		fmt.Printf("Body: %s\n", response.Body)
+	}
+}
+```
+
+**Note:** Use `Init()` for standard compatibility with `chan Response`. Use `Init(cycletls.WithRawBytes())` when you need the performance benefits of handling raw `[]byte` responses directly.
+
 ## Creating an instance
 
 In order to create a `CycleTLS` instance, you can run the following:
@@ -868,6 +920,8 @@ client := &http.Client{Transport: transport}
   ja3: '771,4865-4867-4866-49195-49199-52393-52392-49196-49200-49162-49161-49171-49172-51-57-47-53-10,0-23-65281-10-11-35-16-5-51-43-13-45-28-21,29-23-24-25-256-257,0',
   // JA4R token for enhanced fingerprinting (raw format)
   ja4r: 't13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601',
+  // JA4R token for enhanced fingerprinting (raw format)
+  ja4r: 't13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601',
   // User agent for request
   userAgent: 'Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:87.0) Gecko/20100101 Firefox/87.0',
   // Proxy to send request through (supports http, socks4, socks5, socks5h)
@@ -2789,6 +2843,7 @@ type Browser struct {
 	UserAgent          string
 	JA3                string
 	JA4r               string
+	JA4r               string
 	HTTP2Fingerprint   string
 	QUICFingerprint    string
 	InsecureSkipVerify bool
@@ -2813,12 +2868,17 @@ type SSEEvent struct {
 
 </details>
 
+### How do I use JA4R fingerprinting?
 ### How do I use JA4R fingerprinting?
 
 <details>
 
 > **Note:** Pass `ja4r` (raw format) to configure fingerprints. JA4 hashes are for observation only.
+> **Note:** Pass `ja4r` (raw format) to configure fingerprints. JA4 hashes are for observation only.
+
+JA4R is the raw format for configuring TLS fingerprints with explicit cipher suites and extensions.
 
+### Golang JA4R Fingerprinting
 JA4R is the raw format for configuring TLS fingerprints with explicit cipher suites and extensions.
 
 ### Golang JA4R Fingerprinting
@@ -2835,10 +2895,12 @@ func main() {
 	client := cycletls.Init()
 	defer client.Close()
 
+	// Use both JA3 and JA4R fingerprints
 	// Use both JA3 and JA4R fingerprints
 	response, err := client.Do("https://tls.peet.ws/api/clean", cycletls.Options{
 		Ja3:       "771,4865-4866-4867-49195-49199-49196-49200-52393-52392-49171-49172-156-157-47-53,0-23-65281-10-11-35-16-5-13-18-51-45-43-27-17513,29-23-24,0",
 		Ja4r:      "t13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601", // JA4R fingerprint (raw format)
+		Ja4r:      "t13d1516h2_002f,0035,009c,009d,1301,1302,1303,c013,c014,c02b,c02c,c02f,c030,cca8,cca9_0000,0005,000a,000b,000d,0012,0017,001b,0023,002b,002d,0033,44cd,fe0d,ff01_0403,0804,0401,0503,0805,0501,0806,0601", // JA4R fingerprint (raw format)
 		UserAgent: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36",
 	}, "GET")
 
@@ -2847,6 +2909,7 @@ func main() {
 	}
 
 	log.Println("Response with JA4R:", response.Status)
+	log.Println("Response with JA4R:", response.Status)
 }
 ```
 

cycletls/tests/integration/tls13_auto_retry_test.go

@@ -63,7 +63,6 @@ func TestTLS13ForceRenegotiation(t *testing.T) {
 			t.Errorf("❌ CRITICAL: Force TLS 1.3 renegotiation failed: %s", err.Error())
 		} else {
 			t.Logf("🎉 SUCCESS: Force TLS 1.3 renegotiation worked! Status: %d, Duration: %v", response.Status, duration)
-
 			// Check if response indicates TLS 1.3 was used
 			if strings.Contains(string(response.Body), "TLS 1.3") {
 				t.Logf("✅ CONFIRMED: Server response indicates TLS 1.3 was negotiated")

tests/test-utils.js

@@ -0,0 +1,166 @@
+const initCycleTLS = require("../dist/index.js");
+
+// Track all active instances for emergency cleanup
+const activeInstances = new Set();
+
+/**
+ * Wrapper function that ensures CycleTLS instance cleanup even if test fails.
+ * Use this for individual test cases that need a single CycleTLS instance.
+ *
+ * @param {number|object} portOrOptions - Port number or full options object
+ * @param {Function} testFn - Test function that receives the CycleTLS instance
+ * @returns {Promise} Promise that resolves with test function result
+ *
+ * @example
+ * test("Should handle timeout", async () => {
+ *   await withCycleTLS(9117, async (cycleTLS) => {
+ *     const response = await cycleTLS('https://example.com');
+ *     expect(response.status).toBe(200);
+ *   });
+ * });
+ */
+async function withCycleTLS(portOrOptions, testFn) {
+  const options = typeof portOrOptions === 'number'
+    ? { port: portOrOptions }
+    : portOrOptions;
+
+  const cycleTLS = await initCycleTLS(options);
+  activeInstances.add(cycleTLS);
+
+  try {
+    return await testFn(cycleTLS);
+  } finally {
+    activeInstances.delete(cycleTLS);
+    await cycleTLS.exit();
+  }
+}
+
+/**
+ * Alternative approach for tests that need multiple CycleTLS instances
+ * or want more control over instance lifecycle.
+ *
+ * @param {object} options - CycleTLS initialization options
+ * @returns {Promise} CycleTLS instance that's tracked for cleanup
+ *
+ * @example
+ * test("Multiple instances", async () => {
+ *   const cycleTLS1 = await createSafeCycleTLS({ port: 9001 });
+ *   const cycleTLS2 = await createSafeCycleTLS({ port: 9002 });
+ *
+ *   try {
+ *     // Test logic here
+ *   } finally {
+ *     await cleanupCycleTLS(cycleTLS1);
+ *     await cleanupCycleTLS(cycleTLS2);
+ *   }
+ * });
+ */
+async function createSafeCycleTLS(options) {
+  const cycleTLS = await initCycleTLS(options);
+  activeInstances.add(cycleTLS);
+  return cycleTLS;
+}
+
+/**
+ * Manual cleanup function for instances created with createSafeCycleTLS
+ *
+ * @param {object} instance - CycleTLS instance to cleanup
+ */
+async function cleanupCycleTLS(instance) {
+  if (activeInstances.has(instance)) {
+    activeInstances.delete(instance);
+    await instance.exit();
+  }
+}
+
+/**
+ * Wrapper for test suites that share a single CycleTLS instance
+ * Use this with Jest's beforeAll/afterAll hooks
+ *
+ * @param {object} options - CycleTLS initialization options
+ * @returns {object} Object with instance and cleanup function
+ *
+ * @example
+ * describe("Test Suite", () => {
+ *   let cycleTLS;
+ *   let cleanup;
+ *
+ *   beforeAll(async () => {
+ *     ({ instance: cycleTLS, cleanup } = await createSuiteInstance({ port: 9001 }));
+ *   });
+ *
+ *   afterAll(async () => {
+ *     await cleanup();
+ *   });
+ *
+ *   test("test 1", async () => {
+ *     // Use cycleTLS here
+ *   });
+ * });
+ */
+async function createSuiteInstance(options) {
+  const instance = await createSafeCycleTLS(options);
+
+  const cleanup = async () => {
+    await cleanupCycleTLS(instance);
+  };
+
+  return { instance, cleanup };
+}
+
+/**
+ * Get count of active CycleTLS instances (useful for debugging)
+ */
+function getActiveInstanceCount() {
+  return activeInstances.size;
+}
+
+/**
+ * Emergency cleanup of all active instances
+ * This is called automatically on process exit
+ */
+async function cleanupAll() {
+  if (activeInstances.size > 0) {
+    console.warn(`⚠️  Cleaning up ${activeInstances.size} orphaned CycleTLS instances`);
+    const instances = [...activeInstances];
+    await Promise.all(instances.map(async (instance) => {
+      try {
+        await instance.exit();
+      } catch (error) {
+        console.error('Error cleaning up CycleTLS instance:', error);
+      }
+    }));
+    activeInstances.clear();
+  }
+}
+
+// Global cleanup hooks to prevent process hanging
+// These will catch instances that weren't properly cleaned up
+process.on('beforeExit', async () => {
+  await cleanupAll();
+});
+
+process.on('SIGTERM', async () => {
+  await cleanupAll();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  await cleanupAll();
+  process.exit(0);
+});
+
+// Jest global cleanup hook
+if (typeof afterAll !== 'undefined') {
+  afterAll(async () => {
+    await cleanupAll();
+  });
+}
+
+module.exports = {
+  withCycleTLS,
+  createSafeCycleTLS,
+  cleanupCycleTLS,
+  createSuiteInstance,
+  getActiveInstanceCount
+};