h2non/toxyProxy HTTP hackeável para testes de resiliência e condições de rede simuladas
Não mantido ativamente, pode não funcionar com as versões mais recentes do node.js. Se você estiver interessado em manter o toxy, por favor abra uma issue.
Proxy HTTP hackeável para simular cenários de falha do servidor, testes de resiliência de sistemas e condições de rede inesperadas, construído para node.js.
Foi projetado principalmente para testes de resistência a falhas, onde o toxy se torna particularmente útil para cobrir capacidades de tolerância a falhas e resiliência de um sistema, especialmente em redes tolerantes a disrupção e arquiteturas orientadas a serviços, onde o toxy pode atuar como proxy MitM entre serviços para injetar falhas.
o toxy permite que você conecte venenos, opcionalmente filtrados por regras, que essencialmente podem interceptar e alterar o fluxo HTTP conforme sua necessidade, realizando múltiplas ações maliciosas no meio desse processo, como limitar a largura de banda, atrasar pacotes de rede, injetar latência de jitter de rede ou responder com um erro personalizado ou código de status. Ele opera principalmente na camada L7, embora possa simular condições de rede L3.
o toxy pode ser usado fluentemente de forma programática ou via API HTTP. Ele foi construído sobre o rocky, um proxy HTTP orientado a middleware completo, e também é plugável no connect/express como middleware padrão.
Requer node.js +4.
Existem algumas outras soluções semelhantes ao toxy no mercado, mas a maioria delas não fornece um controle programático adequado e geralmente não são fáceis de modificar, configurar ou são diretamente fechadas à extensibilidade.
Além disso, a maioria dessas soluções opera apenas no nível de pilha TCP L3, em vez de fornecer abstrações de alto nível para cobrir requisitos comuns no domínio específico e na natureza do protocolo HTTP L7, como o toxy tenta fornecer
o toxy traz uma solução poderosa, hackeável e extensível com uma abstração conveniente, mas sem perder as capacidades adequadas de interface de baixo nível para lidar facilmente com primitivas do protocolo HTTP.
o toxy foi projetado baseado nos princípios de composição, simplicidade e extensibilidade. Através de sua camada de middleware hierárquica específica de domínio embutida, você pode facilmente aumentar os recursos do toxy de acordo com suas necessidades.
O toxy introduz duas diretivas: venenos e regras.
Venenos são a lógica específica que infecta uma transação HTTP de entrada ou saída (por exemplo: injetar latência, responder com um erro). Uma transação HTTP pode ser envenenada por um ou múltiplos venenos, e esses venenos também podem ser configurados para infectar tráfego tanto em nível global quanto de rota.
Regras são um tipo de filtros de validação de correspondência que inspecionam uma requisição/resposta HTTP para determinar, dadas certas regras, se a transação HTTP deve ser envenenada ou não (por exemplo: se os cabeçalhos correspondem, parâmetros de consulta, método, corpo...). As regras podem ser reutilizadas e aplicadas a ambos os fluxos de tráfego de entrada e saída, incluindo diferentes escopos: nível global, de rota ou de veneno.
↓ ( 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
## Uso
### Instalação```
npm install toxy
Consulte o diretório exemplos para mais casos de uso.```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')
## Benchmark
Veja [toxy/benchmark](https://github.com/h2non/toxy/tree/master/benchmark) para detalhes.
## Venenos
Os venenos hospedam lógica específica que intercepta e modifica, envolve, altera e/ou cancela uma transação HTTP no servidor proxy.
Os venenos podem ser aplicados ao tráfego de entrada ou saída, ou até mesmo a ambos os fluxos (veja [fases de envenenamento](#poisoning-phases)).
Os venenos podem ser compostos e reutilizados para diferentes cenários HTTP.
Eles são executados em ordem FIFO e de forma assíncrona.
### Escopos de envenenamento
O `toxy` possui um design hierárquico baseado em dois escopos diferentes: `global` e `route`.
**Global** aponta para todo o tráfego HTTP recebido pelo servidor proxy, independentemente do método HTTP ou caminho.
**Route** aponta para qualquer tráfego recebido que corresponda a um verbo HTTP e caminho de URI específicos.
Os venenos podem ser conectados a ambos os escopos, o que significa que você pode operar com maior precisão e restringir o escopo do envenenamento.
Por exemplo, você pode querer aplicar um envenenamento de limite de largura de banda apenas
a certas rotas, como `/download` ou `/images`.
Veja [routes.js](https://github.com/h2non/toxy/blob/master/examples/routes.js) para um exemplo completo.
### Fases de envenenamento
Os venenos podem ser conectados a fluxos de tráfego de entrada ou saída, ou até mesmo a ambos.
**Entrada** O envenenamento é aplicado quando o tráfego foi recebido pelo proxy
mas ainda não foi encaminhado para o servidor de destino.
**Saída** refere-se ao tráfego que foi encaminhado para o servidor de destino e
quando o proxy recebe a resposta dele, mas essa resposta ainda não foi enviada ao cliente.
Isso significa, essencialmente, que você pode conectar seus venenos para infectar o tráfego HTTP
antes ou depois que a requisição seja encaminhada ao servidor HTTP de destino ou enviada ao cliente.
Isso permite que você aplique um envenenamento melhor e mais preciso com base na requisição ou na resposta do servidor.
Por exemplo, dada a natureza de alguns venenos, como `inject error`,
você pode querer ativá-lo de acordo com a resposta do servidor de destino (por exemplo: algum cabeçalho está presente ou não).
Veja [poison-phases.js](https://github.com/h2non/toxy/blob/master/examples/poison-phases.js) para um exemplo completo.
### Venenos nativos
#### Latência
<table>
<tr>
<td><b>Nome</b></td><td>latency</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
<tr>
<td><b>Alcança o servidor</b></td><td>verdadeiro</td>
</tr>
</table>
Infecta o fluxo HTTP injetando uma variação de latência na resposta
**Argumentos**:
- **options** `object`
- **jitter** `number` - Valor de jitter em milissegundos
- **max** `number` - Valor máximo de jitter aleatório
- **min** `number` - Valor mínimo de jitter aleatório```js
toxy.poison(toxy.poisons.latency({ jitter: 1000 }))
// Or alternatively using a random value
toxy.poison(toxy.poisons.latency({ max: 1000, min: 100 }))
| Nome | inject |
| Fase de envenenamento | entrada / saída |
| Alcança o servidor | falso (apenas como envenenamento de entrada) |
Injeta uma resposta personalizada, interceptando a requisição antes de enviá-la ao servidor alvo. Útil para injetar erros originados no servidor.
Argumentos:
object
number - Código de status HTTP da resposta. Padrão 500object - Cabeçalhos opcionais para enviarmixed - Dados opcionais do corpo para enviar. Pode ser um buffer ou stringstring - Codificação do corpo. Padrão para `utf8````js
toxy.poison(toxy.poisons.inject({
code: 503,
body: '{"error": "toxy injected error"}',
headers: {'Content-Type': 'application/json'}
}))#### Largura de Banda
<table>
<tr>
<td><b>Nome</b></td><td>bandwidth</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>incoming / outgoing</td>
</tr>
<tr>
<td><b>Alcança o servidor</b></td><td>true</td>
</tr>
</table>
Limita a quantidade de bytes enviados pela rede no tráfego HTTP de saída para um determinado período de tempo.
Este poison é basicamente um alias para [throttle](#throttle).
**Argumentos**:
- **options** `object`
- **bytes** `number` - Quantidade de blocos de bytes a enviar. Padrão `1024`
- **threshold** `number` - Período de tempo dos pacotes em milissegundos. Padrão `1000````js
toxy.poison(toxy.poisons.bandwidth({ bytes: 512 }))
| Nome | rateLimit |
| Fase de envenenamento | incoming / outgoing |
| Alcança o servidor | true |
Limita a quantidade de requisições recebidas pelo proxy em um intervalo de tempo específico. Projetado para testar limites de API. Expõe cabeçalhos típicos X-RateLimit-*.
Observe que esta é uma implementação de limite de taxa muito simples; de fato, os limites são armazenados em memória, portanto, são completamente voláteis. Existem várias implementações de limitadores de taxa robustas e consistentes no npm que você pode utilizar como veneno. Você também pode se interessar pelo algoritmo token bucket.
Argumentos:
object
number – Quantidade total de requisições. Padrão: 10number – Intervalo de tempo limite em milissegundos. Padrão: 1000string – Mensagem de erro opcional quando o limite é atingido.number – Código de status HTTP quando o limite é atingido. Padrão: 429.```js
toxy.poison(toxy.poisons.rateLimit({ limit: 5, threshold: 10 * 1000 }))#### Leitura lenta
<table>
<tr>
<td><b>Nome</b></td><td>slowRead</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>incoming</td>
</tr>
<tr>
<td><b>Alcança o servidor</b></td><td>true</td>
</tr>
</table>
Lê pacotes de dados de payload recebidos lentamente. Válido apenas para requisições não-GET.
**Argumentos**:
- **options** `object`
- **chunk** `number` - Tamanho do chunk do pacote em bytes. Padrão `1024`
- **threshold** `number` - Limite de tempo limite em milissegundos. Padrão `1000````js
toxy.poison(toxy.poisons.slowRead({ chunk: 2048, threshold: 1000 }))
Nome: slowOpen
| Nome | slowOpen |
| Fase de Envenenamento | incoming |
| Alcança o servidor | true |
Atrasa o estado de pronto da conexão HTTP.
Argumentos:
object
number - Atraso da conexão em milissegundos. Padrão para `1000````js
toxy.poison(toxy.poisons.slowOpen({ delay: 2000 }))#### Fechamento lento
<table>
<tr>
<td><b>Nome</b></td><td>slowClose</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
<tr>
<td><b>Alcança o servidor</b></td><td>true</td>
</tr>
</table>
Atras o sinal de fechamento da conexão HTTP (EOF).
**Argumentos**:
- **options** `object`
- **delay** `number` - Tempo de atraso em milissegundos. Padrão é `1000````js
toxy.poison(toxy.poisons.slowClose({ delay: 2000 }))
| Nome | throttle |
| Fase de Envenenamento | entrada / saída |
| Alcança o servidor | true |
Restringe a quantidade de pacotes enviados pela rede num intervalo de tempo específico.
Argumentos:
object
number - Tamanho do bloco de pacotes em bytes. Padrão: 1024object - Intervalo de atraso do bloco de dados em milissegundos. Padrão: `100````js
toxy.poison(toxy.poisons.throttle({ chunk: 2048, threshold: 1000 }))#### Abortar conexão
<table>
<tr>
<td><b>Nome</b></td><td>abort</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
<tr>
<td><b>Alcança o servidor</b></td><td>falso (apenas como veneno de entrada)</td>
</tr>
</table>
Aborta a conexão TCP. Da perspectiva de baixo nível, isso destruirá o socket no servidor, operando apenas no nível TCP sem enviar nenhum dado específico do nível de aplicação HTTP.
**Argumentos**:
- **options** `object`
- **delay** `number` - Aborta a conexão TCP após esperar os milissegundos fornecidos. Padrão é `0`
- **next** `boolean` - Se `true`, a conexão será abortada se o servidor alvo levar mais tempo do que o parâmetro `delay` para responder. Padrão é `false`
- **error** `Error` - Erro interno personalizado do node.js para usar ao destruir o socket. Padrão é `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 }))
| Nome | timeout |
| Fase de Envenenamento | incoming / outgoing |
| Alcança o servidor | true |
Define um timeout de resposta. Útil quando encaminhado para servidores potencialmente lentos.
Argumentos:
number - Limite de timeout em milissegundos```js
toxy.poison(toxy.poisons.timeout(5000))### Como escrever poisons
Os poisons são implementados como funções middleware padrão com a mesma interface que o middleware connect/express.
Alguns poisons não são triviais de implementar, então você precisa estar familiarizado com o módulo [http](https://nodejs.org/api/http.html) do Node.js e sua API.
Aqui está um exemplo simples de um poison de latência de servidor:```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))
Você pode opcionalmente estender os venenos internos com seus próprios venenos:```js toxy.addPoison(customLatency)
// Then you can use it as a built-in poison proxy .get('/foo') .poison(toxy.poisons.customLatency)
Para um exemplo real em destaque, veja a implementação de [venenos embutidos](https://github.com/h2non/toxy/tree/master/lib/poisons).
## Regras
Regras são filtros de validação simples que inspecionam o tráfego HTTP de entrada ou saída para determinar, dadas certas regras (por exemplo: corresponde ao método, cabeçalhos, parâmetros de consulta, corpo...), se a transação HTTP atual deve ser envenenada ou não, com base no valor de resolução da regra.
Regras são úteis para compor, desacoplar e reutilizar lógica entre diferentes cenários de envenenamento.
Regras podem ser aplicadas ao escopo global, de rota ou mesmo de veneno, e também se aplicam a ambas as [fases de envenenamento](#poisoning-phases).
As regras são executadas em ordem FIFO. Sua lógica de avaliação é equivalente a `Array#every()` em JavaScript: todas as regras devem ser aprovadas para prosseguir com o envenenamento.
### Regras embutidas
#### Probability
<table>
<tr>
<td><b>Nome</b></td><td>probability</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
</table>
Ativa a regra por um probabilístico aleatório. Útil para envenenamento aleatório.
**Argumentos**:
- **percentage** `number` - Porcentagem de filtragem. Padrão `50````js
var rule = toxy.rules.probability(85)
toxy.rule(rule)
| Nome | timeThreshold |
| Fase de Envenenamento | incoming / outgoing |
Regra simples para habilitar envenenamentos com base em um limiar de tempo e duração específicos. Por exemplo, você pode habilitar certos envenenamentos durante uma quantidade específica de tempo (ex: 1 segundo) dentro de um limiar de tempo (ex: 1 minuto).
Argumentos:
object
number - Intervalo de tempo de habilitação em milissegundos. Padrão 1000number - Limiar de tempo em milissegundos para aguardar antes de reabilitar o envenenamento. Padrão `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 }))#### Método
<table>
<tr>
<td><b>Nome</b></td><td>method</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
</table>
Filtra por método HTTP.
**Arguments**:
- **method** `string|array` - Método ou métodos para filtrar.```js
var method = toxy.rules.method(['GET', 'POST'])
toxy.rule(method)
Filtra pelo cabeçalho de tipo de conteúdo. Ele deve estar presente.
Argumentos:
string|regexp - Valor do cabeçalho para corresponder.```js
var rule = toxy.rules.contentType('application/json')
toxy.rule(rule)#### Headers
<table>
<tr>
<td><b>Nome</b></td><td>headers</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
</table>
Filtrar por cabeçalhos de requisição.
**Argumentos**:
- **headers** `object` - Cabeçalhos a serem correspondidos por par chave-valor. `value` pode ser uma string, regexp, `boolean` ou `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)
| Nome | responseHeaders |
| Fase de Envenenamento | outgoing |
Filtrar por cabeçalhos de resposta do servidor alvo. Mesmo que a regra headers, mas avaliando a requisição de saída.
Argumentos:
object - Headers para corresponder por par chave-valor. value pode ser uma string, regexp, boolean ou `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)
#### Body
<table>
<tr>
<td><b>Nome</b></td><td>body</td>
</tr>
<tr>
<td><b>Fase de Envenenamento</b></td><td>entrada / saída</td>
</tr>
</table>
Corresponder ao payload do corpo recebido por uma `string`, `regexp` ou função de filtro `function` personalizada.
Esta regra é bastante simples, então para correspondências complexas de corpo (ex: validação contra um esquema JSON) você provavelmente deve escrever sua própria regra.
**Argumentos**:
- **match** `string|regexp|function` - Conteúdo do corpo a corresponder
- **limit** `string` - Opcional. Limite do corpo em tamanho humano. Ex: `5mb`
- **encoding** `string` - Codificação do corpo. Padrão: `utf8`
- **length** `number` - Tamanho do corpo. Padrão obtido do cabeçalho `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)
| Nome | responseBody |
| Fase de Envenenamento | saída |
Corresponder ao payload do corpo de saída por uma string, regexp ou function de filtro personalizado.
Argumentos:
string|regexp|function - Conteúdo do corpo a corresponderstring - Codificação do corpo. Padrão utf8number - Comprimento do corpo. Padrão obtido do cabeçalho `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)
#### Status de resposta
<table>
<tr>
<td><b>Nome</b></td><td>responseStatus</td>
</tr>
<tr>
<td><b>Fase do Veneno</b></td><td>outgoing</td>
</tr>
</table>
Avalia o status de resposta do servidor de destino.
Aplicável apenas a venenos de saída.
**Argumentos**:
- **range** `array` - Par de intervalo de código de status para corresponder. Padrão `[200, 300]`.
- **lower** `number` - Comparar status como operação `lower than`. Padrão `null`.
- **higher** `number` - Comparar status como operação `higher than`. Padrão `null`.
- **value** `number` - Código de status para corresponder usando comparação estrita de igualdade. Padrão `null`.
- **include** `array` - Lista não ordenada de códigos de status para corresponder. Útil para especificar status personalizados. Padrão `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] }))
Lista de regras de terceiros disponíveis fornecidas pela comunidade. PRs são bem-vindos.
As regras são funções de middleware simples que resolvem de forma assíncrona com um valor boolean para determinar se uma determinada transação HTTP deve ser ignorada durante o envenenamento.
Sua regra deve resolver com um parâmetro boolean chamando a função next(err, shouldIgnore) no middleware, passando um valor true se a regra não tiver correspondências e não deve aplicar o envenenamento, e portanto continuar com a próxima pilha de middleware.
Aqui está um exemplo de uma regra simples que corresponde ao método HTTP para determinar se:```js var toxy = require('toxy')
function customMethodRule(matchMethod) { /**
var proxy = toxy()
// Register and enable the rule proxy .get('/foo') .rule(customMethodRule('GET')) .poison(/* ... */)
Você pode opcionalmente estender as regras internas com suas próprias regras:```js
toxy.addRule(customMethodRule)
// Then you can use it as a built-in poison
proxy
.get('/foo')
.rules(toxy.rules.customMethodRule)
Para exemplos reais em destaque, veja a implementação das regras integradas
A API toxy é completamente construída sobre a API rocky. Em outras palavras, você pode usar qualquer um dos métodos, recursos e camada de middleware fornecidos nativamente pelo rocky.
Crie um novo proxy toxy.
Para as options suportadas, consulte a documentação do 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... ])
Return: `ToxyRoute`
Registra uma nova rota para o método `GET`.
#### toxy#post(path, [ middleware... ])
Return: `ToxyRoute`
Registra uma nova rota para o método `POST`.
#### toxy#put(path, [ middleware... ])
Return: `ToxyRoute`
Registra uma nova rota para o método `PUT`.
#### toxy#patch(path, [ middleware... ])
Return: `ToxyRoute`
#### toxy#delete(path, [ middleware... ])
Return: `ToxyRoute`
Registra uma nova rota para o método `DELETE`.
#### toxy#head(path, [ middleware... ])
Return: `ToxyRoute`
Registra uma nova rota para o método `HEAD`.
#### toxy#all(path, [ middleware... ])
Return: `ToxyRoute`
Registra uma nova rota para qualquer método.
#### toxy#poisons `=>` Object
Expõe um mapa com os venenos embutidos. Alias de protótipo para `toxy.poisons`
#### toxy#rules `=>` Object
Expõe um mapa com os venenos embutidos. Alias de protótipo para `toxy.rules`
#### toxy#forward(url)
Define uma URL para encaminhar o tráfego recebido pelo proxy.
#### toxy#balance(urls)
Encaminha para múltiplos servidores balanceando entre eles.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#programmatic-api)
#### toxy#replay(url)
Define um novo servidor de replay.
Você pode chamar este método várias vezes para definir múltiplos servidores de replay.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#programmatic-api)
#### toxy#use(middleware)
Insere um middleware personalizado.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#middleware-layer).
#### toxy#useResponse(middleware)
Insere um middleware de tráfego de saída (resposta).
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#middleware-layer).
#### toxy#useReplay(middleware)
Insere um middleware de tráfego de replay.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#middleware-layer)
#### toxy#requestBody(middleware)
Intercepta o corpo da requisição recebida. Útil para modificá-lo dinamicamente.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#programmatic-api)
#### toxy#responseBody(middleware)
Intercepta o corpo da resposta de saída. Útil para modificá-lo dinamicamente.
Para mais informações, veja a [documentação do rocky](https://github.com/h2non/rocky#programmatic-api)
#### toxy#middleware()
Retorna um middleware padrão para uso com connect/express.
#### toxy#host(host)
Sobrescreve o cabeçalho `Host` com um valor personalizado. Similar à opção `forwardHost`.
#### toxy#redirect(url)
Redireciona o tráfego para a URL fornecida.
#### toxy#findRoute(routeIdOrPath, [ method ])
Encontra uma rota por ID ou path e método.
#### toxy#listen(port)
Inicia o servidor HTTP embutido, escutando em uma porta TCP específica.
#### toxy#close([ callback ])
Fecha o servidor HTTP.
#### toxy#poison(poison)
Alias: `usePoison`, `useIncomingPoison`
Registra um novo veneno para infectar o tráfego de [entrada](#poisoning-phases).
#### toxy#outgoingPoison(poison)
Alias: `useOutgoingPoison`, `responsePoison`
Registra um novo veneno para infectar o tráfego de [saída](#poisoning-phases).
#### toxy#rule(rule)
Alias: `useRule`
Registra uma nova regra.
#### toxy#withRule(rule)
Aliases: `ifRule`, `whenRule`, `poisonRule`, `poisonFilter`
Aplica uma nova regra ao último veneno registrado.
#### toxy#enable(poison)
Ativa um veneno pelo identificador de nome.
#### toxy#disable(poison)
Desativa um veneno pelo identificador de nome.
#### toxy#remove(poison)
Return: `boolean`
Remove um veneno de tráfego de entrada pelo identificador de nome ou referência de objeto.
#### toxy#removeOutgoing(poison)
Return: `boolean`
Remove um veneno de tráfego de saída pelo identificador de nome ou referência de objeto.
#### toxy#isEnabled(poison)
Return: `boolean`
Verifica se um veneno está ativo pelo identificador de nome.
#### toxy#disableAll()
Alias: `disablePoisons`
Desativa todos os venenos registrados.
#### toxy#getPoison(name)
Return: `Directive|null`
Procura e recupera um veneno registrado na pilha pelo identificador de nome.
#### toxy#getIncomingPoison(name)
Return: `Directive|null`
Procura e recupera um veneno `incoming` registrado na pilha pelo identificador de nome.
#### toxy#getOutgoingPoison(name)
Return: `Directive|null`
Procura e recupera um veneno `outgoing` registrado na pilha pelo identificador de nome.
#### toxy#getPoisons()
Return: `array<Directive>`
Retorna um array de venenos registrados.
#### toxy#getIncomingPoisons()
Return: `array<Directive>`
Retorna um array de venenos `incoming` registrados.
#### toxy#getOutgoingPoisons()
Return: `array<Directive>`
Retorna um array de venenos `outgoing` registrados.
#### toxy#flush()
Alias: `flushPoisons`
Remove todos os venenos registrados para ambos os fluxos de tráfego de entrada e saída.
#### toxy#enableRule(rule)
Ativa uma regra pelo identificador de nome.
#### toxy#disableRule(rule)
Desativa uma regra pelo identificador de nome.
#### toxy#removeRule(rule)
Return: `boolean`
Remove uma regra pelo identificador de nome.
#### toxy#disableRules()
Desativa todas as regras registradas.
#### toxy#isRuleEnabled(rule)
Return: `boolean`
Verifica se a regra fornecida está ativa pelo identificador de nome.
#### toxy#getRule(rule)
Return: `Directive|null`
Procura e recupera uma regra registrada na pilha pelo identificador de nome.
#### toxy#getRules()
Return: `array<Directive>`
Retorna um array com as regras registradas encapsuladas como `Directive`.
#### toxy#flushRules()
Remove todas as regras.
### toxy.addPoison(name, fn)
Estende venenos embutidos.
### toxy.addRule(name, fn)
Estende regras embutidas.
### toxy.poisons `=>` Object
Expõe um mapa com os venenos embutidos.
### toxy.rules `=>` Object
Expõe um mapa com as regras embutidas.
### toxy.VERSION `=>` String
Versão semântica atual do toxy.
### ToxyRoute
`ToxyRoute` expõe a mesma interface que `Toxy` (interface global), apenas adiciona alguns [métodos adicionais](https://github.com/h2non/rocky#routepath) a nível de rota.
Ações posteriores que você realizar contra a API `ToxyRoute` serão aplicáveis apenas no nível da rota (aninhado). Em outras palavras: você já conhece a API.
Este exemplo provavelmente esclarecerá possíveis dúvidas:```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'))
Um wrapper conveniente usado internamente para poisons e regras.
Normalmente você não precisa conhecer esta interface, mas para fins de hacking ou ações de baixo nível pode ser útil.
Retorno: boolean
Retorno: boolean
Retorno: boolean
Apelido: filter
Retorno: function(req, res, next)
A API HTTP do toxy segue as convenções da JSON API, incluindo hypermedia linking baseado em recursos.
Para um caso de uso destacado, veja o exemplo do servidor de administração exemplo.```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)
Para mais detalhes sobre a API programática de administração, veja [abaixo](#programmatic-api-1).
### Autorização
A API HTTP pode ser protegida contra clientes não autorizados.
Clientes autorizados devem definir o token da chave da API via cabeçalhos HTTP `API-Key` ou `Authorization`.
Para habilitá-la, você deve simplesmente passar as seguintes opções para o servidor de administração `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)
Hierarquia:
toxy
Aceita: application/json
Exemplo de payload:```js { "name": "method", "options": "GET" }
#### DELETE /servers/:id/rules
#### GET /servers/:id/rules/:id
#### DELETE /servers/:id/rules/:id
### Envenenamentos
#### GET /servers/:id/poison
#### POST /servers/:id/poisons
Aceita: `application/json`
Exemplo de payload:```js
{
"name": "latency",
"phase": "outgoing",
"options": { "jitter": 1000 }
}
Aceita: application/json
Exemplo de payload:```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
### Rotas
#### GET /servers/:id/routes
#### POST /servers/:id/routes
Aceita: `application/json`
Exemplo de payload:```js
{
"path": "/foo", // Required
"method": "GET", // use ALL for all the methods
"forward": "http://my.server", // Optional custom forward server URL
}
Aceita: application/json
Exemplo de payload:```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
### Venenos de rota
#### GET /servers/:id/routes/:id/poisons
#### POST /servers/:id/routes/:id/poisons
Aceita: `application/json`
Exemplo de payload:```js
{
"name": "latency",
"phase": "outgoing",
"options": { "jitter": 1000 }
}
Aceita: application/json
Exemplo de payload:```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 Programática
O servidor de administração HTTP integrado também fornece uma interface simples aberta para fins de extensibilidade e hacking.
Por exemplo, você pode conectar middleware adicional ao servidor de administração, ou registrar novas rotas.
#### toxy.admin([ opts ])
Retorna: `Admin`
**Opções suportadas**:
- **apiKey** `string` - Chave de API opcional para proteger o servidor
- **port** `number` - Opcional. Porta TCP para escutar
- **cors** `boolean` - Habilitar CORS para acesso via navegador web
- **middleware** `array<function>` - Conecte middleware adicional
- **ssl** `object` - Servidor HTTPS Node.js [opções TLS](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener).
##### Admin#listen([ port, host ])
Começa a escutar na rede.
##### Admin#manage(toxy)
Gerencia uma instância do servidor `toxy`.
##### Admin#find(toxy)
Encontra uma instância toxy. Aceita ID do servidor toxy ou instância toxy.
##### Admin#remove(toxy)
Para de gerenciar uma instância toxy.
##### Admin#use(...middleware)
Registra um middleware.
##### Admin#param(...middleware)
Registra um middleware de parâmetro.
##### Admin#get(path, [ ...middleware ])
Registra uma rota GET.
##### Admin#post(path, [ ...middleware ])
Registra uma rota POST.
##### Admin#put(path, [ ...middleware ])
Registra uma rota PUT.
##### Admin#delete(path, [ ...middleware ])
Registra uma rota DELETE.
##### Admin#patch(path, [ ...middleware ])
Registra uma rota PATCH.
##### Admin#all(path, [ ...middleware ])
Registra uma rota que aceita qualquer método HTTP.
##### Admin#middleware(req, res, next)
Middleware para conectar com connect/express.
##### Admin#close(cb)
Para o servidor.
## Licença
MIT - Tomas Aparicio
[](https://sourcegraph.com/github.com/h2non/toxy)