Pular para o conteúdo

Pré-renderização estática

A pré-renderização estática é um cache HTML anônimo e opcional. Uma resposta armazenável em cache precisa ser um documento HTML completo e pode optar por não participar com <!-- blockstudio:no-cache -->. Blockstudio ignora solicitações que não sejam GET, strings de consulta, WordPress admin, REST, Ajax, cron, feeds, resultados de pesquisa abaixo da base de pesquisa no caminho inicial do site (como /search/term/), cabeçalhos de pré-visualização e canvas, solicitações com nonce, caminhos dinâmicos declarados, cookies de senha/comentário e, por padrão, solicitações de usuários conectados. Uma página cujo caminho contém apenas um segmento search ou preview mais adiante, como /docs/blocks/preview/, é armazenada em cache como qualquer outra página.

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"
      }
    }
  }
}

Usuários conectados podem consumir um resultado existente somente quando serveLoggedIn é verdadeiro; respostas personalizadas nunca criam entradas de cache. Os caminhos dinâmicos usam limites de caminho, então /account corresponde a /account/orders, mas não a /accounting.

Enquanto o recurso está desativado, ele não grava arquivos, não instala um drop-in e não registra hooks de solicitação ou de administração. earlyServe: false também não registra nenhum callback de administração do Early Serve, e warm.enabled: false não registra callback cron nem agendamento. Desativar qualquer um dos recursos remove uma vez o estado que ele gerencia; as solicitações seguintes não fazem verificações de limpeza do sistema de arquivos nem de cron.

Desativar por ambiente

Cada valor acima também pode ser definido com um filtro de configurações. Blockstudio é iniciado antes do tema ativo, a partir de um plugin ou do autoload Composer do tema, então resolve novamente as configurações de execução depois que o tema é carregado e decide sobre os hooks de pré-renderização estática em after_setup_theme. Portanto, um filtro adicionado por um plugin ou em functions.php do tema entra em vigor:

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

Desativar o recurso dessa forma funciona como desativá-lo em blockstudio.json: nenhum hook de solicitação, conteúdo, administração ou cron é registrado, e uma entrada Early Serve de um site que já tenha sido servido antecipadamente é removida uma vez. Um filtro adicionado depois, por exemplo em init, não altera quais hooks são registrados.

Modos de assinatura e grafo

O modo signature preenche uma resposta identificada por identidade quando há uma falta normal no cache para um visitante anônimo. É prático para sites WordPress comuns e é atualizado após mudanças no nível do site.

O modo graph é voltado a integrações determinísticas de compilação e implantação. Chame Static_Prerender_Runtime::build_plan() com os URLs de origem ativos, renderize apenas affectedUrls e registre cada resultado com persist_built_response() ou persist_skipped_response(). O plano compara os arquivos compartilhados e os hashes exatos das dependências de cada página. URLs excluídos e HTML sem referências são removidos por 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);

Os argumentos opcionais de host/alvo inicial reescrevem as rotas para uma implantação sem usar o caminho da primeira página como raiz do site. Ferramentas em lote podem usar Static_Prerender_Batch_Renderer::render() e fragmentos N/TOTAL estáveis; Static_Prerender_Batch_Renderer::parse_shard() e select_shard() dão suporte à opção de fragmento, para que quem chama possa calcular a mesma partição que o renderizador usaria. Durante uma compilação, Static_Prerender_Batch_Renderer::is_rendering() informa se a solicitação atual é uma renderização em lote, e não uma visita, para que um modelo possa pular tarefas que não devem ser executadas durante a compilação. Um transporte internal é fornecido pelo filtro genérico blockstudio/static_prerender/render_internal; a alternativa opcional HTTP usa o cabeçalho de aquecimento normal.

O que o modo de grafo acompanha

Com o transporte padrão HTTP, Static_Prerender_Batch_Renderer::render() envia a cada solicitação aquecida um token assinado, e a solicitação informa os arquivos que leu: o modelo WordPress carregado, o modelo de cada bloco Blockstudio renderizado, arquivos de modelo, arquivos de recursos, arquivos adicionados por meio de blockstudio/render/dependencies e, no caso de uma página sincronizada, seus arquivos de definição, modelo, conteúdo e layout. O relatório é gravado no diretório de cache do site, que o renderizador e o servidor Web já compartilham para os HTML renderizados. Na compilação seguinte, build_plan() calcula novamente o hash desses arquivos e marca apenas as rotas cujos arquivos mudaram, além das novas rotas, das rotas cujo ttl expirou e de todas as rotas quando um arquivo compartilhado muda (blockstudio.json, theme.json, style.css, functions.php, header.php, footer.php, tudo em inc/, parts/ e templates/, além das fontes dos recursos UI empacotados de Blockstudio). A assinatura compartilhada calcula o hash das fontes, nunca do resultado compilado, por isso os arquivos _dist que a primeira renderização de uma compilação compila não a alteram: artifact_entry() deriva o ID da compilação da mesma assinatura que build_plan() viu antes da renderização.

Conteúdo que existe apenas no banco de dados não é um arquivo e não é acompanhado: publicações editadas na administração, opções, linhas geradas ou preços. Uma compilação que precise incluir essas alterações passa $force para build_plan() ou renderiza por conta própria os URLs afetados. O transporte internal registra as dependências retornadas pelo filtro.

Serviço antecipado e implantação atômica

Com earlyServe ativado, Blockstudio gerencia um pequeno wp-content/blockstudio-static-prerender-map.php, um drop-in advanced-cache.php e uma declaração exata de WP_CACHE. O drop-in lê um mapa de rotas por site e transmite uma resposta elegível antes da inicialização de WordPress, dos plugins ou do tema.

Blockstudio nunca substitui um mapa, drop-in ou declaração de WP_CACHE que pertença a terceiros. Os artefatos do grafo validam todos os arquivos HTML referenciados antes da troca do mapa; se a validação falhar, o grafo anterior permanece ativo. As entradas de multisite compartilham o mapa, mas são isoladas por host, caminho inicial e ID do site. Desativar o recurso ou desativar Blockstudio remove apenas a entrada do site atual e remove os artefatos compartilhados somente quando não restar nenhuma entrada gerenciada.

As ferramentas de implantação podem ativar atomicamente um grafo totalmente renderizado:

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

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

A configuração continua sendo a fonte de verdade. install_artifact_entry() retorna false, a menos que enabled e earlyServe sejam verdadeiros, então uma implantação nunca poderá instalar um mapa, um drop-in e uma declaração de WP_CACHE que a próxima solicitação de administração removeria novamente.

install_artifact_entry() mantém o build_id da entrada, para que uma implantação possa compará-lo com o valor retornado depois por installed_map_entries(). O mapa é um arquivo PHP lido com include, e cada gravação o remove do cache de opcode, então essa leitura encontra a nova entrada no mesmo processo, mesmo quando opcache.enable_cli está ativado.

A instalação de um artefato promove seus documentos para um escopo de artefato dedicado, nunca afetado pela poda de retenção, e os arquivos referenciados pelo mapa não podem ser removidos, onde quer que estejam, para que o tráfego de renderização ativo não expulse rotas mapeadas do serviço antecipado. Uma chave de rota não é totalmente endereçada pelo conteúdo, então uma nova renderização pode alterar um documento sem mudar sua chave; a instalação compara os bytes e substitui atomicamente um documento de artefato diferente, deixa documentos idênticos intactos e mantém um documento de artefato cuja cópia no armazenamento desapareceu. Static_Prerender_Early_Serve::last_promotion() informa quantas rotas foram promovidas, substituídas, ignoradas ou mantidas na última instalação, para que uma implantação possa registrá-lo.

Um documento armazenado fixa os recursos da compilação aos quais se vincula por meio de URL, e esses arquivos têm sua própria retenção, então um pode durar mais que o outro. Antes de servir, tanto o cache PHP quanto o drop-in verificam se a folha de estilos Tailwind vinculada e identificada por hash de conteúdo ainda existe no disco. Um documento cuja folha de estilos tenha desaparecido é encaminhado para WordPress em vez de ser servido sem estilos; assim, a folha de estilos e o documento são publicados juntos novamente. A mesma verificação ocorre antes de armazenar uma resposta, então um documento que não poderia ser servido nunca é gravado.

Uma solicitação cujo cabeçalho Accept contém text/markdown ignora tanto o armazenamento PHP quanto o drop-in, porque os documentos armazenados são HTML e uma página pode responder a essa solicitação com sua origemMarkdown. Por isso, os documentos servidos enviam Vary: Accept. A atualização de Blockstudio reescreve um drop-in antigo na próxima gravação do mapa.

As rotas do grafo mapeadas sempre usam o artefato ativado. Se uma rota anônima segura não estiver nesse mapa, mas WordPress já a tiver renderizado e persistido, o Early Serve recorrerá ao armazenamento de execução identificado por identidade antes de inicializar WordPress. Isso dá suporte a rotas geradas ou de cauda longa fora de um grafo de implantação deliberadamente limitado. A alternativa usa a identidade do grafo ativado e as mesmas regras de host, normalização de caminho, TTL, cookie, cabeçalho, string de consulta, caminho dinâmico e desvio de feed das rotas mapeadas, e só encontra documentos armazenados em execução, que nunca incluem resultados de pesquisa.

Cabeçalhos de resposta

Um documento armazenado é reproduzido sem a solicitação que o renderizou, então um cabeçalho enviado por um tema ou plugin com header() ficaria ausente em todos os acessos. Blockstudio armazena os cabeçalhos indicados em replayHeaders com cada documento e os envia novamente tanto pelo cache PHP quanto pelo drop-in de atendimento antecipado. O padrão, ["Link"], abrange cabeçalhos como uma alternativa Markdown de rel="alternate"; type="text/markdown", rel="describedby" ou rel="canonical". Os nomes não diferenciam maiúsculas de minúsculas, e o filtro da configuração altera a lista como qualquer outro valor:

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

    return $headers;
});

Defina replayHeaders como [] para desativar a reprodução dos cabeçalhos. Uma lista explícita substitui o padrão; portanto, inclua Link ao adicionar outros nomes de cabeçalho, caso ainda queira reproduzir cabeçalhos de links.

Os cabeçalhos são capturados no processo que renderiza a página: de headers_list() quando uma falha ao vivo é armazenada e da própria solicitação de aquecimento quando uma compilação ou o aquecedor renderiza sobre HTTP; assim, um cabeçalho que o servidor Web adiciona por conta própria e inclui novamente em cada documento servido nunca é armazenado. Somente quando uma renderização de HTTP não grava um relatório são usados os cabeçalhos da resposta. O transporte internal os retorna como headers no resultado, e persist_built_response() os recebe como último argumento, seja como linhas Name: value, seja como um mapa de nomes e valores.

Eles são gravados em <key>.headers.json junto ao documento, acompanham-no ao longo da promoção de artefatos, da coleta de lixo e da poda de retenção e são removidos quando uma nova renderização não envia nenhum. Cabeçalhos de cookies, cache e transporte nunca são armazenados nem reproduzidos, mesmo quando listados: Set-Cookie, Cache-Control, Expires, Pragma, Age, ETag, Last-Modified, Vary, Content-Type, Content-Length, Content-Encoding, Transfer-Encoding, Location, Status, Date, além dos cabeçalhos hop-by-hop e de autenticação. Um documento servido define seus próprios Content-Type e Vary.

Os cabeçalhos armazenados são verificados novamente em relação à lista no momento do envio. O cache PHP lê a configuração atual; o drop-in lê a cópia na entrada do mapa do site, atualizada pela próxima instalação de artefato ou sincronização do mapa. Documentos armazenados antes de uma atualização não têm arquivo de cabeçalhos e são servidos exatamente como antes até serem renderizados novamente.

Aquecimento, manutenção e observabilidade

A fila de aquecimento é durável, coalesce por URL, executa uma única operação por vez e recupera reivindicações expiradas. Mudanças no conteúdo e no site forçam um trabalho substituto mesmo quando a assinatura atual não muda; execuções periódicas enfileiram apenas trabalhos desatualizados. Cada execução, agendada ou via wp bs prerender warm, renderiza até warm.concurrency trabalhos. O modo graph desativa o aquecedor por URL, porque os artefatos do grafo são compilados e ativados como uma unidade.

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 informa a identidade ativa, os arquivos, os bytes, os registros do grafo, o estado da fila, o relatório do mapa de serviço antecipado e os contadores de acertos, erros, compilações e falhas por escopo.

O mapa de serviço antecipado é compartilhado por todos os sites de uma instalação. map status (e Static_Prerender_Early_Serve::map_report()) lista entradas que o serviço antecipado já não pode usar: entradas orphaned cujo site não existe mais e entradas dead cujo diretório desapareceu, além do número de documentos de rota missing nas entradas restantes. map prune (Static_Prerender_Early_Serve::prune_map()) remove entradas órfãs e inativas sob o bloqueio do mapa e informa o motivo de cada uma; --dry-run apenas gera um relatório. A remoção da última entrada remove o mapa, o drop-in e a declaração de WP_CACHE. A exclusão de um site de uma rede multisite remove suas entradas imediatamente, e a limpeza do cache nunca coleta o namespace de onde um artefato ativado é servido; portanto, as entradas só ficam inativas quando seus arquivos são removidos por outros meios.

Observe os resultados de respostas individuais com blockstudio/static_prerender/outcome e todos os resultados do cache compartilhado com blockstudio/cache/outcome.

Desinstalação

Instalações sem um hook de desativação de plugin, como configurações agrupadas com Composer, podem remover em um único comando tudo o que o recurso gerencia:

Shell
wp bs teardown

Ele remove os eventos cron e o estado de pré-renderização estática gerenciado pela instalação: a entrada do mapa do site atual e o drop-in compartilhado e a declaração de WP_CACHE, assim que a última entrada gerenciada é removida. Os arquivos de configuração permanecem intactos, então o recurso pode ser reativado sem problemas.

Adoção em produção

Uma ordem razoável para adoção:

  1. Defina performance.profile como speed e depois verifique a saída do cabeçalho, os feeds e qualquer plugin que dependa de oEmbed ou de XML-RPC.
  2. Gere assets/media.json, mova os modelos para bs_media_image() e depois ative performance.media.lazy.
  3. Ative performance.staticPrerender com earlyServe desativado, verifique os resultados com wp bs prerender status e depois ative earlyServe.

A reversão é feita por recurso: definir staticPrerender.enabled como false remove uma vez o estado do Early Serve gerenciado por Blockstudio e os agendamentos de aquecimento, e depois deixa o ambiente de execução de pré-renderização sem registro. Definir performance.profile novamente como compat desfaz o perfil. Cada alteração mantém as demais camadas intactas.

Desempenho

Os perfis, o profiler e as técnicas de renderização usadas nos bastidores.

Cache

O único diretório de cache onde ficam todos os artefatos gerados.