Purge (purge/softpurge)

Description

The purge vmod contains functions that offer a finer-grained control than the purge transition in sub vcl_recv. The functions can only be called from sub vcl_hit or sub vcl_miss and they should in general be used in both to ensure that all variants of a same object are taken care of.

vmod_softpurge

vmod_softpurge is older and offers similar functionality to the newer vmod_purge. It is recommended to upgrade to vmod_purge if possible, as its API is more complete.

softpurge.softpurge()

VOID softpurge()

The only function of the vmod performs a soft purge, setting the TTL of the object to 0. It must be called both from sub vcl_hit and sub vcl_miss to make sure all variants of the chosen object are reset.

Migration

softpurge.softpurge() is functionally equivalent to purge.soft(), making the migration easy:

1. Import purge instead of softpurge;
2. Replace softpurge.softpurge() calls with purge.soft().

Example

# make sure to block unauthorized IP addresses trying to purge
sub vcl_recv {
  if (req.method == "PURGE") {
    if (client.ip !~ purge_acl) {
      return (synth(405));
    } else {
      return (hash);
    }
  }
}

# subroutine to kill the object (called from vcl_hit and vcl_miss)
# here, ttl and grace are zero'ed, but keep is set to one day so that the object
# must be revalidated before being sent to the client
sub my_purge {
  set req.http.purged = purge.soft(ttl = 0s, grace = 0s, keep = 1d);
  return (synth(200));
}

sub vcl_hit {
  if (req.method == "PURGE") {
    call my_purge;
  }
}

sub vcl_miss {
  if (req.method == "PURGE") {
    call my_purge;
  }
}

# we are sent here from my_purge, and we can now copy the purged header
# containing the number of purged objects to the response
sub vcl_synth {
  if (req.method == "PURGE") {
    set resp.http.purged = req.http.purged;
    return (deliver);
  }
}

API

hard

INT hard()

This is equivalent to return(purge) but explicitly called from

sub vcl_hit and sub vcl_miss. It returns the number of purged objects.

set req.http.purged = purge.hard();

Arguments: None

Type: Function

Returns: Int

Restricted to: vcl_hit, vcl_miss

soft

INT soft(DURATION ttl = 0, DURATION grace = -1, DURATION keep = -1)

Sets the ttl, grace and keep. By default, ttl is set to 0 with grace and keep periods left untouched. Setting grace or keep to a negative value or to something higher than the objects current value leaves them untouched. Setting all three parameters to 0 is equivalent to a hard purge. Returns the number of soft-purged objects.

A soft-purge can only decrease the lifetime of an object. Let’s consider an object in cache created with ttl, grace, and keep of 60 seconds each:

purge.soft(ttl = 0s, grace = -1s, keep = -1s);

• If the object is fresh, the ttl is reduced to 0 seconds and the object expires after 120 seconds.
• If the object is stale, the expiry time is not changed.

purge.soft(ttl = 0s, grace = 10s, keep = 10s);

• If the object is fresh, the ttl is reduced to 0 seconds, grace and keep are reduced to 10 seconds. The object expires after 20 seconds.
• If the object has been stale for 5 seconds, grace is reduced to 5 seconds and keep is reduced to 10 seconds. The object expires after 15 seconds.
• If the object has been stale for 15 seconds, grace is reduced to 0 seconds and keep is reduced to 5 seconds. The object expires after 5 seconds.
• If the object has been stale for 20 seconds or more, the object immediately expires.

purge.soft(ttl = 10s, grace = -1s, keep = -1s);

• If the object has been fresh for 5 seconds, the ttl is reduced to 10 seconds. The object expires after 130 seconds.
• If the object has been fresh for 55 seconds, the ttl is not changed. The object expires after 125 seconds.
• If the object is stale, the expiry time is not changed.

When the expiry time of an object is reduced due to a softpurge, an EXP_Reduce entry is logged under the ExpKill VSL tag. If a softpurge does not reduce the expiry time of an object, an EXP_Unchanged entry is logged instead.

Arguments:

• ttl accepts type DURATION with a default value of 0 optional

• grace accepts type DURATION with a default value of empty. optional

• keep accepts type DURATION with a default value of empty. optional

Type: Function

Returns: Int

Restricted to: vcl_hit, vcl_miss

Availability

The purge VMOD is available in Varnish Enterprise version 6.0.0r0 and later.