Search
Varnish Cache Plus

Image

Description

The image vmod provides a tool for image modification and optimization.

Example

Convert to WebP

import image;
import headerplus;

sub vcl_recv {
	if (req.http.Accept ~ "image/webp") {
		set req.http.X-Varnish-Webp = "enabled";
	} else {
		unset req.http.X-Varnish-Webp;
	}
}

sub vcl_backend_response {
	if ((beresp.http.Content-Type == "image/jpeg" ||
		beresp.http.Content-Type == "image/png")
		&& bereq.retries == 0 # Part of error handling
		&& bereq.http.X-Varnish-Webp)
	{
		image.webp();
		headerplus.init(beresp);
		headerplus.attr_set("Vary", "X-Varnish-Webp");
		headerplus.write();
		set bereq.http.X-Varnish-Webp = "active";
	}
}

The above uses Vary on a self-maintained header to facilitate serving both the original image and the webp version as different variants.

The example can be further extended to include error handling. To be precise, we want to handle the case where we in sub vcl_backend_response have requested a convertion to webp, and we then end up in sub vcl_backend_error. In such cases, the most likely reason for the failure is an error reported by the JPEG, PNG or Webp libraries, so we simply retry the fetch without attempting to convert.

sub vcl_backend_error {
	if (bereq.retries == 0 && bereq.http.X-Varnish-Webp == "active") {
		# Make filtering easier in varnishlog or varnishncsa
		set bereq.http.X-Varnish-Webp = "failed";
		# Getting here is usually because convertion failed. On the
		# next go, we will not try to convert
		return (retry);
	}
}

Since a failure to convert can only happen after sub vcl_backend_response has finished, the VMOD turns off streaming (equivalent to set beresp.do_stream = false; in VCL). This is needed to allow processing to end up in sub vcl_backend_error when an error occurs.

API

webp

VOID webp([INT quality = 75], [INT resize_width = 0], [INT resize_height = 0], [BOOL aspect_lock = 0], [INT crop_x = 0], [INT crop_y = 0], [INT crop_width = 0], [INT crop_height = 0], [BOOL lossless = 0], [INT lossless_level = 6])

Convert an image to the WebP format and store it in cache. Optionally scale, resize, crop, or change the quality of conversion. Scaling is done by using only one of resize_width or resize_height. quality and lossless are mutually exclusive options. The supported content types to convert are image/png and image/jpeg. When called this function disables streaming. It should not be re-enabled for proper functionality.

Note: The area to crop is defined by X,Y coordinates from the top left corner and then the desired width and height.

Note: When using this function to both crop and rescale an image, the crop will take place prior to rescaling.

Note: quality is a number between 0 and 100, a lower number will result in a smaller size but lower quality. mode is a number between 0 and 9, a lower number is faster but produces a larger file size.

Note: aspect_lock will ensure that the resulting image obeys the aspect ratio of the original image. If the desired resize values do not obey this ratio then the correct dimensions will be calculated using the smallest of the two input values, with resize_width being prioritized if both values are identical.

Arguments:

  • quality accepts type INT with a default value of 75 optional

  • resize_width accepts type INT with a default value of 0 optional

  • resize_height accepts type INT with a default value of 0 optional

  • aspect_lock accepts type BOOL with a default value of 0 optional

  • crop_x accepts type INT with a default value of 0 optional

  • crop_y accepts type INT with a default value of 0 optional

  • crop_width accepts type INT with a default value of 0 optional

  • crop_height accepts type INT with a default value of 0 optional

  • lossless accepts type BOOL with a default value of 0 optional

  • lossless_level accepts type INT with a default value of 6 optional

Type: Function

Returns: None

Availability

The image VMOD is available in the varnish-plus-vmods-extras package.