feat(config): session correlation header injection configuration by SasSwart · Pull Request #197 · coder/boundary

SasSwart · 2026-04-30T09:55:57Z

PR Map

feat(audit): session ID generation, sequence counter, and BoundaryLog wiring #196
👉🏼 feat(config): session correlation header injection configuration #197
feat(proxy): inject session ID and sequence number headers on matching requests #198

RFC: Bridge ↔ Boundaries Correlation

Add YAML and CLI configuration surface for session correlation header injection per FR 2 of the RFC.

Depends on #196.

Changes

config/session_correlation.go: New file. Defines SessionCorrelationConfig, InjectTarget, ParseInjectTarget (with duplicate-key detection), ValidateSessionCorrelation, fixed header name constants (SessionIDHeaderName, SequenceNumberHeaderName), and DefaultInjectTargetFromEnv — a helper that derives a default inject target from CODER_AGENT_URL when no explicit targets are configured.
config/session_correlation_test.go: New file. Table-driven tests for ParseInjectTarget (including duplicate-key rejection), ValidateSessionCorrelation, the end-to-end NewAppConfigFromCliConfig session correlation path (with controlled environ), DefaultInjectTargetFromEnv, CLI+YAML target merging (TestBuildSessionCorrelation_TargetMerge), and the CODER_AGENT_URL fallback path (TestBuildSessionCorrelation_AgentURLFallback).
config/config.go: Wire session correlation fields into CliConfig (three new fields for serpent bindings: SessionCorrelationEnabled, InjectSessionIDTarget, InjectSessionIDTargets) and AppConfig (new SessionCorrelation field). NewAppConfigFromCliConfig now accepts an environ []string parameter so the CODER_AGENT_URL fallback is testable without relying on the host environment. Add buildSessionCorrelation helper that merges YAML+CLI inject targets, falls back to a target derived from CODER_AGENT_URL when none are configured and session correlation is enabled, and validates the result.
cli/cli.go: Register three new serpent options, pass os.Environ() to NewAppConfigFromCliConfig, and add usage examples including a zero-config workspace example.

New CLI flags

Flag	Env	YAML	Default	Description
`--enable-session-correlation`	`BOUNDARY_SESSION_CORRELATION_ENABLED`	`session_correlation_enabled`	`false`	Toggle; when enabled with no explicit targets, the inject target is auto-derived from `CODER_AGENT_URL` (set automatically in Coder workspaces)
`--session-id-inject-target`	`BOUNDARY_SESSION_ID_INJECT_TARGET`	—	—	Repeatable inject target (one target per flag invocation; env accepts one value; use YAML for multiple). Format: `domain=<host> [path=<glob>]`
—	—	`session_id_inject_targets`	—	YAML-only list of inject targets

Header names are fixed constants (X-Coder-Agent-Firewall-Session-Id, X-Coder-Agent-Firewall-Sequence-Number) matching what Coder AI Gateway expects — they are not user-configurable.

Config validation ensures that when correlation is enabled at least one inject target is present (either explicit or auto-derived from CODER_AGENT_URL). Parsing validates the domain=... path=... key-value format, rejects unknown keys, and rejects duplicate keys within a single target string.

This commit adds config and validation only; runtime injection is wired in a follow-up PR.

Note

This PR was authored by Coder Agents.

Add YAML and CLI configuration surface for session correlation header injection per the Bridge/Boundaries Correlation RFC (FR 2). New configuration options: - --enable-session-correlation / session_correlation_enabled: top-level toggle to disable injection entirely for deployments without AI Bridge in front. - --inject-session-id-on / session_id_inject_targets (YAML): repeatable list of inject targets in "domain=<host> [path=<glob>]" format. - --session-id-header-name / session_id_header_name: configurable header name (default X-Coder-Agent-Firewall-Session-Id). - --sequence-number-header-name / sequence_number_header_name: configurable header name (default X-Coder-Agent-Firewall-Sequence-Number). Config validation ensures that when correlation is enabled at least one inject target is present and header names are non-empty. Parsing validates the domain=... path=... key-value format and rejects unknown keys. This commit adds config and validation only; runtime injection is wired in a follow-up PR.

… on the environment

…variables Enhance the NewAppConfigFromCliConfig function to include an additional parameter for environment variables, allowing for more flexible session correlation header injection based on the current environment. Update related tests to validate new functionality.

…ce validation Updated the description for the session ID inject target flag to clarify usage and provide an example. Added validation in the ParseInjectTarget function to prevent duplicate keys for domain and path in the input. Expanded unit tests to cover cases of duplicate keys.

Implemented new tests to validate the merging behavior of session correlation targets from YAML and CLI configurations. The tests cover various scenarios, including individual sources, merged targets, and preservation of multiple entries from each source.

SasSwart

Most review feedback tended to. One tricky outstanding comment left.

…rom configuration Eliminated the session ID and sequence number header name fields from the CliConfig and SessionCorrelationConfig structures. Updated related functions and tests to reflect these changes, ensuring that session correlation validation and configuration remain intact without explicit header name settings.

ssncferreira

LGTM 👍 Thank you for addressing the comments!

ssncferreira · 2026-05-07T14:00:00Z

+			name:    "duplicate domain key",
+			input:   "domain=staging.coder.com domain=prod.coder.com",


…er agreement Add integration tests that verify the core invariants of session correlation across the proxy, auditor, and forwarded request headers working together. These tests fill the gap identified during review of the session correlation PR stack (#196, #197, #198) where unit tests verified each component in isolation but did not verify them in concert. New test file: proxy/proxy_session_correlation_integration_test.go Tests added: - LLMRequestAuditAndHeadersAgree: audit sequence number matches the forwarded header value on inject-target requests. - NonLLMRequestAuditedWithoutHeaders: allowed non-inject-target requests are audited but carry no correlation headers. - DeniedRequestAuditedNeverForwarded: denied requests consume a sequence number but are never forwarded. - MixedRequestsSequenceOrdering: interleaved LLM, non-LLM, and denied requests all advance the counter monotonically. - SequenceGapRevealsAgenticLoop: gap between two LLM sequence numbers precisely equals intermediate tool-use requests. - SpoofedHeadersOverwrittenWithCorrectSequence: client-supplied headers are replaced and the audit event still agrees. - DisabledCorrelationNoHeadersNoPreallocatedSequence: disabled correlation means no headers and no pre-allocated sequence. - ConcurrentRequestsUniqueSequenceNumbers: concurrent requests each get a unique, dense sequence number.

evgeniy-scherbina · 2026-05-11T15:37:28Z

+// InjectTarget represents a parsed target for session correlation header
+// injection. Requests matching the domain (and optional path glob) will
+// receive the session ID and sequence number headers.
+type InjectTarget struct {


I'm a bit concerned that --session-id-inject-target(s) syntax similar but not identical to --allow syntax; and that parsing & matching logic isn't reused (see rulesengine pkg).

rulesengine pkg is well documented, so customers will probably rely on it; and it will be confusing that --session-id-inject-target(s) syntax different from it.

…er agreement Add integration tests that verify the core invariants of session correlation across the proxy, auditor, and forwarded request headers working together. These tests fill the gap identified during review of the session correlation PR stack (#196, #197, #198) where unit tests verified each component in isolation but did not verify them in concert. New test file: proxy/proxy_session_correlation_integration_test.go Tests added: - LLMRequestAuditAndHeadersAgree: audit sequence number matches the forwarded header value on inject-target requests. - NonLLMRequestAuditedWithoutHeaders: allowed non-inject-target requests are audited but carry no correlation headers. - DeniedRequestAuditedNeverForwarded: denied requests consume a sequence number but are never forwarded. - MixedRequestsSequenceOrdering: interleaved LLM, non-LLM, and denied requests all advance the counter monotonically. - SequenceGapRevealsAgenticLoop: gap between two LLM sequence numbers precisely equals intermediate tool-use requests. - SpoofedHeadersOverwrittenWithCorrectSequence: client-supplied headers are replaced and the audit event still agrees. - DisabledCorrelationNoHeadersNoPreallocatedSequence: disabled correlation means no headers and no pre-allocated sequence. - ConcurrentRequestsUniqueSequenceNumbers: concurrent requests each get a unique, dense sequence number.

SasSwart mentioned this pull request Apr 30, 2026

feat(proxy): inject session ID and sequence number headers on matching requests #198

Merged

SasSwart marked this pull request as draft April 30, 2026 13:00

This was referenced Apr 30, 2026

feat(audit): add per-session sequence counter #195

Closed

feat(audit): session ID generation, sequence counter, and BoundaryLog wiring #196

Merged

feat(boundary): generate session ID at startup #194

Closed

SasSwart force-pushed the sasswart/feat-config-session-correlation-header-injection branch from c24a0fd to c08f291 Compare May 1, 2026 10:51

SasSwart mentioned this pull request May 1, 2026

test(proxy): integration tests for session correlation audit and header agreement #199

Open

Base automatically changed from sasswart/feat-audit-session-sequence-wiring to main May 4, 2026 13:37

SasSwart force-pushed the sasswart/feat-config-session-correlation-header-injection branch from c08f291 to 3ea7428 Compare May 5, 2026 09:20

make fmt

fa3d50e

SasSwart self-assigned this May 5, 2026

SasSwart added 3 commits May 5, 2026 10:27

feat: determine which domains to inject correlation headers for based…

0a1fe41

… on the environment

make lint

4687658

make fmt

5ea1fc4

SasSwart requested review from evgeniy-scherbina and ssncferreira May 5, 2026 10:34

SasSwart marked this pull request as ready for review May 5, 2026 10:36

ssncferreira reviewed May 6, 2026

View reviewed changes

SasSwart added 4 commits May 7, 2026 09:11

remove innacuracies from documentation

d2d269c

SasSwart commented May 7, 2026

View reviewed changes

SasSwart requested a review from ssncferreira May 7, 2026 11:43

ssncferreira approved these changes May 7, 2026

View reviewed changes

SasSwart merged commit df62d5b into main May 7, 2026
5 checks passed

SasSwart deleted the sasswart/feat-config-session-correlation-header-injection branch May 7, 2026 14:04

evgeniy-scherbina reviewed May 11, 2026

View reviewed changes

SasSwart mentioned this pull request May 12, 2026

refactor(proxy): unify inject target matching with rulesengine #201

Merged

		name: "duplicate domain key",
		input: "domain=staging.coder.com domain=prod.coder.com",

Conversation

SasSwart commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Map

Changes

New CLI flags

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SasSwart left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ssncferreira left a comment

Choose a reason for hiding this comment

Uh oh!

ssncferreira May 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

evgeniy-scherbina May 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

SasSwart commented Apr 30, 2026 •

edited

Loading