CycleTLS

Accepting Community Support and PR's  [](http://godoc.org/github.com/Danny-Dasilva/CycleTLS/cycletls) [](https://github.com/Danny-Dasilva/CycleTLS/blob/main/LICENSE) [](https://goreportcard.com/report/github.com/Danny-Dasilva/CycleTLS/cycletls) [](https://www.npmjs.org/package/cycletls)

If you have a API change or feature request feel free to open an Issue

🚀 Features

• High-performance Built-in goroutine pool used for handling asynchronous requests
• Custom header ordering via fhttp
• Proxy support | Socks4, Socks5, Socks5h
• Ja3 Token configuration

Table of contents

• Table of contents
• Installation
• Usage
  • QuickStart JS
  • Quickstart Golang
  • Initializing CycleTLS
  • API/Methods
  • Request Config
  • Response Schema
  • Multiple Requests Example
• Local Setup
• QA
• LICENSE

Dependencies

node ^v16.0
golang ^v1.21x

Installation

Node Js

$ npm install cycletls

Golang

$ go get github.com/Danny-Dasilva/CycleTLS/cycletls 

Usage

Example CycleTLS Request for Typescript and Javascript

You can run this test in tests/simple.test.ts

const initCycleTLS = require('cycletls');
// Typescript: import initCycleTLS from 'cycletls';

(async () => {
  // Initiate CycleTLS
  const cycleTLS = await initCycleTLS();

  // Send request
  const response = await cycleTLS('https://ja3er.com/json', {
    body: '',
    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',
    proxy: 'http://username:password@hostname.com:443', 
  }, 'get');

  console.log(response);

  // Cleanly exit CycleTLS
  cycleTLS.exit();

})();

Example CycleTLS Request for Golang

package main

import (
    "log"
    "github.com/Danny-Dasilva/CycleTLS/cycletls"
)

func main() {

    client := cycletls.Init()

    response, err := client.Do("https://ja3er.com/json", cycletls.Options{
        Body : "",
        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");
    if err != nil {
        log.Print("Request Failed: " + err.Error())
    }
    log.Println(response)
}

Example using your own custom http.Client

Creating an instance

In order to create a cycleTLS instance, you can run the following:

JavaScript

// The initCycleTLS function spawns a Golang process that handles all requests concurrently via goroutine loops. 
const initCycleTLS = require('cycletls');
// import initCycleTLS from 'cycletls';

// Async/Await method
const cycleTLS = await initCycleTLS();
// .then method
initCycleTLS().then((cycleTLS) => {});

Golang

import (
    "github.com/Danny-Dasilva/CycleTLS/cycletls"
)

//The `Init` function initializes golang channels to process requests. 
client := cycletls.Init()

CycleTLS Alias Methods

The following methods exist in CycleTLS

cycleTLS(url, [config])

cycleTLS.get(url, [config])

cycleTLS.delete(url, [config])

cycleTLS.head(url, [config])

cycleTLS.options(url, [config])

cycleTLS.post(url, [config])

cycleTLS.put(url, config)

cycleTLS.patch(url, [config])

Url is not optional, config is optional

CycleTLS Request Config

{
  // URL for the request (required if not specified as an argument)
  url: "https://example.com"
  // Method for the request ("head" | "get" | "post" | "put" | "delete" | "trace" | "options" | "connect" | "patch")
  method: "get" // Default method
  // Custom headers to send
  headers: { "Authorization": "Bearer someexampletoken" }
  // Custom cookies to send
  Cookies: [{
    "name": "key",
    "value": "val",
    "path":  "/docs",
    "domain":  "google.com",
                "expires": "Mon, 02-Jan-2022 15:04:05 EST"
    "maxAge": 90,
    "secure": false,
    "httpOnly": true,
    "sameSite": "Lax"       
  }],
  // Body to send with request (must be a string - cannot pass an object)
  body: '',
  // JA3 token to send with request
  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',
  // 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 (must be in the same format)
  proxy: 'http://username:password@hostname.com:443',
  // Amount of seconds before request timeout (default: 7)
  timeout: 2,
  // Toggle if CycleTLS should follow redirects
  disableRedirect: true,
  // Custom header order to send with request (This value will overwrite default header order)
  headerOrder: ["cache-control", "connection", "host"],
  // Toggle if CycleTLS should skip verify certificate (If InsecureSkipVerify is true, TLS accepts any certificate presented by the server and any host name in that certificate.)
  insecureSkipVerify: false 
  // Forces CycleTLS to do a http1 handshake
  forceHTTP1: false 
}

CycleTLS Response Schema

{
  // Status code returned from server (Number)
  status: 200,
  // Body returned from the server (String)
  body: "",
  // Headers returned from the server (Object)
  headers: {
    "some": "header",
    ...
  },
  // FinalUrl returned from the server (String). This field is useful when redirection is active.
  finalUrl: "https://final.url/"    
}

Multiple Requests Example for Typescript and Javascript

If CycleTLS is being used by in a JavaScript environment, CycleTLS will spawn a Golang process to handle requests. This Golang process handles requests concurrently in a worker pool. Due to this, CycleTLS returns response objects as soon as they are made available (in other terms, CycleTLS processes requests as they are received, but responses are returned asynchronously so they will NOT be returned in the order requested)

If you are using CycleTLS in JavaScript, it is necessary to exit out of the instance to prevent zombie processes. The example below shows one way to approach cleanly exiting CycleTLS if you need to process multiple requests (note: keep in mind that calling the exit() function will kill any requests in progress). If your workflow requires requests running the entire time the process runs, modules such as exit-hook could serve as an alternative solution to cleanly exiting CycleTLS.

const initCycleTLS = require("cycletls");
// Typescript: import initCycleTLS from 'cycletls';

// Defining custom JA3 token and user agenton multiple requests,
  "https://httpbin.org/user-agent": {
    ja3: ja3,
    userAgent: userAgent,
  },
  "http://httpbin.org/post": {
    body: '{"field":"POST-VAL"}',
    method: "POST",
  },
  "http://httpbin.org/cookies": {
    cookies: [
      {
        name: "example1",
        value: "aaaaaaa",
        expires: "Mon, 02-Jan-2022 15:04:05 EST",
      },
    ],
  },
};

// Promises array of requests
const promises = [];

// Anonymous async function
(async () => {
  // Initiate CycleTLS
  const cycleTLS = await initCycleTLS();

  // Loop through requestDict (Object) defined above
  for (const url in requestDict) {
    // Fetch configs from requestDict (Object)
    const params = requestDict[url];

    // Send request (note: no waiting)
    const response = cycleTLS(
      url, {
        body: params.body ?? "", //?? is just setting defaults in this case
        ja3: params.ja3 ?? ja3,
        userAgent: params.userAgent ?? userAgent,
        headers: params.headers,
        cookies: params.cookies,
      }, params.method ?? "GET");

    // console.log the response object
    response.then((out) => {
      console.log(url, out);
    });

    // Push request to promise array
    promises.push(response);
  }

  // Wait for all requests to execute successfully
  Promise.all(promises).then(() => {
    // Cleanly exit CycleTLS one all requests have been received
    cycleTLS.exit();
  });
})();

Multiple Requests Example for Golang

The general expectation for golang packages is to expect the user to implement a worker pool or any other form of goroutine/asynchronous processing. This package includes a built in Queue method that leverages a worker pool/channels for long running asynchronous requests against a set of urls.

package main

import (
    "log"

    cycletls "github.com/Danny-Dasilva/CycleTLS/cycletls"
)

// Static variables
var (
    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"
    userAgent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.54 Safari/537.36"
)

// RequestConfig holds the configuration for each request.
type RequestConfig struct {
    URL     string
    Method  string
    Options cycletls.Options
}

func main() {
    client := cycletls.Init(true) // Initialize with worker pool

    // Define the requests
    requests := []RequestConfig{
        {
            URL:    "http://httpbin.org/delay/4",
            Method: "GET",
            Options: cycletls.Options{
                Ja3:       ja3,
                UserAgent: userAgent,
            },
        },
        {
            URL:    "http://httpbin.org/post",
            Method: "POST",
            Options: cycletls.Options{
                Body:      `{"field":"POST-VAL"}`,
                Ja3:       ja3,
                UserAgent: userAgent,
            },
        },
        {
            URL:    "http://httpbin.org/cookies",
            Method: "GET",
            Options: cycletls.Options{
                Ja3:       ja3,
                UserAgent: userAgent,
                Cookies: []cycletls.Cookie{
                    {
                        Name:  "example1",
                        Value: "aaaaaaa",
                    },
                },
            },
        },
    }

    // Queue the requests
    for _, req := range requests {
        client.Queue(req.URL, req.Options, req.Method)
    }

    // Asynchronously read responses as soon as they are available
    // They will return as soon as they are processed
    // e.g. Delay 3 will be returned last
    for i := 0; i < len(requests); i++ {
        response := <-client.RespChan
        log.Println("Response:", response)
    }

    // Close the client
    client.Close()
}

Dev Setup

If you would like to compile CycleTLS on your own, use the following commands:

Set module-aware mode go env -w GO111MODULE=off

Install golang dependencies go get github.com/Danny-Dasilva/CycleTLS/cycletls

install npm packages (this command handles the above)

npm install

To recompile index.ts in the src folder

npm run build

To recompile Golang files in the golang folder

All

npm run build:go

Windows

npm run build:go:windows:amd64

Linux

npm run build:go:linux:amd64

Mac

npm run build:go:mac:arm64

You can view the available compile options within the package.json

Questions

How do I set Cookies

How do I use CookieJar in CycleTLS?

How do I send multipart/form-data in CycleTLS

How do I send a application/x-www-form-urlencoded Post request

How do I download images?

How do I set/force HTTP1

Cross Compiling for other platforms

LICENSE

GPL3 LICENSE SYNOPSIS

**TL;DR*** Here's what the GPL3 license entails:

1. Anyone can copy, modify and distribute this software.
2. You have to include the license and copyright notice with each and every distribution.
3. You can use this software privately.
4. You can use this software for commercial purposes.
5. Source code MUST be made available when the software is distributed.
6. Any modifications of this code base MUST be distributed with the same license, GPLv3.
7. This software is provided without warranty.
8. The software author or license can not be held liable for any damages inflicted by the software.

More information on about the LICENSE can be found here