Skip to content

feat: configure AI Gateway actor identity headers - #29929

Merged
johnstcn merged 20 commits into
mainfrom
feat/actor-header-options
Sep 29, 2026
Merged

johnstcn merged 20 commits into
mainfrom
feat/actor-header-options

Conversation

@johnstcn

@johnstcn johnstcn commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Configure AI Gateway actor ID and username headers independently through --ai-gateway-actor-header-id and --ai-gateway-actor-header-meta-username, with matching environment variables and YAML settings. Each defaults to its standard header name; an empty string disables that attribute. The existing send_actor_headers gate remains off by default.

Validate header names, case-insensitive collisions, and protected destinations for embedded and standalone gateways. Strip standard and configured identity destinations before injecting authenticated values. Includes configuration precedence tests, captured upstream request coverage, and generated help/API documentation.

First PR in the replacement stack, targeting main. #29930 follows this PR and adds email as an explicit opt-in. This PR does not add email support. Replaces the configurability work from #29812 after reversing the stack. #30037 adds a standalone behavioural change to strip actor headers supplied by the client.

Refs https://linear.app/codercom/issue/AIGOV-601

Implementation decisions and verification
  • Use native scalar Serpent options rather than a map, list, custom parser, or - sentinel. Precedence is per attribute: flag, environment, YAML, default. Explicit empty values disable forwarding for that attribute.
  • Keep defaults at deployment configuration loading; runtime header construction forwards only configured supported attributes.
  • Build configurability before email so each PR can ship independently without introducing automatic email forwarding.
  • Extend existing tests for defaults, empty overrides, precedence, reserved destinations, spoofing, and real Anthropic/OpenAI upstream requests.
  • Verified the SDK suite, go test ./aibridge/..., standalone YAML configuration tests, upstream actor-header integration tests, and full make pre-commit generation, formatting, lint, and build checks.

Generated with Coder Agents on behalf of @johnstcn.

@github-actions

github-actions Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

@linear-code

linear-code Bot commented Sep 25, 2026

Copy link
Copy Markdown

AIGOV-601

@johnstcn
johnstcn added this pull request to stack #29932 September 25, 2026 15:51
Comment thread aibridge/intercept/actor_headers.go Resolved
Comment thread aibridge/intercept/actor_headers.go Resolved
@johnstcn
johnstcn marked this pull request as ready for review September 25, 2026 16:36
@johnstcn
johnstcn force-pushed the feat/actor-header-options branch from 62200b4 to c012c90 Compare September 25, 2026 16:38
@johnstcn
johnstcn requested review from pawbana and removed request for dannykopping September 25, 2026 16:44
@coderagents

coderagents Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Documentation Check

Updates Needed

  • docs/ai-coder/ai-gateway/reference.md (open) - This was addressed: the new "Header name restrictions" section in this PR documents the valid-name rule, case-insensitive uniqueness, the full reserved-name list (verified against ValidateActorHeaderNames in codersdk/deployment.go), the X-AI-Bridge-Actor prefix reservation with the standard-name exception, and that an invalid name prevents startup. No further documentation changes are needed; the option rename to --ai-gateway-actor-header-username and the Copilot provider exclusion are both consistent with the updated docs.

Automated review via Coder Agents

@johnstcn
johnstcn force-pushed the feat/actor-header-options branch from c012c90 to 52abf02 Compare September 28, 2026 10:19
@johnstcn
johnstcn requested a review from SasSwart September 28, 2026 10:30

@ssncferreira ssncferreira left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall LGTM, but I have some comments/suggestions

Comment thread aibridge/headers/headers.go Resolved
Comment thread aibridge/headers/headers.go Outdated
for k, v := range actor.Metadata {
headers[ActorMetadataHeader(k)] = fmt.Sprintf("%v", v)
headers := make(map[string]string, len(names))
if name := names["id"]; name != "" {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: should we have constant values for these keys id, username?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In fact, each attribute needs to be hardcoded here 🤔 so every new field grows this function. Maybe we could loop over the configured names instead and look up each value (ID from actor.ID, the rest from actor.Metadata)?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to be careful about casing (username vs Username). Let's stick to known attributes only.

Comment thread aibridge/headers/headers.go Resolved
Comment thread aibridge/intercept/config.go Resolved
Comment thread codersdk/deployment.go
Group: &deploymentGroupAIGateway,
YAML: "api_dump_dir",
}
aiGatewayActorHeaderID := serpent.Option{

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it also a requirement to have different header names? This could get tricky with reserved header names 😕 This means that for every new actor header that we introduce we will need to add a new configuration value 😕
If it is really needed, maybe a map sort of option would be better?

@johnstcn johnstcn Sep 28, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I initially decided to use a map[string]string but the upfront complexity did not seem worth it.

EDIT: To clarify, the map decoding behaviour of github.com/coder/serpent merges an entry that's omitted with the default. My original idea was to add special handling of - to mean "do not send", but that's more complex than just having separate config values.

Comment thread codersdk/deployment.go Resolved
Comment thread aibridge/provider/copilot.go Resolved
Comment thread codersdk/deployment.go Resolved
Comment thread aibridge/headers/headers.go Resolved
headers[name] = actor.ID
}
name := names["username"]
if name == "" {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if only "id" and "username" keys are checked maybe names param should be a struct not a map?
If I understand correctly names map just defines header name value for forwarding actor.ID and actor.Metadata["Username"] so struct with 2 strings should work. It would make code simpler to understand.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth a follow-up!

Comment thread aibridge/headers/headers.go Outdated

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: looks like this could be const

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will refactor in a follow-up.

Comment thread aibridge/headers/headers.go Resolved
Comment thread codersdk/deployment.go Resolved
Comment thread codersdk/deployment.go
continue
}
switch canonical {
case "Authorization", "X-Api-Key", "Proxy-Authorization", "Proxy-Authenticate",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could be defined somewhere, eg, appending all elements from lists from aibridge/headers/headers.go
Would be hard to keep in sync otherwise.

@johnstcn johnstcn Sep 29, 2026 •

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Worth a follow-up (EDIT: AIGOV-689)

Comment thread codersdk/deployment.go Resolved
Comment thread codersdk/deployment_test.go Resolved
"(CODER_AI_GATEWAY_KEY_FILE). A user login or session token is " +
"not required.",
Handler: func(inv *serpent.Invocation) error {
if err := vals.AI.BridgeConfig.ValidateActorHeaderNames(); err != nil {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice 👍

@johnstcn
johnstcn merged commit 05d1fa8 into main Sep 29, 2026
52 of 54 checks passed
@johnstcn
johnstcn deleted the feat/actor-header-options branch September 29, 2026 17:23
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 29, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants