4.0 rewrite

doc/sphinx/users-guide/vcl-built-in-subs.rst

@@ -22,7 +22,7 @@ yourself doing frequently.
 The vcl_recv subroutine may terminate with calling ``return()`` on one
 of the following keywords:
 
-  error code [reason]
+  error 
     Return the specified error code to the client and abandon the request.
 
   pass
@@ -31,56 +31,117 @@ of the following keywords:
   pipe
     Switch to pipe mode.  Control will eventually pass to vcl_pipe.
 
-  lookup
-    Look up the requested object in the cache.  Control will
-    eventually pass to vcl_hit or vcl_miss, depending on whether the
-    object is in the cache.  The ``bereq.method`` value will be set
-    to ``GET`` regardless of the value of ``req.method``.
+  hash
+    Continue processing the object as a potential candidate for
+    caching. Passes the control over to vcl_hash.
 
+  purge
+    Calls vcl_purge where the object will be purged.
 
 
-vcl_backend_fetch
-~~~~~~~~~~~~~~~~~
+vcl_pipe
+~~~~~~~~
 
-Called before sending the backend request. In this subroutine you
-typically alter the request before it gets to the backend.
+Called upon entering pipe mode.  In this mode, the request is passed
+on to the backend, and any further data from either client or backend
+is passed on unaltered until either end closes the
+connection. Basically, Varnish will degrade into a simple TCP proxy,
+shuffling bytes back and forth.
 
-.. XXX Return statements?
+The vcl_pipe subroutine may terminate with calling return() with one
+of the following keywords:
 
+  error code [reason]
+    Return the specified error code to the client and abandon the request.
 
-vcl_backend_response
-~~~~~~~~~~~~~~~~~~~
+  pipe
+    Proceed with pipe mode.
 
-Called after a document has been successfully retrieved from the backend.
+vcl_pass
+~~~~~~~~
 
-The vcl_backend_response subroutine may terminate with calling return() with one
-of the following keywords:
+Called upon entering pass mode.  In this mode, the request is passed
+on to the backend, and the backend's response is passed on to the
+client, but is not entered into the cache.  Subsequent requests
+submitted over the same client connection are handled normally.
 
-  deliver
-    Possibly insert the object into the cache, then deliver it to the
-    client.  Control will eventually pass to vcl_deliver.
+The vcl_pass subroutine may terminate with calling return() with one
+of the following keywords:
 
-  error code [reason]
+  error [reason]
     Return the specified error code to the client and abandon the request.
 
-  hit_for_pass
-    Pass in fetch. Passes the object without caching it. This will
-    create a so-called hit_for_pass object which has the side effect
-    that the decision not to cache will be cached. This is to allow
-    would-be uncachable requests to be passed to the backend at the
-    same time. The same logic is not necessary in vcl_recv because
-    this happens before any potential queueing for an object takes
-    place.  Note that the TTL for the hit_for_pass object will be set
-    to what the current value of beresp.ttl is. Control will be
-    handled to vcl_deliver on the current request, but subsequent
-    requests will go directly to vcl_pass based on the hit_for_pass
-    object.
+  pass
+    Proceed with pass mode.
+
+  restart
+    Restart the transaction. Increases the restart counter. If the number
+    of restarts is higher than *max_restarts* Varnish emits a guru meditation
+    error.
+
+
+vcl_hit
+~~~~~~~
+
+Called is a cache lookup is successful. 
 
   restart
     Restart the transaction. Increases the restart counter. If the number
     of restarts is higher than *max_restarts* Varnish emits a guru meditation
     error.
 
+  deliver
+    Deliver the object. Control passes to vcl_deliver.
+
+  error [reason]
+    Return the specified error code to the client and abandon the request.
+
+
+vcl_miss
+~~~~~~~~
+
+Called after a cache lookup if the requested document was not found in
+the cache.  Its purpose is to decide whether or not to attempt to
+retrieve the document from the backend, and which backend to use.
+
+The vcl_miss subroutine may terminate with calling return() with one
+of the following keywords:
+
+  error [reason]
+    Return the specified error code to the client and abandon the request.
+
+  pass
+    Switch to pass mode.  Control will eventually pass to vcl_pass.
+
+  fetch
+    Retrieve the requested object from the backend.  Control will
+    eventually pass to vcl_fetch.
+
+vcl_hash
+~~~~~~~~
+
+Called after vcl_recv to create a hash value for the request. This is
+used as a key to look up the object in Varnish.
+
+  lookup
+    Look up the object in cache.
+
+
+vcl_purge
+~~~~~~~~~
+
+Purge the object and all it's variants. Variants created when the
+backend issues a Vary response.
+
+  fetch
+    Execute the purge.
+
+  error
+    Fail the purge request. Typically you would call error here it
+    request doesn't pass the ACLs.
+
+
+
 vcl_deliver
 ~~~~~~~~~~~
 
@@ -97,83 +158,82 @@ keywords:
     of restarts is higher than *max_restarts* Varnish emits a guru meditation
     error.
 
-vcl_backend_error
-~~~~~~~~~~~~~~~~~
 
-Called when we hit an error, either explicitly or implicitly due to
-backend or internal errors.
+.. XXX
+.. vcl_error
+.. ~~~~~~~~~
 
-The vcl_backend_error subroutine may terminate by calling return with one of
-the following keywords:
+.. Not sure if we're going to keep this around.
 
-  deliver
-    Deliver the error object to the client.
 
-  restart
-    Restart the transaction. Increases the restart counter. If the number
-    of restarts is higher than *max_restarts* Varnish emits a guru meditation
-    error.
+vcl_backend_fetch
+~~~~~~~~~~~~~~~~~
 
+Called before sending the backend request. In this subroutine you
+typically alter the request before it gets to the backend.
 
-vcl_pipe
-~~~~~~~~
+  fetch
+    Fetch the object from the backend.
 
-Called upon entering pipe mode.  In this mode, the request is passed
-on to the backend, and any further data from either client or
-backend is passed on unaltered until either end closes the
-connection.
+  abandon
+    Abandon the backend request and generates an error.
+  
 
- The vcl_pipe subroutine may terminate with calling return() with one of
- the following keywords:
+vcl_backend_response
+~~~~~~~~~~~~~~~~~~~~
 
-  error code [reason]
-    Return the specified error code to the client and abandon the request.
+Called after an response has been successfully retrieved from the
+backend. The response is availble as beresp. Note that Varnish might
+not be talking to an actual client, so operations that require a
+client to be present are not allowed. Specifically there is no req
+object and restarts are not allowed.
 
-  pipe
-    Proceed with pipe mode.
+The vcl_backend_response subroutine may terminate with calling return() with one
+of the following keywords:
 
-vcl_pass
-~~~~~~~~
+  deliver
+    Possibly insert the object into the cache, then deliver it to the
+    Control will eventually pass to vcl_deliver. Caching is dependant
+    on beresp.cacheable.
 
-Called upon entering pass mode.  In this mode, the request is passed
-on to the backend, and the backend's response is passed on to the
-client, but is not entered into the cache.  Subsequent requests
-submitted over the same client connection are handled normally.
+  error [reason]
+    Return the specified error code to the client and abandon the request.
 
-The vcl_pass subroutine may terminate with calling return() with one
-of the following keywords:
+  retry
+    Retry the backend transaction. Increases the retries counter. If the number
+    of retries is higher than *max_retries* Varnish emits a guru meditation
+    error.
 
-  error code [reason]
-    Return the specified error code to the client and abandon the request.
+vcl_backend_error
+~~~~~~~~~~~~~~~~~
 
-  pass
-    Proceed with pass mode.
+This subroutine is called if we fail the backend fetch. 
 
-  restart
-    Restart the transaction. Increases the restart counter. If the number
-    of restarts is higher than *max_restarts* Varnish emits a guru meditation
-    error.
+  deliver
+    Deliver the error.
 
-vcl_miss
-~~~~~~~~
+  retry
+    Retry the backend transaction. Increases the retries counter. If the number
+    of retries is higher than *max_retries* Varnish emits a guru meditation
+    error.
 
-Called after a cache lookup if the requested document was not found in
-the cache.  Its purpose is to decide whether or not to attempt to
-retrieve the document from the backend, and which backend to use.
 
-The vcl_miss subroutine may terminate with calling return() with one
-of the following keywords:
+vcl_backend_error
+~~~~~~~~~~~~~~~~~
 
-  error code [reason]
-    Return the specified error code to the client and abandon the request.
+Called when we hit an error, either explicitly or implicitly due to
+backend or internal errors.
 
-  pass
-    Switch to pass mode.  Control will eventually pass to vcl_pass.
+The vcl_backend_error subroutine may terminate by calling return with one of
+the following keywords:
 
-  fetch
-    Retrieve the requested object from the backend.  Control will
-    eventually pass to vcl_fetch.
+  deliver
+    Deliver the error object to the client.
 
+  retry
+    Retry the backend transaction. Increases the retries counter. If the number
+    of retries is higher than *max_retries* Varnish emits a guru meditation
+    error.
 
 
 vcl_init