backend/   FastAPI, MongoDB, mitmdump manager
frontend/  Vue 3, Vite, CodeMirror + Python LSP
playground/ servizio locale minimale per test end-to-end

Setup rapido

./setup.sh

Lo script crea backend/.env, genera le credenziali mancanti e avvia lo stack Docker completo:

Frontend  http://localhost:5173
Backend   http://localhost:3671

Questa modalità è buona per smoke test UI/API. Se vuoi provare davvero il takeover della porta di un servizio Docker locale, fai girare il backend sulla macchina host.

Guida completa: TESTING.md

Per installare anche il servizio systemd user:

./setup.sh service

Dev backend

cp backend/.env.example backend/.env
docker compose --env-file backend/.env up -d mongodb
npm run dev:backend

Docs FastAPI in dev: http://localhost:3671/docs.

Test locale realistico

Per simulare il deployment reale, usa il backend sulla macchina host:

./setup.sh deps
export SERVICE_SCAN_ROOT="$PWD"
npm run dev:backend
npm run dev:frontend
./setup.sh playground

Poi:

Apri http://localhost:5173.
Fai login con le credenziali in backend/.env.
Crea un nuovo proxy.
Seleziona il servizio echo rilevato dal backend sotto la cartella playground.
Lascia mode=reverse.
Verifica che proxy_port combaci con la porta del servizio (9081) se vuoi che il proxy prenda davvero il posto della route originale.
Salva e premi Start.
Esegui curl http://127.0.0.1:9081/.

Se il proxy è attivo, la route originale è ora posseduta da mitmdump e il servizio reale è stato spostato su una porta upstream temporanea, visibile nella UI e nello stato runtime.

SERVICE_SCAN_ROOT controls where the backend looks for services. The scan is intentionally shallow: it inspects only the immediate child directories of that root, which matches the expected host layout.

Dev frontend

cd frontend
npm install
npm run dev

Il dev server usa /api come proxy verso http://127.0.0.1:3671.

Test

npm run test

Equivalente a:

cd backend && uv run ruff check . && uv run pytest
cd frontend && npm run build

Per testare solo il playground:

npm run playground:up
npm run playground:down

API principali

POST /auth/login
POST /auth/logout
GET /proxy
POST /proxy
POST /proxy/{port}/start
POST /proxy/{port}/stop
POST /proxy/{port}/restart
GET /proxy/{port}/health
GET /proxy/{port}/logs
WS /proxy/{port}/logs/ws
GET /proxy/mitmproxy/options
GET /proxy/mitmproxy/examples

Riferimenti

Mitmproxy addons: https://docs.mitmproxy.org/stable/addons/examples/
Mitmproxy modes: https://docs.mitmproxy.org/stable/concepts/modes/
Mitmproxy options: https://docs.mitmproxy.org/stable/concepts/options/