Weserv Images#

O módulo weserv redimensiona, recorta e converte imagens em tempo real. Ele faz parte do projeto weserv/images, o código por trás do serviço wsrv.nl. O módulo funciona em um de dois modos:

  • proxy — obtém a imagem do servidor remoto indicado no parâmetro url da query string;

  • filter — processa imagens em respostas geradas por outros handlers, como arquivos estáticos.

Em ambos os modos, a query string define o processamento: w e h definem a largura e a altura de destino, fit define como a imagem se ajusta a elas, output define o formato de saída, e assim por diante. A lista completa de parâmetros está na documentação do wsrv.nl.

Instalação#

Para instalar o módulo, use um dos seguintes pacotes:

  • Angie: angie-module-weserv-images

  • Angie PRO: angie-pro-module-weserv-images

Diretivas#

As principais diretivas do módulo:

  • weserv — habilita o módulo em um location e seleciona o modo, proxy ou filter

  • weserv_deny_ip — proíbe a obtenção de imagens dos endereços ou intervalos CIDR indicados; aplica-se somente a endereços IP escritos diretamente no parâmetro url, não a nomes de host

  • weserv_connect_timeout, weserv_send_timeout, weserv_read_timeout — definem os timeouts para conectar ao servidor remoto, enviar a requisição a ele e ler a sua resposta

  • weserv_max_size — limita o tamanho de uma imagem a ser processada

  • weserv_limit_input_pixels, weserv_limit_output_pixels — limitam o número de pixels nas imagens de entrada e de saída

  • weserv_savers — lista os formatos de saída que o parâmetro output pode solicitar

  • weserv_quality — define a qualidade de saída padrão; diretivas como weserv_jpeg_quality e weserv_webp_quality a substituem para um único formato

No modo proxy, a variável $weserv_response_length contém o tamanho, em bytes, da imagem original obtida; no modo filter, a variável não é definida.

Todas as diretivas, com seus valores padrão, estão descritas na documentação do módulo.

Carregando o módulo#

Para usar o módulo, ele deve ser carregado no contexto main{}:

load_module modules/ngx_weserv_module.so;

Exemplo de configuração#

server {
    listen 80;

    server_name images.weserv.local;

    root /var/www/imagesweserv/public;

    location / {
        weserv proxy;

        add_header X-Upstream-Response-Length $weserv_response_length;
    }

    location /static/ {
        weserv filter;

        alias /var/www/imagesweserv/public/;
    }
}

Aqui, as requisições com o parâmetro url são processadas no modo proxy, e, para as requisições em /static/, o módulo processa os arquivos do diretório /var/www/imagesweserv/public/ no modo filter. Uma requisição a / sem url não é processada pelo módulo e recebe um arquivo estático de root.

O Angie resolve os nomes de host em url com seu próprio resolvedor; por padrão, ele consulta os servidores de nomes listados em /etc/resolv.conf, e o arquivo /etc/hosts não é consultado. Para usar outros servidores DNS, defina a diretiva resolver. Endereços IP em url não precisam de resolução.

Demonstração#

Suponha que um servidor em 127.0.0.1:8081 sirva a imagem original sample.png (400 × 300 pixels, 2351 bytes) e que o mesmo arquivo esteja em /var/www/imagesweserv/public/.

No modo proxy, o módulo obtém a imagem indicada em url e a dimensiona para a largura w, mantendo a proporção:

$ curl -s -D - -o out.png 'http://localhost/?url=127.0.0.1:8081/sample.png&w=100'
HTTP/1.1 200 OK
...
Content-Type: image/png
Content-Length: 15633
Content-Disposition: inline; filename=image.png
Link: <http://127.0.0.1:8081/sample.png>; rel="canonical"
...
X-Upstream-Response-Length: 2351

$ file out.png
out.png: PNG image data, 100 x 75, 8-bit/color RGB, non-interlaced

O cabeçalho Link aponta para a imagem original, e X-Upstream-Response-Length traz o seu tamanho, que a configuração de exemplo adiciona a partir de $weserv_response_length. O prefixo http:// em url é opcional; adicionar &output=jpg à mesma requisição retorna uma imagem JPEG.

No modo filter, os mesmos parâmetros se aplicam a um arquivo local; aqui a imagem é recortada para preencher um quadrado de 50 × 50 e convertida para WebP:

$ curl -s -D - -o small.webp 'http://localhost/static/sample.png?w=50&h=50&fit=cover&output=webp'
HTTP/1.1 200 OK
...
Content-Type: image/webp
Content-Length: 250
...

O arquivo small.webp é uma imagem WebP de 50 × 50. A resposta não tem o cabeçalho X-Upstream-Response-Length: o location /static/ não o adiciona, e no modo filter $weserv_response_length não é definida.

Quando o módulo não consegue retornar uma imagem, ele responde com um erro em JSON:

$ curl -s 'http://localhost/?url=127.0.0.1:8081/missing.png'
{"status":"error","code":404,"message":"The requested URL returned error: 404"}

Informações adicionais#

Versão: v5.1.0

Documentação detalhada e código-fonte estão disponíveis em: weserv/images