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, ValidateSessionCorrelation, default header name constants (X-Coder-Agent-Firewall-Session-Id, X-Coder-Agent-Firewall-Sequence-Number), 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, ValidateSessionCorrelation, the end-to-end NewAppConfigFromCliConfig session correlation path, DefaultInjectTargetFromEnv, and the buildSessionCorrelation CODER_AGENT_URL fallback path.
config/config.go: Wire session correlation fields into CliConfig (five new fields for serpent bindings) and AppConfig (new SessionCorrelation field). 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, applies header name defaults, and validates the result. The helper accepts environ []string explicitly so callers and tests can supply a controlled environment.
cli/cli.go: Register five new serpent options 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 (flag is repeatable; env accepts one value; use YAML for multiple). Format: `domain=<host> [path=<glob>]`
—	—	`session_id_inject_targets`	—	YAML-only list of inject targets
`--session-id-header-name`	`BOUNDARY_SESSION_ID_HEADER_NAME`	`session_id_header_name`	`X-Coder-Agent-Firewall-Session-Id`	Configurable session ID header
`--sequence-number-header-name`	`BOUNDARY_SEQUENCE_NUMBER_HEADER_NAME`	`sequence_number_header_name`	`X-Coder-Agent-Firewall-Sequence-Number`	Configurable sequence number header

Config validation ensures that when correlation is enabled at least one inject target is present (either explicit or auto-derived from CODER_AGENT_URL), 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.

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

ssncferreira · 2026-05-06T09:27:49Z

+    --session-id-inject-target "domain=mydeployment.coder.com path=/api/v2/aibridge/*" \
+    --allow "domain=mydeployment.coder.com" -- python train.py


Would it make sense to set automatically --session-id-inject-target with whatever domain is set via --allow?

ssncferreira · 2026-05-06T09:37:33Z

+				Flag:        "", // No CLI flag, YAML only.
+				Description: "Inject targets from config file (YAML only).",
+				Value:       &cliConfig.InjectSessionIDTargets,
+				YAML:        "session_id_inject_targets",


Couldn't this be merged with the CLI session-id-inject-target? Is this a common pattern in coder to have separate CLI vs YAML options?

ssncferreira · 2026-05-06T09:45:09Z

 	userInfo := GetUserInfo()

+	// Build session correlation config from CLI and YAML sources.
+	sc, err := buildSessionCorrelation(cfg, os.Environ())


nit: os.Environ() is hardcoded here, making NewAppConfigFromCliConfig untestable for the CODER_AGENT_URL fallback path 🤔 Maybe we can pass environ []string as a parameter and use os.Environ() from the caller?

ssncferreira · 2026-05-06T09:45:53Z

+	// Build session correlation config from CLI and YAML sources.
+	sc, err := buildSessionCorrelation(cfg, os.Environ())
+	if err != nil {
+		return AppConfig{}, fmt.Errorf("session correlation config: %w", err)


nit: This should hint at the fix, e.g. "...set --session-id-inject-target or ensure CODER_AGENT_URL is set".

ssncferreira · 2026-05-06T09:50:20Z

+			)
+		}
+		switch key {
+		case "domain":


There is an edge case here, imagine --session-id-inject-target "domain=staging.coder.com domain=prod.coder.com", domain will be overwritten. Probably worth checking for duplicates and adding a test case for this

ssncferreira · 2026-05-06T09:55:43Z

+	}
+
+	return &InjectTarget{
+		Domain: u.Hostname(),


IIUC inject target basically defines which outbound HTTP requests should receive the session correlation headers, but we are stripping the port here. What happens if coder runs on a non-standard port?

ssncferreira · 2026-05-06T10:24:14Z

+	}
+
+	// Apply defaults for header names.
+	sessionIDHeader := cfg.SessionIDHeaderName.Value()


Do we want to make the headers configurable? This means a user could set existing headers for the correlation, like the "Authorization" header, for instance. Also, since this is for correlation with Coder, I assume we would also need to set this on Coder side. So it makes sense to have an agreement on both parts for the same header value, right?

ssncferreira · 2026-05-06T10:25:54Z

+	}
+}
+
+func TestBuildSessionCorrelation_AgentURLFallback(t *testing.T) {


I think we are missing a test for merging CLI and YAML configs.

SasSwart mentioned this pull request Apr 30, 2026

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

Open

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 added 2 commits May 5, 2026 09:09

depend on v2.9 of the agent proto api

c9d8398

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(config): session correlation header injection configuration#197

feat(config): session correlation header injection configuration#197
SasSwart wants to merge 6 commits intomainfrom
sasswart/feat-config-session-correlation-header-injection

SasSwart commented Apr 30, 2026 •

edited

Loading

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

ssncferreira May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		--session-id-inject-target "domain=mydeployment.coder.com path=/api/v2/aibridge/*" \
		--allow "domain=mydeployment.coder.com" -- python train.py

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SasSwart commented Apr 30, 2026 •

edited

Loading