feat: add route-level HeaderMutation support for request header manipulation

[sukumargaonkar]

Description

This commit implements route-level HeaderMutation support for AIGatewayRouteRuleBackendRef. The feature allows users to define header mutations at the route level (per backend reference on AIGatewayRoute) in addition to the existing backend-level HeaderMutation support.

Key Features:

• Route-level HeaderMutation: New headerMutation field in AIGatewayRouteRuleBackendRef for fine-grained header
  control per route
• Smart merge logic: When both route-level and backend-level HeaderMutation are defined, they are intelligently combined
  with route-level taking precedence for conflicts
• Case-insensitive handling: Proper header name normalization and conflict resolution (e.g., X-Custom vs x-custom
  are treated as the same header)
• Full backward compatibility: Existing backend-level only configurations continue to work unchanged

Use Cases:
GCP Provisioned Throughput [docs [1]]:

• Unlike bedrock where provisioned-throughput and pay-as-you-go (on-demand) models get different endpoints, in GCP both provisioned-throughput and pay-as-you-go get the same endpoint.
• whether a request should be counted under provisioned-throughput or pay-as-you-go needs to be controlled via headers.
• This change will allow configuring custom headers at route-level

apiVersion: aigateway.envoyproxy.io/v1alpha1
kind: AIGatewayRoute
metadata:
  annotations:
  name: gemini-2.5-flash
  namespace: gateway
spec:
  # ... other spec fields ...
  rules:
    - backendRefs:
        # Provisioned Throughput on Region-1
        - modelNameOverride: gemini-2.5-flash
          name: gcp-<region-1>
          priority: 0
          headerMutation:  # <-- New
            set:
              - name: X-Vertex-AI-LLM-Request-Type
                value: "dedicated"
        # Provisioned Throughput on Region-2
        - modelNameOverride: gemini-2.5-flash
          name: gcp-<region-2>
          priority: 0
          headerMutation:  # <-- New
            set:
              - name: X-Vertex-AI-LLM-Request-Type
                value: "dedicated"
        # Pay-As-You-GO on Region-1
        - modelNameOverride: gemini-2.5-flash
          name: gcp-<region-1>
          priority: 1
          headerMutation:  # <-- New
            set:
              - name: X-Vertex-AI-LLM-Request-Type
                value: "shared"
        # Pay-As-You-GO on Region-2
        - modelNameOverride: gemini-2.5-flash
          name: gcp-<region-2>
          priority: 1
          headerMutation:  # <-- New
            set:
              - name: X-Vertex-AI-LLM-Request-Type
                value: "shared"
  # ... other spec fields ...

1: https://cloud.google.com/vertex-ai/generative-ai/docs/provisioned-throughput/use-provisioned-throughput#limitations-of-the-dashboard

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.67%. Comparing base (3df0a93) to head (835aba0).

❌ Your project status has failed because the head coverage (78.67%) is below the target coverage (86.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1414      +/-   ##
==========================================
+ Coverage   78.64%   78.67%   +0.03%     
==========================================
  Files         140      140              
  Lines       13789    13813      +24     
==========================================
+ Hits        10844    10868      +24     
  Misses       2289     2289              
  Partials      656      656              

☔ 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.

[aabchoo]

Overall looks good to me. Deferring to Takeshi as he is assigned to this

[aabchoo]

Curious, why add comments for the Set logic but not the Remove? Also, add periods at the end of the comments.

[mathetake]

nit but looks good