feat(server): add response identity headers

[FrankChen021]

Description

This PR adds opt-in response headers that identify the Druid process which generated an HTTP response:

• X-Druid-Server: advertised host and port
• X-Druid-Service: configured druid.service name
• X-Druid-Version: Druid version

The feature is disabled by default and can be enabled with:

druid.server.http.enableResponseIdentityHeaders=true

The identity handler wraps the complete Jetty handler chain and restores the headers after downstream response resets, so locally generated responses, including early HTTP errors, receive the headers when enabled.

Proxy behavior

For query and management requests proxied by a Router:

• If the upstream returns all three identity headers, the Router forwards the upstream identity.
• If the upstream returns none or only a partial set, the Router returns no identity headers.
• If no upstream response is received and the Router generates the response, the headers identify the Router.
• A Router with the feature disabled suppresses upstream identity headers.

Treating the three headers as an all-or-nothing triple prevents clients from receiving an ambiguous partial identity.

The standalone Coordinator's /druid/indexer/* proxy to a separate Overlord follows the same contract, so it forwards a complete Overlord identity without mixing it with the Coordinator identity.

Security

The headers can reveal internal hostnames, IP addresses, ports, and the Druid version. The setting remains disabled by default and should only be enabled when clients are authorized to receive this information.

Automated tests

• 51 focused configuration, handler, management-proxy, and query-proxy tests passed.
• ResponseIdentityHeaderTest: 6 embedded end-to-end tests passed.
• The embedded coverage includes Coordinator and Overlord APIs directly and through Router, the standalone Coordinator-to-Overlord proxy, Broker SQL and native queries directly and through Router, a native query directly to Historical, and Router-generated responses.
• git diff --check passed.

Real nano cluster validation

The feature was tested against a locally built apache-druid-39.0.0-SNAPSHOT nano-quickstart cluster. All 16 requests returned the expected status and complete identity triple.

URL	Request	Status	X-Druid-Server	X-Druid-Service	X-Druid-Version
http://localhost:8888/status/health	Router health	200	localhost:8888	druid/router	39.0.0-SNAPSHOT
http://localhost:8082/status/health	Broker health	200	localhost:8082	druid/broker	39.0.0-SNAPSHOT
http://localhost:8081/status/health	Coordinator/Overlord health	200	localhost:8081	druid/coordinator	39.0.0-SNAPSHOT
http://localhost:8083/status/health	Historical health	200	localhost:8083	druid/historical	39.0.0-SNAPSHOT
http://localhost:8091/status/health	Middle Manager health	200	localhost:8091	druid/middleManager	39.0.0-SNAPSHOT
http://localhost:8081/druid/coordinator/v1/isLeader	Coordinator API direct	200	localhost:8081	druid/coordinator	39.0.0-SNAPSHOT
http://localhost:8888/druid/coordinator/v1/isLeader	Coordinator API via Router	200	localhost:8081	druid/coordinator	39.0.0-SNAPSHOT
http://localhost:8081/druid/indexer/v1/isLeader	Overlord API direct	200	localhost:8081	druid/coordinator	39.0.0-SNAPSHOT
http://localhost:8888/druid/indexer/v1/isLeader	Overlord API via Router	200	localhost:8081	druid/coordinator	39.0.0-SNAPSHOT
http://localhost:8082/druid/v2/sql	SQL direct to Broker	200	localhost:8082	druid/broker	39.0.0-SNAPSHOT
http://localhost:8888/druid/v2/sql	SQL via Router	200	localhost:8082	druid/broker	39.0.0-SNAPSHOT
http://localhost:8082/druid/v2	Native query direct to Broker	200	localhost:8082	druid/broker	39.0.0-SNAPSHOT
http://localhost:8888/druid/v2	Native query via Router	200	localhost:8082	druid/broker	39.0.0-SNAPSHOT
http://localhost:8083/druid/v2	Native query direct to Historical	200	localhost:8083	druid/historical	39.0.0-SNAPSHOT
http://localhost:8888/status/health	Router-generated PATCH rejection	405	localhost:8888	druid/router	39.0.0-SNAPSHOT
http://localhost:8888/not-a-druid-endpoint	Router-generated missing endpoint	404	localhost:8888	druid/router	39.0.0-SNAPSHOT

The nano configuration runs Coordinator and Overlord in one process on port 8081 with druid.service=druid/coordinator, so requests to Overlord endpoints correctly report that process identity.

Release note

Druid can optionally return X-Druid-Server, X-Druid-Service, and X-Druid-Version on HTTP responses, allowing operators to identify the process and version that served a direct or Router-proxied request. Enable the feature with druid.server.http.enableResponseIdentityHeaders=true only for clients permitted to receive cluster topology and version information.

---

Key changed/added classes in this PR

• ResponseIdentityHeaderHandler
• OverlordProxyServlet
• AsyncManagementForwardingServlet
• AsyncQueryForwardingServlet
• ResponseIdentityHeaderTest

---

This PR has:

• been self-reviewed.
• added documentation for new or modified features or behaviors.
• a release note entry in the PR description.
• added comments explaining the "why" and the intent of the code wherever it would not be obvious for an unfamiliar reader.
• added unit tests or modified existing tests to cover new code paths.
• added integration tests.
• been tested in a test Druid cluster.

[Copilot]

🟢 Approval recommended

The implementation matches the documented proxy semantics, stays opt-in by default for security, and includes targeted unit + embedded test coverage for the new behavior.

Pull request overview

Adds an opt-in mechanism for Druid services to emit response identity headers on all HTTP responses (including early errors), and ensures Router proxying forwards these headers only as an all-or-nothing pair to avoid partial/ambiguous identity during mixed deployments.

Changes:

• Introduces ResponseIdentityHeaderHandler (Jetty wrapper) to add X-Druid-Response-Server and X-Druid-Response-Service when druid.server.http.enableResponseIdentityHeaders=true.
• Updates Router proxy servlets to clear Router-added identity and forward upstream identity headers only when both headers are present and the feature is enabled on the Router.
• Adds unit + embedded end-to-end coverage and documents the new configuration and proxy semantics.

File summaries

File	Description
services/src/main/java/org/apache/druid/server/AsyncQueryForwardingServlet.java	Clears Router identity for proxied query responses and forwards upstream identity headers only as a complete pair when enabled.
server/src/main/java/org/apache/druid/server/AsyncManagementForwardingServlet.java	Applies the same all-or-nothing identity header forwarding rules for management proxying via Router.
server/src/main/java/org/apache/druid/server/initialization/ServerConfig.java	Adds enableResponseIdentityHeaders config flag with serde/equals/hashCode/toString support.
server/src/main/java/org/apache/druid/server/initialization/jetty/JettyServerModule.java	Wraps the full Jetty handler chain with ResponseIdentityHeaderHandler when enabled.
server/src/main/java/org/apache/druid/server/initialization/jetty/ResponseIdentityHeaderHandler.java	New handler that injects the two response identity headers and provides helper methods for Router proxy behavior.
server/src/test/java/org/apache/druid/initialization/ServerConfigTest.java	Verifies default config deserialization keeps identity headers disabled.
server/src/test/java/org/apache/druid/server/AsyncManagementForwardingServletTest.java	Updates test wiring for new ServerConfig dependency in the management forwarding servlet.
server/src/test/java/org/apache/druid/server/initialization/jetty/ResponseIdentityHeaderHandlerTest.java	New unit tests for clearing Router identity and enforcing pairwise forwarding rules.
embedded-tests/src/test/java/org/apache/druid/testing/embedded/server/ResponseIdentityHeaderTest.java	New embedded E2E tests covering direct vs Router-proxied identity behavior across multiple services/endpoints.
docs/configuration/index.md	Documents the new druid.server.http.enableResponseIdentityHeaders setting and security caveat.
docs/api-reference/api-reference.md	Documents the headers and Router proxy behavior in the API overview.

Review details

• Files reviewed: 11/11 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[FrankChen021]

Severity	Findings
P0	0
P1	0
P2	3
P3	0
Total	3

Static review found three correctness and integration issues in the response identity-header path. The inline comments describe the affected server configurations and response lifecycles.

Reviewed 11 of 11 changed files.

---

This is an automated review by Codex GPT-5.6-Luna(max)

[FrankChen021]

Severity	Findings
P0	0
P1	0
P2	2
P3	0
Total	2

Static review found two current-head correctness issues in error-response lifecycle and proxy failure handling.

Reviewed 15 of 15 changed files.

---

This is an automated review by Codex GPT-5.6-Luna(max)

[FrankChen021]

I have reviewed the code for correctness, edge cases, concurrency, and integration risks; no new-head issues found.

Reviewed 15 of 15 changed files.

---

This is an automated review by Codex GPT-5.6-Luna(max)