Allow NGINX variables in request and response modifier filters and fix colon and dollar sign restrictions in regex header and query param match by salonichf5 · Pull Request #5008 · nginx/nginx-gateway-fabric

salonichf5 · 2026-03-26T22:29:48Z

Proposed changes

Write a clear and concise description that helps reviewers understand the purpose and impact of your changes. Use the
following format:

Problem: Users want to be able to specify nginx variables in request/response modifier filters and use :$ in regex path matches for headers and query params

Solution: Adds the ability to specify nginx variables in request/response modifier filters and use :$ in regex path matches for headers and query params.

Testing: Manual testing of various cases with the changes added in example guide, doc to follow

Please focus on (optional): If you any specific areas where you would like reviewers to focus their attention or provide
specific feedback, add them here.

Closes #2040
Handles concerns raised in discussion.

Checklist

Before creating a PR, run through this checklist and mark each as complete.

I have read the CONTRIBUTING doc
I have added tests that prove my fix is effective or that my feature works
I have checked that all unit tests pass after adding my changes
I have updated necessary documentation
I have rebased my branch onto main
I will ensure my PR is targeting the main branch and pulling from my branch from my own fork

Release notes

If this PR introduces a change that affects users and needs to be mentioned in the release notes,
please add a brief note that summarizes the change.

Allows specifying NGINX variables in RequestHeaderModifier and ResponseHeaderModifier filters along with allowing the use of colon and dollar sign in RegularExpression path match for headers and query params.

salonichf5 · 2026-03-26T22:32:41Z

I will update the documentation guides as well for this

codecov · 2026-03-26T22:34:53Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.13%. Comparing base (21ff12d) to head (941479c).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5008      +/-   ##
==========================================
+ Coverage   86.05%   86.13%   +0.08%     
==========================================
  Files         144      144              
  Lines       17600    17616      +16     
  Branches       35       35              
==========================================
+ Hits        15145    15173      +28     
+ Misses       2184     2177       -7     
+ Partials      271      266       -5

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot

Pull request overview

Enables more expressive HTTP matching and header modifier configuration by permitting : / $ in regex-based header/query-param matches and allowing NGINX variable references in request/response header modifier filter values.

Changes:

Update NJS headersMatch parsing to allow : inside the header match value portion.
Relax match-part validation to allow $ (e.g., regex end anchors) and : in header/query-param match values; extend tests accordingly.
Add a new validator for escaped strings that permits NGINX variables in header modifier values; update examples to demonstrate variable usage.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/controller/nginx/modules/test/httpmatches.test.js	Adds unit tests covering `:` in header values and `$` anchors in regex query param matches.
internal/controller/nginx/modules/src/httpmatches.js	Adjusts header match parsing to split on the first two `:` delimiters only.
internal/controller/nginx/config/validation/http_njs_match_test.go	Updates validation tests to treat URL-like strings / `$` as valid match parts.
internal/controller/nginx/config/validation/http_njs_match.go	Removes restrictions that previously rejected `:` and `$` in NJS match parts.
internal/controller/nginx/config/validation/http_filters_test.go	Extends filter header value tests to include supported NGINX variables.
internal/controller/nginx/config/validation/http_filters.go	Switches filter header value validation to allow NGINX variables.
internal/controller/nginx/config/validation/common_test.go	Adds tests for the new “escaped string with NGINX vars” validator.
internal/controller/nginx/config/validation/common.go	Introduces `validateEscapedStringWithNginxVars` and its regex/error message.
examples/http-response-header-filter/http-route-filters.yaml	Demonstrates response header modifier values using NGINX variables.
examples/http-response-header-filter/headers.yaml	Updates the example backend nginx.conf to emit additional variable-based headers.
examples/http-request-header-filter/echo-route.yaml	Demonstrates request header modifier values using NGINX variables.
examples/advanced-routing/cafe-routes.yaml	Updates regex examples to include `:` and `$`-anchored patterns.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

internal/controller/nginx/config/validation/common.go

examples/http-response-header-filter/http-route-filters.yaml

…olon and dollar sign restrictions in regex header and query param match and update example guides with new values allowed

sjberman · 2026-03-27T15:39:38Z

examples/advanced-routing/cafe-routes.yaml

      - name: headerRegex
        type: RegularExpression
-        value: "header-[a-z]{1}"
+        value: "^https://example\\.com(/|$)"


I think the original example you had was better. I don't suspect URIs are going to be very common header values.

sjberman · 2026-03-27T15:44:19Z

internal/controller/nginx/config/validation/common.go

+// of the form $variable_name or ${variable_name}, where the name starts with a lowercase letter or
+// underscore followed by lowercase letters, digits, or underscores.
+// All '"' must be escaped and the string must not end with an unescaped '\'.
+func validateEscapedStringWithNginxVars(value string, examples []string) error {


We already have a ValidateNginxVariableName function. Can we just use that?

Are nginx variables ever going to have curly braces in them? I don't think they need them.

I have seen it in the config get concatenated with other variables but I don't think we should support it here either. Copilot convinced me, i'll revert

Re-using ValidateNginxVariableName wouldn't make sense it does not even allow digits. Its too narrow. List of variables also has leading _ , granted allowing curly braces might be much but it is very much allowed in the config so we should not limit ourselves here again and do another PR to relax limitations I feel. What do you think ? Still I am open to remove curly's

one question -- do we want to allow mixed values? like string + nginx variable?

config from an example I was testing. Unless we have a strong reason that curly braces do some damage we shouldn't restrict things I believe

proxy_http_version 1.1; proxy_set_header Accept-Encoding "${accept_encoding_header_var}compress"; proxy_set_header My-cool-header "${my_cool_header_header_var}this-is-an-appended-value"; proxy_set_header X-Request-Method "${x_request_method_header_var}$request_method"; proxy_set_header My-Overwrite-Header "this-is-the-only-value"; proxy_set_header X-Client-IP "$remote_addr";

Yeah, I guess we can be a bit more relaxed with it. Though we should not allow semicolons. Maybe we can enhance the existing ValidateNginxVariableName and use that.

internal/controller/nginx/modules/src/httpmatches.js

sjberman · 2026-03-27T15:49:52Z

internal/controller/nginx/config/validation/http_njs_match.go

 func validateNJSHeaderPart(value string) error {
-	// if it contains the separator, it will break NJS code.
-	if strings.Contains(value, config.HeaderMatchSeparator) {
-		return fmt.Errorf("cannot contain %q", config.HeaderMatchSeparator)
-	}
-
 	return validateCommonNJSMatchPart(value)
 }


we could probably just remove this wrapper function and move validateCommonNJSMatchPart to the caller of validateNJSHeaderPart.

github-project-automation bot added this to NGINX Gateway Fabric Mar 26, 2026

nginx-bot bot added the release-notes label Mar 26, 2026

github-project-automation bot moved this to 🆕 New in NGINX Gateway Fabric Mar 26, 2026

github-actions bot added the bug Something isn't working label Mar 26, 2026

salonichf5 requested a review from Copilot March 26, 2026 22:33

Copilot started reviewing on behalf of salonichf5 March 26, 2026 22:33 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

internal/controller/nginx/config/validation/common.go Outdated Show resolved Hide resolved

examples/http-response-header-filter/http-route-filters.yaml Show resolved Hide resolved

allow nginx variables in request and response modifier filters, fix c…

941479c

…olon and dollar sign restrictions in regex header and query param match and update example guides with new values allowed

salonichf5 force-pushed the fix/allow-nginx-variables-in-filters branch from 60dcf89 to 941479c Compare March 27, 2026 02:10

salonichf5 marked this pull request as ready for review March 27, 2026 15:35

salonichf5 requested a review from a team as a code owner March 27, 2026 15:35

sjberman reviewed Mar 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow NGINX variables in request and response modifier filters and fix colon and dollar sign restrictions in regex header and query param match#5008

Allow NGINX variables in request and response modifier filters and fix colon and dollar sign restrictions in regex header and query param match#5008
salonichf5 wants to merge 1 commit intomainfrom
fix/allow-nginx-variables-in-filters

salonichf5 commented Mar 26, 2026 •

edited by sjberman

Loading

Uh oh!

salonichf5 commented Mar 26, 2026

Uh oh!

codecov bot commented Mar 26, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

sjberman Mar 27, 2026

Uh oh!

sjberman Mar 27, 2026

Uh oh!

salonichf5 Mar 27, 2026

Uh oh!

salonichf5 Mar 27, 2026 •

edited

Loading

Uh oh!

sjberman Mar 27, 2026

Uh oh!

Uh oh!

sjberman Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

salonichf5 commented Mar 26, 2026 • edited by sjberman Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

Checklist

Release notes

Uh oh!

salonichf5 commented Mar 26, 2026

Uh oh!

codecov bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

sjberman Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

sjberman Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

salonichf5 Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

salonichf5 Mar 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sjberman Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sjberman Mar 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

salonichf5 commented Mar 26, 2026 •

edited by sjberman

Loading

codecov bot commented Mar 26, 2026 •

edited

Loading

salonichf5 Mar 27, 2026 •

edited

Loading