Skip to content

2 Funzionamento

Jump to bottom
Valentino Aglianó edited this page May 31, 2026 · 36 revisions

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

Il funzionamento del motore Panzer v7.3 si basa su cinque sezioni di instradamento rigide e su pilastri di sicurezza progettati per garantire la massima tolleranza ai guasti e la protezione dei dati.

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.
⚠️ Configurazione: getNetworkProfile richiede monitoraggio RTT. Non disabilitare le API di rete.

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

Il file del Service Worker (sw.js) è posizionato 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 gateway o proxy locale installato direttamente all'interno del browser.

⚡ 2. Strategia di Fetch: Profilazione Dinamica e Autorigenerazione a 5 Sezioni

Il motore adotta un algoritmo avanzato per scongiurare il blocco dell'interfaccia in caso di connettività degradata (fenomeno della "Lie-Fi"), orchestrato dai parametri di CONFIG.networkResilient e strutturato in 5 Sezioni operative distinte:

🔹Profilazione Dinamica della Rete (`getNetworkProfile`):
Il sistema non si limita a verificare se il dispositivo è online o offline. Calcola in tempo reale un punteggio di efficienza basato sui parametri hardware di navigator.connection (downlink e RTT), mappando dinamicamente i limiti estratti da CONFIG.networkResilient.profiles:

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 
graph TD
    %% Definizione degli stili visivi per massima leggibilità
    classDef inizio stili,fill:#1f4e79,stroke:#113355,stroke-width:2px,color:#fff;
    classDef sezione stili,fill:#f5f5f5,stroke:#333,stroke-width:2px,color:#000;
    classDef successo stili,fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724;
    classDef recupero stili,fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#856404;
    classDef errore stili,fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#721c24;

    %% FLUSSO DEL COLO DELLE 5 SEZIONI
    A[L'utente clicca o chiede una pagina] --> B(Sezione I: Pulizia del Percorso)
    class A inizio;
    class B sezione;

    B --> C{Sezione II: C'è Internet?}
    class C sezione;

    %% RAMO INTERNET PRESENTE
    C -- Sì, Internet Funziona --> D[Scarica i dati freschi dal Server]
    D --> E[Salva una copia protetta in Cassaforte]
    E --> F[Mostra la pagina aggiornata all'utente]
    class D successo;
    class E successo;
    class F successo;

    %% RAMO INTERNET FALLITO / LIE-FI
    C -- No / Internet Troppo Lento --> G(Sezione III: Fallback in Cassaforte)
    G --> H[Prende la copia cifrata dal database locale]
    H --> I[Decifra i dati in memoria RAM e pulisce le tracce]
    I --> J[Mostra la pagina salvata all'utente]
    class G recupero;
    class H recupero;
    class I recupero;
    class J recupero;

    %% GESTIONE IMMAGINI (SEZIONE IV)
    A --> K(Sezione IV: Controllo Immagini)
    class K sezione;
    
    K --> L{L'immagine principale si carica?}
    class L sezione;
    
    L -- No, errore caricamento --> M{Esiste un'immagine alternativa variata?}
    L -- Sì --> N[Mostra l'immagine originale]
    class N successo;
    
    M -- Sì --> O[Mostra la variante alternativa]
    M -- No --> P[Inietta l'immagine di cortesia standard in Base64]
    class O recupero;
    class P recupero;

    %% AVARIA TOTALE (SEZIONE V)
    J --> Q{Sia Internet che Cassaforte hanno fallito?}
    F --> Q
    class Q sezione;
    
    Q -- Sì, Blocco Totale --> R(Sezione V: Schermata di Cortesia)
    R --> S[Mostra Pagina d'Errore 503 Sterile con bordo rosso]
    class R errore;
    class S errore;
Loading

🔄 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, rispettando il tetto massimo di file simultanei (limit). L'attesa dei download eseguiti a blocchi paralleli, è legata a un dispositivo di sblocco immediato tramite Promise.race competitivo agganciato al segnale di abort. Al minimo comando di annullamento, l'esecuzione si interrompe all'istante, neutralizzando i memory leak e sbloccando i thread su dispositivi mobili datati.

Qualsiasi interruzione lancia un errore controllato (throw) verso un unico catch globale, che si occupa di azzerare in sicurezza lo stato operativo (isSyncing = false). Al termine del ciclo, il sistema espone nei log il conteggio reale e veritiero delle sole risorse effettivamente scaricate ex-novo da rete rispetto a quelle lette dalla cache.

🔍 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. 
graph LR
    classDef gabbia fill:#f5f5f5,stroke:#333,stroke-width:2px;
    classDef ok fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724;
    classDef ko fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#721c24;

    A[File Scaricato da Internet] --> B{Sezione I: Firma Corretta?<br>es. 25504446 per PDF singed}
    class B gabbia;
    
    B -- No, non corrisponde --> C[File Corrotto / Alterato: RIFIUTATO]
    class C ko;
    
    B -- Sì, valida --> D{Sezione II: Peso in Byte<br>supera CONFIG.minSizeMap?}
    class D gabbia;
    
    D -- No, file vuoto --> E[File Vuoto / Errore: RIFIUTATO]
    class E ko;
    
    D -- Sì, superato --> F[DNA Check OK: Ammesso in Cache]
    class F ok;
Loading

📦 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:

Important

➡️ Isolamento della Memoria: Le chiavi crittografiche non sono esportabili (extractable: false) e rimangono isolate nello stato di runtime del worker via Structured Clone API. Tutte le funzioni crittografiche azzerano le tracce in transito: il buffer temporaneo in RAM contenente i dati decrittati viene sovrascritto a 0 tramite il comando .fill(0) subito dopo l'uso, neutralizzando i rischi di Memory Inspection.

🔹📦🛡 (Bunker), (mappato in `CONFIG.cacheName`
Area protetta per i file core e d'infrastruttura dell'applicazione. 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, pulisce la RAM e serve il file 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 - Cifrato AES-GCM)" : 55
    "📦🔓 CONFIG.userCacheName (Magazzino Asset Volatili - TTL 7d)" : 35
    "🚨 Buffer di Sicurezza (QuotaExceededError Emergency Reserve)" : 10
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

🗂️ Indice Rapido Wiki

LOGO

Clone this wiki locally