toxy

積極的にメンテナンスされていません。最新のNode.jsランタイムでは動作しない可能性があります。toxyのメンテナンスに興味がある場合は、Issueを開いてください。

ハッキング可能なHTTPプロキシで、サーバーの障害シナリオ、システムの耐障害性テスト、予期しないネットワーク状態をシミュレートするために、node.js用に構築されています。

これは主に障害耐性テストのために設計されており、toxyは特に耐遅延ネットワークやサービス指向アーキテクチャにおいて、システムの耐障害性と回復力の能力をカバーする際に特に有用です。そこではtoxyがサービス間でMitMプロキシとして機能し、障害を注入します。

toxyを使用すると、毒をプラグインでき、オプションでルールでフィルタリングできます。これらは本質的にHTTPフローを必要に応じて傍受および変更し、そのプロセスの途中で帯域幅の制限、ネットワークパケットの遅延、ネットワークジッタレイテンシの注入、カスタムエラーやステータスコードでの応答など、複数の悪質なアクションを実行できます。主にL7で動作しますが、L3のネットワーク状態をシミュレートすることもできます。

toxyはプログラムによるAPIまたはHTTP APIを介して流暢に使用できます。これはrocky（フル機能のミドルウェア指向HTTPプロキシ）上に構築されており、connect/expressに標準ミドルウェアとしてプラグイン可能です。

Node.js +4 が必要です。

特徴

フル機能のHTTP/Sプロキシ（rocky と http-proxy をバックエンドとする）
ハッキング可能でエレガントなプログラムによるAPI（connect/expressに触発）
外部管理と動的構成のための管理HTTP API
ネストされた構成を持つ特徴的な組み込みルーター
ルールベースのフィルタリングによる階層的で合成可能な毒
階層的なミドルウェア層（グローバルスコープとルートスコープの両方）
ミドルウェア（connect/expressミドルウェアベース）による容易な拡張性
着信および発信トラフィックの両方への毒をサポート
組み込みの毒（帯域幅、エラー、中断、レイテンシ、低速読み取り...）
ルールベースの毒（確率的、HTTPメソッド、ヘッダー、ボディ...）
サードパーティの毒とルールをサポート
ミドルウェアを介した組み込みのロードバランサーとトラフィックインターセプター
rocky のAPIと機能を継承
connect/express（およびそれらのミドルウェアのほとんど）と互換性あり
スタンドアロンHTTPプロキシとして実行可能

はじめに

なぜtoxyなのか？

市場にはtoxyに似たソリューションがいくつか存在しますが、それらのほとんどは適切なプログラムによる制御を提供しておらず、通常はハッキングや設定が容易ではないか、拡張性に対して閉じています。

さらに、それらのソリューションの大部分は、特定のドメインとHTTP L7プロトコルの性質における一般的な要件をカバーするための高レベルの抽象化を提供する代わりに、TCP L3レベルスタックでのみ動作します。toxyはそれを提供しようとしています。

toxyは、便利な抽象化を備えた強力でハッキング可能かつ拡張可能なソリューションを提供しますが、HTTPプロトコルのプリミティブを簡単に扱うための適切な低レベルインターフェースの機能を失うことはありません。

toxyは、構成、シンプルさ、拡張性の原則に基づいて設計されました。組み込みの階層的なドメイン固有ミドルウェア層を介して、toxyの機能を独自のニーズに合わせて簡単に拡張できます。

概念

toxyは2つのディレクティブを導入します: 毒とルール。

毒は、着信または発信のHTTPトランザクションに影響を与える（例：レイテンシの注入、エラーでの応答）特定のロジックです。1つのHTTPトランザクションは1つまたは複数の毒によって影響を受ける可能性があり、それらの毒はグローバルトラフィックまたはルートレベルトラフィックの両方に影響を与えるように構成することもできます。

ルールは、HTTPリクエスト/レスポンスを検査して、特定のルールに基づいてHTTPトランザクションに毒を適用するかどうかを判断する（例：ヘッダーが一致するか、クエリパラメータ、メソッド、ボディ...）一種のマッチ検証フィルターです。ルールは再利用可能であり、異なるスコープ（グローバル、ルート、毒レベル）を含む着信および発信のトラフィックフローの両方に適用できます。

動作の仕組み```

↓ ( Incoming request ) ↓ ↓ ||| ↓ ↓ +-------------+ ↓ ↓ | Toxy Router | ↓ -> Match the incoming request ↓ +-------------+ ↓ ↓ ||| ↓ ↓ +--------------------+ ↓ ↓ | Incoming phase | ↓ -> The proxy receives the request from the client ↓ |~~~~~~~~~~~~~~~~~~~~| ↓ ↓ | ---------------- | ↓ ↓ | | Exec Rules | | ↓ -> Apply configured rules for the incoming request ↓ | ---------------- | ↓ ↓ | ||| | ↓ ↓ | ---------------- | ↓ ↓ | | Exec Poisons | | ↓ -> If all rules passed, then poison the HTTP flow ↓ | ---------------- | ↓ ↓ +~~~~~~~~~~~~~~~~~~~~+ ↓ ↓ / \ ↓ ↓ \ / ↓ ↓ +--------------------+ ↓ ↓ | HTTP dispatcher | ↓ -> Forward the HTTP traffic to the target server, either poisoned or not ↓ +--------------------+ ↓ ↓ / \ ↓ ↓ \ / ↓ ↓ +--------------------+ ↓ ↓ | Outgoing phase | ↓ -> Receives response from target server ↓ |~~~~~~~~~~~~~~~~~~~~| ↓ ↓ | ---------------- | ↓ ↓ | | Exec Rules | | ↓ -> Apply configured rules for the outgoing request ↓ | ---------------- | ↓ ↓ | ||| | ↓ ↓ | ---------------- | ↓ ↓ | | Exec Poisons | | ↓ -> If all rules passed, then poison the HTTP flow before send it to the client ↓ | ---------------- | ↓ ↓ +~~~~~~~~~~~~~~~~~~~~+ ↓ ↓ ||| ↓ ↓ ( Send to the client ) ↓ -> Finally, send the request to the client, either poisoned or not

## 使用方法

### インストール```
npm install toxy

例

より多くのユースケースについては、examples ディレクトリを参照してください。```js var toxy = require('toxy') var poisons = toxy.poisons var rules = toxy.rules

// Create a new toxy proxy var proxy = toxy()

// Default server to forward incoming traffic proxy .forward('http://httpbin.org')

// Register global poisons and rules proxy .poison(poisons.latency({ jitter: 500 })) .rule(rules.probability(25))

// Register multiple routes proxy .get('/download/') .forward('http://files.myserver.net') .poison(poisons.bandwidth({ bps: 1024 })) .withRule(rules.headers({'Authorization': /^Bearer (.)$/i }))

// Infect outgoing traffic only (after the server replied properly) proxy .get('/image/*') .outgoingPoison(poisons.bandwidth({ bps: 512 })) .withRule(rules.method('GET')) .withRule(rules.timeThreshold({ duration: 1000, threshold: 1000 * 10 })) .withRule(rules.responseStatus({ range: [ 200, 400 ] }))

proxy .all('/api/*') .poison(poisons.rateLimit({ limit: 10, threshold: 1000 })) .withRule(rules.method(['POST', 'PUT', 'DELETE'])) // And use a different more permissive poison for GET requests .poison(poisons.rateLimit({ limit: 50, threshold: 1000 })) .withRule(rules.method('GET'))

// Handle the rest of the traffic proxy .all('/*') .poison(poisons.slowClose({ delay: 1000 })) .poison(poisons.slowRead({ bps: 128 })) .withRule(rules.probability(50))

proxy.listen(3000) console.log('Server listening on port:', 3000) console.log('Test it:', 'http://localhost:3000/image/jpeg')

## ベンチマーク

詳細は [toxy/benchmark](https://github.com/h2non/toxy/tree/master/benchmark) を参照してください。

## ポイズン

ポイズンは、プロキシサーバー内のHTTPトランザクションをインターセプトして変更、ラップ、修正、またはキャンセルする特定のロジックを提供します。ポイズンは、受信トラフィック、送信トラフィック、またはその両方に適用できます（[ポイズンフェーズ](#poisoning-phases)を参照）。

ポイズンは、さまざまなHTTPシナリオに対して合成および再利用できます。これらはFIFO順で非同期に実行されます。

### ポイズニングスコープ

`toxy` は、`global` と `route` という2つの異なるスコープに基づく階層設計を採用しています。

**グローバル** スコープは、HTTPメソッドやパスに関係なく、プロキシサーバーが受信するすべての受信HTTPトラフィックを対象とします。

**ルート** スコープは、特定のHTTPメソッドとURIパスに一致する受信トラフィックを対象とします。

ポイズンは両方のスコープに接続できるため、より正確に操作し、ポイズニングの範囲を制限できます。例えば、特定のルート（`/download` や `/images` など）にのみ帯域幅制限ポイズンを適用したい場合などです。

実際の例については [routes.js](https://github.com/h2non/toxy/blob/master/examples/routes.js) を参照してください。

### ポイズニングフェーズ

ポイズンは、受信トラフィックフロー、送信トラフィックフロー、またはその両方に接続できます。

**受信** ポイズニングは、トラフィックがプロキシによって受信されたが、まだターゲットサーバーに転送されていない場合に適用されます。

**送信** ポイズニングは、トラフィックがターゲットサーバーに転送され、プロキシがその応答を受信したが、まだクライアントに送信されていない場合のトラフィックを指します。

これは基本的に、リクエストがターゲットHTTPサーバーに転送される前後、またはクライアントに送信される前後に、ポイズンを接続してHTTPトラフィックに感染させることができることを意味します。

これにより、リクエストまたはサーバー応答に基づいて、より正確なポイズニングを適用できます。例えば、`inject error` のような一部のポイズンの性質上、ターゲットサーバーの応答（特定のヘッダーの有無など）に応じて有効にしたい場合があります。

実際の例については [poison-phases.js](https://github.com/h2non/toxy/blob/master/examples/poison-phases.js) を参照してください。

### ビルトインポイズン

#### レイテンシ

<table>
<tr>
<td><b>名前</b></td><td>latency</td>
</tr>
<tr>
<td><b>ポイズニングフェーズ</b></td><td>受信 / 送信</td>
</tr>
<tr>
<td><b>サーバーに到達</b></td><td>true</td>
</tr>
</table>

応答にレイテンシジッターを注入してHTTPフローに感染させます。

**引数**:

- **options** `object`
  - **jitter** `number` - ジッター値（ミリ秒）
  - **max** `number` - ランダムジッターの最大値
  - **min** `number` - ランダムジッターの最小値```js
toxy.poison(toxy.poisons.latency({ jitter: 1000 }))
// Or alternatively using a random value
toxy.poison(toxy.poisons.latency({ max: 1000, min: 100 }))

Inject response

名前	inject
ポイズニングフェーズ	受信 / 送信
サーバーに到達	false（受信ポイズンとしてのみ）

カスタムレスポンスを注入します。リクエストをターゲットサーバーに送信する前にインターセプトします。サーバーで発生したエラーを注入するのに便利です。

引数:

options object
- code number - レスポンスのHTTPステータスコード。デフォルトは500
- headers object - 送信するオプションのヘッダー
- body mixed - 送信するオプションのボディデータ。bufferまたはstringにできます
- encoding string - ボディのエンコーディング。デフォルトは`utf8````js toxy.poison(toxy.poisons.inject({ code: 503, body: '{"error": "toxy injected error"}', headers: {'Content-Type': 'application/json'} }))

#### Bandwidth

<table>
<tr>
<td><b>名前</b></td><td>bandwidth</td>
</tr>
<tr>
<td><b>ポイズニングフェーズ</b></td><td>incoming / outgoing</td>
</tr>
<tr>
<td><b>サーバーに到達</b></td><td>true</td>
</tr>
</table>

送信HTTPトラフィックにおいて、特定の時間枠でネットワークを介して送信されるバイト数を制限します。

このポイズンは基本的に[throttle](#throttle)のエイリアスです。

**引数**:

- **options** `object`
  - **bytes** `number` - 送信するバイトのチャンク量。デフォルトは`1024`
  - **threshold** `number` - パケットのタイムフレーム（ミリ秒）。デフォルトは`1000````js
toxy.poison(toxy.poisons.bandwidth({ bytes: 512 }))

レート制限

名前	rateLimit
毒注入フェーズ	incoming / outgoing
サーバーに到達	true

プロキシが特定の閾値時間内に受信するリクエスト数を制限します。API制限をテストするために設計されています。典型的な X-RateLimit-* ヘッダーを公開します。

これは非常にシンプルなレート制限の実装であり、制限はメモリ内に保存されるため、完全に揮発性であることに注意してください。毒としてプラグインできる、多くの機能を備えた一貫性のあるレートリミッターの実装が npm にあります。また、トークンバケットアルゴリズムにも興味があるかもしれません。

引数:

options object
- limit number - リクエストの合計数。デフォルトは 10
- threshold number - 制限時間枠（ミリ秒）。デフォルトは 1000
- message string - 制限に達した場合のオプションのエラーメッセージ。
- code number - 制限に達した場合のHTTPステータスコード。デフォルトは 429。```js toxy.poison(toxy.poisons.rateLimit({ limit: 5, threshold: 10 * 1000 }))

#### スローリード

<table>
<tr>
<td><b>名前</b></td><td>slowRead</td>
</tr>
<tr>
<td><b>ポイズニングフェーズ</b></td><td>着信</td>
</tr>
<tr>
<td><b>サーバーに到達</b></td><td>true</td>
</tr>
</table>

受信したペイロードデータパケットをゆっくりと読み取ります。GET 以外のリクエストでのみ有効です。

**引数**:

- **options** `object`
  - **chunk** `number` - パケットチャンクサイズ（バイト）。デフォルトは `1024`
  - **threshold** `number` - 制限しきい値の時間枠（ミリ秒）。デフォルトは `1000````js
toxy.poison(toxy.poisons.slowRead({ chunk: 2048, threshold: 1000 }))

スローオープン

Name: slowOpen

名前	slowOpen
ポイズニングフェーズ	incoming
サーバーに到達	true

HTTP接続の準備状態を遅延させます。

引数:

options object
- delay number - 遅延時間（ミリ秒）。デフォルトは `1000````js toxy.poison(toxy.poisons.slowOpen({ delay: 2000 }))

#### Slow close（スロークローズ）

<table>
<tr>
<td><b>名前</b></td><td>slowClose</td>
</tr>
<tr>
<td><b>汚染フェーズ</b></td><td>incoming / outgoing</td>
</tr>
<tr>
<td><b>サーバーに到達するか</b></td><td>true</td>
</tr>
</table>

HTTP 接続のクローズ信号（EOF）を遅延させます。

**引数**：

- **options** `object`
  - **delay** `number` - 遅延時間（ミリ秒）。デフォルトは `1000````js
toxy.poison(toxy.poisons.slowClose({ delay: 2000 }))

スロットル

名前	throttle
ポイズニングフェーズ	受信 / 送信
サーバーに到達	true

特定の閾値時間枠内でネットワーク上に送信されるパケット量を制限します。

引数:

options object
- chunk number - パケットチャンクサイズ（バイト単位）。デフォルトは 1024
- delay object - データチャンクの遅延時間枠（ミリ秒単位）。デフォルトは `100````js toxy.poison(toxy.poisons.throttle({ chunk: 2048, threshold: 1000 }))

#### 接続を中断（アボート）

<table>
<tr>
<td><b>名前</b></td><td>abort</td>
</tr>
<tr>
<td><b>汚染フェーズ</b></td><td>受信 / 送信</td>
</tr>
<tr>
<td><b>サーバーに到達するか</b></td><td>false（受信汚染時のみ）</td>
</tr>
</table>

TCP 接続を中断します。低レベル視点では、サーバー上のソケットを破棄し、TCP レベルでのみ動作し、HTTP アプリケーションレベルのデータを送信しません。

**引数**：

- **options** `object`
  - **delay** `number` - 指定されたミリ秒待機した後に TCP 接続を中断します。デフォルトは `0`
  - **next** `boolean` - `true` の場合、ターゲットサーバーが `delay` パラメータの時間より長く応答を要した場合に接続が中断されます。デフォルトは `false`
  - **error** `Error` - ソケット破棄時に使用するカスタム内部 Node.js エラー。デフォルトは `null````js
// Basic connection abort
toxy.poison(toxy.poisons.abort())
// Abort after a delay
toxy.poison(toxy.poisons.abort(1000))
// In this case, the socket will be closed if
// the target server takes more than
// 2 seconds to respond
toxy.poison(toxy.poisons.abort({ delay: 2000, next: true }))

タイムアウト

名前	timeout
ポイズニングフェーズ	受信 / 送信
サーバーに到達する	true

レスポンスのタイムアウトを定義します。潜在的に遅いサーバーに転送するときに便利です。

引数：

milliseconds number - タイムアウト制限（ミリ秒）```js toxy.poison(toxy.poisons.timeout(5000))

### 毒の書き方

毒は、connect/expressミドルウェアと同じインターフェースを持つ標準のミドルウェア関数として実装されています。

一部の毒は実装が容易ではないため、node.jsの[http](https://nodejs.org/api/http.html)モジュールとそのAPIに精通している必要があります。

以下は、サーバーレイテンシ毒の簡単な例です:```js
var toxy = require('toxy')

function customLatencyPoison (delay) {
  // We name the function since toxy uses it as identifier to get/disable/remove it in the future
  return function customLatency (req, res, next) {
    var timeout = setTimeout(process, delay)
    req.once('close', onClose)

    function onClose () {
      clearTimeout(timeout)
      next('client connection closed')
    }

    function process () {
      req.removeListener('close', onClose)
      next()
    }
  }
}

var proxy = toxy()

// Register and enable the poison
proxy
  .get('/foo')
  .poison(customLatencyPoison(2000))

オプションで、組み込みの毒を独自の毒で拡張することができます：```js toxy.addPoison(customLatency)

// Then you can use it as a built-in poison proxy .get('/foo') .poison(toxy.poisons.customLatency)

実際の例については、[組み込みのpoisons](https://github.com/h2non/toxy/tree/master/lib/poisons)の実装をご覧ください。

## Rules

ルールは、特定のルール（例：メソッド、ヘッダー、クエリパラメータ、ボディなどに一致する）に基づいて、受信または送信HTTPトラフィックを検査し、ルールの解決値に基づいて現在のHTTPトランザクションをポイズンすべきかどうかを判断するシンプルな検証フィルターです。

ルールは、ポイズニングの異なるシナリオ間でロジックを構成、分離、再利用するのに役立ちます。
ルールは、グローバル、ルート、さらにはポイズンスコープに適用でき、[ポイズニングフェーズ](#poisoning-phases)の両方にも適用されます。

ルールはFIFO順で実行されます。評価ロジックはJavaScriptの`Array#every()`と同等です。すべてのルールを通過する必要があり、その後ポイズニングが進行します。

### Built-in rules

#### Probability

<table>
<tr>
<td><b>名前</b></td><td>確率</td>
</tr>
<tr>
<td><b>ポイズンフェーズ</b></td><td>受信 / 送信</td>
</tr>
</table>

ランダムな確率でルールを有効にします。ランダムポイズニングに便利です。

**Arguments**:

- **percentage** `number` - フィルタリングのパーセンテージ。デフォルトは`50````js
var rule = toxy.rules.probability(85)
toxy.rule(rule)

時間しきい値

名前	timeThreshold
ポイズンフェーズ	受信 / 送信

特定の時間しきい値と期間に基づいてポイズンを有効にするシンプルなルール。例えば、時間しきい値（例：1分）の範囲内で、特定の期間（例：1秒）だけ特定のポイズンを有効にできます。

引数：

options object
- duration number - ポイズンを有効にする時間間隔（ミリ秒）。デフォルトは 1000
- threshold number - ポイズンを再度有効にするまでに待つ時間しきい値（ミリ秒）。デフォルトは `10000````js // Enable the poisoning only 100 milliseconds per each 10 seconds proxy.rule(toxy.rules.timeThreshold(100)) // Enable poisoning during 1 second every minute proxy.rule(toxy.rules.timeThreshold({ duration: 1000, period: 1000 * 60 }))

#### メソッド

<table>
<tr>
<td><b>名前</b></td><td>method</td>
</tr>
<tr>
<td><b>ポイズンフェーズ</b></td><td>incoming / outgoing</td>
</tr>
</table>

HTTPメソッドでフィルタリングします。

**引数**:

- **method** `string|array` - フィルタリングするメソッド。```js
var method = toxy.rules.method(['GET', 'POST'])
toxy.rule(method)

コンテンツタイプ

コンテンツタイプヘッダーでフィルタリングします。存在する必要があります。

引数:

value string|regexp - マッチするヘッダー値。```js var rule = toxy.rules.contentType('application/json') toxy.rule(rule)

#### Headers

<table>
<tr>
<td><b>名前</b></td><td>headers</td>
</tr>
<tr>
<td><b>ポイズンフェーズ</b></td><td>受信 / 送信</td>
</tr>
</table>

リクエストヘッダーでフィルタリングします。

**引数**:

- **headers** `object` - キーと値のペアでマッチするヘッダー。`value` は文字列、正規表現、`boolean` または `function(headerValue, headerName) => boolean` にすることができます。```js
var matchHeaders = {
  'content-type': /^application/\json/i,
  'server': true, // meaning it should be present,
  'accept': function (value, key) {
    return value.indexOf('text') !== -1
  }
}

var rule = toxy.rules.headers(matchHeaders)
toxy.rule(rule)

レスポンスヘッダー

Name	responseHeaders
Poison Phase	outgoing

ターゲットサーバーからのレスポンスヘッダーでフィルタリングします。headersルールと同じですが、送信リクエストを評価します。

引数:

headers object - キーと値のペアでマッチするヘッダー。valueはstring、regexp、boolean、またはfunction(headerValue, headerName) => booleanを使用できます。```js var matchHeaders = { 'content-type': /^application/\json/i, 'server': true, // meaning it should be present, 'accept': function (value, key) { return value.indexOf('text') !== -1 } }

var rule = toxy.rules.responseHeaders(matchHeaders) toxy.rule(rule)

#### 本文

<table>
<tr>
<td><b>名前</b></td><td>body</td>
</tr>
<tr>
<td><b>毒フェーズ</b></td><td>受信 / 送信</td>
</tr>
</table>

指定された `string`、`regexp`、またはカスタムフィルター `function` で受信本文ペイロードを照合します。

このルールは非常にシンプルなので、複雑な本文照合（例：JSONスキーマに対する検証）には、独自のルールを作成することをお勧めします。

**引数**:

- **match** `string|regexp|function` - 照合する本文コンテンツ
- **limit** `string` - 省略可能。人間が読みやすい形式での本文制限。例: `5mb`
- **encoding** `string` - 本文エンコーディング。デフォルトは `utf8`
- **length** `number` - 本文の長さ。デフォルトは `Content-Length` ヘッダーから取得```js
var rule = toxy.rules.body('"hello":"world"')
toxy.rule(rule)

// Or using a filter function returning a boolean
var rule = toxy.rules.body(function contains(body) {
  return body.indexOf('hello') !== -1
})
toxy.rule(rule)

レスポンスボディ

名前	responseBody
ポイズンフェーズ	outgoing

指定されたstring、regexp、またはカスタムフィルタfunctionによって送信ボディペイロードをマッチします。

引数:

match string|regexp|function - マッチするボディコンテンツ
encoding string - ボディエンコーディング。デフォルトはutf8
length number - ボディ長。デフォルトはContent-Lengthヘッダーから取得```js var rule = toxy.rules.responseBody('"hello":"world"') toxy.rule(rule)

// Or using a filter function returning a boolean var rule = toxy.rules.responseBody(function contains(body) { return body.indexOf('hello') !== -1 }) toxy.rule(rule)

#### レスポンスステータス

<table>
<tr>
<td><b>名前</b></td><td>responseStatus</td>
</tr>
<tr>
<td><b>ポイズンフェーズ</b></td><td>outgoing</td>
</tr>
</table>

ターゲットサーバーからのレスポンスステータスを評価します。
outgoing（発信）ポイズンにのみ適用可能です。

**引数**:

- **range** `array` - 一致させるステータスコードの範囲のペア。デフォルトは `[200, 300]`。
- **lower** `number` - ステータスを `lower than` 演算として比較します。デフォルトは `null`。
- **higher** `number` - ステータスを `higher than` 演算として比較します。デフォルトは `null`。
- **value** `number` - 厳密な等価比較を使用して一致させるステータスコード。デフォルトは `null`。
- **include** `array` - 一致させるステータスコードの順序なしリスト。カスタムステータスを指定するのに便利です。デフォルトは `null````js
// Strict evaluation of the status code
toxy.rule(toxy.rules.responseBody(200))
// Using a range of valid status
toxy.rule(toxy.rules.responseBody([200, 204]))
// Using relational comparison
toxy.rule(toxy.rules.responseBody({ higher: 199, lower: 400 }))
// Custom unordered status code to match
toxy.rule(toxy.rules.responseBody({ include: [200, 204, 400, 404] }))

サードパーティルール

コミュニティが提供している利用可能なサードパーティルールの一覧です。PRを歓迎します。

IP - クライアントのIPアドレスに基づいてポイズンの有効/無効を切り替えます（CIDR、サブネット、範囲などをサポート）。

ルールの書き方

ルールは、特定のHTTPトランザクションが毒化時に無視されるべきかどうかを判断するために、boolean 値で非同期的に解決するシンプルなミドルウェア関数です。

ルールは、next(err, shouldIgnore) 関数をミドルウェア内で呼び出して boolean パラメータで解決する必要があります。ルールが一致せず、毒化を適用すべきでない場合は true 値を渡し、次のミドルウェアスタックに進みます。

以下は、HTTPメソッドを照合して判断するシンプルなルールの例です。```js var toxy = require('toxy')

function customMethodRule(matchMethod) { /**

We name the function since it's used by toxy to identify the rule to get/disable/remove it in the future */ return function customMethodRule(req, res, next) { var shouldIgnore = req.method !== matchMethod next(null, shouldIgnore) } }

var proxy = toxy()

// Register and enable the rule proxy .get('/foo') .rule(customMethodRule('GET')) .poison(/* ... */)

必要に応じて、組み込みルールを独自のルールで拡張することができます:```js
toxy.addRule(customMethodRule)

// Then you can use it as a built-in poison
proxy
  .get('/foo')
  .rules(toxy.rules.customMethodRule)

実際の使用例については、組み込みルールの実装をご覧ください。

プログラムAPI

toxy APIは完全にrocky APIをベースに構築されています。言い換えれば、rockyがネイティブに提供するメソッド、機能、ミドルウェア層をすべて利用できます。

toxy([ options ])

新しいtoxyプロキシを作成します。

サポートされているoptionsについては、rockyのドキュメントを参照してください。```js var toxy = require('toxy')

toxy({ forward: 'http://server.net', timeout: 30000 })

toxy .get('/foo') .poison(toxy.poisons.latency(1000)) .withRule(toxy.rules.contentType('json')) .forward('http://foo.server')

toxy .post('/bar') .poison(toxy.poisons.bandwidth({ bps: 1024 })) .withRule(toxy.rules.probability(50)) .forward('http://bar.server')

toxy .post('/boo') .outgoingPoison(toxy.poisons.bandwidth({ bps: 1024 })) .withRule(toxy.rules.method('GET')) .forward('http://boo.server')

toxy.all('/*')

toxy.listen(3000)

#### toxy#get(path, [ middleware... ])
戻り値: `ToxyRoute`

`GET`メソッドの新しいルートを登録します。

#### toxy#post(path, [ middleware... ])
戻り値: `ToxyRoute`

`POST`メソッドの新しいルートを登録します。

#### toxy#put(path, [ middleware... ])
戻り値: `ToxyRoute`

`PUT`メソッドの新しいルートを登録します。

#### toxy#patch(path, [ middleware... ])
戻り値: `ToxyRoute`

#### toxy#delete(path, [ middleware... ])
戻り値: `ToxyRoute`

`DELETE`メソッドの新しいルートを登録します。

#### toxy#head(path, [ middleware... ])
戻り値: `ToxyRoute`

`HEAD`メソッドの新しいルートを登録します。

#### toxy#all(path, [ middleware... ])
戻り値: `ToxyRoute`

任意のメソッドの新しいルートを登録します。

#### toxy#poisons `=>` Object

組み込みのpoisonのマップを公開します。プロトタイプのエイリアスは `toxy.poisons`

#### toxy#rules `=>` Object

組み込みのpoisonのマップを公開します。プロトタイプのエイリアスは `toxy.rules`

#### toxy#forward(url)

プロキシが受信した着信トラフィックを転送するURLを定義します。

#### toxy#balance(urls)

複数のサーバーに転送し、それらの間で負荷分散を行います。

詳細については、[rocky docs](https://github.com/h2non/rocky#programmatic-api) を参照してください。

#### toxy#replay(url)

新しいリプレイサーバーを定義します。
このメソッドを複数回呼び出して、複数のリプレイサーバーを定義できます。

詳細については、[rocky docs](https://github.com/h2non/rocky#programmatic-api) を参照してください。

#### toxy#use(middleware)

カスタムミドルウェアをプラグインします。

詳細については、[rocky docs](https://github.com/h2non/rocky#middleware-layer) を参照してください。

#### toxy#useResponse(middleware)

レスポンスの送信トラフィック用のミドルウェアをプラグインします。

詳細については、[rocky docs](https://github.com/h2non/rocky#middleware-layer) を参照してください。

#### toxy#useReplay(middleware)

リプレイトラフィック用のミドルウェアをプラグインします。

詳細については、[rocky docs](https://github.com/h2non/rocky#middleware-layer) を参照してください。

#### toxy#requestBody(middleware)

受信リクエストボディをインターセプトします。その場で変更するのに便利です。

詳細については、[rocky docs](https://github.com/h2non/rocky#programmatic-api) を参照してください。

#### toxy#responseBody(middleware)

送信レスポンスボディをインターセプトします。その場で変更するのに便利です。

詳細については、[rocky docs](https://github.com/h2non/rocky#programmatic-api) を参照してください。

#### toxy#middleware()

connect/express で使用する標準のミドルウェアを返します。

#### toxy#host(host)

`Host` ヘッダーをカスタム値で上書きします。`forwardHost` オプションと同様です。

#### toxy#redirect(url)

トラフィックを指定されたURLにリダイレクトします。

#### toxy#findRoute(routeIdOrPath, [ method ])

IDまたはパスとメソッドでルートを検索します。

#### toxy#listen(port)

組み込みのHTTPサーバーを起動し、特定のTCPポートで待機します。

#### toxy#close([ callback ])

HTTPサーバーを閉じます。

#### toxy#poison(poison)
エイリアス: `usePoison`, `useIncomingPoison`

[着信](#poisoning-phases) トラフィックに感染させる新しいpoisonを登録します。

#### toxy#outgoingPoison(poison)
エイリアス: `useOutgoingPoison`, `responsePoison`

[送信](#poisoning-phases) トラフィックに感染させる新しいpoisonを登録します。

#### toxy#rule(rule)
エイリアス: `useRule`

新しいルールを登録します。

#### toxy#withRule(rule)
エイリアス: `ifRule`, `whenRule`, `poisonRule`, `poisonFilter`

最後に登録されたpoisonに新しいルールを適用します。

#### toxy#enable(poison)

名前識別子でpoisonを有効にします。

#### toxy#disable(poison)

名前識別子でpoisonを無効にします。

#### toxy#remove(poison)
戻り値: `boolean`

名前識別子またはオブジェクト参照で着信トラフィックのpoisonを削除します。

#### toxy#removeOutgoing(poison)
戻り値: `boolean`

名前識別子またはオブジェクト参照で送信トラフィックのpoisonを削除します。

#### toxy#isEnabled(poison)
戻り値: `boolean`

名前識別子でpoisonが有効かどうかを確認します。

#### toxy#disableAll()
エイリアス: `disablePoisons`

登録されているすべてのpoisonを無効にします。

#### toxy#getPoison(name)
戻り値: `Directive|null`

スタック内の登録されたpoisonを名前識別子で検索して取得します。

#### toxy#getIncomingPoison(name)
戻り値: `Directive|null`

スタック内の登録された `incoming` poisonを名前識別子で検索して取得します。

#### toxy#getOutgoingPoison(name)
戻り値: `Directive|null`

スタック内の登録された `outgoing` poisonを名前識別子で検索して取得します。

#### toxy#getPoisons()
戻り値: `array<Directive>`

登録されたpoisonの配列を返します。

#### toxy#getIncomingPoisons()
戻り値: `array<Directive>`

登録された `incoming` poisonの配列を返します。

#### toxy#getOutgoingPoisons()
戻り値: `array<Directive>`

登録された `outgoing` poisonの配列を返します。

#### toxy#flush()
エイリアス: `flushPoisons`

着信と送信の両方のトラフィックフローについて、登録されたすべてのpoisonを削除します。

#### toxy#enableRule(rule)

名前識別子でルールを有効にします。

#### toxy#disableRule(rule)

名前識別子でルールを無効にします。

#### toxy#removeRule(rule)
戻り値: `boolean`

名前識別子でルールを削除します。

#### toxy#disableRules()

登録されているすべてのルールを無効にします。

#### toxy#isRuleEnabled(rule)
戻り値: `boolean`

指定されたルールが名前識別子で有効かどうかを確認します。

#### toxy#getRule(rule)
戻り値: `Directive|null`

スタック内の登録されたルールを名前識別子で検索して取得します。

#### toxy#getRules()
戻り値: `array<Directive>`

ルールを `Directive` としてラップした配列を返します。

#### toxy#flushRules()

すべてのルールを削除します。

### toxy.addPoison(name, fn)

組み込みのpoisonを拡張します。

### toxy.addRule(name, fn)

組み込みのルールを拡張します。

### toxy.poisons `=>` Object

組み込みのpoisonのマップを公開します。

### toxy.rules `=>` Object

組み込みのルールのマップを公開します。

### toxy.VERSION `=>` String

現在のtoxyセマンティックバージョン。

### ToxyRoute

`ToxyRoute` は `Toxy` グローバルインターフェースと同じインターフェースを公開します。さらに、ルートレベルの[追加メソッド](https://github.com/h2non/rocky#routepath)を追加します。

`ToxyRoute` API に対して実行する以降のアクションは、ルートレベル（ネスト）にのみ適用されます。言い換えれば、API は既に知っています。

この例で疑問点を明確にできるでしょう：```js
var toxy = require('toxy')
var proxy = toxy()

// Now using the global API
proxy
  .forward('http://server.net')
  .poison(toxy.poisons.bandwidth({ bps: 1024 }))
  .rule(toxy.rules.method('GET'))

// Now create a route
var route = proxy
  .get('/foo')
  .toPath('/bar') // Route-level API method
  .host('server.net') // Route-level API method
  .forward('http://new.server.net')

// Now using the ToxyRoute interface
route
  .poison(toxy.poisons.bandwidth({ bps: 512 }))
  .rule(toxy.rules.contentType('json'))

Directive(middlewareFn)

ポイズンとルールのために内部的に使用される便利なラッパーです。

通常、このインターフェースを知る必要はありませんが、ハッキング目的やより低レベルの操作に役立つかもしれません。

Directive#enable()

戻り値: boolean

Directive#disable()

戻り値: boolean

Directive#isEnabled()

戻り値: boolean

Directive#rule(rule)

エイリアス: filter

Directive#handler()

戻り値: function(req, res, next)

HTTP API

toxy HTTP APIは、リソースベースのハイパーメディアリンクを含むJSON APIの慣習に従います。

使用法

特集のユースケースについては、admin serverの例を参照してください。```js const toxy = require('toxy')

// Create the toxy admin server var admin = toxy.admin({ cors: true }) admin.listen(9000)

// Create the toxy proxy var proxy = toxy() proxy.listen(3000)

// Add the toxy instance to be managed by the admin server admin.manage(proxy)

// Then configure the proxy proxy .forward('http://my.target.net')

proxy .get('/slow') .poison(toxy.poisons.bandwidth({ bps: 1024 }))

// Handle the rest of the traffic proxy .all('/*') .poison(toxy.poisons.bandwidth({ bps: 1024 * 5 }))

console.log('toxy proxy listening on port:', 3000) console.log('toxy admin server listening on port:', 9000)

管理プログラムAPIの詳細については、[下記](#programmatic-api-1)を参照してください。

### 認可

HTTP APIは、許可されていないクライアントから保護することができます。
許可されたクライアントは、`API-Key` または `Authorization` HTTPヘッダーを介してAPIキートークンを定義する必要があります。

これを有効にするには、`toxy`管理サーバーに次のオプションを渡すだけで済みます。```js
const toxy = require('toxy')

const opts = { apiKey: 's3cr3t' }
var admin = toxy.admin(opts)

admin.listen(9000)
console.log('protected toxy admin server listening on port:', 9000)

API

階層構造:

サーバー - 管理された toxy インスタンス
- ルール - グローバルに適用されるルール
- ポイズン - グローバルに適用されるポイズン
  - ルール - ポイズン固有のルール
- ルート - 設定されたルートのリスト
  - ルート - 各特定ルートのオブジェクト
    - ルール - ルートレベルで登録されたルール
    - ポイズン - ルートレベルで登録されたポイズン
      - ルール - ルートレベルのポイズン固有のルール

GET /

サーバー

GET /servers

GET /servers/:id

ルール

GET /servers/:id/rules

POST /servers/:id/rules

受け付け形式: application/json

ペイロード例:```js { "name": "method", "options": "GET" }

#### DELETE /servers/:id/rules

#### GET /servers/:id/rules/:id

#### DELETE /servers/:id/rules/:id

### ポイズン

#### GET /servers/:id/poison

#### POST /servers/:id/poisons
受け付ける: `application/json`

ペイロード例:```js
{
  "name": "latency",
  "phase": "outgoing",
  "options": { "jitter": 1000 }
}

DELETE /servers/:id/poisons

GET /servers/:id/poisons/:id

DELETE /servers/:id/poisons/:id

GET /servers/:id/poisons/:id/rules

POST /servers/:id/poisons/:id/rules

受け入れ: application/json

ペイロード例:```js { "name": "method", "options": "GET" }

#### DELETE /servers/:id/poisons/:id/rules

#### GET /servers/:id/poisons/:id/rules/:id

#### DELETE /servers/:id/poisons/:id/rules/:id

### ルート

#### GET /servers/:id/routes

#### POST /servers/:id/routes
受け入れ形式: `application/json`

ペイロード例:```js
{
  "path": "/foo", // Required
  "method": "GET", // use ALL for all the methods
  "forward": "http://my.server", // Optional custom forward server URL
}

DELETE /servers/:id/routes

GET /servers/:id/routes/:id

DELETE /servers/:id/routes/:id

ルートルール

GET /servers/:id/routes/:id/rules

POST /servers/:id/routes/:id/rules

受け入れ: application/json

ペイロード例:```js { "name": "method", "options": "GET" }

#### DELETE /servers/:id/routes/:id/rules

#### GET /servers/:id/routes/:id/rules/:id

#### DELETE /servers/:id/routes/:id/rules/:id

### ルートポイズン

#### GET /servers/:id/routes/:id/poisons

#### POST /servers/:id/routes/:id/poisons
Accepts: `application/json`

ペイロード例:```js
{
  "name": "latency",
  "phase": "outgoing",
  "options": { "jitter": 1000 }
}

DELETE /servers/:id/routes/:id/poisons

GET /servers/:id/routes/:id/poisons/:id

DELETE /servers/:id/routes/:id/poisons/:id

GET /servers/:id/routes/:id/poisons/:id/rules

POST /servers/:id/routes/:id/poisons/:id/rules

Accepts: application/json

ペイロードの例:```js { "name": "method", "options": "GET" }

#### DELETE /servers/:id/routes/:id/poisons/:id/rules

#### GET /servers/:id/routes/:id/poisons/:id/rules/:id

#### DELETE /servers/:id/routes/:id/poisons/:id/rules/:id

### プログラム用API

組み込みのHTTP管理サーバーは、拡張性とハッキング目的のためのシンプルなインターフェースも提供します。例えば、管理サーバーに追加のミドルウェアをプラグインしたり、新しいルートを登録したりできます。

#### toxy.admin([ opts ])
戻り値: `Admin`

**サポートされているオプション**:

- **apiKey** `string` - サーバーを保護するためのオプションのAPIキー
- **port** `number` - オプション。リッスンするTCPポート
- **cors** `boolean` - Webブラウザアクセス用のCORSを有効にする
- **middleware** `array<function>` - 追加のミドルウェアをプラグインする
- **ssl** `object` - Node.js HTTPSサーバーの [TLSオプション](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener)。

##### Admin#listen([ port, host ])

ネットワーク上でリッスンを開始します。

##### Admin#manage(toxy)

`toxy` サーバーインスタンスを管理します。

##### Admin#find(toxy)

toxyインスタンスを見つけます。toxyサーバーIDまたはtoxyインスタンスを受け入れます。

##### Admin#remove(toxy)

toxyインスタンスの管理を停止します。

##### Admin#use(...middleware)

ミドルウェアを登録します。

##### Admin#param(...middleware)

パラメータミドルウェアを登録します。

##### Admin#get(path, [ ...middleware ])

GETルートを登録します。

##### Admin#post(path, [ ...middleware ])

POSTルートを登録します。

##### Admin#put(path, [ ...middleware ])

PUTルートを登録します。

##### Admin#delete(path, [ ...middleware ])

DELETEルートを登録します。

##### Admin#patch(path, [ ...middleware ])

PATCHルートを登録します。

##### Admin#all(path, [ ...middleware ])

任意のHTTPメソッドを受け付けるルートを登録します。

##### Admin#middleware(req, res, next)

connect/expressと一緒にプラグインするミドルウェア。

##### Admin#close(cb)

サーバーを停止します。

## License

MIT - Tomas Aparicio

[![views](https://sourcegraph.com/api/repos/github.com/h2non/toxy/.counters/views.svg)](https://sourcegraph.com/github.com/h2non/toxy)

toxy

人気

toxy

目次

特徴

はじめに

なぜtoxyなのか？

概念

動作の仕組み```

例

Inject response

レート制限

スローオープン

スロットル

タイムアウト

時間しきい値

コンテンツタイプ

レスポンスヘッダー

レスポンスボディ

サードパーティルール

ルールの書き方

プログラムAPI

toxy([ options ])

Directive(middlewareFn)

Directive#enable()

Directive#disable()

Directive#isEnabled()

Directive#rule(rule)

Directive#handler()

HTTP API

使用法

API

GET /

サーバー

GET /servers

GET /servers/:id

ルール

GET /servers/:id/rules

POST /servers/:id/rules

DELETE /servers/:id/poisons

GET /servers/:id/poisons/:id

DELETE /servers/:id/poisons/:id

GET /servers/:id/poisons/:id/rules

POST /servers/:id/poisons/:id/rules

DELETE /servers/:id/routes

GET /servers/:id/routes/:id

DELETE /servers/:id/routes/:id

ルートルール

GET /servers/:id/routes/:id/rules

POST /servers/:id/routes/:id/rules

DELETE /servers/:id/routes/:id/poisons

GET /servers/:id/routes/:id/poisons/:id

DELETE /servers/:id/routes/:id/poisons/:id

GET /servers/:id/routes/:id/poisons/:id/rules

POST /servers/:id/routes/:id/poisons/:id/rules