Skip to content

L
libvmod-blobcode
Commit ab31f8a7 authored by Geoff Simmons's avatar Geoff Simmons
Browse files
Options

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
parent 90dfbbc3
Pipeline #85 skipped
Hide whitespace changes
Inline Side-by-side
Showing with 121 additions and 145 deletions
README.rst
View file @ ab31f8a7
......@@ -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
View file @ ab31f8a7
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
View file @ ab31f8a7
# 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
View file @ ab31f8a7
......@@ -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
View file @ ab31f8a7
#-
# 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
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment