[master] 9336709 More work on variable documentation.

Poul-Henning Kamp phk at FreeBSD.org
Fri Feb 16 10:17:09 UTC 2018


commit 933670973050f0e256e865ebcc0595bc0ed34361
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Fri Feb 16 09:43:44 2018 +0000

    More work on variable documentation.

diff --git a/doc/sphinx/reference/vcl_var.rst b/doc/sphinx/reference/vcl_var.rst
index dddc764..9dfea7e 100644
--- a/doc/sphinx/reference/vcl_var.rst
+++ b/doc/sphinx/reference/vcl_var.rst
@@ -381,7 +381,6 @@ req_top.method
 
 	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.
@@ -392,7 +391,6 @@ req_top.url
 	Type: STRING
 
 	Readable from: client
-
 	
 	The requested URL of the top-level request in a tree
 	of ESI requests.
@@ -404,7 +402,6 @@ 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.
@@ -415,7 +412,6 @@ req_top.proto
 	Type: STRING
 
 	Readable from: client
-
 	
 	HTTP protocol version of the top-level request in a tree of
 	ESI requests.
@@ -447,7 +443,6 @@ bereq.xid
 	Type: STRING
 
 	Readable from: backend
-
 	
 	Unique ID of this request.
 	
@@ -457,7 +452,6 @@ bereq.retries
 	Type: INT
 
 	Readable from: backend
-
 	
 	A count of how many times this request has been retried.
 	
@@ -469,7 +463,6 @@ bereq.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
@@ -484,19 +477,18 @@ bereq.body
 	Type: BODY
 
 	Unsetable from: vcl_backend_fetch
-
-	
-	The request body.
 	
+	The request body, only present on `pass` requests.
+
+	Unset will also remove `bereq.http.Content-Length`.
 
 bereq.hash
 
 	Type: BLOB
 
 	Readable from: vcl_pipe, backend
-
 	
-	The hash key of this request.
+	The hash key of this request, a copy of `req.hash`.
 	
 
 bereq.method
@@ -506,9 +498,10 @@ bereq.method
 	Readable from: vcl_pipe, backend
 
 	Writable from: vcl_pipe, backend
-
 	
 	The request type (e.g. "GET", "HEAD").
+
+	Regular (non-pipe, non-pass) fetches are always "GET"
 	
 
 bereq.url
@@ -519,8 +512,7 @@ bereq.url
 
 	Writable from: vcl_pipe, backend
 
-	
-	The requested URL.
+	The requested URL, copied from `req.url`
 	
 
 bereq.proto
@@ -530,9 +522,9 @@ bereq.proto
 	Readable from: vcl_pipe, backend
 
 	Writable from: vcl_pipe, backend
-
 	
-	The HTTP protocol version used to talk to the server.
+	The HTTP protocol version, "HTTP/1.1" unless a pass or pipe
+	request has "HTTP/1.0" in `req.proto`
 	
 
 bereq.http.*
@@ -545,8 +537,7 @@ bereq.http.*
 
 	Unsetable from: vcl_pipe, backend
 
-	
-	The corresponding HTTP header.
+	The headers to be sent to the backend.
 	
 
 bereq.uncacheable
@@ -556,9 +547,8 @@ bereq.uncacheable
 	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.
+	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
@@ -568,9 +558,9 @@ bereq.connect_timeout
 	Readable from: vcl_pipe, backend
 
 	Writable from: vcl_pipe, backend
-
 	
-	The time in seconds to wait for a backend connection.
+	The time in seconds to wait for a backend connection to be
+	established.
 	
 
 bereq.first_byte_timeout
@@ -580,10 +570,9 @@ bereq.first_byte_timeout
 	Readable from: backend
 
 	Writable from: backend
-
 	
-	The time in seconds to wait for the first byte from
-	the backend.  Not available in pipe mode.
+	The time in seconds to wait getting the first byte back
+	from the backend.  Not available in pipe mode.
 	
 
 bereq.between_bytes_timeout
@@ -593,7 +582,6 @@ bereq.between_bytes_timeout
 	Readable from: backend
 
 	Writable from: backend
-
 	
 	The time in seconds to wait between each received byte from the
 	backend.  Not available in pipe mode.
@@ -604,33 +592,33 @@ bereq.is_bgfetch
 	Type: BOOL
 
 	Readable from: backend
-
-	
-	True for background fetches.
 	
+	True for fetches where the client got a hit on an object in
+	grace, and this fetch was kicked of in the background to get
+	a fresh copy.
 
 beresp
 ~~~~~~
 
+The response received from the backend, one cache misses, the
+store object is built from `beresp`.
+
 beresp
 
 	Type: HTTP
 
 	Readable from: vcl_backend_response, vcl_backend_error
 
-	
-	The entire backend response HTTP data structure
-	
+	The entire backend response HTTP data structure, useful as
+	argument to VMOD functions.
 
 beresp.body
 
 	Type: BODY
 
 	Writable from: vcl_backend_error
-
-	
-	The response body.
 	
+	For producing a synthetic body.
 
 beresp.proto
 
@@ -640,8 +628,7 @@ beresp.proto
 
 	Writable from: vcl_backend_response, vcl_backend_error
 
-	
-	The HTTP protocol version used the backend replied with.
+	The HTTP protocol version the backend replied with.
 	
 
 beresp.status
@@ -652,12 +639,15 @@ beresp.status
 
 	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.
-	
+	Status codes on the form XXYZZ can be set where
+	XXYZZ is less than 65536 and Y is [1...9].
+	Only YZZ will be sent back to clients.
+
+	XX can be therefore be used to pass information
+	around inside VCL, for instance `return(synth(22404))`
+	from `vcl_recv{}` to `vcl_synth{}`
 
 beresp.reason
 
@@ -667,9 +657,7 @@ beresp.reason
 
 	Writable from: vcl_backend_response, vcl_backend_error
 
-	
 	The HTTP status message returned by the server.
-	
 
 beresp.http.*
 
@@ -681,9 +669,7 @@ beresp.http.*
 
 	Unsetable from: vcl_backend_response, vcl_backend_error
 
-	
-	The corresponding HTTP header.
-	
+	The HTTP headers returned from the server.
 
 beresp.do_esi
 
@@ -693,11 +679,10 @@ beresp.do_esi
 
 	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.
+	Default: false
+
+	Set it to true to parse the object for ESI directives.
+	Will only be honored if req.esi is true.
 	
 
 beresp.do_stream
@@ -708,11 +693,12 @@ beresp.do_stream
 
 	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.
+	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
@@ -723,12 +709,9 @@ beresp.do_gzip
 
 	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.
-	
+	Default: false
+
+	Set to `true` to gzip the object while storing it.
 
 beresp.do_gunzip
 
@@ -738,10 +721,10 @@ beresp.do_gunzip
 
 	Writable from: vcl_backend_response, vcl_backend_error
 
-	
-	Boolean. Unzip the object before storing it in the
-	cache.  Defaults to false.
-	
+	Default: false
+
+	Set to `true` to unzip the object while storing it in the
+	cache.
 
 beresp.was_304
 
@@ -750,10 +733,9 @@ beresp.was_304
 	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.
-	
+	When `true` this indicates that we got a 304 response
+	to our conditional fetch from the backend and turned
+	that into `beresp.status = 200`
 
 beresp.uncacheable
 
@@ -763,11 +745,11 @@ beresp.uncacheable
 
 	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.
+	Setting this variable makes the object uncacheable.
+
+	This may may produce 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".
@@ -781,7 +763,6 @@ beresp.ttl
 
 	Writable from: vcl_backend_response, vcl_backend_error
 
-	
 	The object's remaining time to live, in seconds.
 	
 
@@ -791,7 +772,6 @@ beresp.age
 
 	Readable from: vcl_backend_response, vcl_backend_error
 
-	
 	The age of the object.
 	
 
@@ -803,7 +783,6 @@ beresp.grace
 
 	Writable from: vcl_backend_response, vcl_backend_error
 
-	
 	Set to a period to enable grace.
 	
 
@@ -815,7 +794,6 @@ beresp.keep
 
 	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.
@@ -831,7 +809,6 @@ beresp.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.
@@ -844,7 +821,6 @@ beresp.backend.name
 
 	Readable from: vcl_backend_response, vcl_backend_error
 
-	
 	Name of the backend this response was fetched from.
 	Same as beresp.backend.
 	
@@ -855,9 +831,7 @@ beresp.backend.ip
 
 	Readable from: vcl_backend_response
 
-	
 	IP of the backend this response was fetched from.
-	
 
 beresp.storage
 
@@ -869,11 +843,12 @@ beresp.storage
 
 	
 	The storage backend to use to save this object.
-	
 
 obj
 ~~~
 
+This is the object we found in cache.  It cannot be modified.
+
 obj.proto
 
 	Type: STRING
@@ -881,7 +856,7 @@ obj.proto
 	Readable from: vcl_hit
 
 	
-	The HTTP protocol version stored with the object.
+	The HTTP protocol version stored in the object.
 	
 
 obj.status
@@ -891,7 +866,7 @@ obj.status
 	Readable from: vcl_hit
 
 	
-	The HTTP status code stored with the object.
+	The HTTP status code stored in the object.
 	
 
 obj.reason
@@ -901,7 +876,7 @@ obj.reason
 	Readable from: vcl_hit
 
 	
-	The HTTP reason phrase stored with the object.
+	The HTTP reason phrase stored in the object.
 	
 
 obj.hits
@@ -911,8 +886,9 @@ obj.hits
 	Readable from: vcl_hit, vcl_deliver
 
 	
-	The count of cache-hits on this object. A value of 0 indicates a
-	cache miss.
+	The count of cache-hits on this object.
+
+	In `vcl_deliver` a value of 0 indicates a cache miss.
 	
 
 obj.http.*
@@ -921,8 +897,7 @@ obj.http.*
 
 	Readable from: vcl_hit
 
-	
-	The corresponding HTTP header.
+	The HTTP headers stored in the object.
 	
 
 obj.ttl
@@ -931,7 +906,6 @@ obj.ttl
 
 	Readable from: vcl_hit, vcl_deliver
 
-	
 	The object's remaining time to live, in seconds.
 	
 
@@ -941,7 +915,6 @@ obj.age
 
 	Readable from: vcl_hit, vcl_deliver
 
-	
 	The age of the object.
 	
 
@@ -951,7 +924,6 @@ obj.grace
 
 	Readable from: vcl_hit, vcl_deliver
 
-	
 	The object's remaining grace period in seconds.
 	
 
@@ -961,7 +933,6 @@ obj.keep
 
 	Readable from: vcl_hit, vcl_deliver
 
-	
 	The object's remaining keep period in seconds.
 	
 
@@ -971,7 +942,6 @@ obj.uncacheable
 
 	Readable from: vcl_deliver
 
-	
 	Whether the object is uncacheable (pass, hit-for-pass or
 	hit-for-miss).
 	
@@ -982,22 +952,23 @@ obj.storage
 
 	Readable from: vcl_hit, vcl_deliver
 
-	
-	The storage backend used to save this object.
+	The storage backend where this object is stored.
 	
 
 resp
 ~~~~
 
+This is the response we send to the client, it is built from either
+`beresp` (pass/miss) or `obj` (hits).
+
 resp
 
 	Type: HTTP
 
 	Readable from: vcl_deliver, vcl_synth
 
-	
-	The entire response HTTP data structure.
-	
+	The entire response HTTP data structure, useful as argument
+	to VMODs.
 
 resp.body
 
@@ -1005,9 +976,7 @@ resp.body
 
 	Writable from: vcl_synth
 
-	
-	The response body.
-	
+	To produce a synthetic response body, for instance for errors.
 
 resp.proto
 
@@ -1017,9 +986,7 @@ resp.proto
 
 	Writable from: vcl_deliver, vcl_synth
 
-	
 	The HTTP protocol version to use for the response.
-	
 
 resp.status
 
@@ -1029,7 +996,6 @@ resp.status
 
 	Writable from: vcl_deliver, vcl_synth
 
-	
 	The HTTP status code that will be returned.
 	
 	Assigning a HTTP standardized code to resp.status will also
@@ -1048,7 +1014,6 @@ resp.reason
 
 	Writable from: vcl_deliver, vcl_synth
 
-	
 	The HTTP status message that will be returned.
 	
 
@@ -1063,7 +1028,7 @@ resp.http.*
 	Unsetable from: vcl_deliver, vcl_synth
 
 	
-	The corresponding HTTP header.
+	The HTTP headers that will be returned.
 	
 
 resp.is_streaming
@@ -1072,13 +1037,12 @@ resp.is_streaming
 
 	Readable from: vcl_deliver, vcl_synth
 
-	
 	Returns true when the response will be streamed
-	from the backend.
+	while being fetched from the backend.
 	
 
-now
-~~~
+Special variables
+~~~~~~~~~~~~~~~~~
 
 now
 
@@ -1087,8 +1051,10 @@ now
 	Readable from: all
 
 	
-	The current time, in seconds since the epoch. When
-	used in string context it returns a formatted string.
+	The current time, in seconds since the UNIX epoch.
+
+	When converted to STRING in expressions it returns
+	a formatted timestamp like `Tue, 20 Feb 2018 09:30:31 GMT`
 	
 
 storage


More information about the varnish-commit mailing list