feat(router): added support for label overrides

[kamilkisiela]

ROUTER-163

This pull request introduces a new top-level configuration option, override_labels, allowing for fine-grained control over progressive override labels (@override(label: "<string>")). This feature enables teams to dynamically activate or deactivate field overrides based on static booleans or runtime expressions evaluated against incoming request data.

How to Configure Override Labels

The new override_labels key can be added to your router.config.yaml. It accepts a map where each key is the name of an override label and the value defines the condition under which it should be considered "active".

Example 1: Static Override

For simple on/off toggling, you can use a boolean value.

override_labels:
  # This label will be active for every single request, enabling the associated override.
  use_new_billing_service: true
  # This label will never be active.
  use_legacy_inventory: false

Example 2: Dynamic Override with an Expression
For more complex scenarios, you can provide an object with an expression key. The expression is evaluated at runtime for each request using the VRL. If the expression evaluates to true, the label becomes active for that request.

override_labels:
  # Activate a label only for internal users or beta testers based on a header.
  activate-beta-feature:
    expression: "request.headers['x-user-group'] == 'beta'"

Error Handling

• Startup: If an expression in the configuration is invalid, the router will fail to start and log a descriptive error, preventing deployment with a broken configuration.
• Runtime: If an expression fails to execute during a request (e.g., it produces a non-boolean result), the router will return a 500 Internal Server Error with the error code LABEL_EVALUATION_FAILED.

[github-actions]

✅ k6-benchmark results

     ✓ response code was 200
     ✓ no graphql errors
     ✓ valid response structure

     █ setup

     checks.........................: 100.00% ✓ 210492      ✗ 0    
     data_received..................: 6.2 GB  205 MB/s
     data_sent......................: 82 MB   2.7 MB/s
     http_req_blocked...............: avg=3.9µs    min=621ns   med=1.67µs  max=5.63ms   p(90)=2.38µs  p(95)=2.76µs  
     http_req_connecting............: avg=1.1µs    min=0s      med=0s      max=3.08ms   p(90)=0s      p(95)=0s      
     http_req_duration..............: avg=20.89ms  min=2.08ms  med=19.88ms max=102.13ms p(90)=28.7ms  p(95)=31.91ms 
       { expected_response:true }...: avg=20.89ms  min=2.08ms  med=19.88ms max=102.13ms p(90)=28.7ms  p(95)=31.91ms 
     http_req_failed................: 0.00%   ✓ 0           ✗ 70184
     http_req_receiving.............: avg=142.23µs min=24.43µs med=39.83µs max=72.33ms  p(90)=94.41µs p(95)=412.99µs
     http_req_sending...............: avg=26.43µs  min=5.57µs  med=10.76µs max=25.05ms  p(90)=16.26µs p(95)=29.43µs 
     http_req_tls_handshaking.......: avg=0s       min=0s      med=0s      max=0s       p(90)=0s      p(95)=0s      
     http_req_waiting...............: avg=20.72ms  min=2.03ms  med=19.75ms max=88.54ms  p(90)=28.42ms p(95)=31.56ms 
     http_reqs......................: 70184   2334.384809/s
     iteration_duration.............: avg=21.37ms  min=5.68ms  med=20.24ms max=239.45ms p(90)=29.15ms p(95)=32.41ms 
     iterations.....................: 70164   2333.71959/s
     vus............................: 50      min=50        max=50 
     vus_max........................: 50      min=50        max=50 

[github-actions]

🐋 This PR was built and pushed to the following Docker images:

Image Names: ghcr.io/graphql-hive/router

Platforms: linux/amd64,linux/arm64

Image Tags: ghcr.io/graphql-hive/router:pr-518 ghcr.io/graphql-hive/router:sha-46028c9

Docker metadata

{
"buildx.build.ref": "builder-ed913a90-fc5a-4bdd-965f-3b59c64ec412/builder-ed913a90-fc5a-4bdd-965f-3b59c64ec4120/8z1aqajqs01odn30qug4k8rh0",
"containerimage.descriptor": {
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "digest": "sha256:680ca0a0e370b6c417aa7858b9439508235d050d1346d40dbbddf436e643187c",
  "size": 1609
},
"containerimage.digest": "sha256:680ca0a0e370b6c417aa7858b9439508235d050d1346d40dbbddf436e643187c",
"image.name": "ghcr.io/graphql-hive/router:pr-518,ghcr.io/graphql-hive/router:sha-46028c9"
}

[kamilkisiela]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a powerful feature for overriding labels using VRL expressions, which is a great addition for dynamic configuration. The implementation is well-structured, isolating the new logic in an OverrideLabelsEvaluator and using lazy evaluation on the hot path to minimize performance impact. I have one suggestion to further optimize the label evaluation logic to avoid a potentially unnecessary allocation, in line with the repository's performance-first style guide.

[dotansimha]

Added a few notes, the most crucial one is how we handle errors in cases where evaluation fails