[master] 001279ebd Document proper design pattern for using hash_data() in vcl_recv, and protect this pattern in the test-case.

[Poul-Henning Kamp]

commit 001279ebd6ee83fafbc7fc1d1805bf2224361dd9
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Fri Feb 12 10:31:36 2021 +0000

    Document proper design pattern for using hash_data() in vcl_recv,
    and protect this pattern in the test-case.

diff --git a/bin/varnishtest/tests/b00076.vtc b/bin/varnishtest/tests/b00076.vtc
index 971c7774e..120339275 100644
--- a/bin/varnishtest/tests/b00076.vtc
+++ b/bin/varnishtest/tests/b00076.vtc
@@ -29,3 +29,39 @@ client c1 {
 	expect resp.status == 200
 	expect resp.http.same == One
 } -run
+
+server s1 {
+	rxreq
+	txresp -hdr "Second: One"
+} -start
+
+varnish v1 -vcl+backend {
+    sub make_hash_key {
+        hash_data("Documented Design Pattern");
+        hash_data(req.url);
+    }
+    
+    sub vcl_hash {
+        call make_hash_key;
+        return (lookup);
+    }
+ 
+    sub vcl_recv {
+        if (req.http.early) {
+            call make_hash_key;
+        }
+    }
+}
+
+client c1 {
+	txreq
+	rxresp
+	expect resp.status == 200
+	expect resp.http.second == One
+
+	txreq -hdr "early: yes"
+	rxresp
+	expect resp.status == 200
+	expect resp.http.second == One
+} -run
+
diff --git a/doc/sphinx/reference/dp_vcl_recv_hash.rst b/doc/sphinx/reference/dp_vcl_recv_hash.rst
new file mode 100644
index 000000000..a44e07006
--- /dev/null
+++ b/doc/sphinx/reference/dp_vcl_recv_hash.rst
@@ -0,0 +1,24 @@
+.. _db_vcl_recv_hash:
+
+Hashing in `vcl_recv{}`
+=======================
+
+Calculating the `hash` used for cache lookup already in `vcl_recv{}`
+makes it possible for certain directors to offer targeted health status.
+
+To ensure consistent hashing, use this design pattern::
+
+    sub make_hash_key {
+        hash_data([…]);
+    }
+    
+    sub vcl_hash {
+        call make_hash_key;
+        return (lookup);
+    }
+
+    sub vcl_recv {
+        […]
+        call make_hash_key;
+        […]
+    }
diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 5cda7e77a..b9bd82c12 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -13,6 +13,14 @@ The VCL language
 	VCL - Varnish Configuration Language <vcl>
 	states.rst
 
+VCL Design Patterns
+-------------------
+
+.. toctree::
+	:maxdepth: 1
+
+	dp_vcl_recv_hash.rst
+
 Bundled VMODs
 -------------