Update README (auto-generated)

README.rst

@@ -23,9 +23,17 @@ SYNOPSIS
 
   import zipflow [as name] [from "path"]
   
+  VOID subreq(STRING url, STRING host)
+  
+  VOID subreqs_from_body(ENUM which)
+  
+  BOOL is_subreq()
+  
+  VOID bundle(BOOL)
+  
   VOID set_level(INT level)
   
-  VOID meta(STRING name, STRING mode, TIME atime, TIME mtime)
+  VOID meta([STRING name], [STRING mode], [TIME atime], [TIME mtime])
   
 NOTE
 ====
@@ -41,7 +49,7 @@ This module provides a Varnish Delivery Processor (VDP) interface to
 Mark Adler's `zipflow`_ library to package and compress
 responses into the ZIP format.
 
-Example
+Example: Send the response body as a zip file containing "filename"
     ::
 
 	import zipflow;
@@ -55,11 +63,202 @@ Example
 		set resp.filters += " zipflow";
 	}
 
+Example: Create a two subrequests for other URLs, which are bundled
+into the ZIP response
+    ::
+
+	import zipflow;
+
+	sub vcl_recv {
+		if (req.url == "/zip") {
+			return (synth(1200));
+		}
+	}
+
+	sub synth_zipflow {
+		if (zipflow.is_subreq()) {
+			return;
+		}
+		# activate zipflow
+		set resp.filters = "zipflow";
+		set resp.body = " "; // REQUIRED!
+
+		# do not put this body into the zip
+		zipflow.bundle(false);
+
+		# create two subrequests to put into the zip
+		zipflow.subreq("/file1");
+		zipflow.subreq("/file2");
+		return (deliver);
+	}
+
+	sub vcl_synth {
+		if (resp.status == 1200) {
+			call synth_zipflow;
+		}
+	}
+
+Example: Read URLs to bundle into the ZIP from the request body
+    ::
+
+	import zipflow;
+	import std;
+
+	sub vcl_recv {
+		if (req.url == "/zip" && req.method == "POST") {
+			if (! std.cache_req_body(1M)) {
+				return (synth(400, "Need request body"));
+			}
+			return (synth(1200));
+		}
+	}
+
+	sub synth_zipflow {
+		if (zipflow.is_subreq()) {
+			return;
+		}
+		# activate zipflow
+		set resp.filters = "zipflow";
+		set resp.body = " "; // REQUIRED!
+
+		# do not put this body into the zip
+		zipflow.bundle(false);
+
+		# read urls from request body
+		zipflow.subreqs_from_body(req_body);
+		return (deliver);
+	}
+
+	sub vcl_synth {
+		if (resp.status == 1200) {
+			call synth_zipflow;
+		}
+	}
+
+VCL INTERFACE REFERENCE
+=======================
+
+**NOTE** Varnish-Cache does not support content generated by Varnish
+Delivery Processors if there is not response body to be sent. This
+means that, on the top level, a response body must always be present,
+as illustrated by ``set resp.body = " ";`` in the examples above.
+
+.. _zipflow.subreq():
+
+VOID subreq(STRING url, STRING host=0)
+--------------------------------------
+
+
+
+Restricted to: ``client``.
+
+Issue a sub requets to *host*/*uri* when the VDP runs, similar to ESI
+processing.
+
+If *host* is omitted (default), it is taken from the parent request.
+
+This function can be called any number of times to add multiple
+files, it can even be called from a sub request, which is to say that
+more files can be added while requests for files are processed.
+
+The sub request can be identified using `zipflow.is_subreq()`_. In the
+sub request, `zipflow.set_level()`_ and `zipflow.meta()`_ should be
+used to control how zipflow handles the body.
+
+Only sub requests with reponse status 200 will be included in the
+resulting zip file.
+
+.. _zipflow.subreqs_from_body():
+
+VOID subreqs_from_body(ENUM {req_body, resp_body} which)
+--------------------------------------------------------
+
+
+
+Restricted to: ``client``.
+
+*Note* this function should eventually be superseded with something
+more versatile.
+
+Parse the given body for tokens in one of the following formats,
+separated by any whitespace (``\\r\\n\\t\\s``)
+
+* ``http://``\ *host*\ *url*
+* ``https://``\ *host*\ *url*
+* ``//``\ *host*\ *url*
+* *url*
+
+with *host* containing any non-whitespace character except for ``/``
+and *url* starting with ``/`` and run a sub request for each token as
+if ``subreq(``\ *url*\ ``, ``\ *host*\ ``)`` was invoced, but not
+using any workspace memory.
+
+.. _RFC 3965: https://www.ietf.org/rfc/rfc3986.txt
+
+*host* may not be empty. The syntactic ambiguity prevents *urls*
+ starting with ``///``.
+
+(Note: *host* and *url* are used in varnish-cache terminology, in `RFC
+3965`_ parlance, *host* is called authority and *url* is a path. The
+``//`` scheme is called a network-path reference)
+
+This function can only be called from the top level, that is, not from
+a sub request.
+
+For ``which = resp_body``, bundling of the current body is turned
+off.
+
+For ``which = req_body``, ``std.cache_req_body()`` must have been
+called earlier.
+
+The order of subrequests is:
+
+* `zipflow.subreq()`_ initiated by the top level request
+
+* ``resp_body``
+
+  * each subreq followed by any `zipflow.subreq()`_ initiated from it
+
+* ``req_body``
+
+  * each subreq followed by any `zipflow.subreq()`_ initiated from it
+
+Only sub requests with reponse status 200 will be included in the
+resulting zip file.
+
+.. _zipflow.is_subreq():
+
+BOOL is_subreq()
+----------------
+
+
+
+Restricted to: ``client``.
+
+True if the current request is a zipflow sub request.
+
+.. _zipflow.bundle():
+
+VOID bundle(BOOL)
+-----------------
+
+
+
+Restricted to: ``client``.
+
+By default, any content handled by zipflow, be it in the parent or sub
+reuqest, is bundled in the resulting ZIP file. This function can be
+used to diable or re-enable bundling of the request's body.
+
 .. _zipflow.set_level():
 
 VOID set_level(INT level)
 -------------------------
 
+
+
+Restricted to: ``vcl_init``, ``client``.
+
 Set the (default) compression level for the zipflow filter.
 
 Valid values for `level` are -1 to select the default compression
@@ -79,29 +278,40 @@ When used elsewhere, sets the level for the current task. Calls from
 
 .. _zipflow.meta():
 
-VOID meta(STRING name, STRING mode, TIME atime, TIME mtime)
------------------------------------------------------------
+VOID meta([STRING name], [STRING mode], [TIME atime], [TIME mtime])
+-------------------------------------------------------------------
 
 ::
 
    VOID meta(
-      STRING name,
-      STRING mode="0644",
-      TIME atime=0,
-      TIME mtime=0
+      [STRING name],
+      [STRING mode],
+      [TIME atime],
+      [TIME mtime]
    )
 
-Set zip metadata for the currently streamed object:
+Set zip metadata for the currently streamed object. Defaults apply if
+`zipflow.meta()`_ is not called, or arguments are not given.
 
 * `name`: Filename
 
-* `mode`: UNIX mode bits, default to 0644
+  Default: Last component of ``req.url`` or, if it is empty,
+  ``unnamed_file``.
+
+* `mode`: UNIX mode bits
+
+  This argument is of string type and interpreted as *octal*.
+
+  Default: ``0644``
+
+* `atime`: Access time
 
-  Note: This argument is of string type and interpreted as *octal*.
+  Default: ``now``.
 
-* `atime`: Access time, defaults to ``now``.
+* `mtime`: Modification time
 
-* `mtime`: Modification time, defaults to ``now``.
+  Default: ``Last-Modified`` header of the response or, if it is not
+  available, ``now``.
 
 SEE ALSO
 ========