allow the *code() functions in vcl_init and vcl_fini

this means that Varnish > 5.0.0 must be enforced, since workspace
is not available in init/fini in earlier versions

README.rst

@@ -65,9 +65,9 @@ DESCRIPTION
 
 This Varnish module (VMOD) supports binary-to-text encodings and
 decodings for the VCL data type BLOB, which may contain arbitrary data
-of any length. Currently (as of Varnish 4.1.1), BLOBs may only be used
-as arguments of VMOD functions; so this module is meant to facilitate
-the use of other VMODs.
+of any length. Currently BLOBs may only be used as arguments of VMOD
+functions; so this module is meant to facilitate the use of other
+VMODs.
 
 ENCODING SCHEMES
 ================
@@ -179,23 +179,22 @@ uppercase, respectively.
 CONTENTS
 ========
 
-* Object blob
-* STRING blob.encode(ENUM)
-* BLOB blob.get()
-* BLOB decode(ENUM, STRING_LIST)
-* BLOB decode_n(INT, ENUM, STRING_LIST)
-* STRING encode(ENUM, BLOB)
-* STRING transcode(ENUM, ENUM, STRING_LIST)
-* STRING transcode_n(INT, ENUM, ENUM, STRING_LIST)
+* BLOB decode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL}, STRING)
+* BLOB decode_n(INT, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL}, STRING)
+* STRING encode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC}, BLOB)
+* STRING transcode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL}, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC}, STRING)
+* STRING transcode_n(INT, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL}, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC}, STRING)
 * STRING version()
+* blob(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL}, STRING)
 
 .. _func_decode:
 
-BLOB decode(ENUM, STRING_LIST)
-------------------------------
+decode
+------
 
-Prototype
-	BLOB decode(ENUM decoding, STRING_LIST encoded)
+::
+
+	BLOB decode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL} decoding="IDENTITY", STRING encoded)
 
 Returns the BLOB derived from the string ``encoded`` according to the
 scheme specified by ``decoding``.
@@ -214,11 +213,12 @@ Example::
 
 .. _func_decode_n:
 
-BLOB decode_n(INT, ENUM, STRING_LIST)
--------------------------------------
+decode_n
+--------
 
-Prototype
-	BLOB decode_n(INT n, ENUM decoding, STRING_LIST encoded)
+::
+
+	BLOB decode_n(INT n, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL} decoding="IDENTITY", STRING encoded)
 
 Same as ``decode()``, but only decode the first ``n`` characters of
 the decoded string. If ``n`` is greater than the length of the string,
@@ -226,11 +226,12 @@ then return the same result as ``decode()``.
 
 .. _func_encode:
 
-STRING encode(ENUM, BLOB)
--------------------------
+encode
+------
+
+::
 
-Prototype
-	STRING encode(ENUM encoding, BLOB blob)
+	STRING encode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC} encoding="IDENTITY", BLOB blob)
 
 Returns a string representation of the BLOB ``blob`` as specifed by
 ``encoding``.
@@ -254,11 +255,12 @@ Example::
 
 .. _func_transcode:
 
-STRING transcode(ENUM, ENUM, STRING_LIST)
------------------------------------------
+transcode
+---------
 
-Prototype
-	STRING transcode(ENUM decoding, ENUM encoding, STRING_LIST encoded)
+::
+
+	STRING transcode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL} decoding="IDENTITY", ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC} encoding="IDENTITY", STRING encoded)
 
 Translates from one encoding to another, by first decoding the string
 ``encoded`` according to the scheme ``decoding``, and then returning
@@ -286,21 +288,23 @@ Example::
 
 .. _func_transcode_n:
 
-STRING transcode_n(INT, ENUM, ENUM, STRING_LIST)
-------------------------------------------------
+transcode_n
+-----------
+
+::
 
-Prototype
-	STRING transcode_n(INT n, ENUM decoding, ENUM encoding, STRING_LIST encoded)
+	STRING transcode_n(INT n, ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL} decoding="IDENTITY", ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC} encoding="IDENTITY", STRING encoded)
 
 Same as ``transcode()``, but only from the first ``n`` characters of
 the encoded string.
 
 .. _func_version:
 
-STRING version()
-----------------
+version
+-------
+
+::
 
-Prototype
 	STRING version()
 
 Returns the version string for this VMOD.
@@ -311,13 +315,12 @@ Example::
 
 .. _obj_blob:
 
-Object blob
-===========
-
+blob
+----
 
-Prototype::
+::
 
-	new OBJ = blobcode.blob(ENUM decoding, STRING_LIST encoded)
+	new OBJ = blob(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEX,URL} decoding="IDENTITY", STRING encoded)
 
 Creates an object that contains the BLOB derived from the string
 ``encoded`` according to the scheme ``decoding``.
@@ -334,10 +337,11 @@ Example::
 
 .. _func_blob.get:
 
-BLOB blob.get()
----------------
+blob.get
+--------
+
+::
 
-Prototype
 	BLOB blob.get()
 
 Returns the BLOB created by the constructor.
@@ -355,11 +359,12 @@ Example::
 
 .. _func_blob.encode:
 
-STRING blob.encode(ENUM)
-------------------------
+blob.encode
+-----------
 
-Prototype
-	STRING blob.encode(ENUM encoding)
+::
+
+	STRING blob.encode(ENUM {IDENTITY,BASE64,BASE64URL,BASE64URLNOPAD,HEXUC,HEXLC,URLUC,URLLC} encoding="IDENTITY")
 
 Returns an encoding of BLOB created by the constructor, according to
 the scheme ``encoding``.
@@ -399,11 +404,6 @@ string is an illegal format for the decoding scheme.
 If the ``blob`` object constructor fails, then the VCL program will
 fail to load, and the VCC compiler will emit an error message.
 
-The VMOD functions -- ``encode()``, ``decode()`` and ``transcode()``
--- may not be called in ``vcl_init()`` or ``vcl_fini()`` (since a
-workspace must be available). Use in ``vcl_init()`` will also cause
-the VCL program to fail with a VCC compiler error.
-
 If any of the VMOD's methods or functions fail at runtime, then an
 error message will be written to the Varnish log using the tag
 ``VCL_Error``. The encoders and decoders return ``NULL`` on failure;
@@ -413,8 +413,9 @@ to a header, then the header will not be set.
 REQUIREMENTS
 ============
 
-This VMOD requires at least Varnish version 4.1.2, and has been tested
-with versions through 5.0.0.
+This version of the VMOD requires at least Varnish version 5.0.0. (See
+branch 4.1 in the project repository for versions that are compatible
+with Varnish since 4.1.2.)
 
 Perl 5 is required for the build.
 
@@ -502,17 +503,27 @@ HISTORY
 
 * version 0.1: initial version
 
+* version 1.0: compatible with Varnish versions since 4.1.2
+
+* version 2.0: compatible with Varnish versions since 5.0.0
+
 SEE ALSO
 ========
 
 * varnishd(1)
 * vcl(7)
+* project repository: https://code.uplex.de/uplex-varnish/libvmod-blobcode
 * VMOD digest: https://github.com/varnish/libvmod-digest
 
 COPYRIGHT
 =========
 
-This document is licensed under the same conditions as the
-libvmod-blobcode project. See LICENSE for details.
+::
+
+  This document is licensed under the same conditions as the
+  libvmod-blobcode project. See LICENSE for details.
+ 
+  Authors: Nils Goroll <nils.goroll@uplex.de>
+           Geoffrey Simmons <geoffrey.simmons@uplex.de>
+ 
 
-* Copyright (c) 2015-2016 UPLEX Nils Goroll Systemoptimierung

configure.ac

 AC_PREREQ(2.59)
 AC_COPYRIGHT([Copyright (c) 2015-2016 UPLEX - Nils Goroll Systemoptimierung])
-AC_INIT([libvmod-blobcode], [0.1])
+AC_INIT([libvmod-blobcode], [2.0])
 AC_CONFIG_MACRO_DIR([m4])
 m4_ifndef([VARNISH_VMOD_INCLUDES], AC_MSG_ERROR([Need varnish.m4 -- see README.rst]))
 AC_CONFIG_SRCDIR(src/vmod_blobcode.vcc)
@@ -65,7 +65,8 @@ AS_VAR_IF([$1], [""], [$5], [$4])dnl
 ])# PKG_CHECK_VAR
 ])
 
-PKG_CHECK_MODULES([libvarnishapi], [varnishapi])
+PKG_CHECK_MODULES([libvarnishapi], [varnishapi = trunk], [],
+                  [PKG_CHECK_MODULES([libvarnishapi], [varnishapi >= 5.0.0])])
 PKG_CHECK_VAR([LIBVARNISHAPI_PREFIX], [varnishapi], [prefix])
 PKG_CHECK_VAR([LIBVARNISHAPI_DATAROOTDIR], [varnishapi], [datarootdir])
 PKG_CHECK_VAR([LIBVARNISHAPI_BINDIR], [varnishapi], [bindir])

src/tests/usage.vtc

-# looks like -*- perl -*-
+# looks like -*- vcl -*-
 
 varnishtest "test permitted use of functions in vcl_subs"
 
 varnish v1 -vcl { backend b { .host="${bad_ip}"; } } -start
 
-varnish v1 -errvcl {vmod blobcode error: decode() is illegal in vcl_init() and vcl_fini().vmod blobcode error: encode() is illegal in vcl_init() and vcl_fini().} {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
+# The blob.get() method and the *code() functions are legal in every VCL sub
+varnish v1 -vcl {
+        import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
+        import std;
 	backend b { .host="${bad_ip}"; }
-	sub vcl_init {
-	  new err = blobcode.blob(IDENTITY, blobcode.encode(IDENTITY,
-				  blobcode.decode(IDENTITY, "x")));
-	}
-}
 
-varnish v1 -errvcl {vmod blobcode error: transcode() is illegal in vcl_init() and vcl_fini().} {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
-	backend b { .host="${bad_ip}"; }
-	sub vcl_init {
-	  new err = blobcode.blob(IDENTITY,
-				  blobcode.transcode(IDENTITY, IDENTITY, "x"));
-	}
-}
-
-varnish v1 -errvcl {vmod blobcode error: encode() is illegal in vcl_init() and vcl_fini().} {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
-	backend b { .host="${bad_ip}"; }
 	sub vcl_init {
+	  new encdec = blobcode.blob(IDENTITY, blobcode.encode(IDENTITY,
+				     blobcode.decode(IDENTITY, "x")));
+	  new xcode = blobcode.blob(IDENTITY,
+				    blobcode.transcode(IDENTITY,IDENTITY,"x"));
 	  new b1 = blobcode.blob(IDENTITY, "foo");
 	  new b2 = blobcode.blob(IDENTITY, blobcode.encode(IDENTITY, b1.get()));
-	}
-}
-
-varnish v1 -errvcl {vmod blobcode error: decode() is illegal in vcl_init() and vcl_fini().vmod blobcode error: encode() is illegal in vcl_init() and vcl_fini().} {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
-	backend b { .host="${bad_ip}"; }
-	sub vcl_init {
-	  new err = blobcode.blob(IDENTITY, blobcode.encode(IDENTITY,
+	  new decn = blobcode.blob(IDENTITY, blobcode.encode(IDENTITY,
 				  blobcode.decode_n(1, IDENTITY, "x")));
+	  new xcoden = blobcode.blob(IDENTITY,
+				     blobcode.transcode_n(1, IDENTITY, IDENTITY,
+						          "x"));
 	}
-}
-
-varnish v1 -errvcl {vmod blobcode error: transcode() is illegal in vcl_init() and vcl_fini().} {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
-	backend b { .host="${bad_ip}"; }
-	sub vcl_init {
-	  new err = blobcode.blob(IDENTITY,
-				  blobcode.transcode_n(1, IDENTITY, IDENTITY,
-						       "x"));
-	}
-}
-
-# The *code() functions are legal in every other VCL sub
-varnish v1 -vcl {
-	import blobcode from "${vmod_topbuild}/src/.libs/libvmod_blobcode.so";
-	backend b { .host="${bad_ip}"; }
 
 	sub vcl_recv {
 	  set req.http.x = blobcode.encode(IDENTITY,
@@ -175,4 +144,12 @@ varnish v1 -vcl {
 	  set bereq.http.x = blobcode.transcode_n(1, IDENTITY, IDENTITY, "foo");
 	}
 
+	sub vcl_fini {
+	  std.log(blobcode.encode(IDENTITY, blobcode.decode(IDENTITY, "foo")));
+	  std.log(blobcode.transcode(IDENTITY, IDENTITY, "foo"));
+	  std.log(blobcode.encode(IDENTITY,
+                                  blobcode.decode_n(1, IDENTITY, "foo")));
+          std.log(blobcode.transcode_n(1, IDENTITY, IDENTITY, "foo"));
+          std.log(blobcode.encode(IDENTITY, b1.get()));
+	}
 }

src/vmod_blobcode.c

@@ -134,11 +134,6 @@ static const struct vmod_blobcode_fptr {
 #define ERRNOMEM(ctx, msg) \
 	ERR((ctx), msg ", out of space")
 
-#define INIT_FINI(ctx) (((ctx)->method & (VCL_MET_INIT | VCL_MET_FINI)) != 0)
-
-#define ILLEGAL(ctx, m) \
-	ERR((ctx), m " is illegal in vcl_init() and vcl_fini().")
-
 static const struct vmod_priv null_blob[1] =
 {
 	{
@@ -197,6 +192,22 @@ err_decode(VRT_CTX, const char *enc)
 	}
 }
 
+/* Event function */
+
+int __match_proto__(vmod_event_f)
+event(VRT_CTX, struct vmod_priv *priv, enum vcl_event_e e)
+{
+	if (e != VCL_EVENT_LOAD)
+		return 0;
+	if (VRT_MAJOR_VERSION < 5) {
+		AN(ctx->msg);
+		VSB_cat(ctx->msg, "vmod blobcode: this version not compatible "
+			"with Varnish versions < 5.0.0");
+		return 1;
+	}
+	return 0;
+}
+
 /* Objects */
 
 VCL_VOID __match_proto__(td_blobcode_blob__init)
@@ -409,11 +420,6 @@ decode(VRT_CTX, VCL_INT n, VCL_ENUM decs,
 
 	CHECK_OBJ_NOTNULL(ctx, VRT_CTX_MAGIC);
 	AENC(dec);
-
-	if (INIT_FINI(ctx)) {
-		ILLEGAL(ctx, "decode()");
-		return NULL;
-	}
 	CHECK_OBJ_NOTNULL(ctx->ws, WS_MAGIC);
 
 	snap = WS_Snapshot(ctx->ws);
@@ -494,10 +500,6 @@ encode(VRT_CTX, enum encoding enc, VCL_BLOB b) {
 	CHECK_OBJ_NOTNULL(ctx, VRT_CTX_MAGIC);
 	AENC(enc);
 
-	if (INIT_FINI(ctx)) {
-		ILLEGAL(ctx, "encode()");
-		return NULL;
-	}
 	if (b == NULL)
 		return NULL;
 
@@ -539,10 +541,6 @@ transcode(VRT_CTX, VCL_INT n, VCL_ENUM decs, VCL_ENUM encs,
 	VCL_STRING r;
 
 	CHECK_OBJ_NOTNULL(ctx, VRT_CTX_MAGIC);
-	if (INIT_FINI(ctx)) {
-		ILLEGAL(ctx, "transcode()");
-		return NULL;
-	}
 	CHECK_OBJ_NOTNULL(ctx->ws, WS_MAGIC);
 
 	AENC(dec);

src/vmod_blobcode.vcc

 #-
-# Copyright (c) 2015-2016 UPLEX Nils Goroll Systemoptimierung
-# All rights reserved
+# This document is licensed under the same conditions as the
+# libvmod-blobcode project. See LICENSE for details.
 #
 # Authors: Nils Goroll <nils.goroll@uplex.de>
 #          Geoffrey Simmons <geoffrey.simmons@uplex.de>
 #
-# See LICENSE
-#
 
 $Module blobcode 3 binary-to-text encodings and decodings for the VCL blob type
 
@@ -51,9 +49,9 @@ DESCRIPTION
 
 This Varnish module (VMOD) supports binary-to-text encodings and
 decodings for the VCL data type BLOB, which may contain arbitrary data
-of any length. Currently (as of Varnish 4.1.1), BLOBs may only be used
-as arguments of VMOD functions; so this module is meant to facilitate
-the use of other VMODs.
+of any length. Currently BLOBs may only be used as arguments of VMOD
+functions; so this module is meant to facilitate the use of other
+VMODs.
 
 ENCODING SCHEMES
 ================
@@ -265,10 +263,6 @@ $Object blob(ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX,
                    URL} decoding="IDENTITY",
              STRING_LIST encoded)
 
-Prototype::
-
-	new OBJ = blobcode.blob(ENUM decoding, STRING_LIST encoded)
-
 Creates an object that contains the BLOB derived from the string
 ``encoded`` according to the scheme ``decoding``.
 
@@ -338,11 +332,6 @@ string is an illegal format for the decoding scheme.
 If the ``blob`` object constructor fails, then the VCL program will
 fail to load, and the VCC compiler will emit an error message.
 
-The VMOD functions -- ``encode()``, ``decode()`` and ``transcode()``
--- may not be called in ``vcl_init()`` or ``vcl_fini()`` (since a
-workspace must be available). Use in ``vcl_init()`` will also cause
-the VCL program to fail with a VCC compiler error.
-
 If any of the VMOD's methods or functions fail at runtime, then an
 error message will be written to the Varnish log using the tag
 ``VCL_Error``. The encoders and decoders return ``NULL`` on failure;
@@ -352,8 +341,9 @@ to a header, then the header will not be set.
 REQUIREMENTS
 ============
 
-This VMOD requires at least Varnish version 4.1.2, and has been tested
-with versions through 5.0.0.
+This version of the VMOD requires at least Varnish version 5.0.0. (See
+branch 4.1 in the project repository for versions that are compatible
+with Varnish since 4.1.2.)
 
 Perl 5 is required for the build.
 
@@ -441,17 +431,16 @@ HISTORY
 
 * version 0.1: initial version
 
+* version 1.0: compatible with Varnish versions since 4.1.2
+
+* version 2.0: compatible with Varnish versions since 5.0.0
+
 SEE ALSO
 ========
 
 * varnishd(1)
 * vcl(7)
+* project repository: https://code.uplex.de/uplex-varnish/libvmod-blobcode
 * VMOD digest: https://github.com/varnish/libvmod-digest
 
-COPYRIGHT
-=========
-
-This document is licensed under the same conditions as the
-libvmod-blobcode project. See LICENSE for details.
-
-* Copyright (c) 2015-2016 UPLEX Nils Goroll Systemoptimierung
+$Event event