feat(router): subgraph header groups (headers.groups) — alternative to #2868

docs-website/router/proxy-capabilities/subgraph-request-header-operations.mdx

@@ -53,6 +53,14 @@ headers:
         - op: "propagate"
           named: "Subgraph-Secret"
           default: "some-secret"
+
+  groups: # Apply rules to a cohort of subgraphs (list, regex, or both)
+    - id: "products-cohort"
+      subgraphs: [products]
+      matching: "^products-feature-.+$"
+      request:
+        - op: "propagate"
+          named: "X-Products-Auth"
 ```
 
 ### What does the snippet do?
@@ -61,6 +69,33 @@ With `all` we address all subgraph requests. Next, we can define several rules o
 
 The `subgraphs` section allows to propagate headers for specific subgraphs. The name must match with the subgraph name in the Studio.
 
+The `groups` section applies a bundle of rules to every subgraph that matches the group's selector. A group can list subgraphs explicitly (`subgraphs:`), match by regex (`matching:`), or both. This is useful for applying the same rules to a base subgraph and its feature variants without duplicating the same block under every entry.
+
+### Rule evaluation order
+
+For each subgraph the router builds a header set in this order:
+
+1. `headers.all` rules.
+2. `headers.groups` entries whose selector matches the subgraph (in config order).
+3. `headers.subgraphs.<name>` rules for the exact subgraph name.
+
+Exact-name rules apply last, so a `headers.subgraphs.products` rule can still override a broader group rule when both target the same header.
+
+### Subgraph header groups
+
+Each entry under `groups` accepts:
+
+* `id` — A unique identifier for the group. Required. Used in router error messages.
+* `subgraphs` — Explicit list of subgraph names this group applies to. Names are case-sensitive identifiers.
+* `matching` — A Go regular expression evaluated against the subgraph name.
+* `negate_match` — If `true`, the regex result is inverted. Subgraphs in the explicit `subgraphs` list are still included positively; `negate_match` only affects the regex.
+* `request` — Request rules to apply when the group matches.
+* `response` — Response rules to apply when the group matches.
+
+At least one of `subgraphs` or `matching` must be specified, and at least one of `request` or `response` must be specified. Invalid configurations fail router startup.
+
+A group with both `subgraphs` and `matching` matches a subgraph if it appears in either (the union — list-match OR regex-match). The group's rules apply at most once per subgraph regardless of how many parts of the selector match.
+
 ### Supported header rules
 
 Currently, we support the following header rules:

docs-website/router/proxy-capabilities/subgraph-response-header-operations.mdx

@@ -64,6 +64,15 @@ headers:
         named: "X-User-Id"
         default: "456"             # Set the value when the header was not set
         algorithm: "last_write"
+
+  groups: # Apply rules to a cohort of subgraphs (list, regex, or both)
+    - id: "products-cohort"
+      subgraphs: [products]
+      matching: "^products-feature-.+$"
+      response:
+        - op: "propagate"
+          named: "X-Products-Trace"
+          algorithm: "last_write"
 ```
 
 ### What does the snippet do?
@@ -72,6 +81,8 @@ With `all` we address all subgraph requests. Next, we can define several rules o
 
 The `subgraphs` section allows to propagate headers for specific subgraphs. The name must match with the subgraph name in the Studio.
 
+The `groups` section applies a bundle of rules to every subgraph that matches the group's selector. A group can list subgraphs explicitly (`subgraphs:`), match by regex (`matching:`), or both. Groups apply after `all` and before exact `subgraphs` rules, so an exact subgraph rule can still override a group rule. See [Subgraph Request Headers Operations](/router/proxy-capabilities/subgraph-request-header-operations#subgraph-header-groups) for the full set of group fields and validation rules.
+
 ### Supported header rules
 
 Currently, we support the following header rules: