feat(router): add options to configure router config assembling in split config poller

[Noroth]

Summary by CodeRabbit

• New Features

  • Added split-config loading capability for flexible modular configuration management from CDN
  • Introduced feature-based access control for API endpoints
  • New manifest endpoints supporting feature-flag configuration distribution

• Documentation

  • Added split-config polling configuration guide with examples and behavioral options

Checklist

• I have discussed my proposed changes in an issue and have received approval to proceed.
• I have followed the coding standards of the project.
• Tests or benchmarks have been added or updated.
• Documentation has been updated on https://github.com/wundergraph/docs-website.
• I have read the Contributors Guide.

Open Source AI Manifesto

This project follows the principles of the Open Source AI Manifesto. Please ensure your contribution aligns with its principles.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wundergraphinc	🟢 Ready	View Preview	May 8, 2026, 1:44 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

This PR implements a complete split-config-loading feature enabling routers to assemble execution configurations from a base graph plus per-feature-flag configs fetched from CDN. It adds JWT feature claims, split-config polling with change detection, mux reuse optimization via per-mux contexts, manifest endpoints with feature gating, and comprehensive configuration/test coverage.

Changes

Split-Config-Loading Feature

Layer / File(s)	Summary
Type Definitions and Data Contracts controlplane/src/types/index.ts, router/pkg/routerconfig/client.go	New 'split-config-loading' feature literal in FeatureIds, features?: string[] claim in GraphApiKeyJwtPayload, Changes type tracking config deltas (added/removed/changed configs).
Shared Error Definitions router/pkg/errs/errors.go	Centralized error variables for config poller (ErrConfigNotModified, ErrRouterConfigNotFound) and CDN (ErrMissingSignatureHeader, ErrInvalidSignature, ErrFileNotFound).
Configuration Schema and Types router/pkg/config/config.go, router/pkg/config/config.schema.json, router/pkg/config/fixtures/full.yaml, router/pkg/config/testdata/*	Configuration types and schema for split_config_poller with skip_missing_feature_flags and ignored_feature_flags options; example and default fixtures.
JWT Feature Claims Parsing router/internal/jwt/claims.go	FederatedGraphTokenClaims adds Features []string field and HasFeature(feature) method; ExtractFederatedGraphTokenClaims parses and validates optional features array claim.
Federated Graph Token Generation controlplane/src/core/bufservices/federated-graph/createFederatedGraphToken.ts, controlplane/src/core/repositories/OrganizationRepository.ts	Token generation includes features claim based on organization-level split-config-loading feature flag lookup.
ConfigPoller Interface and Response router/pkg/controlplane/configpoller/config_poller.go, router/pkg/routerconfig/client.go	ConfigPoller.Subscribe handler signature changed to accept *routerconfig.Response (replacing (newConfig, oldVersion)); error handling shifted to shared errs package.
CDN SplitFetcher Implementation router/pkg/routerconfig/cdn/split_fetcher.go	HTTP client fetching mapper and router config from CDN via authenticated POST with optional HMAC-SHA256 validation and gzip decompression.
SplitConfigPoller Implementation router/pkg/controlplane/configpoller/split_config_poller.go	Poller assembling router config from base graph plus per-feature-flag configs with deterministic change detection and targeted config merging on each poll cycle.
Router Config Poller Initialization router/core/init_config_poller.go	Router startup detects split-config-loading feature in JWT token; if enabled and no custom storage provider, instantiates split-config poller; otherwise falls back to traditional polling.
Router Server Reconfiguration router/core/router.go, router/core/supervisor_instance.go	Router.newServer signature updated to accept routerconfig.Response; feature-flag cleanup and config propagation use response object throughout hot-reload paths.
Graph Server Mux Reuse and Context Management router/core/graph_server.go	Graph server refactored to use per-mux contexts and map-based mux storage; mux reuse logic triggered by response.Changes; contexts cancelled on shutdown for reused muxes.
CDN Manifest Endpoints cdn-server/cdn/src/index.ts	New POST endpoints for manifest/mapper.json, manifest/latest.json, and manifest/feature-flags/{name}.json with JWT feature gating and optional X-Signature-SHA256 header passthrough.
Error Handling Centralization router/pkg/routerconfig/cdn/client.go, router/pkg/routerconfig/s3/client.go	CDN and S3 client error handling migrated to shared errs package (404 → ErrRouterConfigNotFound, 304 → ErrConfigNotModified).
SplitFetcher Test Coverage router/pkg/routerconfig/cdn/split_fetcher_test.go	Tests for HTTP status handling, signature validation, gzip decompression, and successful config unmarshalling with error scenarios.
SplitConfigPoller Test Coverage router/pkg/controlplane/configpoller/split_config_poller_test.go	Tests for GetRouterConfig assembly, config rule handling, feature-flag ignoring/skipping, subscribe polling with change detection, and handler state rollback.
CDN Manifest Endpoint Test Coverage cdn-server/cdn/test/cdn.test.ts	Test suite for manifest endpoints validating JWT auth (401), feature gating (403), version matching (304), blob retrieval (200/404), and org/graph ID validation.
Test Infrastructure Updates router-tests/events/nats_events_test.go, router-tests/operations/cache_warmup_test.go, router-tests/operations/plan_fallback_cache_test.go, router-tests/protocol/config_hot_reload_test.go	Mock ConfigPollerMock updated to use *routerconfig.Response for config updates across all test suites.
Hot Reload and Mux Integration Tests router-tests/protocol/config_hot_reload_test.go	New TestConfigHotReloadGraphServerSwap validates selective websocket closure when only one feature-flag mux is rebuilt while others remain unchanged.
Documentation docs-website/router/configuration.mdx	Split Config Poller section with description, YAML example, and configuration options table.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• wundergraph/cosmo#2814: Implements the same split-config-loading feature with JWT features claim, router JWT feature checks, split-config poller and CDN split fetcher/manifest support.
• wundergraph/cosmo#2839: Modifies CDN server code to add JWT-extracted features context, requireFeature middleware, manifestBlob helper, and new POST manifest routes with corresponding tests.
• wundergraph/cosmo#2823: Makes overlapping changes to split-config loading and feature-flag handling with features claim in federated-graph tokens and mux reuse for unchanged feature-flag configs.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.56% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding configuration options for the split config poller in the router.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch ludwig/eng-9537-router-add-config-for-split-config

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 golangci-lint (2.12.1)

level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies"

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[dkorittki]

Maybe a better name might be ConfigOptions