Vai al contenuto

Prerendering statico

Il prerendering statico è una cache anonima HTML attivabile facoltativamente. Una risposta memorizzabile nella cache deve essere un documento HTML completo e può escludersi con <!-- blockstudio:no-cache -->. Blockstudio esclude le richieste che non sono GET, le query string, WordPress admin, REST, Ajax, cron, i feed, i risultati di ricerca sotto il percorso di base della ricerca alla home del sito (come /search/term/), le intestazioni di anteprima e canvas, le richieste con nonce, i percorsi dinamici dichiarati, i cookie di password/commenti e, per impostazione predefinita, le richieste degli utenti autenticati. Una pagina il cui percorso contiene solo un segmento search o preview più in profondità, come /docs/blocks/preview/, viene memorizzata in cache come qualsiasi altra pagina.

JSON
{
  "performance": {
    "staticPrerender": {
      "enabled": true,
      "ttl": 3600,
      "invalidate": "graph",
      "earlyServe": true,
      "serveLoggedIn": false,
      "dynamicPaths": ["/account", "/checkout"],
      "replayHeaders": ["Link"],
      "warm": {
        "enabled": true,
        "interval": 900,
        "concurrency": 4,
        "transport": "http"
      }
    }
  }
}

Gli utenti autenticati possono utilizzare una cache hit esistente solo quando serveLoggedIn è true; le risposte personalizzate non creano mai voci nella cache. I percorsi dinamici rispettano i confini dei percorsi, quindi /account corrisponde a /account/orders ma non a /accounting.

Quando la funzionalità è disabilitata, non scrive file, non installa drop-in e non registra hook di richiesta o amministrazione. Anche earlyServe: false non registra callback amministrativi Early Serve, e warm.enabled: false non registra callback cron né pianificazioni. Disattivando una delle due funzionalità, lo stato precedentemente gestito viene rimosso una sola volta; le richieste successive non eseguono controlli di pulizia del filesystem o di cron.

Disattivarla per ambiente

Ogni valore qui sopra può essere impostato anche con un filtro delle impostazioni. Blockstudio si avvia prima del tema attivo, da un plugin o dall’autoload Composer del tema, quindi risolve nuovamente le impostazioni di runtime una volta caricato il tema e decide quali hook di prerendering statico registrare in after_setup_theme. Un filtro aggiunto da un plugin o in functions.php del tema ha quindi effetto:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/enabled', function ($enabled) {
    return 'local' === wp_get_environment_type() ? false : $enabled;
});

Disattivare la funzionalità in questo modo equivale a disattivarla in blockstudio.json: non vengono registrati hook di richiesta, contenuto, amministrazione o cron, e una voce Early Serve precedentemente servita in anticipo viene rimossa una sola volta. Un filtro aggiunto in seguito, per esempio in init, non modifica gli hook registrati.

Modalità firma e grafo

La modalità signature riempie una risposta indicizzata per identità in caso di cache miss anonima ordinaria. È comoda per i normali siti WordPress e ruota in seguito a modifiche a livello di sito.

La modalità graph è destinata alle integrazioni deterministiche di build/deploy. Chiamate Static_Prerender_Runtime::build_plan() con gli URL delle sorgenti attive, eseguite il rendering solo di affectedUrls, quindi registrate ogni risultato con persist_built_response() o persist_skipped_response(). Il piano confronta i file condivisi e gli hash esatti delle dipendenze di ogni pagina. Gli URL eliminati e i file HTML non referenziati vengono rimossi da garbage_collect().

PHP
use Blockstudio\Static_Prerender_Runtime;

$plan = Static_Prerender_Runtime::build_plan($sourceUrls);

foreach ($plan['affectedUrls'] as $url) {
    $result = render_with_dependencies($url);

    Static_Prerender_Runtime::persist_built_response(
        $url,
        $result['html'],
        $result['files'],
        $result['virtualHashes']
    );
}

$targets = array_keys($plan['live']);
Static_Prerender_Runtime::garbage_collect($targets);

Gli argomenti facoltativi per host e home di destinazione riscrivono le route per un deploy senza usare il percorso della prima pagina come radice del sito. Gli strumenti batch possono usare Static_Prerender_Batch_Renderer::render() e partizioni N/TOTAL stabili; Static_Prerender_Batch_Renderer::parse_shard() e select_shard() supportano l’opzione di partizione, così chi chiama può calcolare la stessa partizione che userebbe il renderer. Durante una build, Static_Prerender_Batch_Renderer::is_rendering() indica se la richiesta corrente è un rendering batch anziché una visita, così un template può saltare le operazioni che non devono essere eseguite durante una build. Un trasporto internal viene fornito dal filtro generico blockstudio/static_prerender/render_internal; il fallback facoltativo HTTP usa la normale intestazione di warm-up.

Cosa monitora la modalità grafo

Con il trasporto predefinito HTTP, Static_Prerender_Batch_Renderer::render() invia a ogni richiesta di warm-up un token firmato, e la richiesta segnala i file letti: il template caricato WordPress, il template di ogni blocco Blockstudio renderizzato, i file template e i file degli asset, i file aggiunti tramite blockstudio/render/dependencies e, per una pagina sincronizzata, i relativi file di definizione, template, contenuto e layout. Il report viene scritto nella directory cache del sito, che il renderer e il server web condividono già per il rendering di HTML. Alla build successiva, build_plan() calcola di nuovo l’hash di quei file e contrassegna solo le route i cui file sono cambiati, insieme alle nuove route, a quelle oltre il relativo ttl e a tutte le route se cambia un file condiviso (blockstudio.json, theme.json, style.css, functions.php, header.php, footer.php, tutto ciò che si trova in inc/, parts/ e templates/, nonché le sorgenti degli asset UI inclusi nel bundle di Blockstudio). L’hash della firma condivisa viene calcolato sulle sorgenti, mai sull’output compilato, quindi i file _dist compilati dal primo rendering della build non lo modificano: artifact_entry() ricava l’ID della build dalla stessa firma che build_plan() aveva rilevato prima del rendering.

I contenuti che esistono solo nel database non sono file e non vengono monitorati: post modificati nell’area di amministrazione, opzioni, righe generate o prezzi. Una build che deve recepire tali modifiche passa $force a build_plan() oppure esegue autonomamente il rendering degli URL interessati. Il trasporto internal registra le dipendenze restituite dal suo filtro.

Servizio anticipato e deploy atomico

Con earlyServe attivo, Blockstudio gestisce un piccolo wp-content/blockstudio-static-prerender-map.php, un drop-in advanced-cache.php e un’unica dichiarazione WP_CACHE esatta. Il drop-in legge una mappa delle route per sito e trasmette una cache hit idonea prima dell’avvio di WordPress, dei plugin o del tema.

Blockstudio non sovrascrive mai una mappa, un drop-in o una dichiarazione WP_CACHE di terzi. Gli artefatti del grafo convalidano ogni file HTML referenziato prima di sostituire la mappa; se la convalida fallisce, il grafo precedente resta attivo. Le voci multisito condividono la mappa, ma sono isolate per host, percorso home e ID del sito. Disattivando la funzionalità o disattivando Blockstudio, viene rimossa solo la voce del sito corrente; gli artefatti condivisi vengono rimossi solo quando non resta alcuna voce gestita.

Gli strumenti di deploy possono attivare atomicamente un grafo renderizzato per intero:

PHP
$entry = Static_Prerender_Runtime::artifact_entry($targetUrls);

Blockstudio\Static_Prerender_Early_Serve::install_artifact_entry(
    $entry,
    Static_Prerender_Runtime::cache_root_path()
);

La configurazione resta autorevole. install_artifact_entry() restituisce false a meno che enabled e earlyServe non siano entrambi true, così un deploy non può mai installare una mappa, un drop-in e una dichiarazione WP_CACHE che la successiva richiesta amministrativa rimuoverebbe di nuovo.

install_artifact_entry() conserva l’build_id della voce, così un deploy può confrontarlo con quello restituito successivamente da installed_map_entries(). La mappa è un file PHP letto con include e ogni scrittura lo rimuove dalla cache opcode, così la lettura rileva la nuova voce nello stesso processo anche quando opcache.enable_cli è attivo.

L’installazione di un artefatto promuove i suoi documenti in un ambito dedicato agli artefatti, che la potatura per retention non tocca; inoltre, i file referenziati dalla mappa non possono essere espulsi, ovunque si trovino, così il traffico di rendering attivo non può far scadere le route mappate dal servizio anticipato. Una chiave di route non è completamente basata sul contenuto, quindi un nuovo rendering può modificare un documento senza cambiarne la chiave; l’installazione confronta i byte e sostituisce atomicamente i documenti artefatto diversi, lascia invariati quelli identici e conserva un documento artefatto se la relativa copia nello store è scomparsa. Static_Prerender_Early_Serve::last_promotion() indica quante route sono state promosse, sostituite, ignorate o conservate nell’ultima installazione, così un deploy può registrare il dato.

Un documento memorizzato mantiene gli asset di build a cui rimanda tramite URL e i relativi file conservano la propria retention, quindi l’uno può sopravvivere all’altro. Prima di servire una risposta, sia la cache PHP sia il drop-in verificano che un foglio di stile Tailwind collegato e con hash del contenuto esista ancora su disco. Se il foglio di stile non c’è più, il documento viene passato a WordPress invece di essere servito senza stile; così il foglio e il documento vengono pubblicati di nuovo insieme. Lo stesso controllo viene eseguito prima di memorizzare una risposta, perciò un documento che non potrebbe essere servito non viene mai scritto.

Una richiesta la cui intestazione Accept contiene text/markdown bypassa sia lo store PHP sia il drop-in, perché i documenti memorizzati sono HTML e una pagina può rispondere a tale richiesta con la propria sorgente Markdown. I documenti serviti inviano quindi Vary: Accept. Aggiornando Blockstudio, il drop-in precedente viene riscritto alla successiva scrittura della mappa.

Le route del grafo mappate usano sempre l’artefatto attivato. Se una route anonima sicura non è presente nella mappa ma WordPress l’ha renderizzata e memorizzata nel frattempo, Early Serve ripiega sullo store runtime indicizzato per identità prima di avviare WordPress. Questo consente di gestire route generate o di coda lunga al di fuori di un grafo di deploy volutamente limitato. Il fallback usa l’identità del grafo attivato e le stesse regole di bypass per host, normalizzazione del percorso, TTL, cookie, intestazioni, query string, percorso dinamico e feed delle route mappate; inoltre, trova solo i documenti memorizzati dal runtime, che non includono mai i risultati di ricerca.

Intestazioni della risposta

Un documento memorizzato viene riprodotto senza la richiesta che lo ha generato, quindi un’intestazione inviata da un tema o da un plugin con header() mancherebbe in ogni hit. Blockstudio memorizza con ogni documento le intestazioni indicate in replayHeaders e le invia di nuovo sia dalla cache PHP sia dal drop-in di risposta anticipata. Il valore predefinito, ["Link"], include intestazioni come un’alternativa Markdown di rel="alternate"; type="text/markdown", rel="describedby" o rel="canonical". I nomi non distinguono tra maiuscole e minuscole e il filtro dell’impostazione modifica l’elenco come qualsiasi altro valore:

PHP
add_filter('blockstudio/settings/performance/staticPrerender/replayHeaders', function (array $headers): array {
    $headers[] = 'X-Robots-Tag';

    return $headers;
});

Impostate replayHeaders su [] per disabilitare la riproduzione delle intestazioni. Un elenco esplicito sostituisce quello predefinito, quindi includete Link quando aggiungete altri nomi di intestazione, se volete continuare a riprodurre le intestazioni dei link.

Le intestazioni vengono acquisite nel processo che genera la pagina: da headers_list() quando viene memorizzata una risposta a una cache miss live e dalla richiesta di riscaldamento stessa quando una build o il warmer genera la pagina sopra HTTP, quindi un’intestazione aggiunta autonomamente dal server web e aggiunta di nuovo a ogni documento servito non viene mai memorizzata. Solo quando una generazione HTTP non produce alcun report vengono usate le intestazioni della relativa risposta. Il trasporto internal le restituisce come headers nel risultato e persist_built_response() le riceve come ultimo argomento, sotto forma di righe Name: value o di mappa da nome a valore.

Vengono scritte in <key>.headers.json accanto al documento, lo seguono durante la promozione degli artefatti, la raccolta dei rifiuti e la potatura dei contenuti conservati, e vengono rimosse quando una nuova generazione non ne invia. Le intestazioni di cookie, cache e trasporto non vengono mai memorizzate né riprodotte, anche se sono elencate: Set-Cookie, Cache-Control, Expires, Pragma, Age, ETag, Last-Modified, Vary, Content-Type, Content-Length, Content-Encoding, Transfer-Encoding, Location, Status, Date, oltre alle intestazioni hop-by-hop e di autenticazione. Un documento servito imposta i propri valori Content-Type e Vary.

Le intestazioni memorizzate vengono verificate di nuovo rispetto all’elenco al momento dell’invio. La cache PHP legge l’impostazione corrente; il drop-in legge la copia presente nella voce della mappa del sito, aggiornata dalla successiva installazione di artefatti o sincronizzazione della mappa. I documenti memorizzati prima di un aggiornamento non hanno un file delle intestazioni e vengono serviti esattamente come prima finché non vengono generati di nuovo.

Warm-up, manutenzione e osservabilità

La coda di warm-up è persistente, consolida le voci con la stessa URL, gestisce un solo job alla volta e recupera le prenotazioni scadute. Le modifiche ai contenuti e al sito forzano la sostituzione di un job anche se la firma corrente non è cambiata; i passaggi a intervalli accodano solo il lavoro non aggiornato. Ogni passaggio, pianificato o avviato tramite wp bs prerender warm, esegue il rendering di un massimo di warm.concurrency job. La modalità graph disattiva il warm-up per URL, perché gli artefatti del grafo vengono compilati e attivati come un’unica unità.

Shell
wp bs prerender warm
wp bs prerender status
wp bs prerender purge
wp bs prerender map status
wp bs prerender map prune --dry-run

status riporta l’identità attiva, i file, i byte, i record del grafo, lo stato della coda, il report della mappa di Early Serve e i contatori di cache hit/miss/build/errori per ambito.

La mappa di Early Serve è condivisa da tutti i siti di un’installazione. map status (e Static_Prerender_Early_Serve::map_report()) elenca le voci che il servizio anticipato non può più usare: le voci orphaned i cui siti non esistono più e le voci dead con directory mancanti, oltre al numero di documenti di route missing nelle voci rimanenti. map prune (Static_Prerender_Early_Serve::prune_map()) rimuove le voci orfane e non più attive sotto il lock della mappa e riporta il motivo di ciascuna; --dry-run si limita a segnalarle. La rimozione dell’ultima voce elimina la mappa, il drop-in e la dichiarazione WP_CACHE. L’eliminazione di un sito da una rete multisito rimuove subito le relative voci e la pulizia della cache non raccoglie mai lo spazio dei nomi da cui viene servito un artefatto attivato; quindi, le voci diventano inattive solo se i loro file vengono rimossi con altri mezzi.

Osservate i singoli esiti delle risposte con blockstudio/static_prerender/outcome e tutti gli esiti condivisi della cache con blockstudio/cache/outcome.

Rimozione

Le installazioni senza un hook di disattivazione del plugin, come le configurazioni fornite con Composer, possono rimuovere con un solo comando tutto ciò che la funzionalità gestisce:

Shell
wp bs teardown

Rimuove gli eventi cron e lo stato di prerendering statico gestito dall’installazione: la voce della mappa del sito corrente e, una volta eliminata l’ultima voce gestita, il drop-in condiviso e la dichiarazione WP_CACHE. I file di configurazione restano intatti, così la funzionalità può essere riattivata senza problemi.

Adozione in produzione

Un ordine di adozione ragionevole:

  1. Impostate performance.profile su speed, quindi controllate l’output head, i feed e tutti i plugin che si basano su oEmbed o XML-RPC.
  2. Generate assets/media.json, spostate i template in bs_media_image(), quindi attivate performance.media.lazy.
  3. Attivate performance.staticPrerender con earlyServe disattivato, verificate le cache hit con wp bs prerender status, quindi attivate earlyServe.

Il rollback si esegue per funzionalità: impostando staticPrerender.enabled su false, lo stato Early Serve gestito da Blockstudio e le pianificazioni di warm-up vengono rimossi una sola volta; il runtime di prerendering resta quindi non registrato. Impostando di nuovo performance.profile su compat, si annulla il profilo. Ciascun rollback lascia intatti gli altri livelli.

Prestazioni

I profili, il profiler e le tecniche di rendering sottostanti.

Caching

L’unica directory cache che contiene tutti gli artefatti generati.