Improve documentation and test examples

src/Makefile.am

@@ -45,7 +45,10 @@ TESTS = \
 	vtc/coverage.vtc \
 	vtc/sub.vtc \
 	vtc/sub-coalesce.vtc \
-	vtc/sub-body.vtc
+	vtc/sub-body.vtc \
+	vtc/ex1.vtc \
+	vtc/ex2.vtc \
+	vtc/ex3.vtc
 
 # Documentation
 

src/vmod_zipflow.vcc

@@ -23,7 +23,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;
@@ -37,6 +37,81 @@ 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
+=======================
+
 $Function VOID subreq(STRING url, STRING host=0)
 
 $Restrict client

src/vtc/ex1.vtc

+varnishtest "example 1"
+
+feature cmd "type curl && type unzip"
+
+server s1 {
+	rxreq
+	txresp -bodylen 1024
+} -start
+
+varnish v1 -vcl+backend {
+	import zipflow;
+
+	sub vcl_init {
+		zipflow.set_level(9);
+	}
+
+	sub vcl_deliver {
+		zipflow.meta("filename");
+		set resp.filters += " zipflow";
+	}
+} -start
+
+client c1 {
+	txreq
+	rxresp
+	expect resp.status == 200
+	expect resp.bodylen > 100
+} -run
+
+shell "curl -so t.zip -H 'Host: ${v1_addr}' http://${v1_addr}:${v1_port}/ && unzip -Z t.zip"
\ No newline at end of file

src/vtc/ex2.vtc

+varnishtest "example 2"
+
+feature cmd "type curl && type unzip"
+
+server s1 {
+	rxreq
+	txresp -bodylen 1024
+	rxreq
+	txresp -bodylen 1024
+} -start
+
+varnish v1 -vcl+backend {
+
+	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;
+		}
+	}
+} -start
+
+client c1 {
+	txreq -url "/zip"
+	rxresp
+	expect resp.status == 200
+	expect resp.bodylen > 100
+} -run
+
+shell "curl -so t.zip -H 'Host: ${v1_addr}' http://${v1_addr}:${v1_port}/zip && unzip -Z t.zip"
\ No newline at end of file

src/vtc/ex3.vtc

+varnishtest "example 3"
+
+server s1 {
+	rxreq
+	txresp -bodylen 1024
+	rxreq
+	txresp -bodylen 1024
+} -start
+
+varnish v1 -vcl+backend {
+
+	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;
+		}
+	}
+} -start
+
+client c1 {
+	txreq -req POST -url "/zip" -body { /file1 /file2 }
+	rxresp
+	expect resp.status == 200
+	expect resp.bodylen > 100
+} -run