toxy

No mantenido activamente, puede no funcionar con las últimas versiones de node.js. Si estás interesado en mantener toxy, por favor abre un issue.

Proxy HTTP hackeable para simular escenarios de fallo del servidor, pruebas de resiliencia de sistemas y condiciones de red inesperadas, construido para node.js.

Fue diseñado principalmente para pruebas de resistencia a fallos, donde toxy se vuelve particularmente útil para cubrir las capacidades de tolerancia a fallos y resiliencia de un sistema, especialmente en redes tolerantes a disrupción y arquitecturas orientadas a servicios, donde toxy puede actuar como proxy MitM entre servicios para inyectar fallos.

toxy te permite conectar poisons, opcionalmente filtrados por reglas, que esencialmente pueden interceptar y alterar el flujo HTTP según sea necesario, realizando múltiples acciones maliciosas en medio de ese proceso, como limitar el ancho de banda, retrasar paquetes de red, inyectar latencia de jitter de red o responder con un error o código de estado personalizado.

Opera principalmente en la capa L7, aunque puede simular condiciones de red L3.

toxy se puede usar de manera fluida programáticamente o mediante API HTTP.

Fue construido sobre rocky, un proxy HTTP completo orientado a middleware, y también es conectable en connect/express como middleware estándar.

Requiere node.js +4.

Características

Proxy HTTP/S completo (respaldado por rocky y http-proxy)
API programática hackeable y elegante (inspirada en connect/express)
API HTTP de administración para gestión externa y configuración dinámica
Router incorporado con configuración anidada
Envenenamiento jerárquico y componible con filtrado basado en reglas
Capa de middleware jerárquica (tanto a nivel global como de ruta)
Fácilmente ampliable mediante middleware (basado en middleware de connect/express)
Soporta envenenamiento de tráfico entrante y saliente
Poisons incorporados (ancho de banda, error, aborto, latencia, lectura lenta...)
Envenenamiento basado en reglas (probabilístico, método HTTP, cabeceras, cuerpo...)
Soporta poisons y reglas de terceros
Balanceador incorporado e interceptor de tráfico mediante middleware
Hereda API y características de rocky
Compatible con connect/express (y la mayoría de sus middleware)
Capaz de ejecutarse como proxy HTTP independiente

Introducción

¿Por qué toxy?

Existen algunas otras soluciones similares a toxy en el mercado, pero la mayoría no ofrecen un control programático adecuado y normalmente no son fáciles de hackear, configurar o están cerradas a la extensibilidad.

Además, la mayoría de esas soluciones solo operan en la pila de nivel TCP L3 en lugar de proporcionar abstracciones de alto nivel para cubrir requisitos comunes en el dominio específico y la naturaleza del protocolo HTTP L7, como toxy intenta proporcionar.

toxy ofrece una solución potente, hackeable y extensible con una abstracción conveniente, pero sin perder capacidades de interfaz de bajo nivel adecuadas para tratar fácilmente con las primitivas del protocolo HTTP.

toxy fue diseñado basándose en las reglas de composición, simplicidad y extensibilidad. A través de su capa de middleware jerárquica específica de dominio incorporada, puedes ampliar fácilmente las características de toxy según tus necesidades.

Conceptos

toxy introduce dos directivas: poisons y reglas.

Poisons son la lógica específica que infecta una transacción HTTP entrante o saliente (por ejemplo, inyectando latencia, respondiendo con un error). Una transacción HTTP puede ser envenenada por uno o múltiples poisons, y esos poisons también pueden configurarse para infectar tráfico a nivel global o de ruta.

Reglas son un tipo de filtros de validación de coincidencia que inspeccionan una solicitud/respuesta HTTP para determinar, dadas ciertas reglas, si la transacción HTTP debe ser envenenada o no (por ejemplo, si las cabeceras coinciden, parámetros de consulta, método, cuerpo...). Las reglas pueden reutilizarse y aplicarse tanto a flujos de tráfico entrante como saliente, incluyendo diferentes ámbitos: global, de ruta o a nivel de poison.

Cómo funciona```

↓ ( 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

### Instalación```
npm install toxy

Ejemplos

Vea el directorio examples para más 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

See [toxy/benchmark](https://github.com/h2non/toxy/tree/master/benchmark) for details.

## Venenos

Los venenos albergan lógica específica que intercepta y muta, envuelve, modifica y/o cancela una transacción HTTP en el servidor proxy.
Los venenos se pueden aplicar a flujos de tráfico entrantes o salientes, o incluso a ambos (ver [fases de envenenamiento](#poisoning-phases)).

Los venenos se pueden componer y reutilizar para diferentes escenarios HTTP.
Se ejecutan en orden FIFO y de forma asíncrona.

### Ámbitos de envenenamiento

`toxy` tiene un diseño jerárquico basado en dos ámbitos diferentes: `global` y `route`.

El ámbito **Global** apunta a todo el tráfico HTTP entrante recibido por el servidor proxy, independientemente del método HTTP o la ruta.

El ámbito **Route** apunta a cualquier tráfico entrante que coincida con un verbo HTTP y una ruta URI específicos.

Los venenos se pueden conectar a ambos ámbitos, lo que significa que puede operar con mayor precisión y restringir el alcance del envenenamiento; por ejemplo, es posible que desee aplicar un envenenamiento de límite de ancho de banda solo a ciertas rutas, como `/download` o `/images`.

Vea [routes.js](https://github.com/h2non/toxy/blob/master/examples/routes.js) para un ejemplo destacado.

### Fases de envenenamiento

Los venenos se pueden conectar a flujos de tráfico entrantes o salientes, o incluso a ambos.

El **envenenamiento entrante** se aplica cuando el tráfico ha sido recibido por el proxy pero aún no se ha reenviado al servidor de destino.

El **envenenamiento saliente** se refiere al tráfico que ha sido reenviado al servidor de destino y cuando el proxy recibe la respuesta del mismo, pero esa respuesta aún no se ha enviado al cliente.

Esto significa, esencialmente, que puede conectar sus venenos para infectar el tráfico HTTP antes o después de que la solicitud sea reenviada al servidor HTTP de destino o enviada al cliente.

Esto le permite aplicar un envenenamiento mejor y más preciso basado en la solicitud o respuesta del servidor.
Por ejemplo, dada la naturaleza de algunos venenos, como `inject error`, es posible que desee habilitarlo según la respuesta del servidor de destino (por ejemplo, si algún encabezado está presente o no).

Vea [poison-phases.js](https://github.com/h2non/toxy/blob/master/examples/poison-phases.js) para un ejemplo destacado.

### Venenos incorporados

#### Latencia

<table>
<tr>
<td><b>Nombre</b></td><td>latency</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>incoming / outgoing</td>
</tr>
<tr>
<td><b>Alcanza el servidor</b></td><td>true</td>
</tr>
</table>

Infecta el flujo HTTP inyectando un jitter de latencia en la respuesta

**Argumentos**:

- **options** `object`
  - **jitter** `number` - Valor de jitter en milisegundos
  - **max** `number` - Valor máximo de jitter aleatorio
  - **min** `number` - Valor mínimo de jitter aleatorio```js
toxy.poison(toxy.poisons.latency({ jitter: 1000 }))
// Or alternatively using a random value
toxy.poison(toxy.poisons.latency({ max: 1000, min: 100 }))

Inyectar respuesta

Nombre	inject
Fase de envenenamiento	entrante / saliente
Llega al servidor	falso (solo como veneno entrante)

Inyecta una respuesta personalizada, interceptando la solicitud antes de enviarla al servidor destino. Útil para inyectar errores originados en el servidor.

Argumentos:

options object
- code number - Código de estado HTTP de la respuesta. Por defecto 500
- headers object - Encabezados opcionales a enviar
- body mixed - Datos del cuerpo opcionales a enviar. Puede ser un buffer o string
- encoding string - Codificación del cuerpo. Por defecto `utf8````js toxy.poison(toxy.poisons.inject({ code: 503, body: '{"error": "toxy injected error"}', headers: {'Content-Type': 'application/json'} }))

#### Bandwidth

<table>
<tr>
<td><b>Nombre</b></td><td>bandwidth</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
<tr>
<td><b>Alcanza el servidor</b></td><td>true</td>
</tr>
</table>

Limita la cantidad de bytes enviados a través de la red en tráfico HTTP saliente durante un período de tiempo específico.

Este veneno es básicamente un alias de [throttle](#throttle).

**Argumentos**:

- **options** `object`
  - **bytes** `number` - Cantidad de fragmento de bytes a enviar. Predeterminado `1024`
  - **threshold** `number` - Marco de tiempo de paquetes en milisegundos. Predeterminado `1000````js
toxy.poison(toxy.poisons.bandwidth({ bytes: 512 }))

Límite de tasa

Nombre	rateLimit
Fase de envenenamiento	entrante / saliente
Alcanza el servidor	true

Limita la cantidad de solicitudes recibidas por el proxy en un período de tiempo umbral específico. Diseñado para probar límites de API. Expone cabeceras típicas X-RateLimit-*.

Tenga en cuenta que esta es una implementación de límite de tasa muy simple; de hecho, los límites se almacenan en memoria, por lo tanto son completamente volátiles. Hay un montón de implementaciones de limitadores de tasa completas y consistentes en npm que puede conectar como veneno. También podría estar interesado en el algoritmo de token bucket.

Argumentos:

options object
- limit number - Cantidad total de solicitudes. Valor predeterminado 10
- threshold number - Período de tiempo límite en milisegundos. Valor predeterminado 1000
- message string - Mensaje de error opcional cuando se alcanza el límite.
- code number - Código de estado HTTP cuando se alcanza el límite. Valor predeterminado 429.```js toxy.poison(toxy.poisons.rateLimit({ limit: 5, threshold: 10 * 1000 }))

#### Slow read

<table>
<tr>
<td><b>Nombre</b></td><td>slowRead</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>incoming</td>
</tr>
<tr>
<td><b>Llega al servidor</b></td><td>true</td>
</tr>
</table>

Lee los paquetes de datos entrantes lentamente. Solo válido para solicitudes que no sean GET.

**Argumentos**:

- **options** `object`
  - **chunk** `number` - Tamaño del paquete en bytes. Por defecto `1024`
  - **threshold** `number` - Límite de tiempo de espera en milisegundos. Por defecto `1000````js
toxy.poison(toxy.poisons.slowRead({ chunk: 2048, threshold: 1000 }))

Apertura lenta

Nombre: slowOpen

Nombre	slowOpen
Fase de envenenamiento	incoming
Llega al servidor	true

Retrasa el estado listo de la conexión HTTP.

Argumentos:

options object
- delay number - Retrasa la conexión en milisegundos. Valor predeterminado: `1000````js toxy.poison(toxy.poisons.slowOpen({ delay: 2000 }))

#### Slow close

<table>
<tr>
<td><b>Nombre</b></td><td>slowClose</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
<tr>
<td><b>Alcanza el servidor</b></td><td>true</td>
</tr>
</table>

Retrasa la señal de cierre de la conexión HTTP (EOF).

**Argumentos**:

- **options** `object`
  - **delay** `number` - Tiempo de retardo en milisegundos. Por defecto `1000````js
toxy.poison(toxy.poisons.slowClose({ delay: 2000 }))

Throttle

Nombre	throttle
Fase de Envenenamiento	entrante / saliente
Llega al servidor	true

Restringe la cantidad de paquetes enviados a través de la red en un marco de tiempo umbral específico.

Argumentos:

options object
- chunk number - Tamaño del fragmento de paquete en bytes. Por defecto 1024
- delay object - Marco de tiempo de retardo del fragmento de datos en milisegundos. Por defecto `100````js toxy.poison(toxy.poisons.throttle({ chunk: 2048, threshold: 1000 }))

#### Abortar conexión

<table>
<tr>
<td><b>Nombre</b></td><td>abort</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
<tr>
<td><b>Alcanza el servidor</b></td><td>false (solo como veneno entrante)</td>
</tr>
</table>

Aborta la conexión TCP. Desde la perspectiva de bajo nivel, esto destruirá el socket en el servidor, operando solo a nivel TCP sin enviar ningún dato específico a nivel de aplicación HTTP.

**Argumentos**:

- **options** `object`
  - **delay** `number` - Aborta la conexión TCP después de esperar los milisegundos dados. Por defecto `0`
  - **next** `boolean` - Si es `true`, la conexión será abortada si el servidor objetivo tarda más del tiempo del parámetro `delay` en responder. Por defecto `false`
  - **error** `Error` - Error interno personalizado de node.js para usar al destruir el socket. Por defecto `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

Nombre	timeout
Fase de Envenenamiento	incoming / outgoing
Alcanza el servidor	true

Define un tiempo de espera de respuesta. Útil cuando se reenvía a servidores potencialmente lentos.

Argumentos:

milliseconds number - Límite de tiempo de espera en milisegundos```js toxy.poison(toxy.poisons.timeout(5000))

### Cómo escribir venenos

Los venenos se implementan como funciones middleware estándar con la misma interfaz que el middleware connect/express.

Algunos venenos no son triviales de implementar, por lo que debes estar familiarizado con el módulo [http](https://nodejs.org/api/http.html) de node.js y su API.

Aquí hay un ejemplo simple de un veneno de latencia del 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))

Puedes opcionalmente extender los venenos incorporados con tus propios venenos:```js toxy.addPoison(customLatency)

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

Para ver un ejemplo real destacado, echa un vistazo a la implementación de [poisons incorporados](https://github.com/h2non/toxy/tree/master/lib/poisons).

## Reglas

Las reglas son filtros de validación simples que inspeccionan el tráfico HTTP entrante o saliente para determinar, dadas ciertas reglas (p. ej.: coincide con el método, cabeceras, parámetros de consulta, cuerpo...), si la transacción HTTP actual debe ser envenenada o no, basándose en el valor de resolución de la regla.

Las reglas son útiles para componer, desacoplar y reutilizar lógica entre diferentes escenarios de envenenamiento.
Las reglas se pueden aplicar a nivel global, de ruta o incluso de poison, y también se aplican a ambas [fases de envenenamiento](#poisoning-phases).

Las reglas se ejecutan en orden FIFO. Su lógica de evaluación es equivalente a `Array#every()` en JavaScript: todas las reglas deben pasar para proceder con el envenenamiento.

### Reglas incorporadas

#### Probabilidad

<table>
<tr>
<td><b>Nombre</b></td><td>probability</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
</table>

Habilita la regla mediante una probabilidad aleatoria. Útil para envenenamiento aleatorio.

**Argumentos**:

- **percentage** `number` – Porcentaje de filtrado. Por defecto `50````js
var rule = toxy.rules.probability(85)
toxy.rule(rule)

Umbral de tiempo

Nombre	timeThreshold
Fase de veneno	incoming / outgoing

Regla simple para habilitar venenos en función de un umbral de tiempo y una duración específicos. Por ejemplo, puede habilitar ciertos venenos durante una cantidad específica de tiempo (p. ej.: 1 segundo) dentro de un umbral de tiempo (p. ej.: 1 minuto).

Argumentos:

options object
- duration number - Intervalo de tiempo de habilitación en milisegundos. Por defecto 1000
- threshold number - Umbral de tiempo en milisegundos que esperar antes de volver a habilitar el envenenamiento. Por defecto `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 }))

#### Method

<table>
<tr>
<td><b>Nombre</b></td><td>method</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
</table>

Filtra por método HTTP.

**Arguments**:

- **method** `string|array` - Método o métodos para filtrar.```js
var method = toxy.rules.method(['GET', 'POST'])
toxy.rule(method)

Tipo de contenido

Filtra por la cabecera de tipo de contenido. Debe estar presente.

Argumentos:

valor string|regexp - Valor de la cabecera a coincidir.```js var rule = toxy.rules.contentType('application/json') toxy.rule(rule)

#### Cabeceras

<table>
<tr>
<td><b>Nombre</b></td><td>headers</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>entrante / saliente</td>
</tr>
</table>

Filtrar por cabeceras de solicitud.

**Argumentos**:

- **headers** `object` - Cabeceras para comparar por par clave-valor. `value` puede ser una cadena, expresión regular, `boolean` o `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)

Encabezados de respuesta

Nombre	responseHeaders
Fase de Envenenamiento	saliente

Filtra por encabezados de respuesta del servidor de destino. Igual que la regla headers, pero evaluando la solicitud saliente.

Argumentos:

headers object - Encabezados a coincidir por par clave-valor. value puede ser un string, regexp, boolean o `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>Name</b></td><td>body</td>
</tr>
<tr>
<td><b>Poison Phase</b></td><td>incoming / outgoing</td>
</tr>
</table>

Empareja el payload del cuerpo entrante mediante una `string`, `regexp` o `function` de filtro personalizada.

Esta regla es bastante simple, por lo que para coincidencias de cuerpo complejas (p.ej.: validar contra un esquema JSON) probablemente debas escribir tu propia regla.

**Arguments**:

- **match** `string|regexp|function` - Contenido del cuerpo a emparejar
- **limit** `string` - Opcional. Límite del cuerpo en tamaño legible. Ej.: `5mb`
- **encoding** `string` - Codificación del cuerpo. Por defecto `utf8`
- **length** `number` - Longitud del cuerpo. Por defecto tomada del encabezado `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)

Response body

Name	responseBody
Poison Phase	outgoing

Coincide con el payload del cuerpo saliente mediante un string, regexp o function de filtro personalizado.

Argumentos:

match string|regexp|function - Contenido del cuerpo a coincidir
encoding string - Codificación del cuerpo. Por defecto utf8
length number - Longitud del cuerpo. Por defecto tomada del encabezado `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)

#### Estado de respuesta

<table>
<tr>
<td><b>Nombre</b></td><td>responseStatus</td>
</tr>
<tr>
<td><b>Fase de envenenamiento</b></td><td>saliente</td>
</tr>
</table>

Evalúa el estado de respuesta del servidor objetivo. Solo aplicable a poisonings salientes.

**Argumentos**:

- **range** `array` - Par de rango de códigos de estado para coincidir. Predeterminado `[200, 300]`.
- **lower** `number` - Compara el estado como operación `menor que`. Predeterminado `null`.
- **higher** `number` - Compara el estado como operación `mayor que`. Predeterminado `null`.
- **value** `number` - Código de estado para coincidir usando una comparación de igualdad estricta. Predeterminado `null`.
- **include** `array` - Lista desordenada de códigos de estado para coincidir. Útil para especificar un estado personalizado. Predeterminado `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] }))

Reglas de terceros

Lista de reglas de terceros disponibles proporcionadas por la comunidad. Se aceptan PR.

IP - Habilitar/deshabilitar venenos según la dirección IP del cliente (soporta CIDR, subredes, rangos...).

Cómo escribir reglas

Las reglas son funciones middleware simples que se resuelven de forma asíncrona con un valor boolean para determinar si una transacción HTTP dada debe ser ignorada al envenenar.

Tu regla debe resolverse con un parámetro boolean llamando a la función next(err, shouldIgnore) en el middleware, pasando un valor true si la regla no tiene coincidencias y no debe aplicar el envenenamiento, y por lo tanto continuar con la siguiente pila de middleware.

Aquí hay un ejemplo de una regla simple que coincide con el método HTTP para determinar si:```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(/* ... */)

Puedes extender opcionalmente las reglas incorporadas con tus propias reglas:```js
toxy.addRule(customMethodRule)

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

Para ver ejemplos reales destacados, eche un vistazo a la implementación de reglas integrada implementation

API programática

La API de toxy está completamente construida sobre la API de rocky. En otras palabras, puedes usar cualquiera de los métodos, características y capa de middleware proporcionados de forma nativa por rocky.

toxy([ options ])

Crea un nuevo proxy toxy.

Para conocer las options compatibles, consulta la documentación de 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... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `GET`.

#### toxy#post(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `POST`.

#### toxy#put(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `PUT`.

#### toxy#patch(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `PATCH`.

#### toxy#delete(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `DELETE`.

#### toxy#head(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para el método `HEAD`.

#### toxy#all(path, [ middleware... ])
Retorno: `ToxyRoute`

Registra una nueva ruta para cualquier método.

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

Expone un mapa con los venenos incorporados. Alias de prototipo a `toxy.poisons`.

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

Expone un mapa con los venenos incorporados. Alias de prototipo a `toxy.rules`.

#### toxy#forward(url)

Define una URL para reenviar el tráfico entrante recibido por el proxy.

#### toxy#balance(urls)

Reenviar a múltiples servidores balanceando entre ellos.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#programmatic-api).

#### toxy#replay(url)

Define un nuevo servidor de repetición.
Puedes llamar a este método múltiples veces para definir múltiples servidores de repetición.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#programmatic-api).

#### toxy#use(middleware)

Conecta un middleware personalizado.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#middleware-layer).

#### toxy#useResponse(middleware)

Conecta un middleware de tráfico saliente de respuesta.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#middleware-layer).

#### toxy#useReplay(middleware)

Conecta un middleware de tráfico de repetición.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#middleware-layer).

#### toxy#requestBody(middleware)

Intercepta el cuerpo de la solicitud entrante. Útil para modificarlo sobre la marcha.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#programmatic-api).

#### toxy#responseBody(middleware)

Intercepta el cuerpo de la respuesta saliente. Útil para modificarlo sobre la marcha.

Para más información, consulta la [documentación de rocky](https://github.com/h2non/rocky#programmatic-api).

#### toxy#middleware()

Retorna un middleware estándar para usar con connect/express.

#### toxy#host(host)

Sobrescribe el encabezado `Host` con un valor personalizado. Similar a la opción `forwardHost`.

#### toxy#redirect(url)

Redirige el tráfico a la URL dada.

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

Encuentra una ruta por ID o ruta y método.

#### toxy#listen(port)

Inicia el servidor HTTP incorporado, escuchando en un puerto TCP específico.

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

Cierra el servidor HTTP.

#### toxy#poison(poison)
Alias: `usePoison`, `useIncomingPoison`

Registra un nuevo veneno para infectar el tráfico [entrante](#poisoning-phases).

#### toxy#outgoingPoison(poison)
Alias: `useOutgoingPoison`, `responsePoison`

Registra un nuevo veneno para infectar el tráfico [saliente](#poisoning-phases).

#### toxy#rule(rule)
Alias: `useRule`

Registra una nueva regla.

#### toxy#withRule(rule)
Alias: `ifRule`, `whenRule`, `poisonRule`, `poisonFilter`

Aplica una nueva regla para el último veneno registrado.

#### toxy#enable(poison)

Habilita un veneno por identificador de nombre.

#### toxy#disable(poison)

Deshabilita un veneno por identificador de nombre.

#### toxy#remove(poison)
Retorno: `boolean`

Elimina un veneno de tráfico entrante por identificador de nombre o referencia de objeto.

#### toxy#removeOutgoing(poison)
Retorno: `boolean`

Elimina un veneno de tráfico saliente por identificador de nombre o referencia de objeto.

#### toxy#isEnabled(poison)
Retorno: `boolean`

Comprueba si un veneno está habilitado por identificador de nombre.

#### toxy#disableAll()
Alias: `disablePoisons`

Deshabilita todos los venenos registrados.

#### toxy#getPoison(name)
Retorno: `Directive|null`

Busca y recupera un veneno registrado en la pila por identificador de nombre.

#### toxy#getIncomingPoison(name)
Retorno: `Directive|null`

Busca y recupera un veneno `incoming` registrado en la pila por identificador de nombre.

#### toxy#getOutgoingPoison(name)
Retorno: `Directive|null`

Busca y recupera un veneno `outgoing` registrado en la pila por identificador de nombre.

#### toxy#getPoisons()
Retorno: `array<Directive>`

Retorna un array de venenos registrados.

#### toxy#getIncomingPoisons()
Retorno: `array<Directive>`

Retorna un array de venenos `incoming` registrados.

#### toxy#getOutgoingPoisons()
Retorno: `array<Directive>`

Retorna un array de venenos `outgoing` registrados.

#### toxy#flush()
Alias: `flushPoisons`

Elimina todos los venenos registrados tanto para flujos de tráfico entrante como saliente.

#### toxy#enableRule(rule)

Habilita una regla por identificador de nombre.

#### toxy#disableRule(rule)

Deshabilita una regla por identificador de nombre.

#### toxy#removeRule(rule)
Retorno: `boolean`

Elimina una regla por identificador de nombre.

#### toxy#disableRules()

Deshabilita todas las reglas registradas.

#### toxy#isRuleEnabled(rule)
Retorno: `boolean`

Comprueba si la regla dada está habilitada por identificador de nombre.

#### toxy#getRule(rule)
Retorno: `Directive|null`

Busca y recupera una regla registrada en la pila por identificador de nombre.

#### toxy#getRules()
Retorno: `array<Directive>`

Retorna un array con las reglas registradas envueltas como `Directive`.

#### toxy#flushRules()

Elimina todas las reglas.

### toxy.addPoison(name, fn)

Extiende los venenos incorporados.

### toxy.addRule(name, fn)

Extiende las reglas incorporadas.

### toxy.poisons `=>` Object

Expone un mapa con los venenos incorporados.

### toxy.rules `=>` Object

Expone un mapa con las reglas incorporadas.

### toxy.VERSION `=>` String

Versión semántica actual de toxy.

### ToxyRoute

`ToxyRoute` expone la misma interfaz que la interfaz global `Toxy`, solo agrega algunos [métodos adicionales](https://github.com/h2non/rocky#routepath) a nivel de ruta.

Las acciones adicionales que realices contra la API de `ToxyRoute` solo serán aplicables a nivel de ruta (anidado). En otras palabras: ya conoces la API.

Este ejemplo probablemente aclarará posibles dudas:```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)

Un envoltorio conveniente utilizado internamente para venenos y reglas.

Normalmente no necesitas conocer esta interfaz, pero para fines de hacking o acciones de más bajo nivel puede ser útil.

Directive#enable()

Return: boolean

Directive#disable()

Return: boolean

Directive#isEnabled()

Return: boolean

Directive#rule(rule)

Alias: filter

Directive#handler()

Return: function(req, res, next)

HTTP API

La API HTTP de toxy sigue las convenciones de JSON API, incluyendo enlaces de hipermedia basados en recursos.

Usage

Para un caso de uso destacado, consulta el ejemplo del servidor de administración.```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 más detalles sobre la API programática de administración, consulte [abajo](#programmatic-api-1).

### Autorización

La API HTTP puede protegerse de clientes no autorizados.
Los clientes autorizados deben definir el token de clave API mediante las cabeceras HTTP `API-Key` o `Authorization`.

Para habilitarlo, simplemente pase las siguientes opciones al servidor de administración `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

Jerarquía:

Servers - Instancias gestionadas de toxy
- Rules - Reglas aplicadas globalmente
- Poisons - Ponzoñas aplicadas globalmente
  - Rules - Reglas específicas de ponzoña
- Routes - Lista de rutas configuradas
  - Route - Objeto para cada ruta específica
    - Rules - Reglas registradas a nivel de ruta
    - Poisons - Ponzoñas registradas a nivel de ruta
      - Rules - Reglas específicas de ponzoña a nivel de ruta

GET /

Servers

GET /servers

GET /servers/:id

Rules

GET /servers/:id/rules

POST /servers/:id/rules

Acepta: application/json

Ejemplo de payload:```js { "name": "method", "options": "GET" }

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

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

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

### Venenos

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

#### POST /servers/:id/poisons
Acepta: `application/json`

Ejemplo de carga útil:```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

Acepta: application/json

Ejemplo 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

### Rutas

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

#### POST /servers/:id/routes
Acepta: `application/json`

Ejemplo de payload:```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

Reglas de ruta

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

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

Acepta: application/json

Ejemplo de carga útil:```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

### Envenenamientos de rutas

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

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

Ejemplo de payload:```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

Acepta: application/json

Ejemplo 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

El servidor de administración HTTP incorporado también proporciona una interfaz simple abierta a fines de extensibilidad y hacking.
Por ejemplo, puedes conectar middleware adicional al servidor de administración, o registrar nuevas rutas.

#### toxy.admin([ opts ])
Devuelve: `Admin`

**Opciones admitidas**:

- **apiKey** `string` - Clave API opcional para proteger el servidor
- **port** `number` - Opcional. Puerto TCP para escuchar
- **cors** `boolean` - Habilitar CORS para acceso desde navegador web
- **middleware** `array<function>` - Conectar middleware adicional
- **ssl** `object` - Opciones TLS del servidor HTTPS de Node.js [opciones TLS](https://nodejs.org/api/tls.html#tls_tls_createserver_options_secureconnectionlistener).

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

Comienza a escuchar en la red.

##### Admin#manage(toxy)

Gestiona una instancia del servidor `toxy`.

##### Admin#find(toxy)

Encuentra una instancia de toxy. Acepta el ID del servidor toxy o una instancia de toxy.

##### Admin#remove(toxy)

Deja de gestionar una instancia de toxy.

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

Registra un middleware.

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

Registra un middleware de parámetros.

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

Registra una ruta GET.

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

Registra una ruta POST.

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

Registra una ruta PUT.

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

Registra una ruta DELETE.

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

Registra una ruta PATCH.

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

Registra una ruta que acepta cualquier método HTTP.

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

Middleware para conectar con connect/express.

##### Admin#close(cb)

Detiene el servidor.

## 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

Más Populares

toxy

Contenido

Características

Introducción

¿Por qué toxy?

Conceptos

Cómo funciona```

Ejemplos

Inyectar respuesta

Límite de tasa

Apertura lenta

Throttle

Timeout

Umbral de tiempo

Tipo de contenido

Encabezados de respuesta

Response body

Reglas de terceros

Cómo escribir reglas

API programática

toxy([ options ])

Directive(middlewareFn)

Directive#enable()

Directive#disable()

Directive#isEnabled()

Directive#rule(rule)

Directive#handler()

HTTP API

Usage

API

GET /

Servers

GET /servers

GET /servers/:id

Rules

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

Reglas de ruta

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