o desde la rama `master` de GitHub```console
❯ pip install git+https://github.com/abhinavsingh/proxy.py.git@master

## Usando Docker

Los contenedores multiplataforma están disponibles a través de:

- Docker Hub
  - La etiqueta `latest` apunta a la última versión `stable`
  - `docker pull abhinavsingh/proxy.py:latest`
- Registro de contenedores de GitHub (GHCR)
  - La etiqueta `latest` apunta a la última versión `develop`
  - `docker pull ghcr.io/abhinavsingh/proxy.py:latest`

Las versiones estables de contenedores están disponibles para las siguientes plataformas:

- `linux/386`
- `linux/amd64`
- `linux/arm/v6`
- `linux/arm/v7`
- `linux/arm64/v8`
- `linux/ppc64le`
- `linux/s390x`

### Versión estable desde Docker Hub

Ejecuta el contenedor más reciente de `proxy.py`:```console
❯ docker run -it -p 8899:8899 --rm abhinavsingh/proxy.py:latest

### Versión de Desarrollo desde GHCR

Ejecuta el contenedor de `proxy.py` desde el código más reciente en la rama develop:```console
❯ docker run -it -p 8899:8899 --rm ghcr.io/abhinavsingh/proxy.py:latest

[![WARNING](https://img.shields.io/static/v1?label=MacOS&message=warning&color=red)](https://github.com/moby/vpnkit/issues/469)
La imagen de `docker` actualmente está rota en `macOS` debido a incompatibilidad con [vpnkit](https://github.com/moby/vpnkit/issues/469).

## Usando HomeBrew

Las fórmulas actualizadas para `HomeBrew` se mantienen en la rama `develop` bajo el directorio `helper/homebrew`.

- `stable` fórmulas instalan el paquete desde la rama `master`.
- `develop` fórmulas instalan el paquete desde la rama `develop`.

### Versión Estable con HomeBrew```console
❯ brew install https://raw.githubusercontent.com/abhinavsingh/proxy.py/develop/helper/homebrew/stable/proxy.rb

# Iniciar proxy.py

## Desde la línea de comandos cuando se instala mediante PIP

Cuando `proxy.py` se instala mediante `pip`,
se coloca un ejecutable llamado `proxy` en tu `$PATH`.

### Ejecutarlo

Simplemente escribe `proxy` en la línea de comandos para iniciar con la configuración predeterminada.```console
❯ proxy
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Started 8 threadless workers
...[redacted]... - Started 8 acceptors
...[redacted]... - Listening on 127.0.0.1:8899

Puedes usar una sola letra para personalizar el nivel de registro.  Ejemplo:
- `d = DEBUG`
- `i = INFO`
- `w = WARNING`
- `e = ERROR`
- `c = CRITICAL`

Como podemos ver en los registros anteriores, antes de iniciar:

- `proxy.py` intentó establecer el límite de archivos abiertos `ulimit` en el sistema
- El valor predeterminado para `--open-file-limit` utilizado es `1024`
- La bandera `--open-file-limit` no tiene efecto en sistemas operativos `Windows`

Consulta [flags](#flags) para la lista completa de opciones de configuración disponibles.

## Desde la línea de comandos usando el repositorio fuente

Si estás intentando ejecutar `proxy.py` desde el código fuente,
no hay un archivo binario llamado `proxy` en el código fuente.

Para iniciar `proxy.py` desde el código fuente, sigue estas instrucciones:

- Clona el repositorio  ```console
  ❯ git clone https://github.com/abhinavsingh/proxy.py.git
  ❯ cd proxy.py

--hostname 0.0.0.0 --port 8899

❯ docker run -it \
    -p 8899:8899 \
    --rm abhinavsingh/proxy.py:latest \
    -v

Ahora puedes acelerar tu experiencia de navegación diaria visitando tu sitio web favorito usando nombres de dominio de un solo carácter :). Esto funciona en todos los navegadores.

Los siguientes enlaces cortos están habilitados por defecto:

| Enlace Corto |   URL de Destino    |
| :--------: | :---------------: |
|     a/     |    `amazon.com`    |
|     i/     |  `instagram.com`   |
|     l/     |   `linkedin.com`   |
|     f/     |   `facebook.com`   |
|     g/     |    `google.com`    |
|     t/     |   `twitter.com`    |
|     w/     | `web.whatsapp.com` |
|     y/     |   `youtube.com`    |
|   proxy/   |  `localhost:8899`  |

### ModifyPostDataPlugin

Modifica el cuerpo de la solicitud POST antes de enviar la solicitud al servidor upstream.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.ModifyPostDataPlugin

Nota a partir de la respuesta anterior:

1. Los datos POST fueron modificados `"data": "{\"key\": \"modified\"}"`.
   Los datos originales del comando `curl` eran `{"key": "value"}`.
2. Nuestro comando `curl` no añadió ningún encabezado `Content-Type`,
   pero nuestro plugin sí añadió uno `"Content-Type": "application/json"`.
   Lo mismo se puede verificar observando el campo `json` en la salida anterior:   ```
   "json": {
    "key": "modified"
   },

Verificar la respuesta de la API simulada usando `curl -x localhost:8899 http://api.example.com/v1/users/````console
{"count": 2, "next": null, "previous": null, "results": [{"email": "[email protected]", "groups": [], "url": "api.example.com/v1/users/1/", "username": "admin"}, {"email": "[email protected]", "groups": [], "url": "api.example.com/v1/users/2/", "username": "admin"}]}

El registro de acceso muestra `None:None` como servidor `ip:port`. `None` simplemente significa que la conexión al servidor nunca se realizó, ya que la respuesta fue devuelta por nuestro plugin.

Ahora modifique `ProposedRestApiPlugin` para que devuelva respuestas simuladas de la API REST según lo esperado por sus clientes.

### RedirectToCustomServerPlugin

Redirige todas las solicitudes `http` entrantes a un servidor web personalizado.
Por defecto, redirige las solicitudes de los clientes al servidor web integrado,
que también se ejecuta en el puerto `8899`.

Inicie `proxy.py` y habilite el servidor web integrado:```console
❯ proxy \
    --enable-web-server \
    --plugins proxy.plugin.RedirectToCustomServerPlugin

La respuesta `404` anterior fue devuelta por el servidor web `proxy.py`.

Verifique lo mismo inspeccionando los registros de `proxy.py`.
Junto con el registro de solicitud del proxy, también debe ver un registro de solicitud del servidor web http.```
... [redacted] ... - access_log:1241 - ::1:49525 - GET /
... [redacted] ... - access_log:1157 - ::1:49524 - GET localhost:8899/ - 404 NOT FOUND - 70 bytes

Verifique usando `curl -v -x localhost:8899 http://facebook.com`:```console
... [redacted] ...
< HTTP/1.1 418 I'm a tea pot
< Proxy-agent: proxy.py v1.0.0
* no chunk, no close, no size. Assume close to signal end
<
* Closing connection 0

### CacheResponsesPlugin

Almacena en caché las respuestas del servidor upstream.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.CacheResponsesPlugin

Obtén la ruta al archivo de caché de los registros de `proxy.py`:```console
... [redacted] ... - GET httpbin.org:80/get - 200 OK - 556 bytes
... [redacted] ... - Cached response at /var/folders/k9/x93q0_xn1ls9zy76m2mf2k_00000gn/T/httpbin.org-1569378301.407512.txt

### CacheByResponseType

El plugin `CacheResponsesPlugin` también puede almacenar en caché automáticamente las respuestas por `content-type`.
Para probar esto, debes estar ejecutando en modo [Intercepción TLS](#tls-interception)
y luego pasar el flag `--cache-by-content-type`.  Ejemplo:```console
❯ proxy \
    --plugins proxy.plugin.CacheResponsesPlugin \
    --cache-by-content-type \
    --ca-key-file ca-key.pem \
    --ca-cert-file ca-cert.pem \
    --ca-signing-key ca-signing-key.pem

Verificar usando `curl -v -x localhost:8899 http://google.com`:```console
... [redacted] ...
< HTTP/1.1 200 OK
< Content-Length: 28
<
* Connection #0 to host localhost left intact
Hello from man in the middle

1. Convertir dirección IP a entero
2. Convertir entero a dirección IP
3. Convertir dominio a dirección IP
4. Obtener dirección IP desde nombre de host
5. Obtener nombre de host desde dirección IP
6. Obtener registros DNS
7. Búsqueda Whois
8. Búsqueda de dirección MAC```console
❯ proxy --port 9001

Realiza una solicitud curl a través del proxy `8899`:

`curl -v -x localhost:8899 http://httpbin.org/get`

Verifica que el proxy `8899` reenvíe las solicitudes a los proxies upstream revisando los registros respectivos.

Si un proxy upstream requiere credenciales, pásalas como argumentos. Ejemplo:

`--proxy-pool user:[email protected]:port`

### FilterByClientIpPlugin

Rechaza el tráfico de direcciones IP específicas. Por defecto, este plugin bloquea el tráfico de `127.0.0.1` y `::1`.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.FilterByClientIpPlugin

Modifica el plugin a tu gusto, p. ej., permitir solo direcciones IP específicas.

### ModifyChunkResponsePlugin

Este plugin demuestra cómo modificar respuestas codificadas en fragmentos. Para ello, este plugin utiliza el núcleo de `proxy.py` para analizar la respuesta codificada en fragmentos. Luego, reconstruimos la respuesta usando fragmentos personalizados codificados de forma rígida, ignorando los fragmentos originales recibidos del servidor ascendente.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.ModifyChunkResponsePlugin

Modifica `ModifyChunkResponsePlugin` a tu gusto. Por ejemplo, en lugar de enviar fragmentos codificados, analiza y modifica los fragmentos `JSON` originales recibidos del servidor ascendente.

### ModifyRequestHeaderPlugin

Este plugin demuestra cómo modificar las cabeceras de las solicitudes HTTPS salientes en modo de intercepción TLS.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.ModifyRequestHeaderPlugin \
    ... [TLS interception flags] ...

### CloudflareDnsResolverPlugin

Este plugin usa `Cloudflare` hospedado `DNS-over-HTTPS` [API](https://developers.cloudflare.com/1.1.1.1/encrypted-dns/dns-over-https/make-api-requests/dns-json) (json).

`DoH` requiere un cliente compatible con HTTP2. Desafortunadamente `proxy.py` aún no lo proporciona, por lo que usamos una dependencia. Instálala:```console
❯ pip install "httpx[http2]"

Por defecto, `CloudflareDnsResolverPlugin` se ejecuta en modo `security` y proporciona protección contra malware.
Usa `--cloudflare-dns-mode family` para habilitar también la protección de contenido adulto.

### CustomDnsResolverPlugin

Este plugin demuestra cómo usar una implementación de resolución DNS personalizada con `proxy.py`.
Este plugin de ejemplo actualmente usa el mecanismo de resolución incorporado de Python. Personaliza el código
a tu gusto. Por ejemplo, consulta tu servidor DNS personalizado, implementa `DoH` u otros mecanismos.

Inicia `proxy.py` como:```console
❯ proxy \
    --plugins proxy.plugin.CustomDnsResolverPlugin

Haz una solicitud utilizando `curl`:```console
❯ curl -v -x localhost:8899 https://httpbin.org/get

Aviso `curl` en lugar de `::1` o `127.0.0.1` como IP del cliente.

[![WARNING](https://img.shields.io/static/v1?label=Compatibility&message=warning&color=red)](#programnameplugin) Si `ProgramNamePlugin` no funciona de manera fiable en su sistema operativo, por favor contribuya enviando una solicitud de extracción y/o abriendo un issue. ¡¡¡Gracias!!!

## Plugins del Servidor Web HTTP

### Ruta del Servidor Web

Demuestra el enrutamiento integrado del servidor web mediante un plugin.

Inicie `proxy.py` como:```console
❯ proxy --enable-web-server \
    --plugins proxy.plugin.WebServerPlugin

## Plugins de Proxy Inverso

Extiende el servidor web integrado para agregar capacidades de proxy inverso.

### Proxy Inverso

Inicia `proxy.py` como:```console
❯ proxy --enable-reverse-proxy \
    --plugins proxy.plugin.ReverseProxyPlugin

Verifique usando `curl -v localhost:8899/get`:```console
{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "localhost",
    "User-Agent": "curl/7.64.1"
  },
  "origin": "1.2.3.4, 5.6.7.8",
  "url": "https://localhost/get"
}

Esto está sucediendo porque nuestro plugin de proxy inverso predeterminado `ReverseProxyPlugin` está configurado
con un servidor upstream `http` y otro `https`.  Y, por defecto, `ReverseProxyPlugin` preserva el
encabezado de host original.  Mientras que esto funciona con upstreams `https`, no funciona de manera confiable con
upstreams `http`.  Para solucionar este problema use los flags `--rewrite-host-header`.

Example:

```bash
some-command --rewrite-host-header
``````console
❯ proxy --enable-reverse-proxy \
    --plugins proxy.plugin.ReverseProxyPlugin \
    --rewrite-host-header

Inicia `proxy.py` como:```console
❯ proxy \
    --cert-file https-cert.pem \
    --key-file https-key.pem

Si quieres evitar pasar la bandera `--proxy-cacert`, también considera firmar los certificados SSL generados. Ejemplo:

Primero, genera los certificados CA:```console
make ca-certificates

Ahora reinicie el servidor con el indicador `--cert-file https-signed-cert.pem`. Tenga en cuenta que también debe confiar en el certificado `ca-cert.pem` generado en su llavero de sistema.

# Intercepción TLS

Por defecto, `proxy.py` no descifrará el tráfico `https` entre el cliente y el servidor. Para habilitar la intercepción TLS, primero genere los certificados CA raíz:```console
❯ make ca-certificates

[![NOTE](https://img.shields.io/static/v1?label=MacOS&message=note&color=yellow)](https://github.com/abhinavsingh/proxy.py#user-content-flags) También proporcione la ruta explícita del paquete CA necesaria para la validación de certificados de pares. Consulte la bandera `--ca-file`.

Verifique la intercepción TLS usando `curl````console
❯ curl -v -x localhost:8899 --cacert ca-cert.pem https://httpbin.org/get

La línea `issuer` confirma que la respuesta fue interceptada.

También verifica el contenido del archivo de respuesta en caché. Obtén la ruta al archivo de caché de los registros de `proxy.py`.

`❯ cat /path/to/your/tmp/directory/httpbin.org-1569452863.924174.txt````console
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Content-Type: application/json
Date: Wed, 25 Sep 2019 23:07:05 GMT
Referrer-Policy: no-referrer-when-downgrade
Server: nginx
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Length: 202
Connection: keep-alive

{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/7.54.0"
  },
  "origin": "1.2.3.4, 5.6.7.8",
  "url": "https://httpbin.org/get"
}

## Autenticación de Grout

Grout soporta autenticación para proteger tus archivos, carpetas y servicios de accesos no autorizados. Usa la bandera `--basic-auth` para exigir autenticación. Ejemplo:```console
grout /path/to/folder --basic-auth user:pass
grout https://localhost:8080 --basic-auth u:p

## Grout Wildcard Domains

Por defecto, el cliente Grout sirve tráfico entrante en un subdominio dedicado.
Sin embargo, algunos servicios (por ejemplo, Kubernetes) pueden querer servir tráfico en subdominios ad hoc.
Iniciar un cliente Grout dedicado para cada subdominio ad hoc puede no ser una solución práctica.

Para tales escenarios, Grout soporta dominios wildcard. Aquí se explica cómo configurar tu propio dominio wildcard para usar con clientes Grout.

1. Elige un dominio, p. ej. `custom.example.com`
2. Tu servicio desea servir tráfico para `custom.example.com` y `*.custom.example.com`
3. Si planeas usar `https://`, necesitas configurar un balanceador de carga:
   - Configura un balanceador de carga HTTPS (LB)
   - Configura el LB con un certificado generado para `custom.example.com` y `*.custom.example.com`
   - Dirige el tráfico a las direcciones IP públicas del servicio Grout
4. Contacta al equipo de Grout en [email protected] para incluir `custom.example.com` en la lista blanca. El equipo de Grout se asegurará de que realmente eres dueño del dominio y de que has configurado un certificado SSL válido como se describió anteriormente

Inicia Grout con la bandera `--wildcard`. Ejemplo:```console
grout https://localhost:8080 custom.example.com --wildcard
2024-08-05 18:24:59,294 - grout - Logged in as [email protected]
2024-08-05 18:25:03,159 - setup - Grouting https://*.custom.domain.com

Puede proporcionar múltiples rutas personalizadas repitiendo esta bandera.

## Complemento de Cliente Grout

`GroutClientBasePlugin` le permite enrutar tráfico dinámicamente a diferentes upstreams.  A continuación se muestra una implementación simple con una descripción sobre cómo usarlo.```python
class GroutClientPlugin(GroutClientBasePlugin):

    def resolve_route(
        self,
        route: str,
        request: HttpParser,
        origin: HostPort,
        server: HostPort,
    ) -> Tuple[Optional[str], HttpParser]:
        print(request, origin, server, '->', route)
        print(request.header(b'host'), request.path)
        #
        # Here, we send traffic to localhost:7001 irrespective
        # of the original "route" value provided to the grout
        # client OR any custom host:upstream mapping provided
        # through the --tunnel-route-url flags (when using
        # --wildcard).
        #
        # Optionally, you can also strip path before
        # sending traffic to upstrem, like:
        # request.path = b"/"
        #
        # To drop the request, simply return None for route
        # return None, request
        #
        return 'http://localhost:7001', request

Sobre:

- Cambiamos `--entrypoint` a `grout`
- Reemplazamos `localhost` con `host.docker.internal`, para que `grout` pueda enrutar tráfico al puerto `29876` ejecutándose en la máquina host
- *(Opcional)* Montar la carpeta `~/.proxy` de la máquina host, para que las credenciales de `grout` puedan persistir entre reinicios del contenedor

## Cómo funciona Grout

- La infraestructura de `grout` tiene 2 componentes: cliente y servidor
- El cliente de `grout` tiene 2 componentes: un cliente ligero y un cliente pesado
- El cliente ligero de `grout` es parte de `proxy.py` de código abierto (Licencia BSD 3-Clause)
- El cliente pesado de `grout` y los servidores están alojados en [jaxl.io](https://jaxl.io)
  y son propiedad intelectual de [Jaxl Innovations Private Limited](https://jaxl.com)
- El servidor de `grout` tiene 3 componentes: un servidor de registro, un servidor proxy inverso y un servidor de túneles

## `grout` autoalojado

- El cliente pesado de `grout` y los servidores también pueden alojarse en tus infraestructuras GCP, AWS, Cloud
- Con una versión autoalojada, tu tráfico fluye a través de la red que controlas y en la que confías
- Los desarrolladores de `grout` en [jaxl.io](https://jaxl.io) proporcionan imágenes GCP, AWS y Docker para soluciones autoalojadas
- Por favor, envía un correo electrónico a [[email protected]](mailto:[email protected]) para empezar.

# Proxy a través de túnel SSH

**Esto es un trabajo en progreso y puede no funcionar como está documentado**

Requiere `paramiko` para funcionar. Instala las dependencias usando `pip install "proxy.py[tunnel]"`

## Proxy de solicitudes remotas localmente

                            |
    +------------+          |            +----------+
    |   LOCAL    |          |            |  REMOTE  |
    |   HOST     | <== SSH ==== :8900 == |  PROXY   |
    +------------+          |            +----------+
    :8899 proxy.py          |
                            |
                         FIREWALL
                      (allow tcp/22)

### Qué

Proxy de solicitudes HTTP(s) realizadas en un servidor proxy `remoto` a través del servidor `proxy.py` ejecutándose en `localhost`.

### Cómo

- El puerto `remoto` solicitado se reenvía a través de la conexión SSH.
- `proxy.py` ejecutándose en `localhost` maneja y responde a
  las solicitudes proxy `remotas`.

### Requisitos

1. `localhost` DEBE tener acceso SSH al servidor `remoto`
2. El servidor `remoto` DEBE estar configurado para proxy de solicitudes HTTP(s)
   a través del número de puerto reenviado, p. ej., `:8900`.
   - Los puertos `remoto` y `localhost` PUEDEN ser el mismo, p. ej., `:8899`.
   - Se eligió `:8900` en el diagrama ASCII con fines de diferenciación.

### Pruébalo

Inicia `proxy.py` como:```console
❯ # On localhost
❯ proxy --enable-ssh-tunnel \
    --tunnel-username username \
    --tunnel-hostname ip.address.or.domain.name \
    --tunnel-port 22 \
    --tunnel-remote-port 8899 \
    --tunnel-ssh-key /path/to/ssh/private.key \
    --tunnel-ssh-key-passphrase XXXXX
...[redacted]... [I] listener.setup:97 - Listening on 127.0.0.1:8899
...[redacted]... [I] pool.setup:106 - Started 16 acceptors in threadless (local) mode
...[redacted]... [I] transport._log:1873 - Connected (version 2.0, client OpenSSH_7.6p1)
...[redacted]... [I] transport._log:1873 - Authentication (publickey) successful!
...[redacted]... [I] listener.setup:116 - SSH connection established to ip.address.or.domain.name:22...
...[redacted]... [I] listener.start_port_forward:91 - :8899 forwarding successful...

Además, verifique que los registros de `proxy.py` en `localhost` contengan la IP `remote` como IP del cliente.```console
access_log:328 - remote:52067 - GET httpbin.org:80

                        |
+------------+          |     +----------+
|   LOCAL    |          |     |  REMOTE  |
|   HOST     | === SSH =====> |  SERVER  |
+------------+          |     +----------+
                        |     :8899 proxy.py
                        |
                    FIREWALL
                 (allow tcp/22)

Personaliza las banderas de inicio pasándolas como kwargs:```python
import ipaddress
import proxy

if __name__ == '__main__':
  proxy.main(
    hostname=ipaddress.IPv6Address('::1'),
    port=8899
  )

Ten en cuenta que:

1. `Proxy` es similar a `main`, excepto que `Proxy` no bloqueará.
2. Internamente, `Proxy` es un administrador de contexto que iniciará
   `proxy.py` al ser llamado y lo detendrá una vez que el ámbito termine.
3. A diferencia de `main`, las banderas de inicio con `Proxy` también se pueden personalizar
   usando `args` y `kwargs`. p. ej. `Proxy(['--port', '8899'])` o
   pasando banderas como kwargs, p. ej. `Proxy(port=8899)`.
4. A diferencia de `main`, `Proxy` no inspeccionará `sys.argv`.

## Puerto Efímero

Usa `--port=0` para vincular `proxy.py` a un puerto aleatorio asignado por el kernel.

En modo embebido, puedes acceder a este puerto.  Ejemplo:```python
import proxy

if __name__ == '__main__':
  with proxy.Proxy(port=0) as p:
    print(p.flags.port)
    proxy.sleep_loop()

Para simplificar, también puedes pasar la lista de plugins como un argumento de palabra clave a `proxy.main` o al constructor `Proxy`.

Ejemplo:```python
import proxy
from proxy.plugin import FilterByUpstreamHostPlugin

if __name__ == '__main__':
  proxy.main(plugins=[
    b'proxy.plugin.CacheResponsesPlugin',
    FilterByUpstreamHostPlugin,
  ])

def test_my_application_with_proxy(self) -> None:
    self.assertTrue(True)

Tenga en cuenta que:

1. `proxy.TestCase` anula el método `unittest.TestCase.run()` para configurar y cerrar `proxy.py`.
2. El servidor `proxy.py` escuchará en un puerto disponible aleatorio del sistema.
   Este puerto aleatorio está disponible como `self.PROXY.flags.port` dentro de sus casos de prueba.
3. Solo se inicia un único acceptor y worker de forma predeterminada (`--num-workers 1 --num-acceptors 1`) para una configuración y cierre más rápidos.
4. Más importante aún, `proxy.TestCase` también garantiza que el servidor `proxy.py`
   esté en funcionamiento antes de proceder con la ejecución de las pruebas. Por defecto,
   `proxy.TestCase` esperará `10 segundos` para que el servidor `proxy.py` se inicie;
   en caso de fallo, se generará una excepción `TimeoutError`.

## Sobrescribir banderas de inicio

Para sobrescribir las banderas de inicio predeterminadas, defina una variable `PROXY_PY_STARTUP_FLAGS` en su clase de prueba.
Ejemplo:```python
class TestProxyPyEmbedded(TestCase):

    PROXY_PY_STARTUP_FLAGS = [
        '--num-workers', '2',
        '--num-acceptors', '1',
        '--enable-web-server',
    ]

    def test_my_application_with_proxy(self) -> None:
        self.assertTrue(True)

def test_my_application_with_proxy(self) -> None:
    self.assertTrue(True)

def run(self, result: Optional[unittest.TestResult] = None) -> Any:
    with proxy.start([
            '--num-workers', '1',
            '--num-acceptors', '1',
            '--port', '... random port ...']):
        super().run(result)

o simplemente configurar / finalizar `proxy.py` dentro de los métodos de clase `setUpClass` y `teardownClass`.

# Utilidades

## Sockets TCP

### new_socket_connection

Intenta crear una conexión IPv4, luego IPv6 y finalmente una conexión de doble pila hacia la dirección proporcionada.```python
>>> conn = new_socket_connection(('httpbin.org', 80))
>>> ...[ use connection ]...
>>> conn.close()

Como un decorador:```python
>>> @socket_connection(('httpbin.org', 80))
>>> def my_api_call(conn, *args, **kwargs):
>>>   ... [ use connection ] ...

## PKI

### Uso de la API

- `gen_private_key`  ```python
  gen_private_key(
      key_path: str,
      password: str,
      bits: int = 2048,
      timeout: int = 10) -> bool

## Documentación Interna

### Leer la Documentación

- Visita [proxypy.readthedocs.io](https://proxypy.readthedocs.io/)
- Construye localmente usando:

`make lib-doc`

### pydoc

El código está bien documentado. Obtén el código fuente y ejecuta:

`pydoc3 proxy`

### pyreverse

Genera diagramas UML de jerarquía a nivel de clase para un análisis en profundidad:

`make lib-pyreverse`

# Ejecutar Dashboard

El Dashboard está actualmente en desarrollo y aún no incluido en los paquetes `pip`.
Para ejecutar el dashboard, debes clonar el código fuente.

Dashboard está escrito en Typescript y SCSS, así que construyámoslo primero usando:```console
❯ make dashboard

Ahora inicie `proxy.py` con el plugin de panel y sobrescribiendo el directorio raíz para el servidor estático:```console
❯ proxy --enable-dashboard --static-server-dir dashboard/public
...[redacted]... - Loaded plugin proxy.http.server.HttpWebServerPlugin
...[redacted]... - Loaded plugin proxy.dashboard.dashboard.ProxyDashboard
...[redacted]... - Loaded plugin proxy.dashboard.inspect_traffic.InspectTrafficPlugin
...[redacted]... - Loaded plugin proxy.http.inspector.DevtoolsProtocolPlugin
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Listening on ::1:8899
...[redacted]... - Core Event enabled

## Inspeccionar Tráfico

***Esto es un trabajo en progreso y puede que no funcione como está documentado***

Espere a que se cargue `Chrome Dev Console` incrustado. Actualmente, los detalles sobre todo el tráfico que fluye a través de `proxy.py` se envían a la pestaña `Inspeccionar Tráfico`. Sin embargo, los payloads recibidos aún no están integrados con la consola de desarrollador incrustada.

La funcionalidad actual se puede verificar abriendo la `Dev Console` del panel e inspeccionando la conexión websocket que el panel estableció con el servidor `proxy.py`.

[![Proxy.Py Dashboard Inspect Traffic](https://assets.kitploit.com/production/public/readmes/157/1e6258665ca9259fc526ebb90892d4b322094bb1e8139d329ab2379fc76ab66d.png)](https://github.com/abhinavsingh/proxy.py)

# Chrome DevTools Protocol

Para escenarios donde quieras acceso directo al endpoint websocket del protocolo `Chrome DevTools`, inicie `proxy.py` como:```console
❯ proxy --enable-devtools --enable-events

Por lo tanto, se requiere una versión de Python que entienda las anotaciones typing. Asegúrate de usar `Python 3.6+`. Verifica la versión antes de ejecutar `proxy.py`: `❯ python --version` Todas las anotaciones `typing` se pueden reemplazar con anotaciones `comment-only`. Ejemplo:```python
>>> my_strings = [] # List[str]
>>> ################^^^^^^^^^^^

O, simplemente pase la ruta completamente calificada como parámetro, por ej.

`proxy --plugins /path/to/my/app/my_app.proxyPlugin`

Aquí hay un ejemplo rápido de trabajo:

- Contenidos de la carpeta `/tmp/plug````console
╰─ ls -1 /tmp/plug                                                                                                                       ─╯
my_plugin.py

Este es un plugin vacío para demostrar el uso de plugins externos. Debes implementar los métodos necesarios para que tus plugins funcionen con tráfico real

- Inicia `proxy.py` con `MyPlugin````console
╰─ PYTHONPATH=/tmp/plug proxy --plugin my_plugin.MyPlugin                                                                      ─╯
...[redacted]... - Loaded plugin proxy.http.proxy.HttpProxyPlugin
...[redacted]... - Loaded plugin my_plugin.MyPlugin
...[redacted]... - Listening on ::1:8899

import socket
import select

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
try:
    s.connect(('127.0.0.1', 8899))
except Exception as e:
    print("Could not connect to proxy.py:", e)
    raise SystemExit(1)

# Print the file descriptor number
print("Socket FD:", s.fileno())

# Try to select on it
r, w, e = select.select([s], [], [], 1)
print("Readable:", r, "Writable:", w, "Error:", e)
``````console
❯ ./helper/monitor_open_files.sh <proxy-py-pid>

Algunos clientes pueden lanzar `TLSV1_ALERT_UNKNOWN_CA` si no pueden verificar el certificado del servidor porque está firmado por una CA emisora desconocida. Que es el caso cuando estamos realizando interceptación TLS. Esto puede deberse a varias razones, por ejemplo, fijación de certificados, etc.

Otra excepción que podrías ver es `CERTIFICATE_VERIFY_FAILED`:```console
2021-11-06 23:36:02,002 - pid:91033 [E] handler.handle_readables:293 - Exception while receiving from client connection <socket.socket fd=28, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0, laddr=('127.0.0.1', 8899), raddr=('127.0.0.1', 51961)> with reason SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)')
Traceback (most recent call last):
  ...[redacted]...
  ...[redacted]...
  ...[redacted]...
ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate in certificate chain (_ssl.c:997)
...[redacted]... - CONNECT init.push.apple.com:443 - 0 bytes - 892.99 ms

# Guía para desarrolladores de plugins y colaboradores

## Arquitectura de alto nivel```console
                        +-------------+
                        |             |
                        |  Proxy([])  |
                        |             |
                        +------+------+
                               |
                               |
                   +-----------v--------------+
                   |                          |
                   |    AcceptorPool(...)     |
                   |                          |
                   +------------+-------------+
                                |
+-----------------+             |           +-----------------+
|                 |             |           |                 |
|   Acceptor(..)  <-------------+----------->  Acceptor(..)   |
|                 |                         |                 |
+---+-------------+                         +---------+-------+
    |                                                 |
    |                                                 |
    |    +------++------++------++------++------+     |
    |    |      ||      ||      ||      ||      |     |
    +---->      ||      ||      ||      ||      <-----+
         |      ||      ||      ||      ||      |
         +------++------++------++------++------+
                Threadless Worker Processes

# Banderas```console
❯ proxy -h
usage: -m [-h] [--tunnel-hostname TUNNEL_HOSTNAME] [--tunnel-port TUNNEL_PORT]
          [--tunnel-username TUNNEL_USERNAME]
          [--tunnel-ssh-key TUNNEL_SSH_KEY]
          [--tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE]
          [--tunnel-remote-port TUNNEL_REMOTE_PORT] [--threadless]
          [--threaded] [--num-workers NUM_WORKERS] [--enable-events]
          [--inactive-conn-cleanup-timeout INACTIVE_CONN_CLEANUP_TIMEOUT]
          [--enable-proxy-protocol] [--enable-conn-pool] [--key-file KEY_FILE]
          [--cert-file CERT_FILE] [--client-recvbuf-size CLIENT_RECVBUF_SIZE]
          [--server-recvbuf-size SERVER_RECVBUF_SIZE]
          [--max-sendbuf-size MAX_SENDBUF_SIZE] [--timeout TIMEOUT]
          [--local-executor LOCAL_EXECUTOR] [--backlog BACKLOG]
          [--hostname HOSTNAME] [--hostnames HOSTNAMES [HOSTNAMES ...]]
          [--port PORT] [--ports PORTS [PORTS ...]] [--port-file PORT_FILE]
          [--unix-socket-path UNIX_SOCKET_PATH]
          [--num-acceptors NUM_ACCEPTORS] [--version] [--log-level LOG_LEVEL]
          [--log-file LOG_FILE] [--log-format LOG_FORMAT]
          [--open-file-limit OPEN_FILE_LIMIT]
          [--plugins PLUGINS [PLUGINS ...]] [--enable-dashboard]
          [--basic-auth BASIC_AUTH] [--enable-ssh-tunnel]
          [--work-klass WORK_KLASS] [--pid-file PID_FILE] [--openssl OPENSSL]
          [--data-dir DATA_DIR] [--ssh-listener-klass SSH_LISTENER_KLASS]
          [--disable-http-proxy] [--disable-headers DISABLE_HEADERS]
          [--ca-key-file CA_KEY_FILE] [--insecure-tls-interception]
          [--ca-cert-dir CA_CERT_DIR] [--ca-cert-file CA_CERT_FILE]
          [--ca-file CA_FILE] [--ca-signing-key-file CA_SIGNING_KEY_FILE]
          [--auth-plugin AUTH_PLUGIN] [--cache-requests]
          [--cache-by-content-type] [--cache-dir CACHE_DIR]
          [--proxy-pool PROXY_POOL] [--enable-web-server]
          [--enable-static-server] [--static-server-dir STATIC_SERVER_DIR]
          [--min-compression-length MIN_COMPRESSION_LENGTH]
          [--enable-reverse-proxy] [--rewrite-host-header] [--enable-metrics]
          [--metrics-path METRICS_PATH] [--pac-file PAC_FILE]
          [--pac-file-url-path PAC_FILE_URL_PATH]
          [--cloudflare-dns-mode CLOUDFLARE_DNS_MODE]
          [--filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS]
          [--filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE]
          [--filtered-client-ips FILTERED_CLIENT_IPS]
          [--filtered-url-regex-config FILTERED_URL_REGEX_CONFIG]

proxy.py v2.4.8.dev8+gc703edac.d20241013

options:
  -h, --help            show this help message and exit
  --tunnel-hostname TUNNEL_HOSTNAME
                        Default: None. Remote hostname or IP address to which
                        SSH tunnel will be established.
  --tunnel-port TUNNEL_PORT
                        Default: 22. SSH port of the remote host.
  --tunnel-username TUNNEL_USERNAME
                        Default: None. Username to use for establishing SSH
                        tunnel.
  --tunnel-ssh-key TUNNEL_SSH_KEY
                        Default: None. Private key path in pem format
  --tunnel-ssh-key-passphrase TUNNEL_SSH_KEY_PASSPHRASE
                        Default: None. Private key passphrase
  --tunnel-remote-port TUNNEL_REMOTE_PORT
                        Default: 8899. Remote port which will be forwarded
                        locally for proxy.
  --threadless          Default: True. Enabled by default on Python 3.8+ (mac,
                        linux). When disabled a new thread is spawned to
                        handle each client connection.
  --threaded            Default: False. Disabled by default on Python < 3.8
                        and windows. When enabled a new thread is spawned to
                        handle each client connection.
  --num-workers NUM_WORKERS
                        Defaults to number of CPU cores.
  --enable-events       Default: False. Enables core to dispatch lifecycle
                        events. Plugins can be used to subscribe for core
                        events.
  --inactive-conn-cleanup-timeout INACTIVE_CONN_CLEANUP_TIMEOUT
                        Time after which inactive works must be cleaned up.
                        Increase this value if your backend services are slow
                        to response or when proxy.py is handling a high
                        volume. When running proxy.py on Google Cloud (GCP)
                        you may see 'backend_connection_closed_before_data_sen
                        t_to_client', with curl clients you may see 'Empty
                        reply from server' error when '--inactive-conn-
                        cleanup-timeout' value is low for your use-case.
                        Default 1 seconds
  --enable-proxy-protocol
                        Default: False. If used, will enable proxy protocol.
                        Only version 1 is currently supported.
  --enable-conn-pool    Default: False. (WIP) Enable upstream connection
                        pooling.
  --key-file KEY_FILE   Default: None. Server key file to enable end-to-end
                        TLS encryption with clients. If used, must also pass
                        --cert-file.
  --cert-file CERT_FILE
                        Default: None. Server certificate to enable end-to-end
                        TLS encryption with clients. If used, must also pass
                        --key-file.
  --client-recvbuf-size CLIENT_RECVBUF_SIZE
                        Default: 128 KB. Maximum amount of data received from
                        the client in a single recv() operation.
  --server-recvbuf-size SERVER_RECVBUF_SIZE
                        Default: 128 KB. Maximum amount of data received from
                        the server in a single recv() operation.
  --max-sendbuf-size MAX_SENDBUF_SIZE
                        Default: 64 KB. Maximum amount of data to flush in a
                        single send() operation.
  --timeout TIMEOUT     Default: 10.0. Number of seconds after which an
                        inactive connection must be dropped. Inactivity is
                        defined by no data sent or received by the client.
  --local-executor LOCAL_EXECUTOR
                        Default: 1. Enabled by default. Use 0 to disable. When
                        enabled acceptors will make use of local (same
                        process) executor instead of distributing load across
                        remote (other process) executors. Enable this option
                        to achieve CPU affinity between acceptors and
                        executors, instead of using underlying OS kernel
                        scheduling algorithm.
  --backlog BACKLOG     Default: 100. Maximum number of pending connections to
                        proxy server.
  --hostname HOSTNAME   Default: 127.0.0.1. Server IP address.
  --hostnames HOSTNAMES [HOSTNAMES ...]
                        Default: None. Additional IP addresses to listen on.
  --port PORT           Default: 8899. Server port. To listen on more ports,
                        pass them using --ports flag.
  --ports PORTS [PORTS ...]
                        Default: None. Additional ports to listen on.
  --port-file PORT_FILE
                        Default: None. Save server port numbers. Useful when
                        using --port=0 ephemeral mode.
  --unix-socket-path UNIX_SOCKET_PATH
                        Default: None. Unix socket path to use. When provided
                        --host and --port flags are ignored
  --num-acceptors NUM_ACCEPTORS
                        Defaults to number of CPU cores.
  --version, -v         Prints proxy.py version.
  --log-level LOG_LEVEL
                        Valid options: DEBUG, INFO (default), WARNING, ERROR,
                        CRITICAL. Both upper and lowercase values are allowed.
                        You may also simply use the leading character e.g.
                        --log-level d
  --log-file LOG_FILE   Default: sys.stdout. Log file destination.
  --log-format LOG_FORMAT
                        Log format for Python logger.
  --open-file-limit OPEN_FILE_LIMIT
                        Default: 1024. Maximum number of files (TCP
                        connections) that proxy.py can open concurrently.
  --plugins PLUGINS [PLUGINS ...]
                        Comma separated plugins. You may use --plugins flag
                        multiple times.
  --enable-dashboard    Default: False. Enables proxy.py dashboard.
  --basic-auth BASIC_AUTH
                        Default: No authentication. Specify colon separated
                        user:password to enable basic authentication.
  --enable-ssh-tunnel   Default: False. Enable SSH tunnel.
  --work-klass WORK_KLASS
                        Default: proxy.http.HttpProtocolHandler. Work klass to
                        use for work execution.
  --pid-file PID_FILE   Default: None. Save "parent" process ID to a file.
  --openssl OPENSSL     Default: openssl. Path to openssl binary. By default,
                        assumption is that openssl is in your PATH.
  --data-dir DATA_DIR   Default: ~/.proxypy. Path to proxypy data directory.
  --ssh-listener-klass SSH_LISTENER_KLASS
                        Default: proxy.core.ssh.listener.SshTunnelListener. An
                        implementation of BaseSshTunnelListener
  --disable-http-proxy  Default: False. Whether to disable
                        proxy.HttpProxyPlugin.
  --disable-headers DISABLE_HEADERS
                        Default: None. Comma separated list of headers to
                        remove before dispatching client request to upstream
                        server.
  --ca-key-file CA_KEY_FILE
                        Default: None. CA key to use for signing dynamically
                        generated HTTPS certificates. If used, must also pass
                        --ca-cert-file and --ca-signing-key-file
  --insecure-tls-interception
                        Default: False. Disables certificate verification
  --ca-cert-dir CA_CERT_DIR
                        Default: ~/.proxy/certificates. Directory to store
                        dynamically generated certificates. Also see --ca-key-
                        file, --ca-cert-file and --ca-signing-key-file
  --ca-cert-file CA_CERT_FILE
                        Default: None. Signing certificate to use for signing
                        dynamically generated HTTPS certificates. If used,
                        must also pass --ca-key-file and --ca-signing-key-file
  --ca-file CA_FILE     Default: /Users/abhinavsingh/Dev/proxy.py/.venv3122/li
                        b/python3.12/site-packages/certifi/cacert.pem. Provide
                        path to custom CA bundle for peer certificate
                        verification
  --ca-signing-key-file CA_SIGNING_KEY_FILE
                        Default: None. CA signing key to use for dynamic
                        generation of HTTPS certificates. If used, must also
                        pass --ca-key-file and --ca-cert-file
  --auth-plugin AUTH_PLUGIN
                        Default: proxy.http.proxy.auth.AuthPlugin. Auth plugin
                        to use instead of default basic auth plugin.
  --cache-requests      Default: False. Whether to also write request packets
                        in the cache file.
  --cache-by-content-type
                        Default: False. Whether to extract content by type
                        from responses. Extracted content type is written to
                        the cache directory e.g. video.mp4.
  --cache-dir CACHE_DIR
                        Default: /Users/abhinavsingh/.proxy/cache. Flag only
                        applicable when cache plugin is used with on-disk
                        storage.
  --proxy-pool PROXY_POOL
                        List of upstream proxies to use in the pool
  --enable-web-server   Default: False. Whether to enable
                        proxy.HttpWebServerPlugin.
  --enable-static-server
                        Default: False. Enable inbuilt static file server.
                        Optionally, also use --static-server-dir to serve
                        static content from custom directory. By default,
                        static file server serves out of installed proxy.py
                        python module folder.
  --static-server-dir STATIC_SERVER_DIR
                        Default: "public" folder in directory where proxy.py
                        is placed. This option is only applicable when static
                        server is also enabled. See --enable-static-server.
  --min-compression-length MIN_COMPRESSION_LENGTH
                        Default: 20 bytes. Sets the minimum length of a
                        response that will be compressed (gzipped).
  --enable-reverse-proxy
                        Default: False. Whether to enable reverse proxy core.
  --rewrite-host-header
                        Default: False. If used, reverse proxy server will
                        rewrite Host header field before sending to upstream.
  --enable-metrics      Default: False. Enables metrics.
  --metrics-path METRICS_PATH
                        Default: /metrics. Web server path to serve proxy.py
                        metrics.
  --pac-file PAC_FILE   A file (Proxy Auto Configuration) or string to serve
                        when the server receives a direct file request. Using
                        this option enables proxy.HttpWebServerPlugin.
  --pac-file-url-path PAC_FILE_URL_PATH
                        Default: /. Web server path to serve the PAC file.
  --cloudflare-dns-mode CLOUDFLARE_DNS_MODE
                        Default: security. Either "security" (for malware
                        protection) or "family" (for malware and adult content
                        protection)
  --filtered-upstream-hosts FILTERED_UPSTREAM_HOSTS
                        Default: Blocks Facebook. Comma separated list of IPv4
                        and IPv6 addresses.
  --filtered-client-ips-mode FILTERED_CLIENT_IPS_MODE
                        Default: blacklist. Can be either "whitelist"
                        (restrict access to specific IPs)or "blacklist" (allow
                        everything except specific IPs).
  --filtered-client-ips FILTERED_CLIENT_IPS
                        Default: 127.0.0.1,::1. Comma separated list of IPv4
                        and IPv6 addresses.
  --filtered-url-regex-config FILTERED_URL_REGEX_CONFIG
                        Default: No config. Comma separated list of IPv4 and
                        IPv6 addresses.

Proxy.py not working? Report at:
https://github.com/abhinavsingh/proxy.py/issues/new