[Refactoring] Decompose `finalizeHttpTracking` in `containers/api-proxy/token-tracker-http.js`

[github-actions]

Refactoring Opportunity

Summary

• File: containers/api-proxy/token-tracker-http.js
• Current size: 361 lines
• Function: finalizeHttpTracking — 148 lines (lines 175–322)
• Responsibilities identified: 7 distinct concerns crammed into one function

Evidence

finalizeHttpTracking (148 lines, lines 175–322) handles the following concerns in a single monolithic body:

1. Non-2xx early exit — filters and logs non-successful responses
2. SSE streaming parsing — processes any remaining partial line via parseSseDataLines, extracts model/usage from each SSE event, updates state.observedCacheReadTokens and state.streamingUsage
3. Non-streaming JSON extraction — concatenates buffered chunks and calls extractUsageFromJson
4. Usage normalization — calls normalizeUsage, checks cache-read rollup mismatches via warnCacheReadRollupMismatch
5. External callback invocation — calls opts.onUsage for quota enforcement (budget result)
6. Metrics update — calls incrementTokenMetrics
7. Log record building + persistence — assembles a JSONL record via buildTokenUsageRecord, merges budget fields, appends billing info, calls writeTokenUsage and logRequest

The prior refactoring (#4934, completed) extracted finalizeHttpTracking from a 238-line trackTokenUsage. The complexity migrated into the extracted function rather than being decomposed further, leaving a 148-line function that mixes streaming/non-streaming parse paths with quota callbacks, metrics, and persistence.

containers/api-proxy/token-tracker-http.js
  ├─ finalizeHttpTracking (148 lines, lines 175–322)
  │    ├─ non-2xx guard (lines 182–194)
  │    ├─ streaming SSE parse + model/usage accumulation (lines 202–232)
  │    ├─ non-streaming JSON extract (lines 233–242)
  │    ├─ normalization + cache-read rollup check (lines 249–256)
  │    ├─ onUsage quota callback (lines 257–265)
  │    ├─ metrics increment (line 268)
  │    └─ record build + write (lines 271–322)

Proposed Split

Extract helper functions so finalizeHttpTracking becomes an orchestrator (~50 lines):

• extractUsageFromTrackedState(state) — Encapsulates the streaming-vs-non-streaming branching. Returns { usage, model }. Reduces the streaming SSE path duplication and makes the two code paths easy to test independently.
• buildAndWriteTokenRecord(normalized, { requestId, provider, model, ... }) — Bundles record assembly (buildTokenUsageRecord), budget-field merging (mergeBudgetFields), billing/initiator decorators, writeTokenUsage, and logRequest. This is pure persistence/reporting with no quota logic.

After extraction, finalizeHttpTracking would call these two helpers plus the quota callback, keeping the orchestration intent readable.

Affected Callers

grep -rn "finalizeHttpTracking\|token-tracker-http" containers/ 2>/dev/null

• containers/api-proxy/token-tracker.js — imports trackTokenUsage
• containers/api-proxy/token-tracker-http.unit.test.js — imports createChunkHandler and finalizeHttpTracking directly

The exported surface (module.exports) does not need to change.

Effort Estimate

Low — all changes are within a single file and the extraction points are clean seams already separated by comments.

Benefits

• Each extracted helper is independently testable (the streaming parse path in particular)
• finalizeHttpTracking becomes a clear orchestration function, easier to audit for quota logic
• Cache-read accounting and metrics updates are easier to find and reason about

---

Detected by Refactoring Scanner workflow. Run date: 2026-06-15

Generated by Refactoring Opportunity Scanner · ◷

• expires on Aug 14, 2026, 4:42 PM UTC