docs: Improve documentation for builtin VCL and pipe behavior

bin/varnishd/builtin.vcl

@@ -28,7 +28,25 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 # SUCH DAMAGE.
 #
-# This is the builtin VCL code
+# This file contains the builtin VCL code.
+#
+# All subroutines in this file can be overridden by user-provided VCL.
+#
+# There are two main patterns for overridable subroutines:
+#
+# 1. `vcl_builtin_*` subroutines: These wrap core Varnish logic. When you
+#    override these in user VCL, your code runs first, followed by the
+#    builtin VCL code (unless you `return()`). Note that calling
+#    `vcl_builtin_*` from your own `vcl_builtin_*` does not work (triggers
+#    recursion check).
+#
+# 2. `vcl_req_*`, `vcl_beresp_*`, etc. subroutines: These act as specific
+#    "hooks" within the default Varnish behavior. Overriding these allows
+#    you to modify a narrow aspect of behavior without reimplementing the
+#    entire parent `vcl_builtin_*` logic.
+#
+# Consult the Varnish documentation for details on each subroutine and
+# its intended use.
 
 vcl 4.0;
 

doc/sphinx/users-guide/vcl-built-in-code.rst

@@ -174,9 +174,8 @@ code using::
 Built-in VCL reference
 ----------------------
 
-A copy of the ``builtin.vcl`` file might be provided with your Varnish
-installation but :ref:`varnishd(1)` is the reference to determine the code
-that is appended to any loaded VCL.
+A copy of the ``builtin.vcl`` file can be obtained by running
+``varnishd -x builtin``.
 
 The VCL compilation happens in two passes:
 
@@ -186,3 +185,30 @@ The VCL compilation happens in two passes:
 
 Any VCL subroutine present in the built-in VCL can be extended, in which
 case the loaded VCL code will be executed before the built-in code.
+
+Re-enabling pipe mode
+~~~~~~~~~~~~~~~~~~~~~
+
+As of Varnish 8.0, Varnish no longer pipes unknown HTTP methods by default.
+Instead, it returns a 501 synthetic error. If you want to re-enable pipe
+mode for a specific method, you can do so by adding the following to your
+VCL:
+
+.. code-block:: vcl
+
+    sub vcl_req_method {
+            if (req.method == "CUSTOM") {
+                    return (pipe);
+            }
+    }
+
+You can also re-enable pipe mode for a specific request, for example for
+WebSockets:
+
+.. code-block:: vcl
+
+    sub vcl_recv {
+            if (req.http.upgrade == "websocket") {
+                    return (pipe);
+            }
+    }