thePlug/TESTING.md

# Testing Guide

Questa guida descrive come preparare e testare `thePlug` in tre scenari:

1. laptop con backend sulla macchina host
2. laptop con stack tutto Dockerizzato
3. vulnbox reale con backend fuori Docker

L’obiettivo non è solo far partire UI e API, ma verificare il comportamento
reale del proxy: remap della porta del servizio, avvio di `mitmdump`,
healthcheck e ripristino su `Stop`.

## Concetti Chiave

### Cosa fa `Save`

`Save` salva solo la configurazione del proxy nel backend. Non tocca:

- porte del servizio reale
- processi `mitmdump`
- Docker Compose

### Cosa fa `Start`

In `reverse` mode, se il proxy è associato a un servizio Docker Compose e
`mode_spec` non è impostato:

1. il backend sposta la porta pubblica del servizio reale su una porta libera
2. salva quella nuova porta come upstream live
3. avvia `mitmdump` sulla porta originale

Quindi, se vuoi che il proxy prenda davvero il posto del servizio originale,
`proxy_port` deve coincidere con la porta pubblica del servizio.

### Come vengono scoperti i servizi

Il backend cerca i servizi Docker Compose sotto una root di scansione:

- di default: `HOME`
- override: `SERVICE_SCAN_ROOT`

La scansione è volutamente shallow:

- il backend guarda solo le cartelle immediate sotto la root
- non scende ricorsivamente in profondità

Questa scelta riflette il layout atteso sulla macchina reale.

Esempio valido:

```text
/home/user/service-a/docker-compose.yml
/home/user/service-b/docker-compose.yml
```

Esempio non visto se la root è `/home/user`:

```text
/home/user/projects/lab/service-a/docker-compose.yml
```

In quel caso devi cambiare `SERVICE_SCAN_ROOT`.

## Prerequisiti

Su tutte le macchine:

- `docker`
- `docker compose`
- `uv`
- `python 3.14`
- `node 22`

Il backend installerà anche:

- `mitmproxy`
- `basedpyright`

Porte usate tipicamente:

- `3671` backend
- `5173` frontend
- `27017` mongodb
- `6379` redis
- una o più porte proxy/test

## Scenario 1: Laptop con Backend sulla Macchina Host

Questo è il setup migliore per testare davvero il comportamento del proxy.

### Quando usarlo

Usa questo scenario se vuoi verificare:

- discovery servizi
- remap porta Docker Compose
- takeover reale della porta pubblica
- start/stop/restart di `mitmdump`
- esempi script e editor

### Preparazione

Dalla root del progetto:

```bash
cd /home/gabdevele/CTF/thePlug
./setup.sh deps
export SERVICE_SCAN_ROOT="$PWD"
./setup.sh playground
```

Questo fa due cose:

- avvia solo `mongodb` e `redis` in Docker
- avvia un piccolo upstream locale in `playground/`

Il playground espone:

```text
http://127.0.0.1:9081
```

### Avvio applicazione

In un terminale:

```bash
cd /home/gabdevele/CTF/thePlug
npm run dev:backend
```

In un secondo terminale:

```bash
cd /home/gabdevele/CTF/thePlug
npm run dev:frontend
```

### Login

Le credenziali sono in:

- [backend/.env](/home/gabdevele/CTF/thePlug/backend/.env)

Apri:

```text
http://localhost:5173
```

### Test End-to-End Consigliato

1. Crea un nuovo proxy.
2. Seleziona il servizio `echo` rilevato dal backend.
3. Lascia `mode=reverse`.
4. Verifica che `proxy_port=9081`.
5. Salva.
6. Premi `Start`.
7. Esegui:

```bash
curl -i http://127.0.0.1:9081/
```

### Cosa devi vedere

Prima di `Start`:

- `9081` risponde direttamente il servizio playground

Dopo `Start`:

- `mitmdump` è in ascolto su `9081`
- il servizio reale è stato spostato su una porta upstream temporanea
- la UI mostra il live upstream cambiato
- i log del proxy iniziano a popolarsi

Dopo `Stop`:

- la porta pubblica originaria torna al servizio reale
- `service.upstream_port` torna `null`

### Verifiche Utili

Controlla i servizi rilevati:

```bash
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/services
```

Controlla i log proxy dalla UI o via API:

```bash
curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:3671/proxy/9081/logs
```

### Cleanup

```bash
npm run playground:down
docker compose --env-file backend/.env -f docker-compose.yml down
```

## Scenario 2: Laptop con Stack Tutto Dockerizzato

Questo scenario è adatto soprattutto a smoke test applicativi.

### Quando usarlo

Usalo per verificare:

- login/logout
- CRUD proxy
- examples
- options
- persistenza Mongo/Redis
- build frontend e wiring API

### Avvio

```bash
cd /home/gabdevele/CTF/thePlug
./setup.sh
```

Apri:

- frontend: `http://localhost:5173`
- backend: `http://localhost:3671`

### Cosa testare qui

Puoi testare bene:

- creazione proxy
- update/delete
- validazione codice
- examples custom
- health endpoint
- editor e autocomplete

### Limite importante

Questo non è il setup migliore per validare il takeover reale delle porte di un
servizio locale, perché il backend è dentro Docker e non replica la topologia
host-native del deployment reale.

Quindi:

- bene per smoke test UI/API
- non abbastanza per validare il flusso finale di orchestration

Per il test realistico del proxy usa lo Scenario 1.

### Spegnimento

```bash
docker compose --env-file backend/.env -f docker-compose.yml down
```

## Scenario 3: Vulnbox Reale con Backend fuori Docker

Questo è il modello più vicino al deployment reale.

### Layout atteso dei servizi

Caso ideale sotto `HOME`:

```text
/home/user/service-a/docker-compose.yml
/home/user/service-b/docker-compose.yml
/home/user/service-c/docker-compose.yml
```

Se il layout è diverso, imposta `SERVICE_SCAN_ROOT`.

### Preparazione backend

```bash
cd /path/to/thePlug
cp backend/.env.example backend/.env
./setup.sh deps
```

Se i servizi non sono sotto `HOME`:

```bash
export SERVICE_SCAN_ROOT="/path/che/contiene/le/cartelle-servizio"
```

### Avvio backend

```bash
cd /path/to/thePlug
npm run dev:backend
```

### Avvio frontend

In sviluppo:

```bash
cd /path/to/thePlug
npm run dev:frontend
```

Oppure build statico:

```bash
cd /path/to/thePlug/frontend
VITE_API_BASE_URL=http://IP_O_HOST:3671 npm run build
```

### Test operativo reale

1. Apri la UI.
2. Seleziona un servizio reale scoperto dal backend.
3. Se vuoi takeover vero della porta pubblica:
   `proxy_port` deve essere uguale alla porta pubblica del servizio.
4. Salva.
5. Premi `Start`.
6. Verifica da terminale o con la tua applicazione client che il traffico passi
   ancora sulla porta originale.

### Cosa aspettarsi

Su `Start`:

- il servizio reale viene spostato su una porta temporanea
- `mitmdump` si lega alla porta originaria
- il traffico continua a entrare dalla porta originale
- la UI mostra il nuovo live upstream

Su `Stop`:

- la porta originaria torna al servizio reale
- il proxy viene fermato

## Failure Modes Comuni

### Il backend non trova nessun servizio

Controlla:

- valore di `SERVICE_SCAN_ROOT`
- che i compose siano nelle cartelle immediate sotto quella root
- che i file si chiamino uno tra:
  - `compose.yml`
  - `compose.yaml`
  - `docker-compose.yml`
  - `docker-compose.yaml`

### Il proxy parte ma non prende il posto del servizio

Controlla:

- `mode=reverse`
- `mode_spec` vuoto
- `proxy_port` uguale alla porta del servizio
- servizio selezionato dalla UI correttamente

### `Start` fallisce

Controlla:

- `mitmdump` disponibile nel backend host
- conflitti di porta
- errori di sintassi nello script
- log del proxy

### Il frontend mostra session expired

Vuol dire che il token JWT è scaduto o non è più valido. Fai login di nuovo.

## Comandi Utili

Test backend:

```bash
cd backend
uv run ruff check .
uv run pytest
```

Build frontend:

```bash
cd frontend
npm run build
```

Avvio playground:

```bash
./setup.sh playground
```

Solo dipendenze backend per test host:

```bash
./setup.sh deps
```

## Raccomandazione Finale

Per lavorare in modo efficiente:

- usa `./setup.sh` per smoke test rapidi
- usa `backend host + frontend dev + playground` per il test vero del proxy
- usa `backend host` sulla vulnbox reale per validare il comportamento finale

Se devi testare davvero il remap porta, considera valido solo un setup con
backend fuori Docker.