diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2015-02-14 11:55:18 +0200 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2015-02-14 11:55:18 +0200 |
commit | 86be1ec2e77f2d04ef1036e91a9987795884d282 (patch) | |
tree | 495bf6874bd239eb7047a8ce8477dcc9b980bc1f /README | |
parent | a7df6c9f56d96fa1e1c1a5cb67ef951560181984 (diff) | |
download | vmod-variable-86be1ec2e77f2d04ef1036e91a9987795884d282.tar.gz vmod-variable-86be1ec2e77f2d04ef1036e91a9987795884d282.tar.bz2 |
Add README and NEWS files.
Diffstat (limited to 'README')
-rw-r--r-- | README | 222 |
1 files changed, 222 insertions, 0 deletions
@@ -0,0 +1,222 @@ | |||
1 | Vmod-variable README | ||
2 | Copyright (C) 2015 Sergey Poznyakoff | ||
3 | See the end of file for copying conditions. | ||
4 | |||
5 | * Introduction | ||
6 | |||
7 | This file contains brief information about configuring, testing | ||
8 | and using vmod-variable. It is *not* intended as a replacement | ||
9 | for the documentation, and is provided as a brief reference only. | ||
10 | For accessing complete vmod-variable documentation, see the section | ||
11 | 'Documentation' below. | ||
12 | |||
13 | For a list of differences between this module and vmod_var, see | ||
14 | the section "vmod_variable vs. vmod_var". | ||
15 | |||
16 | * Overview | ||
17 | |||
18 | This module provides extended variable support for VCL scripts. | ||
19 | It compiles for Varnish versions 3 and 4. | ||
20 | |||
21 | There are two kinds of variables: session-specific, which have the | ||
22 | lifespan of one HTTP session (connection) and cease to exist when | ||
23 | it is closed, and global, which are shared between all sessions. | ||
24 | |||
25 | Session-specific variables are typed, a pair of functions is provided | ||
26 | for setting and retrieveng variables od a particular type. For | ||
27 | example the function set_duration sets a duration variable, and | ||
28 | get_duration retrieves its value: | ||
29 | |||
30 | set beresp.ttl = variable.get_int("ttl"); | ||
31 | |||
32 | Special functions are provided for testing if a variable is defined: | ||
33 | the defined() function returns true if the variable is defined, and | ||
34 | the type_of() function returns the type of the variable. | ||
35 | |||
36 | A special fearure of this module are regset() and queryset() | ||
37 | functions. The regset() function allows you to parse a string | ||
38 | (e.g. a URL or header value) according to a regular expression | ||
39 | and to set several variables at once to selected substrings of | ||
40 | the input string, optionally converting between different types. | ||
41 | For example, the fragment below sets ttl and grace parameters of | ||
42 | the object according to the Surrogate-Control header: | ||
43 | |||
44 | variable.regset("ttl:d=\1s,grace:d=\2s", | ||
45 | "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))", | ||
46 | beresp.http.Surrogate-Control); | ||
47 | set beresp.ttl = variable.get_duration("ttl"); | ||
48 | set beresp.grace = variable.get_duration("grace"); | ||
49 | |||
50 | The first argument to regset declares a list of variables to be | ||
51 | set, along with their types (":d" standing for "duration") and | ||
52 | values to be assigned (after = signs). The latter use backreferenses | ||
53 | to refer to the substrings captured by the regular expression and add | ||
54 | the "s" suffix to each captured string to obtain a valid duration. | ||
55 | |||
56 | To obtain the same effect without variable.regset, one would have to | ||
57 | use regsub twice, casting the result explicitly | ||
58 | |||
59 | set beresp.ttl = std.duration(regsub(beresp.http.Surrogate-Control, | ||
60 | "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))", | ||
61 | "\1s")); | ||
62 | set beresp.grace = std.duration(regsub(beresp.http.Surrogate-Control, | ||
63 | "^(?:.*,)?max-age=([0-9]+)(?:+([0-9]+))", | ||
64 | "\2s")); | ||
65 | |||
66 | The queryset() function treats its argument as a HTTP query, and | ||
67 | defines variables according to it. For example: | ||
68 | |||
69 | variable.queryset("q:s,n:i,p:i", regsub(req.url, ".*\?(.+)", "\1")); | ||
70 | |||
71 | If req.url contained "q=term&n=10&p=5", this call will define three | ||
72 | variables: a string variable "q" having the value "term", and two | ||
73 | integer variables "n" and "p" with the values 10 and 5 | ||
74 | correspondingly. | ||
75 | |||
76 | * Functions | ||
77 | |||
78 | ** Typed accessors: | ||
79 | |||
80 | VOID set(STRING name, STRING value) | ||
81 | VOID set_string(STRING name, STRING name) | ||
82 | Define a string variable | ||
83 | |||
84 | STRING get(STRING name) | ||
85 | STRING get_string(STRING name) | ||
86 | Retrieve the value of a string variable | ||
87 | |||
88 | VOID set_int(STRING name, INT value) | ||
89 | Define an integer variable | ||
90 | INT get_int(STRING name) | ||
91 | Retrieve the value of an integer variable | ||
92 | |||
93 | VOID set_real(STRING name, REAL value) | ||
94 | Define a floating-point variable | ||
95 | REAL get_real(STRING name) | ||
96 | Retrieve the value of a floating-point variable | ||
97 | |||
98 | VOID set_duration(STRING name, DURATION value) | ||
99 | Define a duration variable | ||
100 | DURATION get_duration(STRING name) | ||
101 | Retrieve the value of a duration variable | ||
102 | |||
103 | VOID unset(STRING name) | ||
104 | Unset the variable | ||
105 | |||
106 | VOID clear() | ||
107 | Unset all variables | ||
108 | |||
109 | ** Testing for existence | ||
110 | |||
111 | BOOL defined(STRING name) | ||
112 | Test if the variable is defined | ||
113 | |||
114 | STRING type_of(STRING name) | ||
115 | Return type of the variable (one of: UNSET, STRING, INT, | ||
116 | REAL, DURATION) | ||
117 | |||
118 | ** Special functions | ||
119 | |||
120 | VOID regset(STRING vardcl, STRING regex, STRING input) | ||
121 | If input matches regular expression regex, initializes variables | ||
122 | declared in vardcl to parts of input captured by parenthesized | ||
123 | groups in regex. | ||
124 | |||
125 | The parameter vardcl contains one or more comma-separated decla- | ||
126 | rations, each one having the syntax NAME[:TYPE][=VALUE] (brackets | ||
127 | denoting optional parts). The :TYPE suffix declares the type | ||
128 | of the variable (STRING, INT, REAL, DURATION). The =VALUE part | ||
129 | defines its value. It can refer to the nine captured | ||
130 | substrings via the usual notation \1 through \9. | ||
131 | |||
132 | VOID queryset(STRING vardcl, STRING input) | ||
133 | Parses input as HTTP query string and assigns variables according | ||
134 | to vardcl. | ||
135 | |||
136 | If vardcl is empty, the function will define all variables | ||
137 | present in input to string values. Otherwies, only the named | ||
138 | variables will be set. | ||
139 | |||
140 | The value of the vardcl variable is a comma-separated list of | ||
141 | variable names, optionally followed by :TYPE construct, whose | ||
142 | meaning is the same as in regset. | ||
143 | |||
144 | ** Global variables | ||
145 | |||
146 | VOID global_set(STRING name, STRING value) | ||
147 | Set a global variable | ||
148 | STRING global_get(STRING name) | ||
149 | Retrieve the value of a global variable | ||
150 | BOOL global_defined(STRING name) | ||
151 | Test whether the global variable is defined | ||
152 | VOID global_unset(STRING name) | ||
153 | Unset a global variable | ||
154 | VOID global_clear() | ||
155 | Unset all global variables | ||
156 | |||
157 | * vmod_variable vs. vmod_var | ||
158 | |||
159 | This module is backward-compatibile with vmod_var. To facilitate | ||
160 | transition, it uses the same naming scheme, so switching to use | ||
161 | vmod_variable in your VCL script is just a matter of replacing | ||
162 | s/var\./variable./ | ||
163 | |||
164 | Main differences of vmod_variable from vmod_var: | ||
165 | |||
166 | 1. Both Varsnish 3 and 4 are supported; | ||
167 | |||
168 | 2. Variables are stored in hash tables with open addressing, to | ||
169 | speed up accesses (vmod_var keeps them in singly-linked lists). | ||
170 | |||
171 | 3. Functions for testing existence and types of variables, and for | ||
172 | unsetting a variable: defined(), type_of() and unset() | ||
173 | |||
174 | 4. The regset() and queryset() functions; | ||
175 | |||
176 | 5. Additional functions for global variables: global_clear(), | ||
177 | global_defined() and global_unset(). | ||
178 | |||
179 | * Installation | ||
180 | |||
181 | In order to compile the package you need to have a configured and | ||
182 | compiled Varnish source tree. Both Varnish 3 and 4 are OK. | ||
183 | |||
184 | Supposing that the varnish source tree is available under | ||
185 | /usr/src/varnish-4.0.2, run: | ||
186 | |||
187 | ./configure --with-varnish-source=/usr/src/varnish-4.0.2 | ||
188 | |||
189 | The `--with-varnish-source' option is mandatory: it tells configure | ||
190 | where Varnish sources reside. | ||
191 | |||
192 | Once configured, do | ||
193 | |||
194 | make | ||
195 | |||
196 | This will build the module. After this step you can optionally run | ||
197 | 'make test' to test the package. | ||
198 | |||
199 | Finally, run the following command as root: | ||
200 | |||
201 | make install | ||
202 | |||
203 | * Documentation | ||
204 | |||
205 | The manual page vmod-variable(3) will be available after a successful | ||
206 | install. To read it without actually installing the module, run | ||
207 | `man src/vmod-variable.3'. | ||
208 | |||
209 | An online copy of the documentation is available from | ||
210 | http://www.gnu.org.ua/software/vmod-variable. | ||
211 | |||
212 | * Bug reporting | ||
213 | |||
214 | Send bug reports and suggestions to <gray@gnu.org> | ||
215 | |||
216 | |||
217 | Local Variables: | ||
218 | mode: outline | ||
219 | paragraph-separate: "[ ]*$" | ||
220 | version-control: never | ||
221 | End: | ||
222 | |||