# Chrome Remote Server

Server Node.js per la gestione intelligente delle sessioni Chrome Remote per il progetto di accessibilità.

## 🎯 Funzionalità

- **Pool di istanze Chrome**: Gestisce fino a 10 istanze Chrome simultanee
- **Riutilizzo profili**: Clona il profilo master solo quando necessario
- **API REST**: Interfaccia semplice per richiedere/rilasciare sessioni
- **Auto-cleanup**: Gestione automatica della terminazione dei processi
- **Health monitoring**: Endpoint per monitorare lo stato del server

## 🚀 Installazione

```bash
cd chrome-remote-server
npm install
```

## 📋 Configurazione

Il server utilizza le seguenti configurazioni (modificabili tramite variabili d'ambiente):

- **Porta server**: `CHROME_REMOTE_PORT` (default: 9221)
- **Porta base Chrome**: 9222-9231 (10 istanze max)
- **Directory profili**: `../chrome-profiles/`
- **Profilo master**: `../chrome-profiles/remote-chrome`

## 🎮 Utilizzo

### Avvio del server

```bash
# Produzione
npm start

# Sviluppo (con auto-restart)
npm run dev

# Stop del server
npm run stop
```

### API Endpoints

#### 1. Health Check
```bash
GET /health
```
Risposta:
```json
{
  "status": "ok",
  "instances": 2,
  "uptime": 3600,
  "timestamp": "2026-03-04T14:30:00.000Z"
}
```

#### 2. Richiedi Sessione Chrome
```bash
POST /session/request
```
Risposta:
```json
{
  "success": true,
  "session": {
    "sessionId": "uuid-here",
    "endpoint": "ws://localhost:9222/devtools/browser/...",
    "port": 9222,
    "profile": "remote-chrome-1"
  }
}
```

#### 3. Rilascia Sessione
```bash
POST /session/release/:sessionId
```
Risposta:
```json
{
  "success": true,
  "message": "Sessione rilasciata"
}
```

#### 4. Lista Sessioni Attive
```bash
GET /sessions
```
Risposta:
```json
{
  "success": true,
  "sessions": [
    {
      "sessionId": "uuid-here",
      "port": 9222,
      "endpoint": "ws://localhost:9222/...",
      "profile": "remote-chrome-1",
      "pid": 12345,
      "status": "active",
      "createdAt": "2026-03-04T14:00:00.000Z",
      "lastUsed": "2026-03-04T14:30:00.000Z"
    }
  ],
  "total": 1
}
```

#### 5. Cleanup Tutte le Sessioni
```bash
POST /sessions/cleanup
```

## 🏗️ Architettura

### Gestione Profili Chrome

```
chrome-profiles/
├── remote-chrome/          # Profilo MASTER (mai modificato)
├── remote-chrome-1/        # Profilo clonato (riutilizzabile)
├── remote-chrome-2/        # Profilo clonato (riutilizzabile)
└── ...
```

**Logica profili**:
1. Il profilo master `remote-chrome` rimane sempre intatto
2. I profili numerati vengono clonati dal master al primo utilizzo
3. I profili vengono riutilizzati tra sessioni (NO svuotamento)
4. Massimo 10 profili simultanei

### Pool di Porte

- **Range**: 9222-9231 (10 porte)
- **Assegnazione**: Automatica alla prima porta libera
- **Verifica**: Controllo con `lsof` prima dell'assegnazione

### Gestione Processi

- **Spawn**: Ogni Chrome è un processo figlio separato
- **Monitoring**: Tracciamento PID e stato
- **Cleanup**: Terminazione graceful (SIGTERM → SIGKILL)
- **Auto-restart**: Il server sopravvive ai crash di singole istanze

## 🔧 Integrazione Laravel

Il server è progettato per essere integrato con Laravel tramite:

1. **deploy.sh**: Avvio automatico del server
2. **Settings save**: Restart del server quando cambiano le configurazioni
3. **Scanner.js**: Richieste HTTP al server per ottenere sessioni

### Configurazione Settings

Il comportamento del server è controllato dalle seguenti impostazioni Laravel:

- **chrome_remote_connection**: `disabled` | `local` | `remote`
- **chrome_remote_usage**: `always` | `after_failure`
- **chrome_remote_endpoint**: Endpoint del server remoto (usato solo quando `connection` è `remote`)

**⚠️ Nota importante**: Quando `chrome_remote_connection` è impostato su `local`, Laravel userà sempre `http://localhost:9221` indipendentemente dal valore salvato in `chrome_remote_endpoint`. Questo previene problemi con dati sporchi quando si switcha tra modalità local e remote.

### Integrazione Automatica

Il server è completamente integrato nel flusso di scansione Laravel con logica semplificata:

1. **Job Laravel** (`PerformScan`) calcola se usare Chrome Remote Server in base a:
   - `chrome_remote_connection`: `disabled` | `local` | `remote`
   - `chrome_remote_usage`: `always` | `after_failure`
   - Numero di tentativi corrente (`$this->attempts()`)

2. **Se deve usare Chrome Remote**, passa `--remote-endpoint` al comando Artisan

3. **Scanner.js** riceve l'endpoint e lo usa direttamente:
   - Se `--remote-endpoint` è presente (e non headless) → usa Chrome Remote Server
   - Altrimenti → usa Puppeteer standalone

**Vantaggi della logica semplificata:**
- ✅ Tutta la logica decisionale è in PHP (più facile da debuggare)
- ✅ Scanner.js riceve solo l'endpoint finale da usare
- ✅ Nessuna lettura di configurazioni Laravel da Node.js
- ✅ Fallback automatico se Chrome Remote non è disponibile

### Esempio integrazione manuale

```javascript
// Richiedi sessione Chrome
const response = await fetch('http://localhost:9221/session/request', {
    method: 'POST'
});
const { session } = await response.json();

// Usa la sessione
const browser = await puppeteer.connect({
    browserWSEndpoint: session.endpoint
});

// ... logica scansione ...

// Rilascia sessione
await fetch(`http://localhost:9221/session/release/${session.sessionId}`, {
    method: 'POST'
});
```

## 🛠️ Troubleshooting

### Chrome non si avvia
- Verifica che Chrome sia installato
- Controlla i permessi sulla directory `chrome-profiles/`
- Verifica che le porte 9222-9231 siano libere

### Profili corrotti
- Elimina i profili numerati (mantieni solo `remote-chrome`)
- Riavvia il server per rigenerare i profili

### Memoria insufficiente
- Riduci `maxInstances` nel codice
- Monitora l'utilizzo RAM delle istanze Chrome

## 📊 Monitoring

Il server fornisce informazioni dettagliate su:
- Numero istanze attive
- Utilizzo porte
- Stato processi Chrome
- Timestamp creazione/ultimo utilizzo sessioni

Usa `/health` e `/sessions` per monitoraggio automatico.

## 🔒 Sicurezza

- Il server ascolta solo su localhost (non esposto pubblicamente)
- Nessuna autenticazione (sicurezza tramite network isolation)
- Processi Chrome isolati con profili separati
- Cleanup automatico alla terminazione del server