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 sull'Isolamento dei Flussi, sull'Erogazione Polimorfa basata sui profili hardware della rete e su pilastri di sicurezza "Zero Trust" progettati per garantire la massima tolleranza ai guasti.

Note

Il Regolatore di Flusso Polimorfo si attiva a ogni singola richiesta dell'utente tramite la routine assegnaFlussoPolimorfo, decidendo in tempo reale se instradare la richiesta via Network-First o Stale-While-Revalidate (SWR) in base ai profili hardware.

Warning

In caso di fallimento del test crittografico a runtime sul Canary Data (CONFIG.vaultCanaryText), il Service Worker attiva la routine distruttiva di Emergency Wipe, cancellando l'intera stiva per prevenire violazioni di tipo Cache Poisoning o corruzioni strutturali.
⚠️ Configurazione: L'algoritmo esegue campionamenti RTT e downlink tramite navigator.connection. Non disabilitare le API di telemetria di rete.

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

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

⚡ 2. Strategia di Fetch: Regolatore di Flusso Polimorfo a 5 Sezioni

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

🔹 Profilazione Hardware della Rete (`assegnaFlussoPolimorfo`):
Il sistema calcola in tempo reale un punteggio di efficienza basato sui parametri hardware di navigator.connection (downlink e RTT), commutando istantaneamente la strategia di erogazione e mappando i limiti estratti dal dizionario dei profili:

Profilo Rete Limite Parallelismo (limit) Timeout di Connessione (timeout) Strategia ed Erogazione Polimorfa
Ultrafast 12 file 15 secondi Forza Network-First (Massima freschezza asset dal server)
Fast 8 file 20 secondi Forza Network-First (Massima freschezza asset dal server)
Medium 4 file 45 secondi Network-First se cache vuota, altrimenti commuta su SWR
Low 2 file 90 secondi Forza Stale-While-Revalidate (Continuità via stiva locale)
Verylow 1 file 120 secondi Blocco d'ufficio dello Smart Sync / Solo erogazione locale 
graph TD
    %% Definizione degli stili visivi per massima leggibilità
    classDef inizio fill:#1f4e79,stroke:#113355,stroke-width:2px,color:#fff;
    classDef sezione fill:#f5f5f5,stroke:#333,stroke-width:2px,color:#000;
    classDef successo fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#155724;
    classDef recupero fill:#fff3cd,stroke:#ffc107,stroke-width:2px,color:#856404;
    classDef errore 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)

Attivato tramite messaggistica IPC dall'evento INIT_DB, il motore di sincronizzazione esegue una bonifica e un allineamento predittivo degli asset tramite logiche combinate:

🔹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 impedire attacchi di Cache Poisoning, pagine ingannevoli di captive portal o file corrotti di rete, ogni blob subisce una validazione rigorosa (strict) prima dell'ammissione in stiva:

🔹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 signed}
    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 locale, tracciato nei log di console con marcatori dedicati e protetto da crittografia hardware-assisted:

Important

➡️ Sicurezza Volatile in RAM: La Master Key è un'istanza crittografica non esportabile (extractable: false) isolata nello stato di runtime del worker. Subito dopo l'elaborazione dei pacchetti binari, i buffer temporanei di transito vengono sovrascritti forzatamente tramite Uint8Array.fill(0) per eliminare ogni residuo crittografico o dato in chiaro dalla RAM del browser (Anti-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 interamente sincronizzata con l'interfaccia utente del frontend:

🔹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[assegnaFlussoPolimorfo]
        C -->|Profilo Canale Rilevato| 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{DNA Check via CONFIG.minSizeMap & Magic Numbers Hex}
        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 / Lie-Fi| 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 + Bonifica fill]
        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 Sterile]
        T -->|NO| V[Ritorna Errore Plain Text Offline 503]
    end

    subgraph FLUSSO_SYNC [2. Evento Sync: Allineamento e Pre-Cache]
        X[Trigger Event: INIT_DB / Connessione Ripristinata] --> Y[assegnaFlussoPolimorfo]
        Y --> Z{Profilo == Verylow?}
        Z -->|SÌ| AA[syncAbortController.abort: Blocco Preventivo Sync]
        Z -->|NO| AB[Universal Object Scanner: Profondità 12 livelli]
        AB --> AC[Download varianti estensione controllato]
        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