ClientSettingsPolicy Enhancement Proposal (nginx#1692)

Problem: Need design for specifying client settings like client_max_body_size Solution: Add enhancement proposal introducing ClientSettingsPolicy.
amimimor · Apr 3, 2024 · 2f65432 · 2f65432
1 parent 5babb43
commit 2f65432
Show file tree

Hide file tree

Showing 18 changed files with 450 additions and 2 deletions.
diff --git a/docs/developer/mapping.md b/docs/developer/mapping.md
@@ -0,0 +1,27 @@
+# Mapping Gateway API Resources to NGINX Contexts
+
+This document shows how NGINX Gateway Fabric maps Gateway API resources to NGINX contexts. Below are the three types of possible mappings (simplified for brevity):
+
+**A. Distinct Hostnames**
+
+![map-a](/docs/images/mapping/mapping-a.png)
+
+When each HTTPRoute attached to a Gateway has a distinct set of hostnames, NGINX Gateway Fabric will generate a server block for each hostname. All the locations contained in the server block belong to a single HTTPRoute.
+In this scenario, each server block is "owned" by a single HTTPRoute.
+
+> Note: This mapping only applies to "Exact" path matches. Some "PathPrefix" path matches will generate an additional location block to handle prefix matching.
+
+**B. Same Hostname**
+
+![map-b](/docs/images/mapping/mapping-b.png)
+
+When HTTPRoutes attached to a Gateway specify the same hostname, NGINX Gateway Fabric generates a single server block containing the locations from all HTTPRoutes that specify the server's hostname.
+In this scenario, the HTTPRoutes share "ownership" of the server block.
+
+**C. Internal Redirect**
+
+![map-c](/docs/images/mapping/mapping-c.png)
+
+When HTTPRoutes attached to a Gateway specify the same hostname _and_ path, NGINX Gateway Fabric will generate a single server block and a single (external) location for that path. In addition, it will generate one named location block -- only used for internal requests -- per HTTPRoute match rule.
+The external location will offload the routing decision to an NGINX JavaScript (NJS) function that will route the request to the appropriate named location.
+In this scenario, the HTTPRoutes share "ownership" of the server block and the external location block.
diff --git a/docs/images/client-settings/attach-1.png b/docs/images/client-settings/attach-1.png
diff --git a/docs/images/client-settings/attach-2.png b/docs/images/client-settings/attach-2.png
diff --git a/docs/images/client-settings/attach-3.png b/docs/images/client-settings/attach-3.png
diff --git a/docs/images/client-settings/example-a1.png b/docs/images/client-settings/example-a1.png
diff --git a/docs/images/client-settings/example-a2.png b/docs/images/client-settings/example-a2.png
diff --git a/docs/images/client-settings/example-a3.png b/docs/images/client-settings/example-a3.png
diff --git a/docs/images/client-settings/example-b1.png b/docs/images/client-settings/example-b1.png
diff --git a/docs/images/client-settings/example-b2.png b/docs/images/client-settings/example-b2.png
diff --git a/docs/images/client-settings/example-b3.png b/docs/images/client-settings/example-b3.png
diff --git a/docs/images/client-settings/example-c1.png b/docs/images/client-settings/example-c1.png
diff --git a/docs/images/client-settings/example-c2.png b/docs/images/client-settings/example-c2.png
diff --git a/docs/images/client-settings/example-c3.png b/docs/images/client-settings/example-c3.png
diff --git a/docs/images/mapping/mapping-a.png b/docs/images/mapping/mapping-a.png
diff --git a/docs/images/mapping/mapping-b.png b/docs/images/mapping/mapping-b.png
diff --git a/docs/images/mapping/mapping-c.png b/docs/images/mapping/mapping-c.png
diff --git a/docs/proposals/client-settings.md b/docs/proposals/client-settings.md
diff --git a/docs/proposals/nginx-extensions.md b/docs/proposals/nginx-extensions.md
@@ -718,7 +718,6 @@ NGINX directives:
 - [`keepalive_requests`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_requests)
 - [`keepalive_time`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_time)
 - [`keepalive_timeout`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout)
-- [`keepalive_disable`](https://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_disable)
 
 These features are grouped because they all deal with client traffic.
 
@@ -731,7 +730,7 @@ An Inherited Policy fits this group best for the following reasons:
 
 #### Future Work
 
-- Can add support for more `client_*` directives: `client_body_buffer_size`, `client_header_buffer_size`, etc.
+- Can add support for more `client_*` directives: `client_body_buffer_size`, `client_header_buffer_size`, `keepalive_disable`, etc.
 
 #### Alternatives