2 Funzionamento

⚙️ Capitolo 2: Architettura e Funzionamento (Sotto il cofano)

Il funzionamento del motore Panzer v7 si basa su tre pilastri architetturali rigidi progettati per la massima resilienza.

Note

La profilazione dinamica della rete si aggiorna a ogni singola richiesta dell'utente, ricalcolando i parametri di timeout in background senza bloccare il thread principale della PWA.

Warning

In caso di fallimento del test crittografico sul Canary Data ("KANARY"), il Service Worker attiverà la routine distruttiva immediata, cancellando l'intero IndexedDB per prevenire violazioni di tipo Cache Poisoning.

---

🌐 1. Scope Globale (sw.js nella Root)

Il file del Service Worker (sw.js) è posizionato chirurgicamente nella cartella radice (root) del dominio tramite la costante CONFIG.ROOT (derivata dinamicamente da self.location.pathname). Questo permette al software di intercettare ogni singola richiesta di rete dell'intera applicazione, agendo come un proxy locale installato nel browser dell'utente.

---

⚡ 2. Strategia di Fetch: Network-First con Profilazione Dinamica e Autorigenerazione

Il motore adotta un algoritmo avanzato di tolleranza ai guasti di rete per scongiurare il blocco dell'interfaccia in caso di connettività degradata (fenomeno della "Lie-Fi"), orchestrato dai parametri configurati in CONFIG.networkResilient:

🔹Profilazione Dinamica della Rete (`getNetworkProfile`):

Il sistema non si limita a verificare lo stato online/offline. Calcola in tempo reale un punteggio di efficienza basato sui parametri `navigator.connection` (downlink e RTT), mappando dinamicamente i limiti estratti dall'oggetto `CONFIG.networkResilient.profiles` secondo la tabella sottostante:

Profilo Rete	Limite Download Simultanei (limit)	Timeout di Connessione (timeout)	Comportamento Bunker
Ultrafast	12 file	15 secondi	Sincronizzazione aggressiva
Fast	8 file	20 secondi	Sincronizzazione standard
Medium	4 file	45 secondi	Sincronizzazione standard
Low	2 file	90 secondi	Controllo HEAD esteso
Verylow	1 file	120 secondi	Blocco preventivo del Sync

🔹Network-First con Race Condition:

Ogni richiesta dinamica intercetta la rete per garantire la massima freschezza del dato, applicando i secondi di `timeout` definiti dal profilo di rete attivo all'interno di `CONFIG.networkResilient.profiles`. Se la rete fallisce, il sistema effettua fino a un massimo di `CONFIG.networkResilient.maxRetries` tentativi distanziati da `CONFIG.networkResilient.timeWaitSec` secondi.

🔹Cache Fallback & Hot Update:

In caso di timeout o fallimento dei tentativi, il Service Worker rilascia immediatamente la risorsa locale memorizzata nel Bunker. Se invece la rete risponde entro i limiti, il sistema aggiorna la cache in background (Hot Update).

🔹Radar degli Aggiornamenti (`ver_site`):

Il sistema monitora le variazioni dell'HTML principale tracciando la versione globale. Se viene rilevato un disallineamento di versione, il Service Worker esegue autonomamente una tabula rasa delle vecchie cache per prevenire conflitti logici o disallineamenti tra i moduli core.

---

🔄 3. Ciclo di Sincronizzazione Intelligente (sync)

Quando il sistema rileva il ripristino della connettività o riceve un evento di sincronizzazione, si attiva la logica di popolamento/allineamento controllata:

🔹Controllo dei Vincoli del Profilo:

Il motore interroga `getNetworkProfile`. Se il profilo è *Verylow*, il ciclo impone un blocco preventivo (`syncAbortController.abort()`) per non saturare la banda degradata dell'utente.

🔹Download in Parallelo Limitato:

Se il profilo lo consente, il motore avvia lo scaricamento delle risorse core rispettando rigorosamente il tetto massimo di file simultanei (`limit`) definito per quel profilo, evitando crash del browser o congestioni di rete.

---

🔍 4. Validazione Strict via SW Forensics (isValidBlob)

Per evitare attacchi informatici (come il Cache Poisoning), pagine di login di hotspot Wi-Fi (captive portal) o file corrotti, ogni risorsa subisce una validazione rigorosa prima dell'ingresso nello storage:

🔹Controllo Dimensionale:

Verifica della dimensione minima del file iniettando come sbarramento la mappa delle specifiche interne definita in `CONFIG.minSizeMap`.

🔹Firma Magica (DNA del File):

Analisi dei primi byte binari (i *Magic Numbers*) per verificare la reale identità e integrità del dato prima di elaborarlo, rifiutando file con estensioni falsificate.

---

📦 Gestione dei Magazzini e della Memoria (Crittografia AES-GCM)

Il sistema opera una separazione netta dello storage logico, tracciato nei log di console con marcatori specifici e protetto da cifratura hardware-assisted:

🔹`📦🛡 (Bunker)` (mappato in `CONFIG.cacheName`

Area protetta e isolata per gli asset Core + Manifest asset, di sistema. Se lo sblocco del Vault ha esito positivo, le risorse destinate a questa stiva subiscono una cifratura simmetrica AES-GCM a 256 bit. In fase di lettura offline, il Service Worker estrae l'ArrayBuffer, esegue la decrittazione al volo via Web Crypto API e serve la risorsa iniettando l'header personalizzato `X-PWA-Source: Bunker-Decrypted`.

🔹`📦🔓 (Magazzino)` (mappato in `CONFIG.userCacheName`

Area sussidiaria per le risorse utente dinamiche, volatili e non cifrate, vincolate a una data di scadenza controllata dal Time-To-Live definito in `CONFIG.userCacheTTL` (pari a 7 giorni).

pie title Allocazione Logica dello Storage nel Client
    "📦🛡️ CONFIG.cacheName (Bunker Core - Cifrato AES-GCM)" : 45
    "📦🔓 CONFIG.userCacheName (Magazzino Asset Volatili - TTL 7d)" : 35
    "🚨 Buffer di Sicurezza (QuotaExceededError Emergency Reserve)" : 20

Loading

---

🧬 Routine di Factory Reset, Messaggistica Frontend e Re-Installazione Totale (Canary Check)

Il motore implementa una logica di tolleranza ai guasti di tipo distruttivo-rigenerativo sincronizzata con l'interfaccia utente:

🔹Canary Vault Check (`deepVaultValidation`):

All'attivazione del Service Worker, viene eseguito un test crittografico di controllo sul vettore statico binario (Canary Data). Se l'operazione fallisce o le chiavi logiche risultano manomesse, il sistema solleva un blocco di sicurezza immediato (`ACTIVATION_ABORTED_SECURITY_BREACH`) ed esegue un wipe preventivo dell'IndexedDB `PWA_Vault`.

🔹Tabula Rasa Immediata:

Se il database del Vault o le chiavi logiche in IndexedDB risultano corrotti durante i cicli operativi, il Service Worker cancella istantaneamente tutte le istanze di cache attive legate a `CONFIG.cacheName` e `CONFIG.userCacheName`.

🔹Notifica di Emergenza via postMessage:

Il Service Worker invia immediatamente un segnale di notifica broadcast a tutte le finestre aperte del frontend per segnalare lo stato di emergenza.

🔹Forzatura del Refresh e Re-Installazione:

Il frontend forza un ricaricamento immediato. Se l'applicazione si satura o solleva un `QuotaExceededError`, si attiva la routine d'emergenza **`🚨 SW: Storage Pieno! Emergency Clean...`** che avvia la pulizia automatica del magazzino volatile (`CONFIG.userCacheName`) per salvaguardare i file vitali custoditi nel Bunker di sistema (`CONFIG.cacheName`).

In assenza dei prerequisiti minimi di sicurezza o delle chiavi logiche in IndexedDB, il sistema si isola in modalità protetta (VAULT_LOCKED_NO_KEY), restituendo risposte di errore o intercettando i file multimediali mancanti per sostituirli con il fallback binario configurato in CONFIG.fallbackImage.

graph LR
    A[Avvio PWA / SW] --> B(deepVaultValidation)
    B --> C{Canary Check: KANARY}
    
    C -->|VALIDATO| D[Vault Sbloccato]
    D --> E[Erogazione e Decrittazione AES-GCM]
    
    C -->|FALLITO / MANOMESSO| F[🚨 SECURITY BREACH]
    F --> G[Wipe di PWA_Vault & Caches]
    G --> H[postMessage Broadcast ai Frontend]
    H --> I[Forzatura Refresh / Re-Installazione Totale]
    I --> J[Riscaricamento Asset Puliti dal Server]

    style D fill:#70ad47,stroke:#fff,color:#fff
    style F fill:#c00000,stroke:#fff,color:#fff
    style G fill:#ffc000,stroke:#000,color:#000

Loading

---

🛠️ Diagramma Globale (Fetch & Sync Engine)

graph TD
    subgraph FLUSSO_FETCH [1. Evento Fetch: Gestione Richieste Client]
        A[Richiesta Utente / Browser] --> B[Proxy SW CONFIG.ROOT]
        B --> C[getNetworkProfile]
        C -->|Rete Rilevata| D{checkRealOnline: C'È RETE?}
        
        D -->|SÌ| E[Fetch con Timeout e Retries]
        E -->|Risposta Server OK| F[RILASCIO IMMEDIATO al Frontend]
        E -->|Risposta Server OK| G[Operazione Asincrona in BACKGROUND]
        
        G --> H_async{isValidBlob Check via CONFIG.minSizeMap}
        H_async -->|Superato| I{shouldBeEncrypted: Asset Core?}
        I -->|SÌ| J[Cifratura AES-GCM + Salva in CONFIG.cacheName 📦🛡️]
        I -->|NO| K[Salva in CONFIG.userCacheName 📦🔓]
        H_async -->|Fallito/Corrotto| L[Ignora Risposta / Non Salvare]

        D -->|NO / Timeout Rete / 404| M[Bunker Mode Fallback]
        M --> N{Match in Cache trovato?}
        N -->|SÌ| O{X-PWA-Encrypted == true?}
        O -->|SÌ| P[verifyVaultIntegrity + decryptBuffer]
        P -->|Successo| Q[Rilascia file decifrato Bunker-Decrypted]
        P -->|Errore/Manomissione| R[Wipe CONFIG.cacheName & CONFIG.userCacheName]
        O -->|NO| S[Rilascia file in chiaro da CONFIG.userCacheName]
        N -->|NO| T{Richiesta Immagine o HTML?}
        T -->|SÌ| U[Eroga CONFIG.fallbackImage o Error Page 503]
        T -->|NO| V[Ritorna Errore Plain Text Offline 503]
    end

    subgraph FLUSSO_SYNC [2. Evento Sync: Allineamento e Pre-Cache]
        X[Trigger Event: sync / Connessione Ripristinata] --> Y[getNetworkProfile]
        Y --> Z{Profilo == Verylow?}
        Z -->|SÌ| AA[syncAbortController.abort: Blocco Preventivo Sync]
        Z -->|NO| AB[Estrae limiti e parallelizzazione download]
        AB --> AC[Download asincrono controllato dei file core]
        AC --> H_async
    end

    style B fill:#1f4e79,stroke:#fff,stroke-width:2px,color:#fff
    style F fill:#2e75b6,stroke:#fff,stroke-width:2px,color:#fff
    style G fill:#7f7f7f,stroke:#fff,stroke-width:1px,stroke-dasharray: 5 5,color:#fff
    style M fill:#c00000,stroke:#fff,stroke-width:2px,color:#fff
    style AA fill:#a5a5a5,stroke:#000,stroke-width:1px,color:#000
    style J fill:#70ad47,stroke:#fff,stroke-width:1px,color:#fff

Loading

↩ Torna alla Home