[master] 540c588 Have generate.py pick the VCL variables out of the documentation, instead of the other way around.
Poul-Henning Kamp
phk at FreeBSD.org
Thu Feb 15 11:40:07 UTC 2018
commit 540c588574141f2391ad1b65d20caa99d290e820
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Thu Feb 15 11:38:38 2018 +0000
Have generate.py pick the VCL variables out of the documentation,
instead of the other way around.
diff --git a/doc/sphinx/reference/vcl.rst b/doc/sphinx/reference/vcl.rst
index 1d04884..566a4c3 100644
--- a/doc/sphinx/reference/vcl.rst
+++ b/doc/sphinx/reference/vcl.rst
@@ -392,7 +392,7 @@ In VCL you have access to certain variable objects. These contain
requests and responses currently being worked on. What variables are
available depends on context.
-.. include:: ../include/vcl_var.rst
+.. include:: vcl_var.rst
Functions
diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
new file mode 100644
index 0000000..cbd06e4
--- /dev/null
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -0,0 +1,1064 @@
+
+remote
+~~~~~~
+
+remote.ip
+
+ Type: IP
+
+ Readable from: client, backend
+
+
+ The IP address of the other end of the TCP connection.
+ This can either be the clients IP, or the outgoing IP
+ of a proxy server.
+
+
+client
+~~~~~~
+
+client.ip
+
+ Type: IP
+
+ Readable from: client, backend
+
+
+ The client's IP address.
+
+
+client.identity
+
+ Type: STRING
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Identification of the client, used to load balance
+ in the client director. Defaults to the client's IP
+ address.
+
+
+local
+~~~~~
+
+local.endpoint
+
+ Type: STRING
+
+ Readable from: client
+
+
+ The transport address of the '-a' socket the session was
+ accepted on.
+
+
+local.socket
+
+ Type: STRING
+
+ Readable from: client
+
+
+ The name of the '-a' socket the session was accepted on.
+
+
+local.ip
+
+ Type: IP
+
+ Readable from: client, backend
+
+
+ The IP address of the local end of the TCP connection.
+
+
+server
+~~~~~~
+
+server.ip
+
+ Type: IP
+
+ Readable from: client, backend
+
+
+ The IP address of the socket on which the client
+ connection was received.
+
+
+server.hostname
+
+ Type: STRING
+
+ Readable from: all
+
+
+ The host name of the server.
+
+
+server.identity
+
+ Type: STRING
+
+ Readable from: all
+
+
+ The identity of the server, as set by the -i
+ parameter. If the -i parameter is not passed to varnishd,
+ server.identity will be set to the hostname of the machine.
+
+
+req
+~~~
+
+req
+
+ Type: HTTP
+
+ Readable from: client
+
+
+ The entire request HTTP data structure
+
+
+req.method
+
+ Type: STRING
+
+ Readable from: client
+
+ Writable from: client
+
+
+ The request type (e.g. "GET", "HEAD").
+
+
+req.hash
+
+ Type: BLOB
+
+ Readable from: vcl_hit, vcl_miss, vcl_pass, vcl_purge, vcl_deliver
+
+
+ The hash key of this request.
+
+
+req.url
+
+ Type: STRING
+
+ Readable from: client
+
+ Writable from: client
+
+
+ The requested URL.
+
+
+req.proto
+
+ Type: STRING
+
+ Readable from: client
+
+ Writable from: client
+
+
+ The HTTP protocol version used by the client.
+
+
+req.http.
+
+ Type: HEADER
+
+ Readable from: client
+
+ Writable from: client
+
+ Unsetable from: client
+
+
+ The corresponding HTTP header.
+
+
+req.restarts
+
+ Type: INT
+
+ Readable from: client
+
+
+ A count of how many times this request has been restarted.
+
+
+req.storage
+
+ Type: STEVEDORE
+
+ Readable from: client
+
+ Writable from: client
+
+
+ The storage backend to use to save this request body.
+
+
+req.esi_level
+
+ Type: INT
+
+ Readable from: client
+
+
+ A count of how many levels of ESI requests we're currently at.
+
+
+req.ttl
+
+ Type: DURATION
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Upper limit on the object age for cache lookups to return hit.
+
+ Usage of req.ttl should be replaced with a check on
+ obj.ttl in vcl_hit, returning miss when needed, but
+ this currently hits bug #1799, so an additional
+ workaround is required.
+
+ Deprecated and scheduled for removal with varnish release 7.
+
+
+req.xid
+
+ Type: STRING
+
+ Readable from: client
+
+
+ Unique ID of this request.
+
+
+req.esi
+
+ Type: BOOL
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Boolean. Set to false to disable ESI processing
+ regardless of any value in beresp.do_esi. Defaults
+ to true. This variable is subject to change in
+ future versions, you should avoid using it.
+
+
+req.can_gzip
+
+ Type: BOOL
+
+ Readable from: client
+
+
+ Does the client accept the gzip transfer encoding.
+
+
+req.backend_hint
+
+ Type: BACKEND
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Set bereq.backend to this if we attempt to fetch.
+ When set to a director, reading this variable returns
+ an actual backend if the director has resolved immediately,
+ or the director otherwise.
+ When used in string context, returns the name of the director
+ or backend, respectively.
+
+
+req.hash_ignore_busy
+
+ Type: BOOL
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Ignore any busy object during cache lookup. You
+ would want to do this if you have two server looking
+ up content from each other to avoid potential deadlocks.
+
+
+req.hash_always_miss
+
+ Type: BOOL
+
+ Readable from: client
+
+ Writable from: client
+
+
+ Force a cache miss for this request. If set to true
+ Varnish will disregard any existing objects and
+ always (re)fetch from the backend.
+
+
+req_top
+~~~~~~~
+
+req_top.method
+
+ Type: STRING
+
+ Readable from: client
+
+
+ The request method of the top-level request in a tree
+ of ESI requests. (e.g. "GET", "HEAD").
+ Identical to req.method in non-ESI requests.
+
+
+req_top.url
+
+ Type: STRING
+
+ Readable from: client
+
+
+ The requested URL of the top-level request in a tree
+ of ESI requests.
+ Identical to req.url in non-ESI requests.
+
+
+req_top.http.
+
+ Type: HEADER
+
+ Readable from: client
+
+
+ HTTP headers of the top-level request in a tree of ESI requests.
+ Identical to req.http. in non-ESI requests.
+
+
+req_top.proto
+
+ Type: STRING
+
+ Readable from: client
+
+
+ HTTP protocol version of the top-level request in a tree of
+ ESI requests.
+ Identical to req.proto in non-ESI requests.
+
+
+bereq
+~~~~~
+
+bereq
+
+ Type: HTTP
+
+ Readable from: backend
+
+
+ The entire backend request HTTP data structure
+
+
+bereq.xid
+
+ Type: STRING
+
+ Readable from: backend
+
+
+ Unique ID of this request.
+
+
+bereq.retries
+
+ Type: INT
+
+ Readable from: backend
+
+
+ A count of how many times this request has been retried.
+
+
+bereq.backend
+
+ Type: BACKEND
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+
+ This is the backend or director we attempt to fetch from.
+ When set to a director, reading this variable returns
+ an actual backend if the director has resolved immediately,
+ or the director otherwise.
+ When used in string context, returns the name of the director
+ or backend, respectively.
+
+
+bereq.body
+
+ Type: BODY
+
+ Unsetable from: vcl_backend_fetch
+
+
+ The request body.
+
+
+bereq.hash
+
+ Type: BLOB
+
+ Readable from: vcl_pipe, backend
+
+
+ The hash key of this request.
+
+
+bereq.method
+
+ Type: STRING
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+
+ The request type (e.g. "GET", "HEAD").
+
+
+bereq.url
+
+ Type: STRING
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+
+ The requested URL.
+
+
+bereq.proto
+
+ Type: STRING
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+
+ The HTTP protocol version used to talk to the server.
+
+
+bereq.http.
+
+ Type: HEADER
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+ Unsetable from: vcl_pipe, backend
+
+
+ The corresponding HTTP header.
+
+
+bereq.uncacheable
+
+ Type: BOOL
+
+ Readable from: backend
+
+
+ Indicates whether this request is uncacheable due
+ to a pass in the client side or a hit on an hit-for-pass
+ object.
+
+
+bereq.connect_timeout
+
+ Type: DURATION
+
+ Readable from: vcl_pipe, backend
+
+ Writable from: vcl_pipe, backend
+
+
+ The time in seconds to wait for a backend connection.
+
+
+bereq.first_byte_timeout
+
+ Type: DURATION
+
+ Readable from: backend
+
+ Writable from: backend
+
+
+ The time in seconds to wait for the first byte from
+ the backend. Not available in pipe mode.
+
+
+bereq.between_bytes_timeout
+
+ Type: DURATION
+
+ Readable from: backend
+
+ Writable from: backend
+
+
+ The time in seconds to wait between each received byte from the
+ backend. Not available in pipe mode.
+
+
+bereq.is_bgfetch
+
+ Type: BOOL
+
+ Readable from: backend
+
+
+ True for background fetches.
+
+
+beresp
+~~~~~~
+
+beresp
+
+ Type: HTTP
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+
+ The entire backend response HTTP data structure
+
+
+beresp.body
+
+ Type: BODY
+
+ Writable from: vcl_backend_error
+
+
+ The response body.
+
+
+beresp.proto
+
+ Type: STRING
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ The HTTP protocol version used the backend replied with.
+
+
+beresp.status
+
+ Type: INT
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ The HTTP status code returned by the server.
+
+ Status codes >1000 can be set for vcl-internal
+ purposes and will be taken modulo 1000 on delivery.
+
+
+beresp.reason
+
+ Type: STRING
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ The HTTP status message returned by the server.
+
+
+beresp.http.
+
+ Type: HEADER
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+ Unsetable from: vcl_backend_response, vcl_backend_error
+
+
+ The corresponding HTTP header.
+
+
+beresp.do_esi
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Boolean. ESI-process the object after fetching it.
+ Defaults to false. Set it to true to parse the
+ object for ESI directives. Will only be honored if
+ req.esi is true.
+
+
+beresp.do_stream
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Deliver the object to the client while fetching the whole
+ object into varnish. For uncacheable objects, storage for
+ parts of the body which have been sent to the client may
+ get freed early, depending on the storage engine used.
+
+
+beresp.do_gzip
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Boolean. Gzip the object before storing it. Defaults
+ to false. When http_gzip_support is on Varnish will
+ request already compressed content from the backend
+ and as such compression in Varnish is not needed.
+
+
+beresp.do_gunzip
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Boolean. Unzip the object before storing it in the
+ cache. Defaults to false.
+
+
+beresp.was_304
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+
+ Boolean. If this is a successful 304 response to a
+ backend conditional request refreshing an existing
+ cache object.
+
+
+beresp.uncacheable
+
+ Type: BOOL
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Inherited from bereq.uncacheable, see there.
+
+ Setting this variable makes the object uncacheable, which may
+ get stored as a hit-for-miss object in the cache.
+
+ Clearing the variable has no effect and will log the warning
+ "Ignoring attempt to reset beresp.uncacheable".
+
+
+beresp.ttl
+
+ Type: DURATION
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ The object's remaining time to live, in seconds.
+
+
+beresp.age
+
+ Type: DURATION
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+
+ The age of the object.
+
+
+beresp.grace
+
+ Type: DURATION
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Set to a period to enable grace.
+
+
+beresp.keep
+
+ Type: DURATION
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ Set to a period to enable conditional backend requests.
+
+ The keep time is cache lifetime in addition to the ttl.
+
+ Objects with ttl expired but with keep time left may be used
+ to issue conditional (If-Modified-Since / If-None-Match)
+ requests to the backend to refresh them.
+
+
+beresp.backend
+
+ Type: BACKEND
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+
+ This is the backend we fetched from. If bereq.backend
+ was set to a director, this will be the backend selected
+ by the director.
+ When used in string context, returns its name.
+
+
+beresp.backend.name
+
+ Type: STRING
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+
+ Name of the backend this response was fetched from.
+ Same as beresp.backend.
+
+
+beresp.backend.ip
+
+ Type: IP
+
+ Readable from: vcl_backend_response
+
+
+ IP of the backend this response was fetched from.
+
+
+beresp.storage
+
+ Type: STEVEDORE
+
+ Readable from: vcl_backend_response, vcl_backend_error
+
+ Writable from: vcl_backend_response, vcl_backend_error
+
+
+ The storage backend to use to save this object.
+
+
+obj
+~~~
+
+obj.proto
+
+ Type: STRING
+
+ Readable from: vcl_hit
+
+
+ The HTTP protocol version stored with the object.
+
+
+obj.status
+
+ Type: INT
+
+ Readable from: vcl_hit
+
+
+ The HTTP status code stored with the object.
+
+
+obj.reason
+
+ Type: STRING
+
+ Readable from: vcl_hit
+
+
+ The HTTP reason phrase stored with the object.
+
+
+obj.hits
+
+ Type: INT
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The count of cache-hits on this object. A value of 0 indicates a
+ cache miss.
+
+
+obj.http.
+
+ Type: HEADER
+
+ Readable from: vcl_hit
+
+
+ The corresponding HTTP header.
+
+
+obj.ttl
+
+ Type: DURATION
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The object's remaining time to live, in seconds.
+
+
+obj.age
+
+ Type: DURATION
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The age of the object.
+
+
+obj.grace
+
+ Type: DURATION
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The object's remaining grace period in seconds.
+
+
+obj.keep
+
+ Type: DURATION
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The object's remaining keep period in seconds.
+
+
+obj.uncacheable
+
+ Type: BOOL
+
+ Readable from: vcl_deliver
+
+
+ Whether the object is uncacheable (pass, hit-for-pass or
+ hit-for-miss).
+
+
+obj.storage
+
+ Type: STEVEDORE
+
+ Readable from: vcl_hit, vcl_deliver
+
+
+ The storage backend used to save this object.
+
+
+resp
+~~~~
+
+resp
+
+ Type: HTTP
+
+ Readable from: vcl_deliver, vcl_synth
+
+
+ The entire response HTTP data structure.
+
+
+resp.body
+
+ Type: BODY
+
+ Writable from: vcl_synth
+
+
+ The response body.
+
+
+resp.proto
+
+ Type: STRING
+
+ Readable from: vcl_deliver, vcl_synth
+
+ Writable from: vcl_deliver, vcl_synth
+
+
+ The HTTP protocol version to use for the response.
+
+
+resp.status
+
+ Type: INT
+
+ Readable from: vcl_deliver, vcl_synth
+
+ Writable from: vcl_deliver, vcl_synth
+
+
+ The HTTP status code that will be returned.
+
+ Assigning a HTTP standardized code to resp.status will also
+ set resp.reason to the corresponding status message.
+
+ resp.status 200 will get changed into 304 by core code after
+ a return(deliver) from vcl_deliver for conditional requests
+ to cached content if validation succeeds.
+
+
+resp.reason
+
+ Type: STRING
+
+ Readable from: vcl_deliver, vcl_synth
+
+ Writable from: vcl_deliver, vcl_synth
+
+
+ The HTTP status message that will be returned.
+
+
+resp.http.
+
+ Type: HEADER
+
+ Readable from: vcl_deliver, vcl_synth
+
+ Writable from: vcl_deliver, vcl_synth
+
+ Unsetable from: vcl_deliver, vcl_synth
+
+
+ The corresponding HTTP header.
+
+
+resp.is_streaming
+
+ Type: BOOL
+
+ Readable from: vcl_deliver, vcl_synth
+
+
+ Returns true when the response will be streamed
+ from the backend.
+
+
+now
+~~~
+
+now
+
+ Type: TIME
+
+ Readable from: all
+
+
+ The current time, in seconds since the epoch. When
+ used in string context it returns a formatted string.
+
+
+storage
+~~~~~~~
+
+storage.<name>.free_space
+
+ Type: BYTES
+
+ Readable from: client, backend
+
+
+ Free space available in the named stevedore. Only available for
+ the malloc stevedore.
+
+
+storage.<name>.used_space
+
+ Type: BYTES
+
+ Readable from: client, backend
+
+
+ Used space in the named stevedore. Only available for the malloc
+ stevedore.
+
+
+storage.<name>.happy
+
+ Type: BOOL
+
+ Readable from: client, backend
+
+
+ Health status for the named stevedore. Not available in any of the
+ current stevedores.
+
diff --git a/include/Makefile.am b/include/Makefile.am
index 27a557a..b98f8d0 100644
--- a/include/Makefile.am
+++ b/include/Makefile.am
@@ -102,7 +102,8 @@ nobase_noinst_HEADERS = \
vmod_abi.h: \
$(top_srcdir)/lib/libvcc/generate.py \
$(top_srcdir)/include/vdef.h \
- $(top_srcdir)/include/vrt.h
+ $(top_srcdir)/include/vrt.h \
+ $(top_srcdir)/doc/sphinx/reference/vcl_var.rst
mkdir -p $(top_builddir)/include/tbl
@PYTHON@ $(top_srcdir)/lib/libvcc/generate.py \
$(top_srcdir) $(top_builddir)
diff --git a/lib/libvcc/generate.py b/lib/libvcc/generate.py
index 1eb857e..345ee6a 100755
--- a/lib/libvcc/generate.py
+++ b/lib/libvcc/generate.py
@@ -169,7 +169,7 @@ returns = (
sp_variables = collections.OrderedDict()
class vardef(object):
- def __init__(self, nam, typ, rd, wr, doc, uns = None):
+ def __init__(self, nam, typ, rd, wr, doc, uns):
sp_variables[nam] = self
self.nam = nam
self.typ = typ
@@ -178,662 +178,54 @@ class vardef(object):
self.doc = doc
self.uns = uns
-vardef('remote.ip',
- 'IP',
- ('both',),
- (), """
- The IP address of the other end of the TCP connection.
- This can either be the clients IP, or the outgoing IP
- of a proxy server.
- """
-)
-vardef('client.ip',
- 'IP',
- ('both',),
- (), """
- The client's IP address.
- """
-)
-vardef('client.identity',
- 'STRING',
- ('client',),
- ('client',), """
- Identification of the client, used to load balance
- in the client director. Defaults to the client's IP
- address.
- """
-)
-vardef('local.ip',
- 'IP',
- ('both',),
- (), """
- The IP address of the local end of the TCP connection.
- """
-)
-vardef('server.ip',
- 'IP',
- ('both',),
- (), """
- The IP address of the socket on which the client
- connection was received.
- """
-)
-vardef('server.hostname',
- 'STRING',
- ('all',),
- (), """
- The host name of the server.
- """
-)
-vardef('server.identity',
- 'STRING',
- ('all',),
- (), """
- The identity of the server, as set by the -i
- parameter. If the -i parameter is not passed to varnishd,
- server.identity will be set to the hostname of the machine.
- """
-)
-vardef('req',
- 'HTTP',
- ('client',),
- (), """
- The entire request HTTP data structure
- """
-)
-vardef('req.method',
- 'STRING',
- ('client',),
- ('client',), """
- The request type (e.g. "GET", "HEAD").
- """
-)
-vardef('req.hash',
- 'BLOB',
- ('hit', 'miss', 'pass', 'purge', 'deliver', ),
- (), """
- The hash key of this request.
- """
-)
-vardef('req.url',
- 'STRING',
- ('client',),
- ('client',), """
- The requested URL.
- """
-)
-vardef('req.proto',
- 'STRING',
- ('client',),
- ('client',), """
- The HTTP protocol version used by the client.
- """
-)
-vardef('req.http.',
- 'HEADER',
- ('client',),
- ('client',), """
- The corresponding HTTP header.
- """,
- uns = ('client',)
-)
-vardef('req.restarts',
- 'INT',
- ('client',),
- (), """
- A count of how many times this request has been restarted.
- """
-)
-vardef('req.storage',
- 'STEVEDORE',
- ('client',),
- ('client',), """
- The storage backend to use to save this request body.
- """
-)
-vardef('req.esi_level',
- 'INT',
- ('client',),
- (), """
- A count of how many levels of ESI requests we're currently at.
- """
-)
-vardef('req.ttl',
- 'DURATION',
- ('client',),
- ('client',), """
- Upper limit on the object age for cache lookups to return hit.
-
- Usage of req.ttl should be replaced with a check on
- obj.ttl in vcl_hit, returning miss when needed, but
- this currently hits bug #1799, so an additional
- workaround is required.
-
- Deprecated and scheduled for removal with varnish release 7.
- """
-)
-vardef('req.xid',
- 'STRING',
- ('client',),
- (), """
- Unique ID of this request.
- """
-)
-vardef('req.esi',
- 'BOOL',
- ('client',),
- ('client',), """
- Boolean. Set to false to disable ESI processing
- regardless of any value in beresp.do_esi. Defaults
- to true. This variable is subject to change in
- future versions, you should avoid using it.
- """
-)
-vardef('req.can_gzip',
- 'BOOL',
- ('client',),
- (), """
- Does the client accept the gzip transfer encoding.
- """
-)
-vardef('req.backend_hint',
- 'BACKEND',
- ('client', ),
- ('client',), """
- Set bereq.backend to this if we attempt to fetch.
- When set to a director, reading this variable returns
- an actual backend if the director has resolved immediately,
- or the director otherwise.
- When used in string context, returns the name of the director
- or backend, respectively.
- """
-)
-vardef('req.hash_ignore_busy',
- 'BOOL',
- ('client',),
- ('client',), """
- Ignore any busy object during cache lookup. You
- would want to do this if you have two server looking
- up content from each other to avoid potential deadlocks.
- """
-)
-vardef('req.hash_always_miss',
- 'BOOL',
- ('client',),
- ('client',), """
- Force a cache miss for this request. If set to true
- Varnish will disregard any existing objects and
- always (re)fetch from the backend.
- """
-)
-vardef('req_top.method',
- 'STRING',
- ('client',),
- (), """
- The request method of the top-level request in a tree
- of ESI requests. (e.g. "GET", "HEAD").
- Identical to req.method in non-ESI requests.
- """
-)
-vardef('req_top.url',
- 'STRING',
- ('client',),
- (), """
- The requested URL of the top-level request in a tree
- of ESI requests.
- Identical to req.url in non-ESI requests.
- """
-)
-vardef('req_top.http.',
- 'HEADER',
- ('client',),
- (), """
- HTTP headers of the top-level request in a tree of ESI requests.
- Identical to req.http. in non-ESI requests.
- """
-)
-vardef('req_top.proto',
- 'STRING',
- ('client',),
- (), """
- HTTP protocol version of the top-level request in a tree of
- ESI requests.
- Identical to req.proto in non-ESI requests.
- """
-)
-vardef('bereq',
- 'HTTP',
- ('backend',),
- (), """
- The entire backend request HTTP data structure
- """
-)
-vardef('bereq.xid',
- 'STRING',
- ('backend',),
- (), """
- Unique ID of this request.
- """
-)
-vardef('bereq.retries',
- 'INT',
- ('backend',),
- (), """
- A count of how many times this request has been retried.
- """
-)
-vardef('bereq.backend',
- 'BACKEND',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- This is the backend or director we attempt to fetch from.
- When set to a director, reading this variable returns
- an actual backend if the director has resolved immediately,
- or the director otherwise.
- When used in string context, returns the name of the director
- or backend, respectively.
- """
-)
-vardef('bereq.body',
- 'BODY',
- (),
- (), """
- The request body.
- """,
- uns = ('backend_fetch',)
-)
-vardef('bereq.hash',
- 'BLOB',
- ('pipe', 'backend', ),
- (), """
- The hash key of this request.
- """
-)
-vardef('bereq.method',
- 'STRING',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- The request type (e.g. "GET", "HEAD").
- """
-)
-vardef('bereq.url',
- 'STRING',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- The requested URL.
- """
-)
-vardef('bereq.proto',
- 'STRING',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- The HTTP protocol version used to talk to the server.
- """
-)
-vardef('bereq.http.',
- 'HEADER',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- The corresponding HTTP header.
- """,
- uns = ('pipe', 'backend', )
-)
-vardef('bereq.uncacheable',
- 'BOOL',
- ('backend', ),
- (), """
- Indicates whether this request is uncacheable due
- to a pass in the client side or a hit on an hit-for-pass
- object.
- """
-)
-vardef('bereq.connect_timeout',
- 'DURATION',
- ('pipe', 'backend', ),
- ('pipe', 'backend', ), """
- The time in seconds to wait for a backend connection.
- """
-)
-vardef('bereq.first_byte_timeout',
- 'DURATION',
- ('backend', ),
- ('backend', ), """
- The time in seconds to wait for the first byte from
- the backend. Not available in pipe mode.
- """
-)
-vardef('bereq.between_bytes_timeout',
- 'DURATION',
- ('backend', ),
- ('backend', ), """
- The time in seconds to wait between each received byte from the
- backend. Not available in pipe mode.
- """
-)
-vardef('bereq.is_bgfetch',
- 'BOOL',
- ('backend', ),
- (), """
- True for background fetches.
- """
-)
-vardef('beresp',
- 'HTTP',
- ('backend_response', 'backend_error'),
- (), """
- The entire backend response HTTP data structure
- """
-)
-vardef('beresp.body',
- 'BODY',
- (),
- ('backend_error',), """
- The response body.
- """
-)
-vardef('beresp.proto',
- 'STRING',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The HTTP protocol version used the backend replied with.
- """
-)
-vardef('beresp.status',
- 'INT',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The HTTP status code returned by the server.
-
- Status codes >1000 can be set for vcl-internal
- purposes and will be taken modulo 1000 on delivery.
- """
-)
-vardef('beresp.reason',
- 'STRING',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The HTTP status message returned by the server.
- """
-)
-vardef('beresp.http.',
- 'HEADER',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The corresponding HTTP header.
- """,
- uns = ('backend_response', 'backend_error')
-)
-vardef('beresp.do_esi',
- 'BOOL',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Boolean. ESI-process the object after fetching it.
- Defaults to false. Set it to true to parse the
- object for ESI directives. Will only be honored if
- req.esi is true.
- """
-)
-vardef('beresp.do_stream',
- 'BOOL',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Deliver the object to the client while fetching the whole
- object into varnish. For uncacheable objects, storage for
- parts of the body which have been sent to the client may
- get freed early, depending on the storage engine used.
- """
-)
-vardef('beresp.do_gzip',
- 'BOOL',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Boolean. Gzip the object before storing it. Defaults
- to false. When http_gzip_support is on Varnish will
- request already compressed content from the backend
- and as such compression in Varnish is not needed.
- """
-)
-vardef('beresp.do_gunzip',
- 'BOOL',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Boolean. Unzip the object before storing it in the
- cache. Defaults to false.
- """
-)
-vardef('beresp.was_304',
- 'BOOL',
- ('backend_response', 'backend_error'),
- (), """
- Boolean. If this is a successful 304 response to a
- backend conditional request refreshing an existing
- cache object.
- """
-)
-vardef('beresp.uncacheable',
- 'BOOL',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Inherited from bereq.uncacheable, see there.
-
- Setting this variable makes the object uncacheable, which may
- get stored as a hit-for-miss object in the cache.
-
- Clearing the variable has no effect and will log the warning
- "Ignoring attempt to reset beresp.uncacheable".
- """
-)
-vardef('beresp.ttl',
- 'DURATION',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The object's remaining time to live, in seconds.
- """
-)
-vardef('beresp.age',
- 'DURATION',
- ('backend_response', 'backend_error'),
- (), """
- The age of the object.
- """
-)
-vardef('beresp.grace',
- 'DURATION',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Set to a period to enable grace.
- """
-)
-vardef('beresp.keep',
- 'DURATION',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- Set to a period to enable conditional backend requests.
-
- The keep time is cache lifetime in addition to the ttl.
-
- Objects with ttl expired but with keep time left may be used
- to issue conditional (If-Modified-Since / If-None-Match)
- requests to the backend to refresh them.
- """
-)
-vardef('beresp.backend',
- 'BACKEND',
- ('backend_response', 'backend_error'),
- (), """
- This is the backend we fetched from. If bereq.backend
- was set to a director, this will be the backend selected
- by the director.
- When used in string context, returns its name.
- """
-)
-vardef('beresp.backend.name',
- 'STRING',
- ('backend_response', 'backend_error'),
- (), """
- Name of the backend this response was fetched from.
- Same as beresp.backend.
- """
-)
-vardef('beresp.backend.ip',
- 'IP',
- ('backend_response',),
- (), """
- IP of the backend this response was fetched from.
- """
-)
-vardef('beresp.storage',
- 'STEVEDORE',
- ('backend_response', 'backend_error'),
- ('backend_response', 'backend_error'), """
- The storage backend to use to save this object.
- """
-)
-vardef('obj.proto',
- 'STRING',
- ('hit',),
- (), """
- The HTTP protocol version stored with the object.
- """
-)
-vardef('obj.status',
- 'INT',
- ('hit',),
- (), """
- The HTTP status code stored with the object.
- """
-)
-vardef('obj.reason',
- 'STRING',
- ('hit',),
- (), """
- The HTTP reason phrase stored with the object.
- """
-)
-vardef('obj.hits',
- 'INT',
- ('hit', 'deliver'),
- (), """
- The count of cache-hits on this object. A value of 0 indicates a
- cache miss.
- """
-)
-vardef('obj.http.',
- 'HEADER',
- ('hit',),
- (), """
- The corresponding HTTP header.
- """
-)
-vardef('obj.ttl',
- 'DURATION',
- ('hit', 'deliver'),
- (), """
- The object's remaining time to live, in seconds.
- """
-)
-vardef('obj.age',
- 'DURATION',
- ('hit', 'deliver'),
- (), """
- The age of the object.
- """
-)
-vardef('obj.grace',
- 'DURATION',
- ('hit', 'deliver'),
- (), """
- The object's remaining grace period in seconds.
- """
-)
-vardef('obj.keep',
- 'DURATION',
- ('hit', 'deliver'),
- (), """
- The object's remaining keep period in seconds.
- """
-)
-vardef('obj.uncacheable',
- 'BOOL',
- ('deliver',),
- (), """
- Whether the object is uncacheable (pass, hit-for-pass or
- hit-for-miss).
- """
-)
-vardef('obj.storage',
- 'STEVEDORE',
- ('hit', 'deliver'),
- (), """
- The storage backend used to save this object.
- """
-)
-vardef('resp',
- 'HTTP',
- ('deliver', 'synth'),
- (), """
- The entire response HTTP data structure.
- """
-)
-vardef('resp.body',
- 'BODY',
- (),
- ('synth',), """
- The response body.
- """
-)
-vardef('resp.proto',
- 'STRING',
- ('deliver', 'synth'),
- ('deliver', 'synth'), """
- The HTTP protocol version to use for the response.
- """
-)
-vardef('resp.status',
- 'INT',
- ('deliver', 'synth'),
- ('deliver', 'synth'), """
- The HTTP status code that will be returned.
-
- Assigning a HTTP standardized code to resp.status will also
- set resp.reason to the corresponding status message.
-
- resp.status 200 will get changed into 304 by core code after
- a return(deliver) from vcl_deliver for conditional requests
- to cached content if validation succeeds.
- """
-)
-vardef('resp.reason',
- 'STRING',
- ('deliver', 'synth'),
- ('deliver', 'synth'), """
- The HTTP status message that will be returned.
- """
-)
-vardef('resp.http.',
- 'HEADER',
- ('deliver', 'synth'),
- ('deliver', 'synth'), """
- The corresponding HTTP header.
- """,
- uns = ('deliver', 'synth')
-)
-vardef('resp.is_streaming',
- 'BOOL',
- ('deliver', 'synth'),
- (), """
- Returns true when the response will be streamed
- from the backend.
- """
-)
-vardef('now',
- 'TIME',
- ('all',),
- (), """
- The current time, in seconds since the epoch. When
- used in string context it returns a formatted string.
- """
-)
+def parse_var(ln):
+ vn = ln.pop(0).split()
+ assert len(vn) == 1
+ vn = vn[0]
+ vr = []
+ vw = []
+ vu = []
+ while True:
+ l = ln.pop(0)
+ if l == "":
+ continue
+ j = l.split()
+ if j[0] == "Type:":
+ assert len(j) == 2
+ vt = j[1]
+ continue
+ if j[0] == "Readable" and j[1] == "from:":
+ for i in j[2:]:
+ vr.append(i.strip(",."))
+ continue
+ if j[0] == "Writable" and j[1] == "from:":
+ for i in j[2:]:
+ vw.append(i.strip(",."))
+ continue
+ if j[0] == "Unsetable" and j[1] == "from:":
+ for i in j[2:]:
+ vu.append(i.strip(",."))
+ continue
+ break
+ doc = "\n" + l + "\n" + "\n".join(ln)
+ if vn[:8] != "storage.":
+ vardef(vn, vt, vr, vw, doc, uns=vu)
+
+def parse_var_doc(fn):
+ s = 0
+ l = []
+ for i in open(fn):
+ l.append(i.rstrip())
+ for n in range(0, len(l)):
+ j = l[n].split()
+ if len(j) != 2 or j[0] != "Type:" or not l[n][0].isspace():
+ continue
+ m = n
+ while m < len(l) and ( l[m] == "" or l[m][0].isspace() ):
+ m += 1
+ parse_var(l[n-2:m-1])
+
+parse_var_doc(join(buildroot, "doc/sphinx/reference/vcl_var.rst"))
# Backwards compatibility:
aliases = []
@@ -1204,6 +596,8 @@ fo.close()
def restrict(fo, spec):
d = dict()
for j in spec:
+ if j[:4] == "vcl_":
+ j = j[4:]
if j == 'all':
for i in vcls:
d[i] = True
@@ -1219,6 +613,8 @@ def restrict(fo, spec):
for i in vcls_backend:
d[i] = True
else:
+ if not j in vcls:
+ print("JJ", j)
assert j in vcls
d[j] = True
p = ""
@@ -1398,59 +794,6 @@ fo.close()
#######################################################################
-fp_vclvar = open(join(buildroot, "doc/sphinx/include/vcl_var.rst"), "w")
-
-def rst_where(fo, h, l):
- ll = list()
- if len(l) == 0:
- return
- fo.write("\t" + h)
- s = ""
- for j in l:
- if j == "both":
- ll.append("client")
- ll.append("backend")
- elif j == "client":
- ll.append(j)
- elif j == "backend":
- ll.append(j)
- elif j == "all":
- ll.append(j)
- else:
- ll.append("vcl_" + j)
- for j in ll:
- fo.write(s + j)
- s = ", "
- fo.write("\n\n")
-
-hdr = ""
-for i in sp_variables.values():
- j = i.nam.split(".")
- if j[0] != hdr:
- fp_vclvar.write("\n" + j[0] + "\n")
- fp_vclvar.write("~" * len(j[0]) + "\n")
- hdr = j[0]
- fp_vclvar.write("\n" + i.nam + "\n\n")
- fp_vclvar.write("\tType: " + i.typ + "\n\n")
- rst_where(fp_vclvar, "Readable from: ", i.rd)
- rst_where(fp_vclvar, "Writable from: ", i.wr)
- for j in i.doc.split("\n"):
- fp_vclvar.write("\t%s\n" % j.strip())
-
-hdr = "storage"
-fp_vclvar.write("\n" + hdr + "\n")
-fp_vclvar.write("~" * len(hdr) + "\n")
-for i in stv_variables:
- fp_vclvar.write("\n" + i[3] + "\n\n")
- fp_vclvar.write("\tType: " + i[1] + "\n\n")
- fp_vclvar.write("\tReadable from: client, backend\n\n")
- for j in i[4].split("\n"):
- fp_vclvar.write("\t%s\n" % j.strip())
-
-fp_vclvar.close()
-
-#######################################################################
-
if os.path.isdir(os.path.join(srcroot, ".git")):
v = subprocess.check_output([
"git --git-dir=" + os.path.join(srcroot, ".git") +
More information about the varnish-commit
mailing list