File: //usr/share/doc/varnish/html/reference/vmod_blob.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>VMOD blob - Utilities for the VCL blob type, encoding and decoding — Varnish version 6.4.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '6.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Varnish version 6.4.0 documentation" href="../index.html" />
<link rel="up" title="The Varnish Reference Manual" href="index.html" />
<link rel="next" title="VMOD cookie - Varnish Cookie Module" href="vmod_cookie.html" />
<link rel="prev" title="VSM: Shared Memory Logging and Statistics" href="vsm.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="vsm.html" title="VSM: Shared Memory Logging and Statistics"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="vmod-blob-utilities-for-the-vcl-blob-type-encoding-and-decoding">
<span id="vmod-blob-3"></span><h1>VMOD blob - Utilities for the VCL blob type, encoding and decoding<a class="headerlink" href="#vmod-blob-utilities-for-the-vcl-blob-type-encoding-and-decoding" title="Permalink to this headline">¶</a></h1>
<div class="section" id="synopsis">
<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
<pre class="literal-block">
import blob [as name] [from "path"]
<a class="reference internal" href="#blob-decode"><em>BLOB decode(ENUM decoding, INT length, STRING encoded)</em></a>
<a class="reference internal" href="#blob-encode"><em>STRING encode(ENUM encoding, ENUM case, BLOB blob)</em></a>
<a class="reference internal" href="#blob-transcode"><em>STRING transcode(ENUM decoding, ENUM encoding, ENUM case, INT length, STRING encoded)</em></a>
<a class="reference internal" href="#blob-same"><em>BOOL same(BLOB, BLOB)</em></a>
<a class="reference internal" href="#blob-equal"><em>BOOL equal(BLOB, BLOB)</em></a>
<a class="reference internal" href="#blob-length"><em>INT length(BLOB)</em></a>
<a class="reference internal" href="#blob-sub"><em>BLOB sub(BLOB, BYTES length, BYTES offset=0)</em></a>
<a class="reference internal" href="#blob-blob"><em>new xblob = blob.blob(ENUM decoding, STRING encoded)</em></a>
<a class="reference internal" href="#xblob-get"><em>BLOB xblob.get()</em></a>
<a class="reference internal" href="#xblob-encode"><em>STRING xblob.encode(ENUM encoding, ENUM case)</em></a>
</pre>
</div>
<div class="section" id="description">
<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>This VMOD provides utility functions and an object for the VCL data
type <tt class="docutils literal"><span class="pre">BLOB</span></tt>, which may contain arbitrary data of any length.</p>
<p>Examples:</p>
<div class="highlight-python"><pre>sub vcl_init {
# Create blob objects from encodings such as base64 or hex.
new myblob = blob.blob(BASE64, "Zm9vYmFy");
new yourblob = blob.blob(encoded="666F6F", decoding=HEX);
}
sub vcl_deliver {
# The .get() method retrieves the BLOB from an object.
set resp.http.MyBlob-As-Hex
= blob.encode(blob=myblob.get(), encoding=HEX);
# The .encode() method efficiently retrieves an encoding.
set resp.http.YourBlob-As-Base64 = yourblob.encode(BASE64);
# decode() and encode() functions convert blobs to text and
# vice versa at runtime.
set resp.http.Base64-Encoded
= blob.encode(BASE64,
blob=blob.decode(HEX,
encoded=req.http.Hex-Encoded));
}
sub vcl_recv {
# transcode() converts from one encoding to another.
# case=UPPER specifies upper-case hex digits A-F.
set req.http.Hex-Encoded
= blob.transcode(decoding=BASE64, encoding=HEX,
case=UPPER, encoded="YmF6");
# transcode() from URL to IDENTITY effects a URL decode.
set req.url = blob.transcode(encoded=req.url, decoding=URL);
# transcode() from IDENTITY to URL effects a URL encode.
set req.http.url_urlcoded
= blob.transcode(encoded=req.url, encoding=URL);
}</pre>
</div>
<div class="section" id="encoding-schemes">
<h3>ENCODING SCHEMES<a class="headerlink" href="#encoding-schemes" title="Permalink to this headline">¶</a></h3>
<p>Binary-to-text encoding schemes are specified by ENUMs in the VMOD's
constructor, methods and functions. Decodings convert a (possibly
concatenated) string into a blob, while encodings convert a blob into
a string.</p>
<p>ENUM values for an encoding scheme can be one of:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">IDENTITY</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BASE64</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BASE64URL</span></tt></li>
<li><tt class="docutils literal"><span class="pre">BASE64URLNOPAD</span></tt></li>
<li><tt class="docutils literal"><span class="pre">HEX</span></tt></li>
<li><tt class="docutils literal"><span class="pre">URL</span></tt></li>
</ul>
<p>Empty strings are decoded into a "null blob" (of length 0), and
conversely a null blob is encoded as the empty string.</p>
<p>For encodings with <tt class="docutils literal"><span class="pre">HEX</span></tt> or <tt class="docutils literal"><span class="pre">URL</span></tt>, you may also specify a <em>case</em>
ENUM with one of the values <tt class="docutils literal"><span class="pre">LOWER</span></tt>, <tt class="docutils literal"><span class="pre">UPPER</span></tt> or <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> to
produce a string with lower- or uppercase hex digits (in <tt class="docutils literal"><span class="pre">[a-f]</span></tt> or
<tt class="docutils literal"><span class="pre">[A-F]</span></tt>). The default value for <em>case</em> is <tt class="docutils literal"><span class="pre">DEFAULT</span></tt>, which for
<tt class="docutils literal"><span class="pre">HEX</span></tt> and <tt class="docutils literal"><span class="pre">URL</span></tt> means the same as <tt class="docutils literal"><span class="pre">LOWER</span></tt>.</p>
<p>The <em>case</em> ENUM is not relevant for decodings; <tt class="docutils literal"><span class="pre">HEX</span></tt> or <tt class="docutils literal"><span class="pre">URL</span></tt>
strings to be decoded as BLOBs may have hex digits in either case, or
in mixed case.</p>
<p>The <em>case</em> ENUM MUST be set to <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> for the other encodings
(<tt class="docutils literal"><span class="pre">BASE64*</span></tt> and <tt class="docutils literal"><span class="pre">IDENTITY</span></tt>). You cannot, for example, produce an
uppercase string by using the <tt class="docutils literal"><span class="pre">IDENTITY</span></tt> scheme with
<tt class="docutils literal"><span class="pre">case=UPPER</span></tt>. To change the case of a string, use the <tt class="docutils literal"><span class="pre">std.toupper()</span></tt> or
<tt class="docutils literal"><span class="pre">std.tolower()</span></tt> functions from <a class="reference internal" href="vmod_std.html#vmod-std-3"><em>VMOD std - Varnish Standard Module</em></a>.</p>
<div class="section" id="identity">
<h4>IDENTITY<a class="headerlink" href="#identity" title="Permalink to this headline">¶</a></h4>
<p>The simplest encoding converts between the BLOB and STRING data types,
leaving the contents byte-identical.</p>
<p>Note that a BLOB may contain a null byte at any position before its
end; if such a BLOB is decoded with <tt class="docutils literal"><span class="pre">IDENTITY</span></tt>, the resulting STRING
will have a null byte at that position. Since VCL strings, like C
strings, are represented with a terminating null byte, the string will
be truncated, appearing to contain less data than the original
blob. For example:</p>
<div class="highlight-python"><pre># Decode from the hex encoding for "foo\0bar".
# The header will be seen as "foo".
set resp.http.Trunced-Foo1
= blob.encode(IDENTITY, blob=blob.decode(HEX,
encoded="666f6f00626172"));</pre>
</div>
<p><tt class="docutils literal"><span class="pre">IDENTITY</span></tt> is the default encoding and decoding. So the above can
also be written as:</p>
<div class="highlight-python"><pre># Decode from the hex encoding for "foo\0bar".
# The header will be seen as "foo".
set resp.http.Trunced-Foo2
= blob.encode(blob=blob.decode(HEX, encoded="666f6f00626172"));</pre>
</div>
<p>The <em>case</em> ENUM MUST be set to <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> for <tt class="docutils literal"><span class="pre">IDENTITY</span></tt> encodings.</p>
</div>
<div class="section" id="base64">
<h4>BASE64*<a class="headerlink" href="#base64" title="Permalink to this headline">¶</a></h4>
<p>The base64 encoding schemes use 4 characters to encode 3 bytes. There
are no newlines or maximal line lengths -- whitespace is not
permitted.</p>
<p>The <tt class="docutils literal"><span class="pre">BASE64</span></tt> encoding uses the alphanumeric characters, <tt class="docutils literal"><span class="pre">+</span></tt> and
<tt class="docutils literal"><span class="pre">/</span></tt>; and encoded strings are padded with the <tt class="docutils literal"><span class="pre">=</span></tt> character so that
their length is always a multiple of four.</p>
<p>The <tt class="docutils literal"><span class="pre">BASE64URL</span></tt> encoding also uses the alphanumeric characters, but
<tt class="docutils literal"><span class="pre">-</span></tt> and <tt class="docutils literal"><span class="pre">_</span></tt> instead of <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">/</span></tt>, so that an encoded string
can be used safely in a URL. This scheme also uses the padding
character <tt class="docutils literal"><span class="pre">=</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">BASE64URLNOPAD</span></tt> encoding uses the same alphabet as
<tt class="docutils literal"><span class="pre">BASE6URL</span></tt>, but leaves out the padding. Thus the length of an
encoding with this scheme is not necessarily a multiple of four.</p>
<p>The <em>case</em> ENUM MUST be set to <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> for for all of the
<tt class="docutils literal"><span class="pre">BASE64*</span></tt> encodings.</p>
</div>
<div class="section" id="hex">
<h4>HEX<a class="headerlink" href="#hex" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">HEX</span></tt> encoding scheme converts hex strings into blobs and vice
versa. For encodings, you may use the <em>case</em> ENUM to specify upper-
or lowercase hex digits <tt class="docutils literal"><span class="pre">A</span></tt> through <tt class="docutils literal"><span class="pre">f</span></tt> (default <tt class="docutils literal"><span class="pre">DEFAULT</span></tt>,
which means the same as <tt class="docutils literal"><span class="pre">LOWER</span></tt>). A prefix such as <tt class="docutils literal"><span class="pre">0x</span></tt> is not
used for an encoding and is illegal for a decoding.</p>
<p>If a hex string to be decoded has an odd number of digits, it is
decoded as if a <tt class="docutils literal"><span class="pre">0</span></tt> is prepended to it; that is, the first digit is
interpreted as representing the least significant nibble of the first
byte. For example:</p>
<div class="highlight-python"><pre># The concatenated string is "abcdef0", and is decoded as "0abcdef0".
set resp.http.First = "abc";
set resp.http.Second = "def0";
set resp.http.Hex-Decoded
= blob.encode(HEX, blob=blob.decode(HEX,
encoded=resp.http.First + resp.http.Second));</pre>
</div>
</div>
<div class="section" id="url">
<h4>URL<a class="headerlink" href="#url" title="Permalink to this headline">¶</a></h4>
<p>The <tt class="docutils literal"><span class="pre">URL</span></tt> decoding replaces any <tt class="docutils literal"><span class="pre">%<2-hex-digits></span></tt> substrings with
the binary value of the hexadecimal number after the <tt class="docutils literal"><span class="pre">%</span></tt> sign.</p>
<p>The <tt class="docutils literal"><span class="pre">URL</span></tt> encoding implements "percent encoding" as per RFC3986. The
<em>case</em> ENUM determines the case of the hex digits, but does not
affect alphabetic characters that are not percent-encoded.</p>
</div>
</div>
<div class="section" id="blob-decode-enum-decoding-int-length-string-encoded">
<span id="blob-decode"></span><h3>BLOB decode(ENUM decoding, INT length, STRING encoded)<a class="headerlink" href="#blob-decode-enum-decoding-int-length-string-encoded" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>BLOB decode(
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} decoding=IDENTITY,
INT length=0,
STRING encoded
)</pre>
</div>
<p>Returns the BLOB derived from the string <em>encoded</em> according to the
scheme specified by <em>decoding</em>.</p>
<p>If <em>length</em> > 0, only decode the first <em>length</em> characters of the
encoded string. If <em>length</em> <= 0 or greater than the length of the
string, then decode the entire string. The default value of <em>length</em>
is 0.</p>
<p><em>decoding</em> defaults to IDENTITY.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">BASE64</span><span class="p">,</span> <span class="n">encoded</span><span class="o">=</span><span class="s">"Zm9vYmFyYmF6"</span><span class="p">);</span>
<span class="c"># same with named parameters</span>
<span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s">"Zm9vYmFyYmF6"</span><span class="p">,</span> <span class="n">decoding</span><span class="o">=</span><span class="n">BASE64</span><span class="p">);</span>
<span class="c"># convert string to blob</span>
<span class="n">blob</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoded</span><span class="o">=</span><span class="s">"foo"</span><span class="p">);</span>
</pre></div>
</div>
</div>
<div class="section" id="string-encode-enum-encoding-enum-case-blob-blob">
<span id="blob-encode"></span><h3>STRING encode(ENUM encoding, ENUM case, BLOB blob)<a class="headerlink" href="#string-encode-enum-encoding-enum-case-blob-blob" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>STRING encode(
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} encoding=IDENTITY,
ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT,
BLOB blob
)</pre>
</div>
<p>Returns a string representation of the BLOB <em>blob</em> as specified by
<em>encoding</em>. <em>case</em> determines the case of hex digits for the <tt class="docutils literal"><span class="pre">HEX</span></tt>
and <tt class="docutils literal"><span class="pre">URL</span></tt> encodings, and is ignored for the other encodings.</p>
<p><em>encoding</em> defaults to <tt class="docutils literal"><span class="pre">IDENTITY</span></tt>, and <em>case</em> defaults to
<tt class="docutils literal"><span class="pre">DEFAULT</span></tt>. <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> is interpreted as <tt class="docutils literal"><span class="pre">LOWER</span></tt> for the <tt class="docutils literal"><span class="pre">HEX</span></tt>
and <tt class="docutils literal"><span class="pre">URL</span></tt> encodings, and is the required value for the other
encodings.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set resp.http.encode1
= blob.encode(HEX,
blob=blob.decode(BASE64, encoded="Zm9vYmFyYmF6"));
# same with named parameters
set resp.http.encode2
= blob.encode(blob=blob.decode(encoded="Zm9vYmFyYmF6",
decoding=BASE64),
encoding=HEX);
# convert blob to string
set resp.http.encode3
= blob.encode(blob=blob.decode(encoded="foo"));</pre>
</div>
</div>
<div class="section" id="string-transcode-enum-decoding-enum-encoding-enum-case-int-length-string-encoded">
<span id="blob-transcode"></span><h3>STRING transcode(ENUM decoding, ENUM encoding, ENUM case, INT length, STRING encoded)<a class="headerlink" href="#string-transcode-enum-decoding-enum-encoding-enum-case-int-length-string-encoded" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>STRING transcode(
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} decoding=IDENTITY,
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} encoding=IDENTITY,
ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT,
INT length=0,
STRING encoded
)</pre>
</div>
<p>Translates from one encoding to another, by first decoding the string
<em>encoded</em> according to the scheme <em>decoding</em>, and then returning
the encoding of the resulting blob according to the scheme
<em>encoding</em>. <em>case</em> determines the case of hex digits for the
<tt class="docutils literal"><span class="pre">HEX</span></tt> and <tt class="docutils literal"><span class="pre">URL</span></tt> encodings, and is ignored for other encodings.</p>
<p>As with <a class="reference internal" href="#blob-decode">blob.decode()</a>: If <em>length</em> > 0, only decode the first
<em>length</em> characters of the encoded string, otherwise decode the
entire string. The default value of <em>length</em> is 0.</p>
<p><em>decoding</em> and <em>encoding</em> default to IDENTITY, and <em>case</em> defaults to
<tt class="docutils literal"><span class="pre">DEFAULT</span></tt>. <tt class="docutils literal"><span class="pre">DEFAULT</span></tt> is interpreted as <tt class="docutils literal"><span class="pre">LOWER</span></tt> for the <tt class="docutils literal"><span class="pre">HEX</span></tt>
and <tt class="docutils literal"><span class="pre">URL</span></tt> encodings, and is the required value for the other
encodings.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set resp.http.Hex2Base64-1
= blob.transcode(HEX, BASE64, encoded="666f6f");
# same with named parameters
set resp.http.Hex2Base64-2
= blob.transcode(encoded="666f6f",
encoding=BASE64, decoding=HEX);
# URL decode -- recall that IDENTITY is the default encoding.
set resp.http.urldecoded
= blob.transcode(encoded="foo%20bar", decoding=URL);
# URL encode
set resp.http.urlencoded
= blob.transcode(encoded="foo bar", encoding=URL);</pre>
</div>
</div>
<div class="section" id="bool-same-blob-blob">
<span id="blob-same"></span><h3>BOOL same(BLOB, BLOB)<a class="headerlink" href="#bool-same-blob-blob" title="Permalink to this headline">¶</a></h3>
<p>Returns <tt class="docutils literal"><span class="pre">true</span></tt> if and only if the two BLOB arguments are the same
object, i.e. they specify exactly the same region of memory, or both
are empty.</p>
<p>If the BLOBs are both empty (length is 0 and/or the internal pointer
is <tt class="docutils literal"><span class="pre">NULL</span></tt>), then <a class="reference internal" href="#blob-same">blob.same()</a> returns <tt class="docutils literal"><span class="pre">true</span></tt>. If any
non-empty BLOB is compared to an empty BLOB, then <a class="reference internal" href="#blob-same">blob.same()</a>
returns <tt class="docutils literal"><span class="pre">false</span></tt>.</p>
</div>
<div class="section" id="bool-equal-blob-blob">
<span id="blob-equal"></span><h3>BOOL equal(BLOB, BLOB)<a class="headerlink" href="#bool-equal-blob-blob" title="Permalink to this headline">¶</a></h3>
<p>Returns true if and only if the two BLOB arguments have equal contents
(possibly in different memory regions).</p>
<p>As with <a class="reference internal" href="#blob-same">blob.same()</a>: If the BLOBs are both empty, then <a class="reference internal" href="#blob-equal">blob.equal()</a>
returns <tt class="docutils literal"><span class="pre">true</span></tt>. If any non-empty BLOB is compared to an empty BLOB,
then <a class="reference internal" href="#blob-equal">blob.equal()</a> returns <tt class="docutils literal"><span class="pre">false</span></tt>.</p>
</div>
<div class="section" id="int-length-blob">
<span id="blob-length"></span><h3>INT length(BLOB)<a class="headerlink" href="#int-length-blob" title="Permalink to this headline">¶</a></h3>
<p>Returns the length of the BLOB.</p>
</div>
<div class="section" id="blob-sub-blob-bytes-length-bytes-offset-0">
<span id="blob-sub"></span><h3>BLOB sub(BLOB, BYTES length, BYTES offset=0)<a class="headerlink" href="#blob-sub-blob-bytes-length-bytes-offset-0" title="Permalink to this headline">¶</a></h3>
<p>Returns a new BLOB formed from <em>length</em> bytes of the BLOB argument
starting at <em>offset</em> bytes from the start of its memory region. The
default value of <em>offset</em> is <tt class="docutils literal"><span class="pre">0B</span></tt>.</p>
<p><a class="reference internal" href="#blob-sub">blob.sub()</a> fails and returns NULL if the BLOB argument is empty, or if
<tt class="docutils literal"><span class="pre">offset</span> <span class="pre">+</span> <span class="pre">length</span></tt> requires more bytes than are available in the
BLOB.</p>
</div>
<div class="section" id="new-xblob-blob-blob-enum-decoding-string-encoded">
<span id="blob-blob"></span><h3>new xblob = blob.blob(ENUM decoding, STRING encoded)<a class="headerlink" href="#new-xblob-blob-blob-enum-decoding-string-encoded" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>new xblob = blob.blob(
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} decoding=IDENTITY,
STRING encoded
)</pre>
</div>
<p>Creates an object that contains the BLOB derived from the string
<em>encoded</em> according to the scheme <em>decoding</em>.</p>
<p>Example:</p>
<div class="highlight-python"><pre>new theblob1 = blob.blob(BASE64, encoded="YmxvYg==");
# same with named arguments
new theblob2 = blob.blob(encoded="YmxvYg==", decoding=BASE64);
# string as a blob
new stringblob = blob.blob(encoded="bazz");</pre>
</div>
</div>
<div class="section" id="blob-xblob-get">
<span id="xblob-get"></span><h3>BLOB xblob.get()<a class="headerlink" href="#blob-xblob-get" title="Permalink to this headline">¶</a></h3>
<p>Returns the BLOB created by the constructor.</p>
<p>Example:</p>
<div class="highlight-python"><pre>set resp.http.The-Blob1 =
blob.encode(blob=theblob1.get());
set resp.http.The-Blob2 =
blob.encode(blob=theblob2.get());
set resp.http.The-Stringblob =
blob.encode(blob=stringblob.get());</pre>
</div>
</div>
<div class="section" id="string-xblob-encode-enum-encoding-enum-case">
<span id="xblob-encode"></span><h3>STRING xblob.encode(ENUM encoding, ENUM case)<a class="headerlink" href="#string-xblob-encode-enum-encoding-enum-case" title="Permalink to this headline">¶</a></h3>
<div class="highlight-python"><pre>STRING xblob.encode(
ENUM {IDENTITY, BASE64, BASE64URL, BASE64URLNOPAD, HEX, URL} encoding=IDENTITY,
ENUM {LOWER, UPPER, DEFAULT} case=DEFAULT
)</pre>
</div>
<p>Returns an encoding of BLOB created by the constructor, according to
the scheme <em>encoding</em>. <em>case</em> determines the case of hex digits
for the <tt class="docutils literal"><span class="pre">HEX</span></tt> and <tt class="docutils literal"><span class="pre">URL</span></tt> encodings, and MUST be set to <tt class="docutils literal"><span class="pre">DEFAULT</span></tt>
for the other encodings.</p>
<p>Example:</p>
<div class="highlight-python"><pre># blob as text
set resp.http.The-Blob = theblob1.encode();
# blob as base64
set resp.http.The-Blob-b64 = theblob1.encode(BASE64);</pre>
</div>
<p>For any <a class="reference internal" href="#blob-blob">blob.blob()</a> object, <cite>encoding</cite> and <cite>case</cite>, encodings via
the <a class="reference internal" href="#xblob-encode">xblob.encode()</a> method and the <a class="reference internal" href="#blob-encode">blob.encode()</a>
function are equal:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># Always true:</span>
<span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">ENC</span><span class="p">,</span> <span class="n">CASE</span><span class="p">,</span> <span class="n">blob</span><span class="o">.</span><span class="n">get</span><span class="p">())</span> <span class="o">==</span> <span class="n">blob</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">ENC</span><span class="p">,</span> <span class="n">CASE</span><span class="p">)</span>
</pre></div>
</div>
<p>But the <a class="reference internal" href="#xblob-encode">xblob.encode()</a> object method is more efficient --
the encoding is computed once and cached (with allocation in heap
memory), and the cached encoding is retrieved on every subsequent
call. The <a class="reference internal" href="#blob-encode">blob.encode()</a> function computes the encoding on every
call, allocating space for the string in Varnish workspaces.</p>
<p>So if the data in a BLOB are fixed at VCL initialization time, so that
its encodings will always be the same, it is better to create a
<a class="reference internal" href="#blob-blob">blob.blob()</a> object. The VMOD's functions should be used for data that are
not known until runtime.</p>
</div>
</div>
<div class="section" id="errors">
<h2>ERRORS<a class="headerlink" href="#errors" title="Permalink to this headline">¶</a></h2>
<p>The encoders, decoders and <a class="reference internal" href="#blob-sub">blob.sub()</a> may fail if there is
insufficient space to create the new blob or string. Decoders may also
fail if the encoded string is an illegal format for the decoding
scheme. Encoders will fail for the <tt class="docutils literal"><span class="pre">IDENTITY</span></tt> and <tt class="docutils literal"><span class="pre">BASE64*</span></tt>
encoding schemes if the <em>case</em> ENUM is not set to <tt class="docutils literal"><span class="pre">DEFAULT</span></tt>.</p>
<p>If any of the VMOD's methods, functions or constructor fail, then VCL
failure is invoked, just as if <tt class="docutils literal"><span class="pre">return(fail)</span></tt> had been called in the
VCL source. This means that:</p>
<ul class="simple">
<li>If the <a class="reference internal" href="#blob-blob">blob.blob()</a> object constructor fails, or if any methods or
functions fail during <tt class="docutils literal"><span class="pre">vcl_init{}</span></tt>, then the VCL program will fail
to load, and the VCC compiler will emit an error message.</li>
<li>If a method or function fails in any other VCL subroutine besides
<tt class="docutils literal"><span class="pre">vcl_synth{}</span></tt>, then control is directed to <tt class="docutils literal"><span class="pre">vcl_synth{}</span></tt>. The
response status is set to 503 with the reason string <tt class="docutils literal"><span class="pre">"VCL</span>
<span class="pre">failed"</span></tt>, and an error message will be written to the <a class="reference internal" href="vsl.html#vsl-7"><em>VSL</em></a>
using the tag <tt class="docutils literal"><span class="pre">VCL_Error</span></tt>.</li>
<li>If the failure occurs during <tt class="docutils literal"><span class="pre">vcl_synth{}</span></tt>, then <tt class="docutils literal"><span class="pre">vcl_synth{}</span></tt>
is aborted. The response line <tt class="docutils literal"><span class="pre">"503</span> <span class="pre">VCL</span> <span class="pre">failed"</span></tt> is returned, and
the <tt class="docutils literal"><span class="pre">VCL_Error</span></tt> message is written to the log.</li>
</ul>
</div>
<div class="section" id="limitations">
<h2>LIMITATIONS<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
<p>The VMOD allocates memory in various ways for new blobs and
strings. The <a class="reference internal" href="#blob-blob">blob.blob()</a> object and its methods allocate memory
from the heap, and hence they are only limited by available virtual
memory.</p>
<p>The <a class="reference internal" href="#blob-encode">blob.encode()</a>, <a class="reference internal" href="#blob-decode">blob.decode()</a> and
<a class="reference internal" href="#blob-transcode">blob.transcode()</a> functions allocate Varnish workspace, as does
<a class="reference internal" href="#blob-sub">blob.sub()</a> for the newly created BLOB. If these functions are
failing, as indicated by "out of space" messages in the Varnish log
(with the <tt class="docutils literal"><span class="pre">VCL_Error</span></tt> tag), then you will need to increase the
varnishd parameters <tt class="docutils literal"><span class="pre">workspace_client</span></tt> and/or <tt class="docutils literal"><span class="pre">workspace_backend</span></tt>.</p>
<p>The <a class="reference internal" href="#blob-transcode">blob.transcode()</a> function also allocates space on the stack
for a temporary BLOB. If this function causes stack overflow, you may
need to increase the varnishd parameter <tt class="docutils literal"><span class="pre">thread_pool_stack</span></tt>.</p>
</div>
<div class="section" id="see-also">
<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<ul class="simple">
<li><a class="reference internal" href="varnishd.html#varnishd-1"><em>varnishd</em></a></li>
<li><a class="reference internal" href="vcl.html#vcl-7"><em>VCL</em></a></li>
<li><a class="reference internal" href="vsl.html#vsl-7"><em>VSL</em></a></li>
<li><a class="reference internal" href="vmod_std.html#vmod-std-3"><em>VMOD std - Varnish Standard Module</em></a></li>
</ul>
</div>
<div class="section" id="copyright">
<h2>COPYRIGHT<a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><pre>This document is licensed under the same conditions as Varnish itself.
See LICENSE for details.
Authors: Nils Goroll <nils.goroll@uplex.de>
Geoffrey Simmons <geoffrey.simmons@uplex.de></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h4>Previous topic</h4>
<p class="topless"><a href="vsm.html"
title="previous chapter">VSM: Shared Memory Logging and Statistics</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="vmod_cookie.html"
title="next chapter">VMOD cookie - Varnish Cookie Module</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/vmod_blob.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="vmod_cookie.html" title="VMOD cookie - Varnish Cookie Module"
>next</a> |</li>
<li class="right" >
<a href="vsm.html" title="VSM: Shared Memory Logging and Statistics"
>previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" >The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>