From d359644428e0a47e331f3457b63b866d93161873 Mon Sep 17 00:00:00 2001 From: Micooz Date: Wed, 9 Aug 2017 14:55:13 +0800 Subject: [PATCH] docs: update --- README.md | 32 ++++++++---- docs/development/architecture/README.md | 35 +++++++------ docs/development/steps/README.md | 13 ++++- docs/presets/README.md | 69 +++++++++++-------------- 4 files changed, 82 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index c66107e..b198cc5 100755 --- a/README.md +++ b/README.md @@ -10,31 +10,37 @@ [![Coverage](https://img.shields.io/codecov/c/github/blinksocks/blinksocks/master.svg)](https://codecov.io/gh/blinksocks/blinksocks) [![%e2%9d%a4](https://img.shields.io/badge/made%20with-%e2%9d%a4-ff69b4.svg)](https://github.com/blinksocks/blinksocks) -A framework for building composable proxy protocol stack. Inspired by [Shadowsocks](https://shadowsocks.org), -and [ShadowsocksR](https://github.com/shadowsocksr/shadowsocksr). +A framework for building composable proxy protocol stack. ## Features -* HTTP/Socks5/Socks4/Socks4a using the same port -* Customizable Protocols([presets](docs/presets)): simple, composable, and flexible +* Simple proxy interfaces for Socks5/Socks4/Socks4a and HTTP +* Customizable Protocols(using [presets](docs/presets)): simple, composable, and flexible * Cross-platform: running on Linux based, Windows and macOS +* Portable/Executable versions available * Partially compatible with **shadowsocks** [#27](https://github.com/blinksocks/blinksocks/issues/27) -* Dynamic server switch ## GUI ready For desktop use, you can download official [blinksocks-desktop](https://github.com/blinksocks/blinksocks-desktop), a cross-platform GUI for blinksocks. +## Executables ready(Not GUI) + +You can download precompiled executables for different platforms and use it directly without having Node.js installed: + +[Download](https://github.com/blinksocks/blinksocks/releases). + ## Getting Started ### Requirements -blinksocks is built on top of [Node.js](https://nodejs.org), so please install Node.js(**greater than v6.x**) on your operating system. +blinksocks is built on top of [Node.js](https://nodejs.org), if you want to use it in an ordinary way or do some hacking, +please install Node.js(**v6.x and above**) on your operating system. ### Install or Upgrade -You can get the latest pre-compiled library(including executables) of blinksocks from **yarn** or **npm**. +You can get the latest blinksocks via package manager **yarn** or **npm**. > NOTE: Node.js comes with npm installed so you don't have to install npm individually. @@ -42,7 +48,7 @@ You can get the latest pre-compiled library(including executables) of blinksocks $ npm install -g blinksocks ``` -### Without Install? +### Without yarn or npm? If you hate to install and want to get a even more portable version, we have one: @@ -52,18 +58,24 @@ $ wget https://raw.githubusercontent.com/blinksocks/blinksocks/master/build/blin ## Run blinksocks -**installed version** +**installed version(require Node.js)** ``` $ blinksocks client -c blinksocks.client.json ``` -**portable version** +**portable version(require Node.js)** ``` $ node blinksocks.js -c blinksocks.client.json ``` +**executable version(~~Node.js~~)** + +``` +$ ./blinksocks(.exe) --help +``` + For configuring blinksocks, please refer to [Configuration](docs/config). ## Documents diff --git a/docs/development/architecture/README.md b/docs/development/architecture/README.md index 2eca8b1..0a8a567 100755 --- a/docs/development/architecture/README.md +++ b/docs/development/architecture/README.md @@ -71,20 +71,22 @@ These two presets act as two middlewares, processing data from the bottom to the +-----------+ ``` -Ordinarily, `DST.ADDR` and `DST.PORT` is required to be sent to server(like "origin" preset), +Ordinarily, `DST.ADDR` and `DST.PORT` is required to be sent to server(like "ss-base" preset), otherwise server cannot figure out where to send data to. -Blinksocks will pass **target address** to the first preset once a connection between application -and blinksocks client was constructed, so you can obtain that address in your frame preset. +The framework will prepend `proxy` preset to the preset list on client side. Action(PROXY_HANDSHAKE_DONE) is fired +once this preset resolved the target address. Other presets(such as "ss-base") who want to use the address should implement +`onNotified(action)` method, the address is stored in `action.payload.targetAddress`. ```js // core/socket.js -const presets = __PRESETS__.map( - (preset, i) => createMiddleware(preset.name, { - ...preset.params, - ...(i === 0 ? addr : {}) - }) -); +let presets = __PRESETS__; +// prepend "proxy" preset to the top of presets on client side +if (__IS_CLIENT__ && presets[0].name !== 'proxy') { + presets = [{name: 'proxy'}].concat(presets); +} +// create middlewares and pipe +const middlewares = presets.map((preset) => createMiddleware(preset.name, preset.params || {})); ``` Store target address for further use: @@ -93,21 +95,20 @@ Store target address for further use: // presets/ss-base.js import {IPreset} from './defs'; -export default class SSBasePreset extends IPreset { +export default class SsBasePreset extends IPreset { _atyp = ATYP_V4; - _addr = null; // buffer + _host = null; // buffer _port = null; // buffer - constructor(addr) { - super(); - if (__IS_CLIENT__) { - const {type, host, port} = addr; + onNotified(action) { + if (__IS_CLIENT__ && action.type === PROXY_HANDSHAKE_DONE) { + const {type, host, port} = action.payload.targetAddress; this._atyp = type; - this._addr = host; - this._port = port; + this._port = numberToBuffer(port); + this._host = type === ATYP_DOMAIN ? Buffer.from(host) : ip.toBuffer(host); } } diff --git a/docs/development/steps/README.md b/docs/development/steps/README.md index 1745a1d..1b9b362 100644 --- a/docs/development/steps/README.md +++ b/docs/development/steps/README.md @@ -78,16 +78,27 @@ Compilation of blinksocks is ultra easy: $ npm run compile ``` -This will compile `src` to `build`. +This will compile `src/*` to `build/*`. ## Bundle For portable use, we use **webpack** to compile, bundle and compress `src` into `build/blinksocks.js`: +``` +$ npm run bundle +``` + +## Pack + +For users don't have Node.js installed, we use **zeit/pkg** to prepare compiled executables: + ``` $ npm run pack ``` +This will generate compressed executables for different platforms named `blinksocks-{platform}-${arch}-${version}.gz`. +And can be distribute to target platform and architecture at once. + ## Profile By adding `--profile` option in the command line, you will get a report named `blinksocks.profile.log` after diff --git a/docs/presets/README.md b/docs/presets/README.md index a840402..51d1b17 100644 --- a/docs/presets/README.md +++ b/docs/presets/README.md @@ -8,14 +8,36 @@ If you want custom a preset, feel free to read [this](../development/architectur > You **MUST** put [ss-base] or [exp-base-with-padding] or [exp-base-auth-stream] to the first in presets list if you want to relay data to blinksocks server. +## [proxy] + +This preset turns blinksocks to a proxy server, works on both client and server side. + +* For client side, this preset is added by default on **client side**, so you don't have to put it into preset list. +* For server side, this preset is useful to setup a network middleware(act as Man-in-the-middle) to do traffic analysis. + +For example, setup a local proxy server using **blinksocks server** at 1080: + +> applications ---Socks5/HTTP---> **[blinksocks server]** ------> destinations + +```json +// blinksocks.server.json +{ + "host": "localhost", + "port": 1080, + "presets": [{ + "name": "proxy" + }], + ... +} +``` + ## [ss-base] This is a very basic preset which delivers the real destination address from blinksocks client to blinksocks server. ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }] ``` @@ -211,31 +233,6 @@ A TLS obfuscator, do TLS handshake using SessionTicket TLS mechanism, transfer d ] ``` -# Special Presets - -## [proxy] - -This preset turns blinksocks to a proxy server. This is useful to setup a network middleware(act as Man-in-the-middle) to do traffic analysis. - -For example, setup a local proxy server using **blinksocks server** at 1080: - -> applications ---Socks5/HTTP---> **[blinksocks server]** ------> destinations - -```json -// blinksocks.server.json -{ - "host": "localhost", - "port": 1080, - "presets": [ - { - "name": "proxy", - "params": {} - } - ], - ... -} -``` - # Recommended Combinations ## Work with shadowsocks @@ -246,8 +243,7 @@ To work with **shadowsocks**, please choose one of the following configuration: ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }, { "name": "ss-stream-cipher", "params": { @@ -260,8 +256,7 @@ To work with **shadowsocks**, please choose one of the following configuration: ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }, { "name": "ss-aead-cipher", "params": { @@ -279,8 +274,7 @@ You can use **http** or **tls** obfuscator to avoid bad [QoS], **tls** is recomm ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }, { "name": "ss-aead-cipher", "params": { @@ -297,8 +291,7 @@ You can use **http** or **tls** obfuscator to avoid bad [QoS], **tls** is recomm ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }, { "name": "ss-aead-cipher", "params": { @@ -321,8 +314,7 @@ The fastest one: ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }] ``` @@ -330,8 +322,7 @@ Make some cheat: ```json "presets": [{ - "name": "ss-base", - "params": {} + "name": "ss-base" }, { "name": "obfs-tls1.2-ticket", "params": {