feat(llm-gateway): forward priority

[along-2017]

TL;DR

The gateway now forwards the caller priority that NVCF API resolves during invocation auth to Stargate, as the X-Priority header on all three LLM paths (chat/completions, responses, embeddings/generic proxy). The header is gateway-owned: client-supplied values are stripped on the proxied paths, an explicit 0 (highest priority) is forwarded, and an unset priority omits the header so Stargate applies its own default.

Additional Details

• Priority arrives on the auth response as proto3 optional uint32 and stays nullable end to end, so "no priority configured" is never conflated with priority 0.
• Emission mirrors the existing trusted optional headers (x-routing-method, x-cache-affinity-key): set only when resolved, never defaulted.
• Rejecting client-supplied X-Priority with an explicit 400 will be tracked in a separate PR; the strip here makes forwarding safe regardless of merge order.

For the Reviewer

• Proxy in provider/stargate.go is the subtle site: it clones inbound client headers, so X-Priority is deleted right after the clone and set only from the resolved value.
• The .pb.go files are regenerated from the proto change; review llm_gateway.proto instead.

For QA

• go build ./... and go test ./... are green in the gateway module. New tests cover resolved, explicit-zero, unset, and client-supplied-header cases on every path, at the middleware, client-mapping, and header-emission layers; the two highest-risk regressions (unset mapped to 0, proxy emitting 0 unconditionally) were verified by mutation.

Issues

Closes #186.

Checklist

• I am familiar with the Contributing Guidelines.
• I have signed off my commits for Developer Certificate of Origin (DCO) compliance.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

The gateway maps optional priority from NVCF authorization into RequestContext and forwards it as a gateway-controlled X-Priority header to response proxy and Stargate requests. Tests cover resolved, zero-valued, absent, and client-supplied priority cases.

Changes

Resolved priority forwarding

Layer / File(s)	Summary
Priority contract and authorization propagation src/invocation-plane-services/llm-api-gateway/nvcf/..., src/invocation-plane-services/llm-api-gateway/requestctx/requestctx.go, src/invocation-plane-services/llm-api-gateway/api/auth_middleware...	Optional priority is mapped from the proto response, copied into RequestContext, and tested for present and absent values.
Responses proxy header ownership src/invocation-plane-services/llm-api-gateway/api/responses_handler...	The responses proxy removes client-provided X-Priority and emits only the resolved context priority.
Stargate priority forwarding src/invocation-plane-services/llm-api-gateway/provider/stargate...	Stargate forwards resolved priority, preserves explicit zero, and strips or omits client-supplied priority when unset.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant LLM API Gateway
  participant NVCF Authorization
  participant Stargate
  Client->>LLM API Gateway: Invocation request
  LLM API Gateway->>NVCF Authorization: AuthorizeInvocation
  NVCF Authorization-->>LLM API Gateway: Optional resolved Priority
  LLM API Gateway->>LLM API Gateway: Store Priority in RequestContext
  LLM API Gateway->>Stargate: Proxy with controlled X-Priority
  Stargate-->>LLM API Gateway: Upstream response
  LLM API Gateway-->>Client: Proxied response

Loading

Suggested reviewers: max-nv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Linked Issues check	✅ Passed	The PR forwards resolved priority as X-Priority, omits it when unset, and adds tests covering both behaviors as required by #186.
Out of Scope Changes check	✅ Passed	The changes stay focused on propagating and stripping priority headers, with no clear unrelated modifications.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: forwarding priority through the LLM gateway.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/llm-gateway-forward-x-priority

---

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

[github-actions]

🛡️ CodeQL Analysis

🚨 Found 2 issue(s)

Severity Breakdown:

• 🔴 Errors: 0
• 🟡 Warnings: 0
• 🔵 Notes: 0

📋 Top Issues

🔗 View full details in Security tab

_{🕐 Last updated: 2026-07-20 23:06:59 UTC | Commit: 6dddab2}

[kristinapathak]

Please provide a github issue instead of an internal JIRA.