1VMOD_VTC(3) VMOD_VTC(3)
2
6 vmod_vtc - Utility module for varnishtest
7
9 import vtc [as name] [from "path"]
10 VOID barrier_sync(STRING addr, DURATION timeout)
12 BACKEND no_backend()
14 STEVEDORE no_stevedore()
16 IP no_ip()
18 VOID panic(STRING)
20 VOID sleep(DURATION)
22 VOID workspace_alloc(ENUM, INT size)
24 BYTES workspace_reserve(ENUM, INT size)
26 INT workspace_free(ENUM)
28 VOID workspace_snapshot(ENUM)
30 VOID workspace_reset(ENUM)
32 BOOL workspace_overflowed(ENUM)
34 VOID workspace_overflow(ENUM)
36 BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
38 INT typesize(STRING)
40 BLOB proxy_header(ENUM version, IP client, IP server, STRING authority)
42 VOID vsl(INT vxid, STRING tag, ENUM side, STRING s)
44 VOID vsl_replay(STRING s)
46
48 The goal for this VMOD is to provide VCL users and VMOD authors means
49 to test corner cases or reach certain conditions with varnishtest.
50 VOID barrier_sync(STRING addr, DURATION timeout=0)
52 When writing test cases, the most common pattern is to start a mock
53 server instance, a Varnish instance, and spin up a mock client. Those
54 entities run asynchronously, and others exist like background processes
55 (process) or log readers (logexpect). While you can synchronize with
56 individual entities and wait for their completion, you must use a bar‐
57 rier if you need to synchronize two or more entities, or wait until a
58 certain point instead of completion.
59 Not only is it possible to synchronize between test entities, with the
61 barrier_sync function you can even synchronize VCL code:
62 sub vcl_recv {
64 # wait for some barrier b1 to complete
65 vtc.barrier_sync("${b1_sock}");
66 }
67 If the function fails to synchronize with the barrier for some reason,
69 or if it reaches the optional timeout, it fails the VCL transaction.
70
72 BACKEND no_backend()
73 Fails at backend selection.
74 STEVEDORE no_stevedore()
76 Fails at storage selection.
77 IP no_ip()
79 Returns a null IP address, not even a bogo_ip.
80 VOID panic(STRING)
82 It can be useful to crash the child process in order to test the ro‐
83 bustness of a VMOD.
84 VOID sleep(DURATION)
86 Block the current worker thread.
87
89 It can be useful to put a workspace in a given state when testing cor‐
90 ner cases like resource exhaustion for a transaction, especially for
91 VMOD development. All functions available allow to pick which workspace
92 you need to tamper with, available values are client, backend, session
93 and thread.
94 VOID workspace_alloc(ENUM, INT size)
96 VOID workspace_alloc(
97 ENUM {client, backend, session, thread},
98 INT size
99 )
100 Allocate and zero out memory from a workspace. A negative size will al‐
102 locate as much as needed to leave that many bytes free. The actual al‐
103 location size may be higher to comply with memory alignment require‐
104 ments of the CPU architecture. A failed allocation fails the transac‐
105 tion.
106 BYTES workspace_reserve(ENUM, INT size)
108 BYTES workspace_reserve(
109 ENUM {client, backend, session, thread},
110 INT size
111 )
112 Attempt to reserve size bytes, zero out that memory and release the
114 reservation right away. Return the size of the reservation.
115 See vtc.workspace_alloc() for semantics of the size argument.
117 INT workspace_free(ENUM {client, backend, session, thread})
119 Find how much unallocated space there is left in a workspace.
120 VOID workspace_snapshot(ENUM)
122 VOID workspace_snapshot(ENUM {client, backend, session, thread})
123 Snapshot a workspace. Only one snapshot may be active at a time and
125 each VCL can save only one snapshot, so concurrent tasks requiring
126 snapshots are not supported.
127 VOID workspace_reset(ENUM)
129 VOID workspace_reset(ENUM {client, backend, session, thread})
130 Reset to the previous snapshot of a workspace, it must be the same
132 workspace too.
133 BOOL workspace_overflowed(ENUM)
135 BOOL workspace_overflowed(ENUM {client, backend, session, thread})
136 Find whether the workspace overflow mark is set or not.
138 VOID workspace_overflow(ENUM)
140 VOID workspace_overflow(ENUM {client, backend, session, thread})
141 Mark a workspace as overflowed.
143 BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
145 BLOB workspace_dump(
146 ENUM {client, backend, session, thread},
147 ENUM {s, f, r},
148 BYTES off=0,
149 BYTES len=64
150 )
151 Return data from a workspace's s, f, or r pointer as a blob. Data is
153 copied onto the primary workspace to avoid it being subsequently over‐
154 written.
155 The maximum len is 1KB.
157 INT typesize(STRING)
159 Returns the size in bytes of a collection of C-datatypes:
160 • 'p': pointer
162 • 'i': int
164 • 'd': double
166 • 'f': float
168 • 'l': long
170 • 's': short
172 • 'z': size_t
174 • 'o': off_t
176 • 'j': intmax_t
178 This can be useful for VMOD authors in conjunction with workspace oper‐
180 ations.
181 BLOB proxy_header(ENUM version, IP client, IP server, STRING authority)
183 BLOB proxy_header(
184 ENUM {v1, v2} version,
185 IP client,
186 IP server,
187 STRING authority=0
188 )
189 Format a proxy header of the given version v1 or v2 and addresses (The
191 VCL IP type also contains the port number).
192 Optionally also send an authority TLV with version v2 (ignored for ver‐
194 sion v1).
195 Candidate for moving into vmod_proxy, but there were concerns about the
197 interface design
198
200 These functions allow to generate arbitrary log entries to test the
201 Varnish Shared Log (VSL) implementation and readers like varnishlog.
202 VOID vsl(INT vxid, STRING tag, ENUM {c, b} side, STRING s)
204 Call VSLs() with the given parameters.
205 The argument order is chosen to match VSL output.
207 A VCL error is triggered if tag can not be resolved at runtime or if
209 vxid is out of bounds.
210 VOID vsl_replay(STRING s)
212 Replay literal log lines.
213 The parser accepts the output generated by varnishlog -g raw and var‐
215 nishtest log vsl| lines.
216 Unparsable lines are silently ignored.
218
220 • vtc(7)
221 • vcl(7)
223
225 Copyright (c) 2017 Varnish Software AS
226 All rights reserved.
227 Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
229 SPDX-License-Identifier: BSD-2-Clause
231 Redistribution and use in source and binary forms, with or without
233 modification, are permitted provided that the following conditions
234 are met:
235 1. Redistributions of source code must retain the above copyright
236 notice, this list of conditions and the following disclaimer.
237 2. Redistributions in binary form must reproduce the above copyright
238 notice, this list of conditions and the following disclaimer in the
239 documentation and/or other materials provided with the distribution.
240 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
242 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
243 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
244 ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
245 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
246 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
247 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
248 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
249 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
250 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
251 SUCH DAMAGE.
252 NB: Default to strict $ABI handling, so that path is tested in vmodtool.py
254 VMOD_VTC(3)