vmod_vtc(3)

1VMOD_VTC(3)                                                        VMOD_VTC(3)
2
3
4

NAME

6       vmod_vtc - Utility module for varnishtest
7

SYNOPSIS

9          import vtc [as name] [from "path"]
10
11          VOID barrier_sync(STRING addr, DURATION timeout)
12
13          BACKEND no_backend()
14
15          STEVEDORE no_stevedore()
16
17          IP no_ip()
18
19          VOID panic(STRING)
20
21          VOID sleep(DURATION)
22
23          VOID workspace_alloc(ENUM, INT size)
24
25          BYTES workspace_reserve(ENUM, INT size)
26
27          INT workspace_free(ENUM)
28
29          VOID workspace_snapshot(ENUM)
30
31          VOID workspace_reset(ENUM)
32
33          BOOL workspace_overflowed(ENUM)
34
35          VOID workspace_overflow(ENUM)
36
37          BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
38
39          INT typesize(STRING)
40
41          BLOB proxy_header(ENUM version, IP client, IP server, STRING authority)
42

DESCRIPTION

44       The  goal  for this VMOD is to provide VCL users and VMOD authors means
45       to test corner cases or reach certain conditions with varnishtest.
46
47   VOID barrier_sync(STRING addr, DURATION timeout=0)
48       When writing test cases, the most common pattern is  to  start  a  mock
49       server  instance,  a Varnish instance, and spin up a mock client. Those
50       entities run asynchronously, and others exist like background processes
51       (process)  or  log  readers (logexpect). While you can synchronize with
52       individual entities and wait for their completion, you must use a  bar‐
53       rier  if  you need to synchronize two or more entities, or wait until a
54       certain point instead of completion.
55
56       Not only is it possible to synchronize between test entities, with  the
57       barrier_sync function you can even synchronize VCL code:
58
59          sub vcl_recv {
60              # wait for some barrier b1 to complete
61              vtc.barrier_sync("${b1_sock}");
62          }
63
64       If  the function fails to synchronize with the barrier for some reason,
65       or if it reaches the optional timeout, it fails the VCL transaction.
66

MISCELLANEOUS

68   BACKEND no_backend()
69       Fails at backend selection.
70
71   STEVEDORE no_stevedore()
72       Fails at storage selection.
73
74   IP no_ip()
75       Returns a null IP address, not even a bogo_ip.
76
77   VOID panic(STRING)
78       It can be useful to crash the  child  process  in  order  to  test  the
79       robustness of a VMOD.
80
81   VOID sleep(DURATION)
82       Block the current worker thread.
83

WORKSPACES

85       It  can be useful to put a workspace in a given state when testing cor‐
86       ner cases like resource exhaustion for a  transaction,  especially  for
87       VMOD development. All functions available allow to pick which workspace
88       you need to tamper with, available values are client, backend,  session
89       and thread.
90
91   VOID workspace_alloc(ENUM, INT size)
92          VOID workspace_alloc(
93             ENUM {client, backend, session, thread},
94             INT size
95          )
96
97       Allocate  and  zero  out  memory from a workspace. A negative size will
98       allocate as much as needed to leave that many bytes  free.  The  actual
99       allocation  size may be higher to comply with memory alignment require‐
100       ments of the CPU architecture. A failed allocation fails  the  transac‐
101       tion.
102
103   BYTES workspace_reserve(ENUM, INT size)
104          BYTES workspace_reserve(
105             ENUM {client, backend, session, thread},
106             INT size
107          )
108
109       Attempt  to  reserve size bytes and release the reservation right away.
110       Return the size of the reservation.
111
112       See vtc.workspace_alloc() for semantics of the size argument.
113
114   INT workspace_free(ENUM {client, backend, session, thread})
115       Find how much unallocated space there is left in a workspace.
116
117   VOID workspace_snapshot(ENUM)
118          VOID workspace_snapshot(ENUM {client, backend, session, thread})
119
120       Snapshot a workspace. Only one snapshot may be active  at  a  time  and
121       each  VCL  can  save  only  one snapshot, so concurrent tasks requiring
122       snapshots are not supported.
123
124   VOID workspace_reset(ENUM)
125          VOID workspace_reset(ENUM {client, backend, session, thread})
126
127       Reset to the previous snapshot of a workspace,  it  must  be  the  same
128       workspace too.
129
130   BOOL workspace_overflowed(ENUM)
131          BOOL workspace_overflowed(ENUM {client, backend, session, thread})
132
133       Find whether the workspace overflow mark is set or not.
134
135   VOID workspace_overflow(ENUM)
136          VOID workspace_overflow(ENUM {client, backend, session, thread})
137
138       Mark a workspace as overflowed.
139
140   BLOB workspace_dump(ENUM, ENUM, BYTES off, BYTES len)
141          BLOB workspace_dump(
142             ENUM {client, backend, session, thread},
143             ENUM {s, f, r},
144             BYTES off=0,
145             BYTES len=64
146          )
147
148       Return  data  from  a workspace's s, f, or r pointer as a blob. Data is
149       copied onto the primary workspace to avoid it being subsequently  over‐
150       written.
151
152       The maximum len is 1KB.
153
154   INT typesize(STRING)
155       Returns the size in bytes of a collection of C-datatypes:
156
157       · 'p': pointer
158
159       · 'i': int
160
161       · 'd': double
162
163       · 'f': float
164
165       · 'l': long
166
167       · 's': short
168
169       · 'z': size_t
170
171       · 'o': off_t
172
173       · 'j': intmax_t
174
175       This can be useful for VMOD authors in conjunction with workspace oper‐
176       ations.
177
178   BLOB proxy_header(ENUM version, IP client, IP server, STRING authority)
179          BLOB proxy_header(
180             ENUM {v1, v2} version,
181             IP client,
182             IP server,
183             STRING authority=0
184          )
185
186       Format a proxy header of the given version v1 or v2 and addresses  (The
187       VCL IP type also conatins the port number).
188
189       Optionally also send an authority TLV with version v2 (ignored for ver‐
190       sion v1).
191
192       Candidate for moving into vmod_proxy, but there were concerns about the
193       interface design
194

COPYRIGHT

201          Copyright (c) 2017 Varnish Software AS
202          All rights reserved.
203
204          Author: Dridi Boukelmoune <dridi.boukelmoune@gmail.com>
205
206          SPDX-License-Identifier: BSD-2-Clause
207
208          Redistribution and use in source and binary forms, with or without
209          modification, are permitted provided that the following conditions
210          are met:
211          1. Redistributions of source code must retain the above copyright
212             notice, this list of conditions and the following disclaimer.
213          2. Redistributions in binary form must reproduce the above copyright
214             notice, this list of conditions and the following disclaimer in the
215             documentation and/or other materials provided with the distribution.
216
217          THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
218          ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
219          IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
220          ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
221          FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
222          DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
223          OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
224          HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
225          LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
226          OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
227          SUCH DAMAGE.
228
229
230
231
232                                                                   VMOD_VTC(3)

NAME

SYNOPSIS

DESCRIPTION

MISCELLANEOUS

WORKSPACES

SEE ALSO

COPYRIGHT