Boas práticas de Applications

A maioria dos erros na camada entre os seus usuários e a sua origem fica invisível até que um usuário encontre um deles. Um visitante vê uma versão de uma página que você já substituiu. A origem responde a requisições que uma cópia armazenada poderia ter respondido. Um cookie de sessão chega a um usuário para quem nunca foi emitido, ou uma imagem chega mais pesada ou recortada de forma diferente do que a página pediu.

A causa raramente é um único valor errado. Com mais frequência, uma cache key varia por algo que a resposta ignora, ou um único TTL cobre conteúdo que muda em ritmos diferentes. Ou uma mudança é avaliada antes que alguém leia a resposta.

Estas práticas se aplicam a uma aplicação, aos seus device groups, às regras do Rules Engine para Applications que agem sobre o seu tráfego e aos cache settings que essas regras aplicam. Como Applications funciona explica os mecanismos por trás delas, e Limites de Applications traz o valor de cada limite.

As duas primeiras práticas se aplicam à própria aplicação. Em seguida vêm as seções de Cache, Application Accelerator e Image Processor, uma por Produto que uma aplicação pode habilitar. Cada uma segue a ordem em que você encontra as suas decisões.

Defina um device group pelas palavras que só esse dispositivo envia

A expressão regular de cada device group é testada contra o header User-Agent. O grupo que uma requisição recebe decide as suas regras e a sua variação de cache. Google Chrome Android e Google Chrome Symbian compartilham Google Chrome, então uma expressão sobre esse nome coloca as duas em um só grupo.

Escreva cada expressão sobre as palavras que distinguem a sua classe de dispositivo. Um grupo chamado Mobile com (Mobile|iP(hone|od)|BlackBerry|IEMobile) captura a maioria dos dispositivos móveis.

O custo é a cobertura: um dispositivo da classe cujo header não carrega nenhuma das palavras fica fora do grupo. Quando duas classes compartilham uma palavra, vence o primeiro grupo correspondente da lista, como mostra Device Groups. Para criar um grupo, consulte Crie device groups.

Envie os headers de upgrade do WebSocket só nas requisições que abrem uma conexão

Por padrão, uma aplicação com WebSocket Proxy habilitado faz proxy de toda requisição com Upgrade: websocket e Connection: upgrade para a origem como uma conexão WebSocket. Ela não verifica o path. A Azion recomenda que a aplicação que você constrói controle esses headers e os envie só onde o protocolo WebSocket deve ser usado.

A decisão fica então no código do seu cliente. O mesmo cliente também reabre uma conexão que se fecha. A Azion recicla as conexões keepalive aproximadamente a cada 15 minutos, o que pode fechar uma conexão WebSocket ativa.

Uma conexão que se abre retorna 101 Switching Protocols, e qualquer outro status, mesmo um 2xx ou um 3xx, significa que o upgrade não se completou. Para os headers e os status, consulte WebSocket Proxy.

Cache

Um cache setting decide por quanto tempo a Azion mantém uma cópia de uma resposta. Mantida por tempo demais, a cópia mostra a um visitante um conteúdo que a origem já substituiu. Mantida por pouco tempo, ela envia à origem requisições que uma cópia armazenada poderia ter respondido.

Estas práticas se aplicam aos cache settings de uma aplicação e às regras cujo behavior Set Cache Policy os aplica. A primeira prática mostra um cache setting completo, na forma que a API aceita, e as práticas seguintes nomeiam só o campo que mudam. A última prática mostra como confirmar cada mudança na resposta.

Ajuste cada TTL à frequência com que o seu conteúdo muda

Sob Override cache behavior, o Max Age define o TTL de uma cópia. Um TTL mais longo responde a mais requisições, mas fica mais atrasado em relação à origem. Assets podem mudar só quando um deploy os substitui, enquanto uma página muda ao longo do dia, então um único TTL não serve para parte do conteúdo.

Dê a cada grupo de paths que muda em um mesmo ritmo o seu próprio cache setting e a sua própria regra. Este setting mantém os assets por 86.400 segundos no navegador e por 300 segundos na Azion:

Páginas editadas durante o dia recebem um segundo setting e uma segunda regra, com um Max Age menor. Um Max Age menor que 60 segundos exige Application Accelerator, ou a API o recusa com 21021. Para cada limite, consulte Limites de Applications. Para os passos, consulte Crie um cache setting.

Mude o nome de um objeto quando o conteúdo dele mudar

Um objeto que mantém o nome exige um purge de cada camada de cache e de cada variação sempre que o seu conteúdo muda. Em vez disso, coloque uma versão no nome do arquivo. O cache trata cada versão como um objeto separado, e a primeira requisição para ela busca os bytes atuais na origem. Qualquer esquema serve, como um contador, um timestamp ou um hash do conteúdo, desde que conteúdo diferente sempre receba um nome diferente: https://static.example.com/assets/image_1.jpg passa a ser https://static.example.com/assets/image_2.jpg.

Nenhum purge é necessário para que uma atualização chegue aos usuários, e um navegador que ainda guarda o nome anterior mantém um objeto válido. As duas versões ficam disponíveis, então reverter significa apontar as suas páginas para o nome anterior. O custo é que toda referência ao objeto muda junto com ele, o que uma etapa de build pode automatizar e uma edição manual não pode.

Purgue um objeto que varia por cache key ou wildcard

Real-Time Purge encontra uma cópia pela sua cache key, e um objeto que varia tem uma key por variação. Um purge por URL converte a URL em uma key. Uma cópia que varia por cookie, device group ou formato de imagem sobrevive a ele, enquanto o purge informa sucesso.

Nomeie essas keys em um purge por cache key, até 50 por requisição, ou alcance-as com um wildcard. Estes comandos do Azion CLI enviam os dois, com o wildcard terminado em @@* para as variações por cookie:

Cada comando imprime Purge carried out successfully. Uma variação com muitos valores custa mais para purgar e para armazenar, então escolha o seu purge quando escolher a variação. Para o purge que alcança cada variação, consulte Real-Time Purge. Para os passos, consulte Purgue conteúdo em cache.

Reserve Tiered Cache para objetos de vida longa com corpo estável

Tiered Cache acrescenta uma segunda camada de cache que os data centers consultam antes da origem, então uma busca na origem serve todos eles. Ative-o para objetos de vida longa com corpo estável, com modules.cache.tiered_cache definido como { "enabled": true, "topology": "nearest-region" }.

O setting precisa de override, ou a API o recusa com 21001. Com Application Accelerator ativo, o piso do Max Age é de 3 segundos, e um valor menor recebe 21020. O custo é um salto a mais em um miss na primeira camada, e a camada não serve para conteúdo que muda a cada poucos segundos.

Uma regra com Bypass Cache não alcança a camada, como explica Descarte Tiered Cache antes de contar com Bypass Cache. Para remover um objeto das duas camadas, purgue o Tiered Cache antes do Cache, como mostra Tiered Cache.

Ative stale cache onde uma página antiga é melhor que um erro

Com Stale cache ativo, a Azion serve uma cópia além do seu TTL quando a revalidação com a origem falha, enquanto durar a janela de stale. O visitante recebe a última versão boa em vez de uma página de erro. Defina modules.cache.stale_cache.enabled como true para um artigo, uma listagem ou uma página de produto. Mantenha-o desativado para um preço ou um dado de disponibilidade em que um visitante baseia uma decisão.

Uma resposta servida assim informa STALE em x-cache. Para a duração da janela, o que faz uma revalidação falhar e quando um purge serve melhor que a expiração, consulte Expiração e atualização.

Leia o status de cache depois de cada mudança de cache

Um setting diz o que a Azion deveria armazenar, e só a resposta mostra o que ela armazenou. Envie uma requisição com Pragma: azion-debug-cache cada vez que criar um setting, mudar um TTL ou executar um purge:

A resposta carrega x-cache: MISS from 192.0.2.10 with HTTP/2.0 e x-cache-key: httpswww.example.com/static/site.js. x-cache começa com o status, HIT para uma cópia armazenada e MISS para uma ida à origem. x-cache-key traz a key que um purge por cache key recebe, com as variações que o setting acrescenta.

Uma resposta descreve uma cópia em um servidor, então repita a requisição antes de concluir qualquer coisa. Para cada valor de status, consulte Cache keys. Para os passos, consulte Verifique o status de cache de uma resposta.

Application Accelerator

Cada atributo pelo qual uma cache key varia multiplica as cópias que a Azion mantém de uma URL, uma cópia por valor. Quando o atributo não altera a resposta, essas cópias carregam bytes idênticos, dividem o tráfego entre si e acrescentam keys que um purge precisa alcançar.

Application Accelerator acrescenta o objeto modules.application_accelerator a um cache setting e libera behaviors do Rules Engine como Bypass Cache e Forward Cookies. Enquanto ele está desativado na aplicação, a API recusa qualquer campo desse objeto com 21013. As quatro primeiras práticas moldam a key, e x-cache-key mostra o que cada uma acrescenta, como explica Leia o status de cache depois de cada mudança de cache.

Monte a cache key só com os argumentos de que a resposta depende

Por padrão, ignore deixa a query string fora da cache key, então ?category=shoes e o path sem argumentos compartilham uma cópia. Sob all, todo argumento entra na key, então um link com um argumento de campanha recebe uma cópia idêntica própria.

Sob allowlist, só os argumentos listados variam a key, então o número de cópias acompanha o conteúdo, e não o tráfego. Liste exatamente os argumentos que mudam a resposta:

Uma lista vazia é recusada com 21018. Deixe de fora um argumento que muda a resposta, e um visitante pode ver conteúdo destinado a outro. Para os valores de cada variação, consulte Cache settings. Para os passos, consulte Configure a Advanced Cache Key para uma aplicação.

Ordene a query string antes que ela entre na key

Sem ordenação, os argumentos listados entram na cache key na ordem em que o cliente os escreveu. ?category=shoes&page=2 e ?page=2&category=shoes passam então a ser duas cópias da mesma resposta. Com sort_enabled definido como true no mesmo objeto cache_vary_by_querystring, os argumentos entram na key em ordem alfabética, e as duas requisições chegam a uma única cópia.

O custo aparece na hora do purge: um purge por URL alcança a cópia só quando nomeia os argumentos em ordem alfabética. O Azion CLI define sort_enabled só por meio de --file e de um corpo JSON. Para ver qual purge alcança cada variação, consulte Real-Time Purge.

Liste só os cookies que segmentam conteúdo

Os navegadores enviam todos os cookies que guardam para um domínio, e poucos deles mudam o que a origem retorna. Sob all, um identificador de analytics ou uma flag de consentimento entra na key, e as cópias se multiplicam com os valores dos cookies, e não com o conteúdo. Sob allowlist, só os cookies que você nomeia variam a key, e é assim que uma aplicação segmenta conteúdo por perfil de usuário ou por outro agrupamento.

A Azion recomenda a allowlist quando cookies gerenciam sessões de usuário: behavior definido como allowlist e session_id em cookie_names, sob modules.application_accelerator.cache_vary_by_cookies. O custo são as cópias: um cookie único por visitante significa uma cópia por visitante. Para os passos, consulte Configure a Advanced Cache Key para uma aplicação.

Coloque os cookies de sessão na denylist onde Forward Cookies roda

O behavior Forward Cookies repassa aos usuários o header Set-Cookie da origem, incluindo os cache hits. Uma resposta em cache pode então entregar a um usuário o Set-Cookie da sessão de outro usuário. A solução que a Azion documenta é o behavior denylist da variação por cookie, nomeando os cookies de sessão que devem permanecer privados: behavior definido como denylist, com session_id em cookie_names.

Coloque a denylist no cache setting que a regra com Forward Cookies aplica por meio de Set Cache Policy. Um cache setting tem um único behavior de cookie, então uma allowlist de segmentação exige um setting separado. Para os passos, consulte Configure políticas de cache para uma aplicação.

Prefira um TTL de 0 segundos onde todos podem compartilhar a resposta

Um Max Age de 0 e o behavior Bypass Cache impedem, ambos, que os usuários recebam uma cópia armazenada. Bypass Cache encaminha cada requisição que corresponde a ele. Um TTL de 0 mantém a requisição no caminho do cache, onde requisições simultâneas chegam à origem como uma só.

Use o TTL de 0 quando o conteúdo dinâmico é o mesmo para todos que o pedem no mesmo momento, com modules.cache.max_age definido como 0. Use Bypass Cache, { "type": "bypass_cache" } na API, quando duas requisições que chegam juntas precisam de respostas diferentes. Com Tiered Cache ativo, nenhuma das opções vale nas duas camadas: o Max Age para em 3 segundos, e Bypass Cache não alcança a camada. Para saber como cada uma trata uma requisição, consulte Variação de cache.

Descarte Tiered Cache antes de contar com Bypass Cache

Bypass Cache impede que o cache da Azion armazene a resposta da origem, mas a camada do Tiered Cache fica fora do alcance da regra. Enquanto a regra está ativa, uma camada que os cache settings ativam continua armazenando objetos em cache pelo TTL mínimo. A regra não mostra nenhum sinal disso, então uma regra que parece certa ainda pode deixar conteúdo em cache.

Quando o requisito é conteúdo atualizado, procure modules.cache.tiered_cache.enabled definido como true nos cache settings que cobrem os paths da regra. Se nenhuma camada puder manter uma cópia, decida sobre Tiered Cache junto com a regra. Para o sintoma que uma camada esquecida produz e a sua correção, consulte Solucionar problemas de Applications.

Image Processor

Uma imagem transformada pode prejudicar uma página de três formas. O arquivo pesa mais do que a página precisa, ou o recorte remove algo que ninguém pretendia remover. Ou a requisição falha por causa da posição de um parâmetro na URL. Em torno da transformação, o cache setting decide como as imagens derivadas são armazenadas e com que frequência o mesmo trabalho é executado de novo.

Estas práticas se aplicam a Image Processor: a query string ims, a regra cujo behavior Optimize Images age sobre ela e o cache setting dessa regra. As quatro primeiras práticas tratam da requisição, e as duas últimas tratam do cache setting.

Solicite qualidade 85, a menos que uma imagem precise de outro valor

O filtro de qualidade controla o quanto Image Processor comprime uma imagem derivada, trocando bytes por fidelidade visual. O seu argumento é um número inteiro de 0 a 100. A Azion recomenda ?ims=filters:quality(85), que otimiza o arquivo sem perda perceptível de qualidade visual.

Um valor menor deixa o arquivo ainda menor, e a imagem entregue mostra a perda. Um valor maior acrescenta um peso que quem vê a imagem não consegue perceber. Afaste-se de 85 só para uma imagem que precisa parecer mais nítida, ou pesar menos, do que 85 entrega. Para o argumento e a sua faixa, consulte Parâmetros de URL do Image Processor.

Use fit-in quando a imagem precisar manter as proporções

?ims=WidthxHeight preenche uma caixa exata, e, quando o formato solicitado difere do da imagem de origem, um recorte automático centralizado corta o eixo que ultrapassa a caixa. Parte do assunto pode ir junto. fit-in, por sua vez, coloca a imagem dentro da mesma caixa, mantendo a proporção e sem nunca ampliá-la.

Em uma fotografia em paisagem, ?ims=400x400 recorta a imagem para preencher o quadrado. ?ims=fit-in/400x400 mantém a imagem inteira e não preenche o quadrado em um dos lados. Use o redimensionamento simples quando o layout precisa da caixa preenchida, e fit-in quando nenhuma margem da imagem pode ser perdida. Para cada forma de redimensionamento, consulte Parâmetros de URL do Image Processor.

Mantenha ims como o último parâmetro da query string

Image Processor espera que ims seja o último parâmetro da query string. Um parâmetro colocado depois dele pode fazer a requisição retornar um erro 504. example.com/image.jpeg?ims=1000x1000&ts=1234 é a forma incorreta, e example.com/image.jpeg?ts=1234&ims=1000x1000 é a correta.

Timestamps de cache-busting e valores de rastreamento que outro sistema acrescenta seguem a mesma regra. Um script que acrescenta um parâmetro precisa inseri-lo antes de ims, e não no final. Para a regra, consulte Parâmetros de URL do Image Processor.

Adicione o header Accept que uma conversão para WEBP ou AVIF exige

Uma conversão para WEBP ou AVIF exige um header de requisição correspondente. filters:format(webp) exige Accept: image/webp, e filters:format(avif) exige Accept: image/avif. Na Request Phase, o behavior Add Request Header fornece o header, de modo que a conversão deixa de depender do que o cliente envia.

Uma regra que converte para WEBP carrega { "type": "add_request_header", "attributes": { "value": "Accept: image/webp" } }. A API rejeita o tipo add_header com 10039. Mantenha cada valor em sincronia com o formato que a sua string ims solicita. Para o filtro de conversão, consulte Parâmetros de URL do Image Processor. Para os critérios que restringem uma regra a requisições de imagem, consulte Configurações do Image Processor.

Coloque ims na allowlist do cache setting que serve imagens

ims carrega a transformação, então é um argumento de que a resposta depende. Monte a cache key só com os argumentos de que a resposta depende se aplica a ele. O cache setting que a regra de imagens aplica define fields como ["ims"] sob uma allowlist.

A diferença é um segundo Produto: cache_vary_by_querystring pertence a modules.application_accelerator, então incluir ims na cache key exige Application Accelerator, embora transformar uma imagem não exija. Para os controles de Azion Console que definem o campo, consulte Configurações do Image Processor.

Mantenha imagens derivadas em cache pelo tempo que as imagens de origem permitirem

Image Processor conta cada transformação, seja um redimensionamento, um recorte, uma conversão de formato ou um filtro, no medidor mensal Images. Uma requisição que o cache responde não executa transformação e não acrescenta nada. Um Max Age curto faz Image Processor refazer a mesma transformação em um intervalo sem relação com mudanças na imagem de origem.

Dê ao cache setting das imagens derivadas o maior modules.cache.max_age que o seu conteúdo de origem tolera, até 31.536.000 segundos. O custo é a atualização do conteúdo. Uma imagem de origem substituída deixa as suas versões derivadas, uma key por processamento e por formato, em cache até expirarem ou até que um purge as remova. Para as imagens que cada plano inclui, consulte Limites de Applications.

Recursos relacionados