Code Coverage: vinyl-cache/include/vrt.h
 
82217aa4fc7094b3610340078afaf78cd95a8ec9
 
0
/*-
1
 * Copyright (c) 2006 Verdens Gang AS
2
 * Copyright (c) 2006-2021 Varnish Software AS
3
 * All rights reserved.
4
 *
5
 * Author: Poul-Henning Kamp <phk@phk.freebsd.dk>
6
 *
7
 * SPDX-License-Identifier: BSD-2-Clause
8
 *
9
 * Redistribution and use in source and binary forms, with or without
10
 * modification, are permitted provided that the following conditions
11
 * are met:
12
 * 1. Redistributions of source code must retain the above copyright
13
 *    notice, this list of conditions and the following disclaimer.
14
 * 2. Redistributions in binary form must reproduce the above copyright
15
 *    notice, this list of conditions and the following disclaimer in the
16
 *    documentation and/or other materials provided with the distribution.
17
 *
18
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21
 * ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
22
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28
 * SUCH DAMAGE.
29
 *
30
 * Runtime support for compiled VCL programs and VMODs.
31
 *
32
 * NB: When this file is changed, lib/libvcc/generate.py *MUST* be rerun.
33
 */
34
35
#ifdef CACHE_H_INCLUDED
36
#  error "vrt.h included after cache.h - they are inclusive"
37
#endif
38
39
#ifdef VRT_H_INCLUDED
40
#  error "vrt.h included multiple times"
41
#endif
42
#define VRT_H_INCLUDED
43
44
#ifndef VDEF_H_INCLUDED
45
#  error "include vdef.h before vrt.h"
46
#endif
47
48 466
#define VRT_MAJOR_VERSION       24U
49
50 238
#define VRT_MINOR_VERSION       3U
51
52
/***********************************************************************
53
 * Major and minor VRT API versions.
54
 *
55
 * Whenever something is added, increment MINOR version
56
 * Whenever something is deleted or changed in a way which is not
57
 * binary/load-time compatible, increment MAJOR version
58
 *
59
 * 24.3
60
 *      // XXX this would be a major bump, but for next release we'll bump
61
 *      // anyway
62
 *      ctx->specific is now an ssize_t * in vcl_synth, -1 is failed
63
 * 24.2
64
 *      un-const storage_close_f
65
 * 24.1
66
 *      fixed stevedore ban notification in BAN_Commit()
67
 * 24.0 (2026-09-16)
68
 *      VRT_Rollback() no longer takes a VCL_HTTP argument
69
 *      struct vmod_data has moved to vmod_abi.h
70
 *      enum gethdr_e gained a new HDR_REQ0 value
71
 *      http_req0 added to struct vrt_ctx
72
 *      struct vmod_data moved to vmod_abi.h
73
 *      stuct VCL_conf declaration removed from vrt.h
74
 *      struct VSC_main declaration removed from vrt.h
75
 *      VRT_r_req0_method() added
76
 *      VRT_r_req0_proto() added
77
 *      VRT_r_req0_url() added
78
 *      VRT_r_beresp_esi_disable_xml_check() added
79
 *      VRT_l_beresp_esi_disable_xml_check() added
80
 *      VRT_r_beresp_esi_ignore_https() added
81
 *      VRT_l_beresp_esi_ignore_https() added
82
 *      VRT_r_beresp_esi_ignore_other_elements() added
83
 *      VRT_l_beresp_esi_ignore_other_elements() added
84
 *      VRT_r_beresp_esi_remove_bom() added
85
 *      VRT_l_beresp_esi_remove_bom() added
86
 *      VRT_r_resp_esi_include_onerror() added
87
 *      VRT_l_resp_esi_include_onerror() added
88
 *      VRT_r_resp_storage() added
89
 *      VRT_l_resp_storage() added
90
 *      VRT_synth_strands() removed
91
 *      VRT_synth_blob() removed
92
 *      VRT_synth_page() removed
93
 *      VRT_Stv() removed
94
 * 23.0 (2026-03-16)
95
 *      [cache.h] http_method_eq() added
96
 *      [cache.h] http_method_among() added
97
 *      [cache.h] http_SetWellKnownMethod() added
98
 *      VRT_r_req_max_age() added
99
 *      VRT_l_req_max_age() added
100
 *      VRT_u_req_max_age() added
101
 *      VRT_r_bereq_retry_connect() added
102
 *      VRT_l_bereq_retry_connect() added
103
 *      VRT_r_beresp_storage_hint() removed
104
 *      VRT_l_beresp_storage_hint() removed
105
 *      "vcl_name" member added to vrt_backend_probe{}
106
 *      VRT_PROBE_string() added
107
 * 22.0 (2025-09-15)
108
 *      VRT_r_obj_stale_age() added
109
 *      VRT_r_obj_stale_can_esi() added
110
 *      VRT_r_obj_stale_grace() added
111
 *      VRT_r_obj_stale_hits() added
112
 *      VRT_r_obj_stale_keep() added
113
 *      VRT_r_obj_stale_proto() added
114
 *      VRT_r_obj_stale_reason() added
115
 *      VRT_r_obj_stale_status() added
116
 *      VRT_r_obj_stale_storage() added
117
 *      VRT_r_obj_stale_time() added
118
 *      VRT_r_obj_stale_ttl() added
119
 *      VRT_r_obj_stale_uncacheable() added
120
 *      VRT_r_obj_stale_is_valid() added
121
 *      enum gethdr_e has new value HDR_OBJ_STALE
122
 *      typedef hdr_t added
123
 *      struct gethdr_s.what changed to hdr_t
124
 *      VRT_VSC_Alloc() renamed to VRT_VSC_Allocv()
125
 *      new VRT_VSC_Alloc() added
126
 *      VRT_r_param_backend_idle_timeout() added
127
 *      VRT_r_param_backend_wait_limit() added
128
 *      VRT_r_param_backend_wait_timeout() added
129
 *      VRT_r_param_between_bytes_timeout() added
130
 *      VRT_r_param_connect_timeout() added
131
 *      VRT_r_param_default_grace() added
132
 *      VRT_r_param_default_keep() added
133
 *      VRT_r_param_default_ttl() added
134
 *      VRT_r_param_first_byte_timeout() added
135
 *      VRT_r_param_idle_send_timeout() added
136
 *      VRT_r_param_max_esi_depth() added
137
 *      VRT_r_param_max_restarts() added
138
 *      VRT_r_param_max_retries() added
139
 *      VRT_r_param_pipe_task_deadline() added
140
 *      VRT_r_param_pipe_timeout() added
141
 *      VRT_r_param_send_timeout() added
142
 *      VRT_r_param_shortlived() added
143
 *      VRT_r_param_timeout_idle() added
144
 *      VRT_r_param_transit_buffer() added
145
 *      VRT_r_param_uncacheable_ttl() added
146
 *      VRT_AddVFP() removed
147
 *      VRT_AddVDP() removed
148
 *      VRT_RemoveVFP() removed
149
 *      VRT_RemoveVDP() removed
150
 *      struct vrt_blob magic added
151
 *      struct strands magic added;
152
 * 21.0 (2025-03-17)
153
 *      VRT_u_req_grace() added
154
 *      VRT_u_req_ttl() added
155
 *      VRT_r_req_filters() added
156
 *      VRT_l_req_filters() added
157
 *      VRT_r_bereq_filters() added
158
 *      VRT_l_bereq_filters() added
159
 * 20.1 (2024-11-08 7.6.1)
160
 *      VDI_EVENT_SICK added to enum vcl_event_e
161
 * 20.0 (2024-09-13)
162
 *      struct vrt_backend.backend_wait_timeout added
163
 *      struct vrt_backend.backend_wait_limit  added
164
 * 19.1 (2024-05-27)
165
 *      [cache_int.h] ObjWaitExtend() gained statep argument
166
 * 19.0 (2024-03-18)
167
 *      [cache.h] (struct req).filter_list renamed to vdp_filter_list
168
 *      order of vcl/vmod and director COLD events reversed to directors first
169
 *      VRT_u_sess_idle_send_timeout() added
170
 *      VRT_u_sess_send_timeout() added
171
 *      VRT_u_sess_timeout_idle() added
172
 *      VRT_u_sess_timeout_linger() added
173
 *      (struct vrt_backend).*_timeout must be initialized to a negative value
174
 *      VRT_BACKEND_INIT() helper macro added
175
 *      VRT_l_bereq_task_deadline() added
176
 *      VRT_r_bereq_task_deadline() added
177
 *      VRT_u_bereq_task_deadline() added
178
 *      VRT_u_bereq_between_bytes_timeout() added
179
 *      VRT_u_bereq_connect_timeout() added
180
 *      VRT_u_bereq_first_byte_timeout() added
181
 * 18.1 (2023-12-05)
182
 *      vbf_objiterate() implementation changed #4013
183
 * 18.0 (2023-09-15)
184
 *      [cache_filter.h] struct vdp gained priv1 member
185
 *      VRT_trace() added
186
 * 17.0 (2023-03-15)
187
 *      VXID is 64 bit
188
 *      [cache.h] http_GetRange() changed
189
 *      exp_close added to struct vrt_backend_probe
190
 *      VRT_new_backend() signature changed
191
 *      VRT_new_backend_clustered() signature changed
192
 *      authority field added to struct vrt_backend
193
 *      release field added to struct vdi_methods
194
 * 16.0 (2022-09-15)
195
 *      VMOD C-prototypes moved into JSON
196
 *      VRT_AddVDP() deprecated
197
 *      VRT_AddVFP() deprecated
198
 *      VRT_RemoveVDP() deprecated
199
 *      VRT_RemoveVFP() deprecated
200
 * 15.0 (2022-03-15)
201
 *      VRT_r_req_transport() added
202
 *      VRT_Assign_Backend() added
203
 *      VRT_StaticDirector() added
204
 *      enum lbody_e changed
205
 *      - previous enum lbody_e values are defined as macros
206
 *      The following functions changed to take `const char *, BODY`:
207
 *      - VRT_l_beresp_body()
208
 *      - VRT_l_resp_body()
209
 *      BODY can either be a BLOB or a STRANDS, but only a STRANDS
210
 *      can take a non-NULL const char * prefix. The changes to BODY
211
 *      assignments doesn't break the ABI or the API.
212
 *      TOSTRAND() and TOSTRANDS() macros added
213
 *      [cache.h] enum sess_close replaced by struct stream_close
214
 *      [cache.h] http_IsHdr() added
215
 *      [cache_filter.h] vfp_init_f() changed to take a VRT_CTX
216
 *      [cache_filter.h] vdp_init_f() changed to take a VRT_CTX
217
 *      [cache_filter.h] VRT_AddFilter() added
218
 *      [cache_filter.h] VRT_RemoveFilter() added
219
 * 14.0 (2021-09-15)
220
 *      VIN_n_Arg() no directly returns the directory name.
221
 *      VSB_new() and VSB_delete() removed
222
 *      VCL_STRINGLIST, vrt_magic_string_end removed
223
 *      VRT_String(), VRT_StringList(), VRT_CollectString() removed
224
 *      VRT_CollectStrands() renamed to VRT_STRANDS_string()
225
 *      The following functions changed to take `const char *, STRANDS`:
226
 *      - VRT_l_client_identity()
227
 *      - VRT_l_req_method()
228
 *      - VRT_l_req_url()
229
 *      - VRT_l_req_proto()
230
 *      - VRT_l_bereq_method()
231
 *      - VRT_l_bereq_url()
232
 *      - VRT_l_bereq_proto()
233
 *      - VRT_l_beresp_body()
234
 *      - VRT_l_beresp_proto()
235
 *      - VRT_l_beresp_reason()
236
 *      - VRT_l_beresp_storage_hint()
237
 *      - VRT_l_beresp_filters()
238
 *      - VRT_l_resp_body()
239
 *      - VRT_l_resp_proto()
240
 *      - VRT_l_resp_reason()
241
 *      - VRT_l_resp_filters()
242
 *      - VRT_SetHdr()
243
 *      VRT_UnsetHdr() added
244
 *      vrt_magic_string_unset removed (use VRT_UnsetHdr() instead)
245
 *      VNUMpfx() removed, SF_Parse_{Integer|Decimal|Number} added
246
 *      vrt_null_strands added
247
 *      vrt_null_blob added
248
 *      VRT_NULL_BLOB_TYPE added as the .type of vrt_null_blob
249
 *      VRT_blob() changed to return vrt_null_blob for
250
 *          len == 0 or src == NULL arguments
251
 *      [cache.h] WS_Front() removed
252
 *      [cache.h] WS_Inside() removed
253
 *      [cache.h] WS_Assert_Allocated() removed
254
 *      [cache.h] WS_Allocated() added
255
 *      [cache.h] WS_Dump() added
256
 * 13.0 (2021-03-15)
257
 *      Move VRT_synth_page() to deprecated status
258
 *      Add VRT_synth_strands() and VRT_synth_blob()
259
 *      struct vrt_type now produced by generate.py
260
 *      VRT_acl_log() moved to VPI_acl_log()
261
 *      VRT_Endpoint_Clone() added.
262
 *      Calling convention for VDP implementation changed
263
 *      VRT_ValidHdr() added.
264
 *      struct vmod_priv_methods added
265
 *      struct vmod_priv free member replaced with methods
266
 *      VRT_CTX_Assert() added
267
 *      VRT_ban_string() signature changed
268
 *      VRT_priv_task_get() added
269
 *      VRT_priv_top_get() added
270
 *      VRT_re_init removed
271
 *      VRT_re_fini removed
272
 *      VRT_re_match signature changed
273
 *      VRT_regsub signature changed
274
 *      VRT_call() added
275
 *      VRT_check_call() added
276
 *      VRT_handled() added
277
 * 12.0 (2020-09-15)
278
 *      Added VRT_DirectorResolve()
279
 *      Added VCL_STRING VRT_BLOB_string(VRT_CTX, VCL_BLOB)
280
 *      [cache.h] WS_Reserve() removed
281
 *      [cache.h] WS_Printf() changed
282
 *      [cache.h] WS_ReservationSize() added
283
 *      [cache.h] WS_Front() deprecated
284
 *      [cache.h] WS_Reservation() added
285
 * 11.0 (2020-03-16)
286
 *      Changed type of vsa_suckaddr_len from int to size_t
287
 *      New prefix_{ptr|len} fields in vrt_backend
288
 *      VRT_HashStrands32() added
289
 *      VRT_l_resp_body() changed
290
 *      VRT_l_beresp_body() changed
291
 *      VRT_Format_Proxy() added        // transitional interface
292
 *      VRT_AllocStrandsWS() added
293
 * 10.0 (2019-09-15)
294
 *      VRT_UpperLowerStrands added.
295
 *      VRT_synth_page now takes STRANDS argument
296
 *      VRT_hashdata() now takes STRANDS argument
297
 *      VCL_BOOL VRT_Strands2Bool(VCL_STRANDS) added.
298
 *      VRT_BundleStrands() moved to vcc_interface.h
299
 *      VRT_VCL_{Busy|Unbusy} changed to VRT_VCL_{Prevent|Allow}_Cold
300
 *      VRT_re[fl]_vcl changed to VRT_VCL_{Prevent|Allow}_Discard
301
 *      VRT_Vmod_{Init|Unload} moved to vcc_interface.h
302
 *      VRT_count moved to vcc_interface.h
303
 *      VRT_VCL_Prevent_Cold() and VRT_VCL_Allow_Cold() added.
304
 *      VRT_vcl_get moved to vcc_interface.h
305
 *      VRT_vcl_rel moved to vcc_interface.h
306
 *      VRT_vcl_select moved to vcc_interface.h
307
 *      VRT_VSA_GetPtr() changed
308
 *      VRT_ipcmp() changed
309
 *      VRT_Stv_*() functions renamed to VRT_stevedore_*()
310
 *      [cache.h] WS_ReserveAll() added
311
 *      [cache.h] WS_Reserve(ws, 0) deprecated
312
 * 9.0 (2019-03-15)
313
 *      Make 'len' in vmod_priv 'long'
314
 *      HTTP_Copy() removed
315
 *      HTTP_Dup() added
316
 *      HTTP_Clone() added
317
 *      VCL_BLOB changed to newly introduced struct vrt_blob *
318
 *      VRT_blob() changed
319
 *      req->req_bodybytes removed
320
 *          use: AZ(ObjGetU64(req->wrk, req->body_oc, OA_LEN, &u));
321
 *      struct vdi_methods .list callback signature changed
322
 *      VRT_LookupDirector() added
323
 *      VRT_SetChanged() added
324
 *      VRT_SetHealth() removed
325
 *      // in cache_filter.h:
326
 *      VRT_AddVDP() added
327
 *      VRT_RemoveVDP() added
328
 * 8.0 (2018-09-15)
329
 *      VRT_Strands() added
330
 *      VRT_StrandsWS() added
331
 *      VRT_CollectStrands() added
332
 *      VRT_STRANDS_string() removed from vrt.h (never implemented)
333
 *      VRT_Vmod_Init signature changed
334
 *      VRT_Vmod_Fini changed to VRT_Vmod_Unload
335
 *      // directors
336
 *      VRT_backend_healthy() removed
337
 *      VRT_Healthy() changed prototype
338
 *      struct vdi_methods and callback prototypes added
339
 *      struct director added;
340
 *      VRT_AddDirector() added
341
 *      VRT_SetHealth() added
342
 *      VRT_DisableDirector() added
343
 *      VRT_DelDirector() added
344
 *      // in cache_filter.h:
345
 *      VRT_AddVFP() added
346
 *      VRT_RemoveVFP() added
347
 * 7.0 (2018-03-15)
348
 *      lots of stuff moved from cache.h to cache_int.h
349
 *         (ie: from "$Abi vrt" to "$Abi strict")
350
 *      VCL_INT and VCL_BYTES are always 64 bits.
351
 *      path field added to struct vrt_backend
352
 *      VRT_Healthy() added
353
 *      VRT_VSC_Alloc() added
354
 *      VRT_VSC_Destroy() added
355
 *      VRT_VSC_Hide() added
356
 *      VRT_VSC_Reveal() added
357
 *      VRT_VSC_Overhead() added
358
 *      struct director.event added
359
 *      struct director.destroy added
360
 *      VRT_r_beresp_storage_hint() VCL <= 4.0  #2509
361
 *      VRT_l_beresp_storage_hint() VCL <= 4.0  #2509
362
 *      VRT_blob() added
363
 *      VCL_STRANDS added
364
 * 6.1 (2017-09-15 aka 5.2)
365
 *      http_CollectHdrSep added
366
 *      VRT_purge modified (may fail a transaction, signature changed)
367
 *      VRT_r_req_hash() added
368
 *      VRT_r_bereq_hash() added
369
 * 6.0 (2017-03-15):
370
 *      VRT_hit_for_pass added
371
 *      VRT_ipcmp added
372
 *      VRT_Vmod_Init signature changed
373
 *      VRT_vcl_lookup removed
374
 *      VRT_fail added
375
 *      [cache.h] WS_Reset and WS_Snapshot signatures changed
376
 *      [cache.h] WS_Front added
377
 *      [cache.h] WS_ReserveLumps added
378
 *      [cache.h] WS_Inside added
379
 *      [cache.h] WS_Assert_Allocated added
380
 * 5.0:
381
 *      Varnish 5.0 release "better safe than sorry" bump
382
 * 4.0:
383
 *      VCL_BYTES changed to long long
384
 *      VRT_CacheReqBody changed signature
385
 * 3.2:
386
 *      vrt_backend grew .proxy_header field
387
 *      vrt_ctx grew .sp field.
388
 *      vrt_acl type added
389
 */
390
391
/***********************************************************************/
392
393
#include <stddef.h>             // NULL, size_t
394
#include <stdint.h>             // [u]int%d_t
395
396
struct busyobj;
397
struct director;
398
struct http;
399
struct lock;
400
struct req;
401
struct stevedore;
402
struct stream_close;
403
struct suckaddr;
404
struct vcl;
405
struct vcldir;
406
struct vcl_sub;
407
struct vmod;
408
struct vmod_priv;
409
struct vrt_acl;
410
struct vsb;
411
struct vsc_seg;
412
struct vsl_log;
413
struct vsmw_cluster;
414
struct wrk_vpi;
415
struct ws;
416
417
typedef const struct stream_close *stream_close_t;
418
419
/***********************************************************************
420
 * VCL_STRANDS:
421
 *
422
 * An argc+argv type of data structure where n indicates the number of
423
 * strings in the p array. Individual components of a strands may be null.
424
 *
425
 * A STRANDS allows you to work on a strings concatenation with the
426
 * option to collect it into a single STRING, or if possible work
427
 * directly on individual parts.
428
 *
429
 * The memory management is very strict: a VMOD function receiving a
430
 * STRANDS argument should keep no reference after the function returns.
431
 * Retention of a STRANDS further in the ongoing task is undefined
432
 * behavior and may result in a panic or data corruption.
433
 */
434
435
struct strands {
436
        unsigned        magic;
437 108773
#define STRANDS_MAGIC   0x5d5ab196
438
        int             n;
439
        const char      **p;
440
};
441
442
/*
443
 * A VCL_STRANDS return value must never be NULL. Use this instead
444
 */
445
extern const struct strands *const vrt_null_strands;
446
447
/*
448
 * Macros for VCL_STRANDS creation
449
 */
450 106797
#define TOSTRAND(s)(&(struct strands)                           \
451 106797
        {.magic=STRANDS_MAGIC,.n=1,.p=(const char *[1]){(s)}})
452 1789
#define TOSTRANDS(x, ...)(&(struct strands)                     \
453 1789
        {.magic=STRANDS_MAGIC,.n=x,.p=(const char *[x]){__VA_ARGS__}})
454
455
/*
456
 * Macros for VCL_STRANDS use
457
 */
458
459
//lint -emacro(506, _strands_foreach) constant value boolean
460
#define _strands_foreach(var, s, iter, end)             \
461 103707
        for (const char * const *iter = (s)->p,         \
462 103707
                * const *end = iter + (s)->n,           \
463 103707
                *var = NULL;                            \
464 218023
            iter < end && (var = *iter, 1);             \
465 114316
            iter++)
466
467
#define STRANDS_FOREACH(var, s)                         \
468 103707
        _strands_foreach(var, s,                        \
469 103707
            VUNIQ_NAME(_v_ ## var ## _iter),            \
470 103707
            VUNIQ_NAME(_v_ ## var ## _end))
471
472
/***********************************************************************
473
 * VCL_BLOB:
474
 *
475
 * Opaque, immutable data (pointer + length), minimum lifetime is the
476
 * VCL task.
477
 *
478
 * Type (optional) is owned by the creator of the blob. blob consumers
479
 * may use it for checks, but should not assert on it.
480
 *
481
 * The data behind the blob pointer is assumed to be immutable for the
482
 * blob's lifetime.
483
 *
484
 * - memory for shortlived blobs can be put on the tasks workspace
485
 *
486
 * - management of memory for longer lived blobs is up to the vmod
487
 *   (in which case the blob will probably be embedded in an object or
488
 *    referenced by other state with vcl lifetime)
489
 */
490
491
struct vrt_blob {
492
        unsigned        magic;
493 65
#define VRT_BLOB_MAGIC  0xe114db9e
494
        unsigned        type;
495
        size_t          len;
496
        const void      *blob;
497
};
498
499
#define VRT_NULL_BLOB_TYPE 0xfade4fa0
500
extern const struct vrt_blob *const vrt_null_blob;
501
502
/***********************************************************************
503
 * This is the central definition of the mapping from VCL types to
504
 * C-types.  The python scripts read these from here.
505
 * (keep alphabetic order)
506
 */
507
508
typedef const struct vrt_acl *                  VCL_ACL;
509
typedef const struct director *                 VCL_BACKEND;
510
typedef const struct vrt_blob *                 VCL_BLOB;
511
typedef const void *                            VCL_BODY;
512
typedef unsigned                                VCL_BOOL;
513
typedef int64_t                                 VCL_BYTES;
514
typedef vtim_dur                                VCL_DURATION;
515
typedef const char *                            VCL_ENUM;
516
typedef const struct gethdr_s *                 VCL_HEADER;
517
typedef struct http *                           VCL_HTTP;
518
typedef void                                    VCL_INSTANCE;
519
typedef int64_t                                 VCL_INT;
520
typedef const struct suckaddr *                 VCL_IP;
521
typedef const struct vrt_backend_probe *        VCL_PROBE;
522
typedef double                                  VCL_REAL;
523
typedef const struct vre *                      VCL_REGEX;
524
typedef const struct stevedore *                VCL_STEVEDORE;
525
typedef const struct strands *                  VCL_STRANDS;
526
typedef const char *                            VCL_STRING;
527
typedef const struct vcl_sub *                  VCL_SUB;
528
typedef vtim_real                               VCL_TIME;
529
typedef struct vcl *                            VCL_VCL;
530
typedef void                                    VCL_VOID;
531
532
/***********************************************************************
533
 * This is the composite "context" argument for compiled VCL, VRT and
534
 * VMOD functions.
535
 */
536
537
struct vrt_ctx {
538
        unsigned                        magic;
539
#define VRT_CTX_MAGIC                   0x6bb8f0db
540
541
        unsigned                        syntax;
542
        unsigned                        vclver;
543
        unsigned                        method;
544
545
        struct wrk_vpi                  *vpi;
546
547
        /*
548
         * msg is for error messages and exists only for
549
         * VCL_EVENT_LOAD
550
         * VCL_EVENT_WARM
551
         */
552
        struct vsb                      *msg;
553
        struct vsl_log                  *vsl;
554
        VCL_VCL                         vcl;
555
        struct ws                       *ws;
556
557
        struct sess                     *sp;
558
559
        struct req                      *req;
560
        VCL_HTTP                        http_req;
561
        VCL_HTTP                        http_req0;
562
        VCL_HTTP                        http_req_top;
563
        VCL_HTTP                        http_resp;
564
565
        struct busyobj                  *bo;
566
        VCL_HTTP                        http_bereq;
567
        VCL_HTTP                        http_beresp;
568
569
        vtim_real                       now;
570
571
        /*
572
         * method specific argument:
573
         *    hash:             struct VSHA256Context
574
         *    error:            struct vsb *
575
         *    synth:            ssize_t *
576
         */
577
        void                            *specific;
578
        /* if present, vbitmap of called subs */
579
        void                            *called;
580
};
581
582
#define VRT_CTX         const struct vrt_ctx *ctx
583
void VRT_CTX_Assert(VRT_CTX);
584
585
enum vcl_func_call_e {
586
        VSUB_STATIC,    // VCL "call" action, only allowed from VCC
587
        VSUB_DYNAMIC,   // VRT_call()
588
        VSUB_CHECK      // VRT_check_call()
589
};
590
591
enum vcl_func_fail_e {
592
        VSUB_E_OK,
593
        VSUB_E_RECURSE, // call would recurse
594
        VSUB_E_METHOD   // cannot be called from this method
595
};
596
597
typedef void vcl_func_f(VRT_CTX, enum vcl_func_call_e, enum vcl_func_fail_e *);
598
599
/***********************************************************************
600
 * Events sent to VMODs and directors:
601
 * - VCL: VCL temperature events
602
 * - VDI: director events
603
 */
604
605
enum vcl_event_e {
606
        VCL_EVENT_LOAD,
607
        VCL_EVENT_WARM,
608
        VCL_EVENT_COLD,
609
        VCL_EVENT_DISCARD,
610
611
        VDI_EVENT_SICK
612
};
613
614
typedef int vmod_event_f(VRT_CTX, struct vmod_priv *, enum vcl_event_e);
615
616
/***********************************************************************
617
 * Utility functions operating on VCL_types
618
 * (alphabetic by type-ish)
619
 */
620
621
/* VCL_ACL */
622
int VRT_acl_match(VRT_CTX, VCL_ACL, VCL_IP);
623
624
/* VCL_BACKEND */
625
VCL_BACKEND VRT_DirectorResolve(VRT_CTX, VCL_BACKEND);
626
627
/* VCL_BLOB */
628
VCL_BLOB VRT_blob(VRT_CTX, const char *, const void *, size_t, unsigned);
629
630
/* VCL_INT */
631
int VRT_INT_is_valid(VCL_INT);
632
633
/* VCL_IP */
634
int VRT_VSA_GetPtr(VRT_CTX, VCL_IP sua, const unsigned char ** dst);
635
VCL_BOOL VRT_ipcmp(VRT_CTX, VCL_IP, VCL_IP);
636
void VRT_Format_Proxy(struct vsb *, VCL_INT, VCL_IP, VCL_IP, VCL_STRING);
637
638
/* VCL_REAL */
639
int VRT_REAL_is_valid(VCL_REAL);
640
641
/* VCL_REGEX */
642
VCL_BOOL VRT_re_match(VRT_CTX, VCL_STRING, VCL_REGEX);
643
VCL_STRING VRT_regsub(VRT_CTX, int all, VCL_STRING, VCL_REGEX, VCL_STRING);
644
645
/* VCL_STEVEDORE */
646
VCL_STEVEDORE VRT_stevedore(const char *nm);
647
648
/* VCL_STRANDS */
649
struct strands * VRT_AllocStrandsWS(struct ws *, int);
650
int VRT_CompareStrands(VCL_STRANDS a, VCL_STRANDS b);
651
VCL_BOOL VRT_Strands2Bool(VCL_STRANDS);
652
uint32_t VRT_HashStrands32(VCL_STRANDS);
653
char *VRT_Strands(char *, size_t, VCL_STRANDS);
654
VCL_STRING VRT_StrandsWS(struct ws *, const char *, VCL_STRANDS);
655
VCL_STRING VRT_UpperLowerStrands(VRT_CTX, VCL_STRANDS s, int up);
656
657
/* VCL_SUB */
658
VCL_STRING VRT_check_call(VRT_CTX, VCL_SUB);
659
VCL_VOID VRT_call(VRT_CTX, VCL_SUB);
660
661
/* Functions to turn types into canonical strings */
662
663
VCL_STRING VRT_BACKEND_string(VCL_BACKEND);
664
VCL_STRING VRT_BOOL_string(VCL_BOOL);
665
VCL_STRING VRT_BLOB_string(VRT_CTX, VCL_BLOB);
666
VCL_STRING VRT_INT_string(VRT_CTX, VCL_INT);
667
VCL_STRING VRT_IP_string(VRT_CTX, VCL_IP);
668
VCL_STRING VRT_PROBE_string(VCL_PROBE);
669
VCL_STRING VRT_REAL_string(VRT_CTX, VCL_REAL);
670
VCL_STRING VRT_STEVEDORE_string(VCL_STEVEDORE);
671
VCL_STRING VRT_STRANDS_string(VRT_CTX, VCL_STRANDS);
672
VCL_STRING VRT_TIME_string(VRT_CTX, VCL_TIME);
673
674
/* historical */
675
int VRT_strcmp(const char *s1, const char *s2);
676
void VRT_memmove(void *dst, const void *src, unsigned len);
677
678
/***********************************************************************
679
 * We want the VCC to spit this structs out as const, but when VMODs
680
 * come up with them we want to clone them into malloc'ed space which
681
 * we can free again.
682
 * We collect all the knowledge here by macroizing the fields and make
683
 * a macro for handling them all.
684
 * See also:  cache_backend.h & cache_backend_cfg.c
685
 * One of those things...
686
 */
687
688
struct vrt_endpoint {
689
        unsigned                        magic;
690
#define VRT_ENDPOINT_MAGIC              0xcc419347
691
        VCL_IP                          ipv4;
692
        VCL_IP                          ipv6;
693
        const char                      *uds_path;
694
        const struct vrt_blob           *preamble;
695
};
696
697
#define VRT_BACKEND_FIELDS(rigid)                               \
698
        rigid char                      *vcl_name;              \
699
        rigid char                      *hosthdr;               \
700
        rigid char                      *authority;             \
701
        vtim_dur                        connect_timeout;        \
702
        vtim_dur                        first_byte_timeout;     \
703
        vtim_dur                        between_bytes_timeout;  \
704
        vtim_dur                        backend_wait_timeout;   \
705
        unsigned                        max_connections;        \
706
        unsigned                        proxy_header;           \
707
        unsigned                        backend_wait_limit;
708
709
#define VRT_BACKEND_INIT(be)                                    \
710 31
        do {                                                    \
711 31
                INIT_OBJ(be, VRT_BACKEND_MAGIC);                \
712 31
                (be)->connect_timeout = -1.0;                   \
713 31
                (be)->first_byte_timeout = -1.0;                \
714 31
                (be)->between_bytes_timeout = -1.0;             \
715 31
                (be)->backend_wait_timeout = -1.0;              \
716 31
        } while(0)
717
718
#define VRT_BACKEND_HANDLE()                    \
719 1477
        do {                                    \
720 1477
                DA(vcl_name);                   \
721 1477
                DA(hosthdr);                    \
722 1477
                DA(authority);                  \
723 1398
                DN(connect_timeout);            \
724 1398
                DN(first_byte_timeout);         \
725 1398
                DN(between_bytes_timeout);      \
726 1398
                DN(backend_wait_timeout);       \
727 1398
                DN(max_connections);            \
728 1398
                DN(proxy_header);               \
729 1398
                DN(backend_wait_limit);         \
730 1477
        } while(0)
731
732
struct vrt_backend {
733
        unsigned                        magic;
734
#define VRT_BACKEND_MAGIC               0x4799ce6c
735
        const struct vrt_endpoint       *endpoint;
736
        VRT_BACKEND_FIELDS(const)
737
        VCL_PROBE                       probe;
738
};
739
740
#define VRT_BACKEND_PROBE_FIELDS(rigid)                         \
741
        vtim_dur                        timeout;                \
742
        vtim_dur                        interval;               \
743
        unsigned                        exp_status;             \
744
        unsigned                        window;                 \
745
        unsigned                        threshold;              \
746
        unsigned                        initial;                \
747
        unsigned                        exp_close;
748
749
#define VRT_BACKEND_PROBE_HANDLE()              \
750 44
        do {                                    \
751 44
                DN(timeout);                    \
752 44
                DN(interval);                   \
753 44
                DN(exp_status);                 \
754 44
                DN(window);                     \
755 44
                DN(threshold);                  \
756 44
                DN(initial);                    \
757 44
                DN(exp_close);                  \
758 44
        } while (0)
759
760
struct vrt_backend_probe {
761
        unsigned                        magic;
762
#define VRT_BACKEND_PROBE_MAGIC         0x84998490
763
        const char                      *url;
764
        const char                      *request;
765
        VRT_BACKEND_PROBE_FIELDS(const)
766
        const char                      *vcl_name;
767
};
768
769
/* Backend related */
770
VCL_BACKEND VRT_new_backend(VRT_CTX, const struct vrt_backend *, VCL_BACKEND);
771
VCL_BACKEND VRT_new_backend_clustered(VRT_CTX,
772
    struct vsmw_cluster *, const struct vrt_backend *, VCL_BACKEND);
773
size_t VRT_backend_vsm_need(VRT_CTX);
774
void VRT_delete_backend(VRT_CTX, VCL_BACKEND *);
775
struct vrt_endpoint *VRT_Endpoint_Clone(const struct vrt_endpoint *vep);
776
777
778
/***********************************************************************
779
 * Getting hold of the various struct http
780
 */
781
782
enum gethdr_e {
783
        HDR_REQ,
784
        HDR_REQ0,
785
        HDR_REQ_TOP,
786
        HDR_RESP,
787
        HDR_OBJ,
788
        HDR_BEREQ,
789
        HDR_BERESP,
790
        HDR_OBJ_STALE
791
};
792
793
typedef const struct {
794
        unsigned char   len;
795
        const char      str[];
796
} *hdr_t;
797
798
//lint -esym(754, _hdr_s, _hdr_l) local struct member ... not referenced
799
//lint -emacro(740, HDR) unusual cast
800
#define HDR(name)                                                       \
801
        ((hdr_t)&(const struct {                                        \
802
                unsigned char _hdr_l;                                   \
803
                char _hdr_s[sizeof(name ":")];                          \
804
        }){ sizeof(name), name ":" })
805
806
#define CHECK_HDR(hdr)                                                  \
807 630659
        do {                                                            \
808 630659
                AN(hdr);                                                \
809 630659
                assert((hdr)->len > 0);                                 \
810 630659
                assert((hdr)->len == vstrlen((hdr)->str));              \
811 630659
                assert((hdr)->str[(hdr)->len - 1] == ':');              \
812 630659
        } while (0)
813
814
#define CAST_HDR(hdr, str)                                              \
815 1065
        do {                                                            \
816 1065
                hdr = (hdr_t)(str);                                     \
817 1065
                CHECK_HDR(hdr);                                         \
818 1065
        } while (0)
819
820
struct gethdr_s {
821
        enum gethdr_e   where;
822
        hdr_t           what;
823
};
824
825
VCL_HTTP VRT_selecthttp(VRT_CTX, enum gethdr_e);
826
VCL_STRING VRT_GetHdr(VRT_CTX, VCL_HEADER);
827
828
/***********************************************************************
829
 * req related
830
 */
831
832
enum lbody_e {
833
        LBODY_SET_STRING,
834
        LBODY_ADD_STRING,
835
        LBODY_SET_BLOB,
836
        LBODY_ADD_BLOB
837
};
838
839
VCL_BYTES VRT_CacheReqBody(VRT_CTX, VCL_BYTES maxsize);
840
841
VCL_STRING VRT_ban_string(VRT_CTX, VCL_STRING);
842
VCL_INT VRT_purge(VRT_CTX, VCL_DURATION, VCL_DURATION, VCL_DURATION);
843
VCL_VOID VRT_synth(VRT_CTX, VCL_INT, VCL_STRING);
844
VCL_VOID VRT_hit_for_pass(VRT_CTX, VCL_DURATION);
845
846
VCL_BOOL VRT_ValidHdr(VRT_CTX, VCL_STRANDS);
847
VCL_VOID VRT_UnsetHdr(VRT_CTX, VCL_HEADER);
848
VCL_VOID VRT_SetHdr(VRT_CTX, VCL_HEADER, const char *pfx, VCL_STRANDS);
849
VCL_VOID VRT_handling(VRT_CTX, unsigned hand);
850
unsigned VRT_handled(VRT_CTX);
851
VCL_VOID VRT_trace(VRT_CTX, VCL_BOOL);
852
VCL_VOID VRT_fail(VRT_CTX, const char *fmt, ...) v_printflike_(2,3) v_cold_;
853
VCL_VOID VRT_hashdata(VRT_CTX, VCL_STRANDS);
854
855
VCL_VOID VRT_Rollback(VRT_CTX);
856
857
/***********************************************************************
858
 * VDI - Director API
859
 */
860
typedef VCL_BOOL vdi_healthy_f(VRT_CTX, VCL_BACKEND, VCL_TIME *);
861
typedef VCL_BACKEND vdi_resolve_f(VRT_CTX, VCL_BACKEND);
862
typedef int vdi_gethdrs_f(VRT_CTX, VCL_BACKEND);
863
typedef VCL_IP vdi_getip_f(VRT_CTX, VCL_BACKEND);
864
typedef void vdi_finish_f(VRT_CTX, VCL_BACKEND);
865
typedef stream_close_t vdi_http1pipe_f(VRT_CTX, VCL_BACKEND);
866
typedef void vdi_event_f(VCL_BACKEND, enum vcl_event_e);
867
typedef void vdi_release_f(VCL_BACKEND);
868
typedef void vdi_destroy_f(VCL_BACKEND);
869
typedef void vdi_panic_f(VCL_BACKEND, struct vsb *);
870
typedef void vdi_list_f(VRT_CTX, VCL_BACKEND, struct vsb *, int, int);
871
872
struct vdi_methods {
873
        unsigned                        magic;
874
#define VDI_METHODS_MAGIC               0x4ec0c4bb
875
        const char                      *type;
876
        vdi_http1pipe_f                 *http1pipe;
877
        vdi_healthy_f                   *healthy;
878
        vdi_resolve_f                   *resolve;
879
        vdi_gethdrs_f                   *gethdrs;
880
        vdi_getip_f                     *getip;
881
        vdi_finish_f                    *finish;
882
        vdi_event_f                     *event;
883
        // called by VRT_DelDirector: deref all backends
884
        vdi_release_f                   *release;
885
        // when refcount goes 0
886
        vdi_destroy_f                   *destroy;
887
        vdi_panic_f                     *panic;
888
        vdi_list_f                      *list;
889
};
890
891
struct director {
892
        unsigned                        magic;
893
#define DIRECTOR_MAGIC                  0x3336351d
894
        void                            *priv;
895
        char                            *vcl_name;
896
        struct vcldir                   *vdir;
897
        struct lock                     *mtx;
898
};
899
900
VCL_BOOL VRT_Healthy(VRT_CTX, VCL_BACKEND, VCL_TIME *);
901
VCL_VOID VRT_SetChanged(VCL_BACKEND, VCL_TIME);
902
VCL_BACKEND VRT_AddDirector(VRT_CTX, const struct vdi_methods *,
903
    void *, const char *, ...) v_printflike_(4, 5);
904
void VRT_DisableDirector(VCL_BACKEND);
905
void VRT_StaticDirector(VCL_BACKEND);
906
VCL_BACKEND VRT_LookupDirector(VRT_CTX, VCL_STRING);
907
void VRT_DelDirector(VCL_BACKEND *);
908
void VRT_Assign_Backend(VCL_BACKEND *dst, VCL_BACKEND src);
909
910
/***********************************************************************
911
 * vmod_priv related
912
 */
913
typedef void vmod_priv_fini_f(VRT_CTX, void *);
914
915
struct vmod_priv_methods {
916
        unsigned                        magic;
917
#define VMOD_PRIV_METHODS_MAGIC 0xcea5ff99
918
        const char                      *type;
919
        vmod_priv_fini_f                *fini;
920
};
921
922
struct vmod_priv {
923
        void                            *priv;
924
        long                            len;
925
        const struct vmod_priv_methods  *methods;
926
};
927
928
void VRT_priv_fini(VRT_CTX, const struct vmod_priv *p);
929
struct vmod_priv *VRT_priv_task(VRT_CTX, const void *vmod_id);
930
struct vmod_priv *VRT_priv_task_get(VRT_CTX, const void *vmod_id);
931
struct vmod_priv *VRT_priv_top(VRT_CTX, const void *vmod_id);
932
struct vmod_priv *VRT_priv_top_get(VRT_CTX, const void *vmod_id);
933
934
/***********************************************************************
935
 * VSM and VSC
936
 */
937
938
struct vsmw_cluster *VRT_VSM_Cluster_New(VRT_CTX, size_t);
939
void VRT_VSM_Cluster_Destroy(VRT_CTX, struct vsmw_cluster **);
940
941
#ifdef va_start // XXX: hackish
942
void *VRT_VSC_Allocv(struct vsmw_cluster *, struct vsc_seg **,
943
    const char *, size_t, const unsigned char *, size_t, const char *, va_list);
944
void *VRT_VSC_Alloc(struct vsmw_cluster *, struct vsc_seg **,
945
    const char *, size_t, const unsigned char *, size_t, const char *, ...);
946
#endif
947
void VRT_VSC_Destroy(const char *, struct vsc_seg *);
948
void VRT_VSC_Hide(const struct vsc_seg *);
949
void VRT_VSC_Reveal(const struct vsc_seg *);
950
size_t VRT_VSC_Overhead(size_t);
951
952
/***********************************************************************
953
 * API to restrict the VCL in various ways
954
 */
955
956
struct vclref;
957
struct vclref * VRT_VCL_Prevent_Cold(VRT_CTX, const char *);
958
void VRT_VCL_Allow_Cold(struct vclref **);
959
960
struct vclref * VRT_VCL_Prevent_Discard(VRT_CTX, const char *);
961
void VRT_VCL_Allow_Discard(struct vclref **);