<commit_before># blinksocks

[![version](https://img.shields.io/npm/v/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![downloads](https://img.shields.io/npm/dt/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![license](https://img.shields.io/npm/l/blinksocks.svg)](https://github.com/micooz/blinksocks/blob/master/LICENSE)
[![dependencies](https://img.shields.io/david/micooz/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![devDependencies](https://img.shields.io/david/dev/micooz/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)

[![Travis](https://img.shields.io/travis/micooz/blinksocks.svg)](https://travis-ci.org/micooz/blinksocks)
[![Coverage](https://img.shields.io/codecov/c/github/micooz/blinksocks/master.svg)](https://codecov.io/gh/micooz/blinksocks)
[![%e2%9d%a4](https://img.shields.io/badge/made%20with-%e2%9d%a4-ff69b4.svg)](https://github.com/micooz/blinksocks)

Yet another socks5 proxy, designed for speed :zap:. Inspired by [Shadowsocks](https://shadowsocks.org/en/index.html).

> Across the Great Wall we can reach every corner in the world.

## Features

* SOCKS5 support
* TCP & UDP support
* Universal server and client
* Full data strong encryption
* Ultra fast
* Easy to use

## Installation

You can get pre-compiled library(including executable) of blinksocks from **yarn** or **npm**. Both approach requires your system have had [Node.js](https://nodejs.org) installed.

### -> via yarn

If you know [yarn](https://yarnpkg.com/), this way is recommended:

```
$ yarn global add blinksocks
```

### -> via npm

```
$ npm install -g blinksocks
```

## Usage

Once installed, you can access blinksocks from command line directly:

```
$ blinksocks --help
```

### Options

The options are quite simple at present:

```

  Usage: blinksocks [options] [...]

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -c, --config <file>  a json file for configuration
    --ciphers            show all supported ciphers on the current platform

```

## Configuration

To start a server/client, you must specify a configuration json file(`config.json` for example) via `--config` or `-c`.

For **Client**, the file looks like:

```
{
  "host": "localhost",
  "port": 1080,
  "server_host": "example.com",
  "server_port": 7777,
  "password": "<PASSWORD>",
  "cipher": "aes-256-cfb",
  "use_iv": true,
  "log_level": "error"
}
```

For **Server**, the file looks like(without `server_host` and `server_port`):

```
{
  "host": "0.0.0.0",
  "port": 7777,
  "password": "<PASSWORD>",
  "cipher": "aes-256-cfb",
  "use_iv": true,
  "log_level": "error"
}
```

* `host`: Typically **localhost**.
* `port`: Typically **1080**.
* `server_host`: Typically **0.0.0.0**.
* `server_port`: Any available number.
* `password`: For data encryption, please keep it secret!
* `cipher`: Encryption method. You can enable **non-encryption mode** by set it to empty string.
* `use_iv`: Whether encrypt/decrypt with initialization vector or not.
* `log_level`: should take a value from Logging Level of
[Log4js.Level](http://stritti.github.io/log4js/docu/users-guide.html#configuration). The levels are case-insensitive and cumulative.

## Examples

Once prepared the `config.json`, you can start a service by a simple command:

```
$ blinksocks -c config.json
```

## Compile

For production use, we are running our code under `lib` not `src`, so compilation is necessary.

Compilation of blinksocks is super easy:

```
$ npm run compile
```

This will compile `src` to `lib`.

## Test

Any application who supports socks5 protocol([RFC 1928](https://tools.ietf.org/html/rfc1928)) can be used for testing.

For example:

```
$ curl --socks5-hostname localhost:1080 https://www.google.com
```

## For Firefox/Google Chrome and more...

A common usage of blinksocks is used it on **browsers**, so I give an advise here.

For Google Chrome, [SwitchyOmega](https://github.com/FelisCatus/SwitchyOmega) extension is a great approach to use socks5 service.

For FireFox, you can configure proxy at `Settings - Advanced - Network - Proxy`.

## Documentation

If you are interesting in `Principle`, `Architecture` or `Spec` of blinksocks, please
check out: [docs](https://github.com/micooz/blinksocks/tree/master/docs).

## Roadmap

Done:

* [x] non-encryption mode for debugging and non-security scenarios

Next major version(**v2.0.0**):

* [x] streaming data send/receive
* [x] encrypt/decrypt with initialization vector
* [x] DNS cache
* [x] UDP relay(need test!)
* [ ] docker deploy scripts
* [ ] more command line options

**v2.1.0**:

* [ ] daemon mode
* [ ] cluster processes

Further versions:

* [ ] ip ban
* [ ] more tests
* [ ] more docs
* [ ] more cipher support
* [ ] ...

## Contributors

Micooz(Owner), <EMAIL>

Waiting for more contributors...

## License

Apache License 2.0<commit_msg>docs(README): update<commit_after># blinksocks

[![version](https://img.shields.io/npm/v/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![downloads](https://img.shields.io/npm/dt/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![license](https://img.shields.io/npm/l/blinksocks.svg)](https://github.com/micooz/blinksocks/blob/master/LICENSE)
[![dependencies](https://img.shields.io/david/micooz/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)
[![devDependencies](https://img.shields.io/david/dev/micooz/blinksocks.svg)](https://www.npmjs.com/package/blinksocks)

[![Travis](https://img.shields.io/travis/micooz/blinksocks.svg)](https://travis-ci.org/micooz/blinksocks)
[![Coverage](https://img.shields.io/codecov/c/github/micooz/blinksocks/master.svg)](https://codecov.io/gh/micooz/blinksocks)
[![%e2%9d%a4](https://img.shields.io/badge/made%20with-%e2%9d%a4-ff69b4.svg)](https://github.com/micooz/blinksocks)

Yet another socks5 proxy, designed for speed :zap:. Inspired by [Shadowsocks](https://shadowsocks.org/en/index.html).

> Across the Great Wall we can reach every corner in the world.

## Features

* SOCKS5 support
* TCP & UDP support
* Universal server and client
* Full encryption
* Ultra fast
* Easy to use
* Docker integration

## Installation

You can get pre-compiled library(including executable) of blinksocks from **yarn** or **npm**. Both approach requires your system have had [Node.js](https://nodejs.org) installed.

### -> via yarn

If you know [yarn](https://yarnpkg.com/), this way is recommended:

```
$ yarn global add blinksocks
```

### -> via npm

```
$ npm install -g blinksocks
```

## Usage

Once installed, you can access blinksocks from command line directly:

```
$ blinksocks --help
```

### Options

The options are quite simple at present:

```

  Usage: blinksocks [options] [...]

  Options:

    -h, --help           output usage information
    -V, --version        output the version number
    -c, --config <file>  a json file for configuration
    --ciphers            show all supported ciphers on the current platform

```

## Configuration

To start a server/client, you must specify a configuration json file(`config.json` for example) via `--config` or `-c`.

For **Client**, the file looks like:

```
{
  "host": "localhost",
  "port": 1080,
  "server_host": "example.com",
  "server_port": 7777,
  "password": "<PASSWORD>",
  "cipher": "aes-256-cfb",
  "use_iv": true,
  "log_level": "error"
}
```

For **Server**, the file looks like(without `server_host` and `server_port`):

```
{
  "host": "0.0.0.0",
  "port": 7777,
  "password": "<PASSWORD>",
  "cipher": "aes-256-cfb",
  "use_iv": true,
  "log_level": "error"
}
```

* `host`: Typically **localhost**.
* `port`: Typically **1080**.
* `server_host`: Typically **0.0.0.0**.
* `server_port`: Any available number.
* `password`: For data encryption, please keep it secret!
* `cipher`: Encryption method. You can enable **non-encryption mode** by set it to empty string.
* `use_iv`: Whether encrypt/decrypt with initialization vector or not.
* `log_level`: should take a value from Logging Level of
[Log4js.Level](http://stritti.github.io/log4js/docu/users-guide.html#configuration). The levels are case-insensitive and cumulative.

## Examples

Once prepared the `config.json`, you can start a service by a simple command:

```
$ blinksocks -c config.json
```

## Compile

For production use, we are running our code under `lib` not `src`, so compilation is necessary.

Compilation of blinksocks is super easy:

```
$ npm run compile
```

This will compile `src` to `lib`.

## Test

Any application who supports socks5 protocol([RFC 1928](https://tools.ietf.org/html/rfc1928)) can be used for testing.

For example:

```
$ curl --socks5-hostname localhost:1080 https://www.google.com
```

## Deploy

We use Docker to auto-deploy a blinksocks server.

### Get image

You can build an image manually or pull it from docker hub:

* Build an image

```
$ docker build --tags blinksocks:latest .
```

* Pull from docker hub

```
$ docker pull blinksocks:latest
```

### Run in a container

Container will expose `1080` port, so you must bind a host port to `1080` via `-p`.

```
$ docker run -d -p 7777:1080 blinksocks:latest
```

## For Firefox/Google Chrome and more...

A common usage of blinksocks is used it on **browsers**, so I give an advise here.

For Google Chrome, [SwitchyOmega](https://github.com/FelisCatus/SwitchyOmega) extension is a great approach to use socks5 service.

For FireFox, you can configure proxy at `Settings - Advanced - Network - Proxy`.

## Documentation

If you are interesting in `Principle`, `Architecture` or `Spec` of blinksocks, please
check out: [docs](https://github.com/micooz/blinksocks/tree/master/docs).

## Roadmap

Done:

* [x] non-encryption mode for debugging and non-security scenarios

Next major version(**v2.0.0**):

* [x] streaming data send/receive
* [x] encrypt/decrypt with initialization vector
* [x] DNS cache
* [x] UDP relay(need test!)
* [x] docker deploy scripts
* [ ] more command line options

**v2.1.0**:

* [ ] http proxy
* [ ] daemon mode
* [ ] cluster processes

Further versions:

* [ ] ip ban
* [ ] more tests
* [ ] more docs
* [ ] more cipher support
* [ ] ...

## Contributors

Micooz(Owner), <EMAIL>

Waiting for more contributors...

## License

Apache License 2.0
{'fraction_non_alphanumeric': 0.1574596382026843, 'fraction_numerical': 0.014783116125267459, 'mean_word_length': 4.133799301048428, 'pattern_counts': {'":': 28, '<': 11, '<?xml version=': 0, '>': 17, 'https://': 46, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '435004', 'n_tokens_mistral': 3676, 'n_tokens_neox': 3391, 'n_words': 984}