feat(frontend): declare request priority via X-Priority header

[dgarros]

Why

When an Infrahub instance runs heavy background work (generators, artifacts, diffs, syncs, computed attributes) while a human uses the UI, both compete for the same finite API worker pool and Neo4j connections. The server-side admission layer (IFC-2886) can shed load by priority — but only if callers declare one via X-Priority. Today the frontend declares nothing, so its requests arrive as normal, indistinguishable from background traffic, and the interactive user gets no protection from the overload the admission layer was built to handle.

Goal: make the frontend a first-class emitter of X-Priority so interactive requests win contention and background frontend work sheds first — with no per-call-site configuration.

Non-goals: enforcing that a high claim is legitimate (deferred with IFC-2886); building a prefetch/preload system; a large enumeration of existing loads to demote (the v1 low set is intentionally empty — this ships the mechanism + convention).

Implements IFC-2890. Related JPD idea INFP-636.

Stacked on #9879 (IFC-2886, dga/feat-rate-limiting-api-zb38x → develop). This PR targets that branch so the diff is IFC-2890-only; it will auto-retarget to develop once #9879 merges.

What changed

Behavioral changes (what users/operators observe):

• Interactive frontend requests now leave as X-Priority: high; under background overload the admission layer serves them first and sheds background-tagged frontend work first.
• A developer can mark a query background with a single low opt-in at its definition; every fetch for that query inherits it — no other call-site changes.
• Watched live-status polls (task list/status, proposed-change details/events, branch action state) stay high even though they poll, so watched data stays fresh under load.
• Cross-origin deployments (dev / split-host) work: the API's CORS preflight now permits x-priority, and CORS preflights are no longer shed by the admission layer under load.

Implementation notes:

• New typed contract frontend/app/src/shared/api/priority/ — RequestPriority = 'high' | 'low', DEFAULT_PRIORITY, PRIORITY_HEADER, and a resolvePriority() normalizer that makes emitting normal/unheadered structurally impossible.
• Header injected at all four transport entry points: Apollo link (priorityLink), REST openapi-fetch middleware, raw fetchUrl (origin-guarded so it never leaks to external hosts), and the GraphiQL sandbox fetcher.
• The header survives 401-refresh replay (both transports) and file uploads (uploads ride the shared Apollo upload link).
• low opt-in convention per transport: Apollo context: { priority: 'low' }; REST params.header; fetchUrl(url, payload, { priority: 'low' }).

What stayed the same: no GraphQL schema change, no new endpoint, no new dependency, no persistence. The ~89 interactive call sites are untouched — they inherit high.

How to review

• Start with frontend/app/src/shared/api/priority/index.ts (the contract), then the four injection points: graphql/graphqlClientApollo.tsx, rest/client.ts, rest/fetch.ts, libs/graphiql/use-graphiql-fetcher.ts.
• Extra scrutiny: backend/infrahub/api/admission/middleware.py — a narrow _is_cors_preflight bypass so CORS OPTIONS preflights (which carry no X-Priority) are not shed under load. This is a security-adjacent change to the IFC-2886 admission path, added because FR-006's "cross-origin request succeeds" would otherwise fail under exactly the overload this feature targets. It only exempts OPTIONS requests advertising access-control-request-method; test_cors_priority.py proves real requests are still shed.
• Planning artifacts under dev/specs/ifc-2890-frontend-request-priority/ (spec, plan, critique, contracts, implement report) give the full rationale.

How to test

# Frontend transport unit tests (browser-mode in CI; node-mode locally)
cd frontend/app && pnpm test src/shared/api/priority src/shared/api/rest src/shared/api/graphql
cd frontend/app && pnpm test src/entities/tasks src/entities/proposed-changes src/entities/branches

# Backend CORS preflight + config default
uv run pytest backend/tests/unit/config/test_config.py -k cors backend/tests/component/api/test_cors_priority.py

# E2E (interactive high vs background low, none normal)
cd frontend/app && pnpm test:e2e -g "X-Priority|priority"

Expected: every transport emits high by default and low when opted in; the header survives replay/upload; external-host requests carry no header; the CORS preflight allow-lists x-priority. Locally verified: 21 frontend unit + 3 backend tests pass. E2E runs in CI (needs a running stack + browser).

Impact & rollout

• Backward compatibility: additive. The backend already parses X-Priority; unheadered/normal remains valid for non-frontend callers. No migration.
• Performance: O(1) header injection per request; no new queries.
• Config/env changes: x-priority added to the CORS allowed-headers default (INFRAHUB_API_CORS_ALLOW_HEADERS). Security-adjacent per AGENTS.md "Ask First" — flagged for maintainer review.
• Deployment notes: safe to deploy. Full user-facing benefit (interactive requests holding latency / ~0 shed under saturating load) is realized jointly with the IFC-2886 admission layer (feat(api): priority-aware server-side API backpressure #9879).

Checklist

• Tests added/updated
• Changelog entry added (changelog/+ifc-2890.added.md)
• External docs updated (n/a — no user-facing docs surface; header is internal)
• Internal .md docs updated (dev/knowledge/frontend/request-priority.md)
• I have reviewed AI generated content

---

Summary by cubic

Frontend now sends X-Priority on all API requests (high by default, low opt-in) so the admission layer favors interactive traffic and sheds background under load. Implements IFC-2890 and aligns with IFC-2886.

• New Features

  • Injected at all entry points: Apollo link (priorityLink), REST openapi-fetch middleware, raw fetchUrl (Infrahub API origin only), and GraphiQL fetcher.
  • Default is high; opt-in low per call: Apollo context: { priority: 'low' }, REST headers: { 'X-Priority': 'low' }, fetchUrl(..., { headers: { 'X-Priority': 'low' } }).
  • Header survives 401 refresh/replay and file uploads.

• Bug Fixes

  • Backend CORS allows x-priority, and CORS OPTIONS preflights bypass admission to keep cross-origin requests working under load.

^{Written for commit 5be38ed. Summary will update on new commits.}

[dgarros]

🔎 Maintainer review requested — security-adjacent change.

Beyond the frontend X-Priority emitter + the one-line CORS allow-header addition, this PR includes a 15-line behavior change to the IFC-2886 admission middleware (backend/infrahub/api/admission/middleware.py): CORS OPTIONS preflights (which carry no X-Priority) now bypass the load-shedding gate.

Why it's here: a preflight would otherwise be classified normal and could be shed under saturation — stripping the CORS response and breaking every cross-origin request in exactly the overload scenario this feature targets (FR-006). The bypass is narrow (only OPTIONS + access-control-request-method) and test_cors_priority.py::test_non_preflight_request_is_still_shed proves real requests are still shed.

Why flagged: the IFC-2890 PRD's declared backend surface was only "add x-priority to CORS allowed-headers." An independent ship-gate reviewer dissented (1 of 3) that this exceeds that surface. Two of three passed it as a necessary correctness enabler. Please confirm you're comfortable with this touching the admission/shedding path, or advise splitting it into #9879 (where the middleware originates).

[cubic-dev-ai]

3 issues found across 33 files

Confidence score: 4/5

• In dev/specs/ifc-2890-frontend-request-priority/contracts/request-priority.contract.md, the query-class guarantee conflicts with the raw fetch transport exception, so readers could implement or validate request-priority behavior against contradictory rules and ship inconsistent client behavior — clarify the guarantee’s scope (or the exception) before merging.
• dev/specs/ifc-2890-frontend-request-priority/data-model.md (and aligned spec docs) describe per-request REST opt-in, but the noted implementation behavior differs, which can mislead follow-on work and cause avoidable regressions when engineers use the documented API shape — reconcile the docs to the actual rest client behavior (or adjust code) before merge.
• In dev/specs/ifc-2890-frontend-request-priority/plan.md, the FastAPI version reference is stale versus pinned dependencies; this is low risk but can reduce trust in the plan as a source of truth — update the version string to match the project baseline.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="dev/specs/ifc-2890-frontend-request-priority/contracts/request-priority.contract.md">

<violation number="1" location="dev/specs/ifc-2890-frontend-request-priority/contracts/request-priority.contract.md:87">
P2: The query-class guarantee (line 82-84) states that *any frontend-origin request on any transport* carries high or low — never absent. But the raw fetch transport (line 66) explicitly says requests to non-Infrahub-API origins carry NO X-Priority header. These guarantees are contradictory: if the universal claim is true, the external-host exception is invalid; if the exception stands, the universal claim is false. The contract should either scope the universal guarantee to Infrahub-API-bound requests, or remove the exception from the raw fetch transport.</violation>
</file>

<file name="dev/specs/ifc-2890-frontend-request-priority/plan.md">

<violation number="1" location="dev/specs/ifc-2890-frontend-request-priority/plan.md:17">
P3: FastAPI version reference (0.131) is inconsistent with the project's pinned dependency (fastapi==0.136.3). Update the plan's Technical Context to match the actual project version so the document remains a reliable reference for future readers.</violation>
</file>

<file name="dev/specs/ifc-2890-frontend-request-priority/data-model.md">

<violation number="1" location="dev/specs/ifc-2890-frontend-request-priority/data-model.md:40">
P3: The data-model.md, research.md, plan.md, and request-priority.contract.md describe a REST opt-in approach (`{ priority: 'low' }` per-request option) that doesn't match the implementation. The actual code in `rest/client.ts` uses `params: { header: { 'X-Priority': 'low' } }` because openapi-fetch's `options` is read-only and can't carry custom fields. Since these planning documents will persist (they're in the repo, under `dev/specs/`), update the affected passages in data-model.md and request-priority.contract.md to describe the actual mechanism so future readers don't try a non-existent API. The knowledge doc (`dev/knowledge/frontend/request-priority.md`) already describes it correctly, so the fix can mirror its wording.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The query-class guarantee (line 82-84) states that any frontend-origin request on any transport carries high or low — never absent. But the raw fetch transport (line 66) explicitly says requests to non-Infrahub-API origins carry NO X-Priority header. These guarantees are contradictory: if the universal claim is true, the external-host exception is invalid; if the exception stands, the universal claim is false. The contract should either scope the universal guarantee to Infrahub-API-bound requests, or remove the exception from the raw fetch transport.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/specs/ifc-2890-frontend-request-priority/contracts/request-priority.contract.md, line 87:

<comment>The query-class guarantee (line 82-84) states that *any frontend-origin request on any transport* carries high or low — never absent. But the raw fetch transport (line 66) explicitly says requests to non-Infrahub-API origins carry NO X-Priority header. These guarantees are contradictory: if the universal claim is true, the external-host exception is invalid; if the exception stands, the universal claim is false. The contract should either scope the universal guarantee to Infrahub-API-bound requests, or remove the exception from the raw fetch transport.</comment>

<file context>
@@ -0,0 +1,95 @@
+THEN it carries `X-Priority: high`
+AND none of these queries is declared `low`
+
+GIVEN the frontend's full request mix
+WHEN any frontend-origin request is observed on any transport
+THEN it carries either `high` or `low` — never `normal`, never absent
</file context>

[cubic-dev-ai]

P3: FastAPI version reference (0.131) is inconsistent with the project's pinned dependency (fastapi==0.136.3). Update the plan's Technical Context to match the actual project version so the document remains a reliable reference for future readers.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/specs/ifc-2890-frontend-request-priority/plan.md, line 17:

<comment>FastAPI version reference (0.131) is inconsistent with the project's pinned dependency (fastapi==0.136.3). Update the plan's Technical Context to match the actual project version so the document remains a reliable reference for future readers.</comment>

<file context>
@@ -0,0 +1,127 @@
+
+**Language/Version**: TypeScript 5.9 (frontend), Python 3.14 (backend CORS change only)
+
+**Primary Dependencies**: React 19.2 + Apollo Client 3.13 (`@apollo/client`), `apollo-upload-client` 18 (`createUploadLink`), `openapi-fetch` 0.17 (REST), TanStack Query 5 (polling/refetch), Vitest 4.1 (unit); backend: FastAPI 0.131 `CORSMiddleware`, Pydantic settings
+
+**Storage**: N/A (no persistence; a request header only)
</file context>

[cubic-dev-ai]

P3: The data-model.md, research.md, plan.md, and request-priority.contract.md describe a REST opt-in approach ({ priority: 'low' } per-request option) that doesn't match the implementation. The actual code in rest/client.ts uses params: { header: { 'X-Priority': 'low' } } because openapi-fetch's options is read-only and can't carry custom fields. Since these planning documents will persist (they're in the repo, under dev/specs/), update the affected passages in data-model.md and request-priority.contract.md to describe the actual mechanism so future readers don't try a non-existent API. The knowledge doc (dev/knowledge/frontend/request-priority.md) already describes it correctly, so the fix can mirror its wording.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At dev/specs/ifc-2890-frontend-request-priority/data-model.md, line 40:

<comment>The data-model.md, research.md, plan.md, and request-priority.contract.md describe a REST opt-in approach (`{ priority: 'low' }` per-request option) that doesn't match the implementation. The actual code in `rest/client.ts` uses `params: { header: { 'X-Priority': 'low' } }` because openapi-fetch's `options` is read-only and can't carry custom fields. Since these planning documents will persist (they're in the repo, under `dev/specs/`), update the affected passages in data-model.md and request-priority.contract.md to describe the actual mechanism so future readers don't try a non-existent API. The knowledge doc (`dev/knowledge/frontend/request-priority.md`) already describes it correctly, so the fix can mirror its wording.</comment>

<file context>
@@ -0,0 +1,59 @@
+| Transport | Default source | `low` opt-in surface | Consumed by |
+|-----------|----------------|----------------------|-------------|
+| GraphQL (Apollo) | priority link default | Apollo operation `context: { priority: 'low' }` | new `setContext` priority link in `graphqlClientApollo.tsx` |
+| REST (`openapi-fetch`) | middleware default | per-request option `{ priority: 'low' }` | `authMiddleware.onRequest` in `rest/client.ts` |
+| Raw fetch (`fetchUrl`) | argument default | optional arg `{ priority: 'low' }` | `fetchUrl` in `rest/fetch.ts` |
+| GraphiQL fetcher | hard-coded `high` | none (sandbox tool; always `high`) | `use-graphiql-fetcher.ts` |
</file context>

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing dga/feat-priority-frontend-nl5ss (5be38ed) with dga/feat-rate-limiting-api-zb38x (896fab6)}

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 4 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 14 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="frontend/app/src/shared/api/rest/fetch.ts">

<violation number="1" location="frontend/app/src/shared/api/rest/fetch.ts:35">
P2: Raw REST callers can no longer mark background work low priority: this signature drops the third `options.priority` argument and the header is now always `high`. Preserve the priority option and resolve it before stamping the API-origin header.</violation>
</file>

<file name="frontend/app/src/shared/api/rest/fetch.test.ts">

<violation number="1" location="frontend/app/src/shared/api/rest/fetch.test.ts:43">
P2: Custom agent: **Flag AI Slop and Fabricated Changes**

The `priority: 'low'` opt-in for REST fetchUrl calls (a stated feature of this PR) lost its only unit-test regression coverage when the `'low'` assertion was removed from `fetch.test.ts`. Without it, a future change that breaks low-priority header injection for REST calls would not be caught at the unit level. Consider restoring a regression assertion for the low-priority path — either in this file or, if coverage was intentionally moved, confirm that another test module covers the same `{ priority: 'low' }` → `X-Priority: low` flow through the REST transport.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Raw REST callers can no longer mark background work low priority: this signature drops the third options.priority argument and the header is now always high. Preserve the priority option and resolve it before stamping the API-origin header.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At frontend/app/src/shared/api/rest/fetch.ts, line 35:

<comment>Raw REST callers can no longer mark background work low priority: this signature drops the third `options.priority` argument and the header is now always `high`. Preserve the priority option and resolve it before stamping the API-origin header.</comment>

<file context>
@@ -32,17 +32,10 @@ export class FetchError extends Error {
-  payload?: RequestInit,
-  options?: { priority?: RequestPriority }
-) => {
+export const fetchUrl = async (url: string, payload?: RequestInit) => {
   const localToken = getAccessToken();
 
</file context>

[cubic-dev-ai]

P2: Custom agent: Flag AI Slop and Fabricated Changes

The priority: 'low' opt-in for REST fetchUrl calls (a stated feature of this PR) lost its only unit-test regression coverage when the 'low' assertion was removed from fetch.test.ts. Without it, a future change that breaks low-priority header injection for REST calls would not be caught at the unit level. Consider restoring a regression assertion for the low-priority path — either in this file or, if coverage was intentionally moved, confirm that another test module covers the same { priority: 'low' } → X-Priority: low flow through the REST transport.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At frontend/app/src/shared/api/rest/fetch.test.ts, line 43:

<comment>The `priority: 'low'` opt-in for REST fetchUrl calls (a stated feature of this PR) lost its only unit-test regression coverage when the `'low'` assertion was removed from `fetch.test.ts`. Without it, a future change that breaks low-priority header injection for REST calls would not be caught at the unit level. Consider restoring a regression assertion for the low-priority path — either in this file or, if coverage was intentionally moved, confirm that another test module covers the same `{ priority: 'low' }` → `X-Priority: low` flow through the REST transport.</comment>

<file context>
@@ -41,16 +40,7 @@ describe("fetchUrl — outbound X-Priority header", () => {
-  });
-
-  it("does NOT stamp X-Priority on a request to an external host (FR-007)", async () => {
+  it("does NOT stamp X-Priority on a request to an external host", async () => {
     await fetchUrl("https://example.com/whatever");
 
</file context>