xithead 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (661) hide show
  1. package/.actrc +14 -0
  2. package/.actrc.local.example +15 -0
  3. package/.changelog.md +2 -0
  4. package/.claude/agents/academic-anthropologist.md +125 -0
  5. package/.claude/agents/academic-geographer.md +127 -0
  6. package/.claude/agents/academic-historian.md +123 -0
  7. package/.claude/agents/academic-narratologist.md +118 -0
  8. package/.claude/agents/academic-psychologist.md +118 -0
  9. package/.claude/agents/academic-statistician.md +144 -0
  10. package/.claude/agents/accounts-payable-agent.md +205 -0
  11. package/.claude/agents/agentic-identity-trust.md +394 -0
  12. package/.claude/agents/agents-orchestrator.md +367 -0
  13. package/.claude/agents/automation-governance-architect.md +216 -0
  14. package/.claude/agents/blender-addon-engineer.md +243 -0
  15. package/.claude/agents/business-strategist.md +488 -0
  16. package/.claude/agents/change-management-consultant.md +497 -0
  17. package/.claude/agents/chief-financial-officer.md +388 -0
  18. package/.claude/agents/corporate-training-designer.md +192 -0
  19. package/.claude/agents/customer-service.md +398 -0
  20. package/.claude/agents/customer-success-manager.md +460 -0
  21. package/.claude/agents/data-consolidation-agent.md +60 -0
  22. package/.claude/agents/data-privacy-officer.md +412 -0
  23. package/.claude/agents/design-brand-guardian.md +322 -0
  24. package/.claude/agents/design-image-prompt-engineer.md +236 -0
  25. package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
  26. package/.claude/agents/design-persona-walkthrough.md +272 -0
  27. package/.claude/agents/design-ui-designer.md +386 -0
  28. package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
  29. package/.claude/agents/design-ux-architect.md +482 -0
  30. package/.claude/agents/design-ux-researcher.md +329 -0
  31. package/.claude/agents/design-visual-storyteller.md +149 -0
  32. package/.claude/agents/design-whimsy-injector.md +460 -0
  33. package/.claude/agents/economy-designer.md +156 -0
  34. package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
  35. package/.claude/agents/engineering-ai-engineer.md +146 -0
  36. package/.claude/agents/engineering-api-platform-engineer.md +181 -0
  37. package/.claude/agents/engineering-ats-validator-architect.md +383 -0
  38. package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
  39. package/.claude/agents/engineering-backend-architect.md +255 -0
  40. package/.claude/agents/engineering-china-network-engineer.md +252 -0
  41. package/.claude/agents/engineering-cms-developer.md +536 -0
  42. package/.claude/agents/engineering-code-reviewer.md +76 -0
  43. package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
  44. package/.claude/agents/engineering-data-engineer.md +349 -0
  45. package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
  46. package/.claude/agents/engineering-database-optimizer.md +188 -0
  47. package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
  48. package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
  49. package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
  50. package/.claude/agents/engineering-devops-automator.md +385 -0
  51. package/.claude/agents/engineering-drupal-performance.md +347 -0
  52. package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
  53. package/.claude/agents/engineering-electrical-engineer.md +575 -0
  54. package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
  55. package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
  56. package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
  57. package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
  58. package/.claude/agents/engineering-finops-engineer.md +164 -0
  59. package/.claude/agents/engineering-frontend-developer.md +257 -0
  60. package/.claude/agents/engineering-gaussdb-expert.md +334 -0
  61. package/.claude/agents/engineering-git-workflow-master.md +98 -0
  62. package/.claude/agents/engineering-i18n-engineer.md +214 -0
  63. package/.claude/agents/engineering-identity-access-engineer.md +217 -0
  64. package/.claude/agents/engineering-incident-response-commander.md +444 -0
  65. package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
  66. package/.claude/agents/engineering-it-service-manager.md +561 -0
  67. package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
  68. package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
  69. package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
  70. package/.claude/agents/engineering-mobile-app-builder.md +493 -0
  71. package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
  72. package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
  73. package/.claude/agents/engineering-network-engineer.md +245 -0
  74. package/.claude/agents/engineering-orgscript-engineer.md +113 -0
  75. package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
  76. package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
  77. package/.claude/agents/engineering-platform-engineer.md +270 -0
  78. package/.claude/agents/engineering-privacy-engineer.md +152 -0
  79. package/.claude/agents/engineering-prompt-engineer.md +209 -0
  80. package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
  81. package/.claude/agents/engineering-rapid-prototyper.md +466 -0
  82. package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
  83. package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
  84. package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
  85. package/.claude/agents/engineering-section-508-specialist.md +339 -0
  86. package/.claude/agents/engineering-senior-developer.md +176 -0
  87. package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
  88. package/.claude/agents/engineering-software-architect.md +112 -0
  89. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
  90. package/.claude/agents/engineering-sre.md +90 -0
  91. package/.claude/agents/engineering-technical-writer.md +393 -0
  92. package/.claude/agents/engineering-universal-document-compiler.md +370 -0
  93. package/.claude/agents/engineering-uswds-developer.md +340 -0
  94. package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
  95. package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
  96. package/.claude/agents/engineering-webassembly-engineer.md +153 -0
  97. package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
  98. package/.claude/agents/engineering-wordpress-performance.md +346 -0
  99. package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
  100. package/.claude/agents/esg-sustainability-officer.md +396 -0
  101. package/.claude/agents/finance-bookkeeper-controller.md +260 -0
  102. package/.claude/agents/finance-financial-analyst.md +234 -0
  103. package/.claude/agents/finance-fpa-analyst.md +263 -0
  104. package/.claude/agents/finance-investment-researcher.md +272 -0
  105. package/.claude/agents/finance-tax-strategist.md +239 -0
  106. package/.claude/agents/game-audio-engineer.md +264 -0
  107. package/.claude/agents/game-designer.md +167 -0
  108. package/.claude/agents/gis-3d-scene-developer.md +111 -0
  109. package/.claude/agents/gis-analyst.md +91 -0
  110. package/.claude/agents/gis-bim-specialist.md +108 -0
  111. package/.claude/agents/gis-cartography-designer.md +150 -0
  112. package/.claude/agents/gis-drone-reality-mapping.md +120 -0
  113. package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
  114. package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
  115. package/.claude/agents/gis-qa-engineer.md +133 -0
  116. package/.claude/agents/gis-solution-engineer.md +101 -0
  117. package/.claude/agents/gis-spatial-data-engineer.md +97 -0
  118. package/.claude/agents/gis-spatial-data-scientist.md +111 -0
  119. package/.claude/agents/gis-technical-consultant.md +86 -0
  120. package/.claude/agents/gis-web-gis-developer.md +108 -0
  121. package/.claude/agents/godot-gameplay-scripter.md +338 -0
  122. package/.claude/agents/godot-multiplayer-engineer.md +301 -0
  123. package/.claude/agents/godot-shader-developer.md +267 -0
  124. package/.claude/agents/government-digital-presales-consultant.md +363 -0
  125. package/.claude/agents/grant-writer.md +511 -0
  126. package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
  127. package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
  128. package/.claude/agents/healthcare-customer-service.md +389 -0
  129. package/.claude/agents/healthcare-innovation-strategist.md +433 -0
  130. package/.claude/agents/healthcare-marketing-compliance.md +395 -0
  131. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
  132. package/.claude/agents/hospitality-guest-services.md +603 -0
  133. package/.claude/agents/hr-onboarding.md +451 -0
  134. package/.claude/agents/identity-graph-operator.md +303 -0
  135. package/.claude/agents/language-translator.md +264 -0
  136. package/.claude/agents/legal-billing-time-tracking.md +569 -0
  137. package/.claude/agents/legal-client-intake.md +492 -0
  138. package/.claude/agents/legal-document-review.md +454 -0
  139. package/.claude/agents/level-designer.md +208 -0
  140. package/.claude/agents/loan-officer-assistant.md +555 -0
  141. package/.claude/agents/lsp-index-engineer.md +320 -0
  142. package/.claude/agents/ma-integration-manager.md +427 -0
  143. package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
  144. package/.claude/agents/marketing-aeo-foundations.md +264 -0
  145. package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
  146. package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
  147. package/.claude/agents/marketing-app-store-optimizer.md +321 -0
  148. package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
  149. package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
  150. package/.claude/agents/marketing-book-co-author.md +110 -0
  151. package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
  152. package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
  153. package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
  154. package/.claude/agents/marketing-content-creator.md +54 -0
  155. package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
  156. package/.claude/agents/marketing-developer-community-builder.md +285 -0
  157. package/.claude/agents/marketing-douyin-strategist.md +149 -0
  158. package/.claude/agents/marketing-email-strategist.md +249 -0
  159. package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
  160. package/.claude/agents/marketing-growth-hacker.md +54 -0
  161. package/.claude/agents/marketing-instagram-curator.md +113 -0
  162. package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
  163. package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
  164. package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
  165. package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
  166. package/.claude/agents/marketing-podcast-strategist.md +277 -0
  167. package/.claude/agents/marketing-pr-communications-manager.md +473 -0
  168. package/.claude/agents/marketing-private-domain-operator.md +308 -0
  169. package/.claude/agents/marketing-reddit-community-builder.md +123 -0
  170. package/.claude/agents/marketing-seo-specialist.md +370 -0
  171. package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
  172. package/.claude/agents/marketing-social-media-strategist.md +125 -0
  173. package/.claude/agents/marketing-tiktok-strategist.md +125 -0
  174. package/.claude/agents/marketing-twitter-engager.md +126 -0
  175. package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
  176. package/.claude/agents/marketing-wechat-official-account.md +145 -0
  177. package/.claude/agents/marketing-weibo-strategist.md +240 -0
  178. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
  179. package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
  180. package/.claude/agents/marketing-zhihu-strategist.md +162 -0
  181. package/.claude/agents/medical-billing-coding-specialist.md +491 -0
  182. package/.claude/agents/narrative-designer.md +243 -0
  183. package/.claude/agents/operations-manager.md +399 -0
  184. package/.claude/agents/organizational-psychologist.md +391 -0
  185. package/.claude/agents/paid-media-auditor.md +71 -0
  186. package/.claude/agents/paid-media-creative-strategist.md +71 -0
  187. package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
  188. package/.claude/agents/paid-media-ppc-strategist.md +71 -0
  189. package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
  190. package/.claude/agents/paid-media-search-query-analyst.md +71 -0
  191. package/.claude/agents/paid-media-tracking-specialist.md +71 -0
  192. package/.claude/agents/personal-growth-mentor.md +159 -0
  193. package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
  194. package/.claude/agents/product-dx-engineer.md +332 -0
  195. package/.claude/agents/product-feedback-synthesizer.md +119 -0
  196. package/.claude/agents/product-manager.md +469 -0
  197. package/.claude/agents/product-sprint-prioritizer.md +154 -0
  198. package/.claude/agents/product-trend-researcher.md +159 -0
  199. package/.claude/agents/project-management-experiment-tracker.md +198 -0
  200. package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
  201. package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
  202. package/.claude/agents/project-management-project-shepherd.md +194 -0
  203. package/.claude/agents/project-management-studio-operations.md +200 -0
  204. package/.claude/agents/project-management-studio-producer.md +203 -0
  205. package/.claude/agents/project-manager-senior.md +135 -0
  206. package/.claude/agents/real-estate-buyer-seller.md +596 -0
  207. package/.claude/agents/recruitment-specialist.md +515 -0
  208. package/.claude/agents/report-distribution-agent.md +65 -0
  209. package/.claude/agents/research-synthesist.md +136 -0
  210. package/.claude/agents/resume-tailor.md +230 -0
  211. package/.claude/agents/retail-customer-returns.md +566 -0
  212. package/.claude/agents/roblox-avatar-creator.md +297 -0
  213. package/.claude/agents/roblox-experience-designer.md +306 -0
  214. package/.claude/agents/roblox-systems-scripter.md +332 -0
  215. package/.claude/agents/sales-account-strategist.md +227 -0
  216. package/.claude/agents/sales-coach.md +271 -0
  217. package/.claude/agents/sales-data-extraction-agent.md +67 -0
  218. package/.claude/agents/sales-deal-strategist.md +180 -0
  219. package/.claude/agents/sales-discovery-coach.md +225 -0
  220. package/.claude/agents/sales-engineer.md +182 -0
  221. package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
  222. package/.claude/agents/sales-outbound-strategist.md +201 -0
  223. package/.claude/agents/sales-outreach.md +425 -0
  224. package/.claude/agents/sales-pipeline-analyst.md +267 -0
  225. package/.claude/agents/sales-proposal-strategist.md +217 -0
  226. package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
  227. package/.claude/agents/security-appsec-engineer.md +536 -0
  228. package/.claude/agents/security-architect.md +307 -0
  229. package/.claude/agents/security-blockchain-security-auditor.md +482 -0
  230. package/.claude/agents/security-cloud-security-architect.md +576 -0
  231. package/.claude/agents/security-compliance-auditor.md +158 -0
  232. package/.claude/agents/security-incident-responder.md +450 -0
  233. package/.claude/agents/security-penetration-tester.md +399 -0
  234. package/.claude/agents/security-secrets-credential-engineer.md +189 -0
  235. package/.claude/agents/security-senior-secops.md +760 -0
  236. package/.claude/agents/security-threat-detection-engineer.md +553 -0
  237. package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
  238. package/.claude/agents/specialized-chief-of-staff.md +279 -0
  239. package/.claude/agents/specialized-civil-engineer.md +356 -0
  240. package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
  241. package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
  242. package/.claude/agents/specialized-developer-advocate.md +317 -0
  243. package/.claude/agents/specialized-document-generator.md +55 -0
  244. package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
  245. package/.claude/agents/specialized-focus-music-architect.md +175 -0
  246. package/.claude/agents/specialized-french-consulting-market.md +194 -0
  247. package/.claude/agents/specialized-korean-business-navigator.md +216 -0
  248. package/.claude/agents/specialized-master-plan-architect.md +157 -0
  249. package/.claude/agents/specialized-mcp-builder.md +260 -0
  250. package/.claude/agents/specialized-model-qa.md +528 -0
  251. package/.claude/agents/specialized-pricing-analyst.md +243 -0
  252. package/.claude/agents/specialized-salesforce-architect.md +182 -0
  253. package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
  254. package/.claude/agents/specialized-workflow-architect.md +597 -0
  255. package/.claude/agents/study-abroad-advisor.md +282 -0
  256. package/.claude/agents/supply-chain-strategist.md +591 -0
  257. package/.claude/agents/support-analytics-reporter.md +387 -0
  258. package/.claude/agents/support-executive-summary-generator.md +212 -0
  259. package/.claude/agents/support-finance-tracker.md +480 -0
  260. package/.claude/agents/support-infrastructure-maintainer.md +628 -0
  261. package/.claude/agents/support-legal-compliance-checker.md +591 -0
  262. package/.claude/agents/support-support-responder.md +607 -0
  263. package/.claude/agents/technical-artist.md +233 -0
  264. package/.claude/agents/terminal-integration-specialist.md +70 -0
  265. package/.claude/agents/testing-accessibility-auditor.md +327 -0
  266. package/.claude/agents/testing-api-tester.md +334 -0
  267. package/.claude/agents/testing-evidence-collector.md +210 -0
  268. package/.claude/agents/testing-performance-benchmarker.md +283 -0
  269. package/.claude/agents/testing-reality-checker.md +249 -0
  270. package/.claude/agents/testing-test-automation-engineer.md +196 -0
  271. package/.claude/agents/testing-test-results-analyzer.md +330 -0
  272. package/.claude/agents/testing-tool-evaluator.md +416 -0
  273. package/.claude/agents/testing-workflow-optimizer.md +463 -0
  274. package/.claude/agents/unity-architect.md +271 -0
  275. package/.claude/agents/unity-editor-tool-developer.md +310 -0
  276. package/.claude/agents/unity-multiplayer-engineer.md +323 -0
  277. package/.claude/agents/unity-shader-graph-artist.md +269 -0
  278. package/.claude/agents/unreal-multiplayer-architect.md +364 -0
  279. package/.claude/agents/unreal-systems-engineer.md +322 -0
  280. package/.claude/agents/unreal-technical-artist.md +256 -0
  281. package/.claude/agents/unreal-world-builder.md +273 -0
  282. package/.claude/agents/visionos-spatial-engineer.md +54 -0
  283. package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
  284. package/.claude/agents/xr-immersive-developer.md +32 -0
  285. package/.claude/agents/xr-interface-architect.md +32 -0
  286. package/.claude/agents/zk-steward.md +211 -0
  287. package/.claude-plugin/marketplace.json +30 -0
  288. package/.commitlintrc.json +26 -0
  289. package/.devcontainer/Dockerfile +24 -0
  290. package/.devcontainer/devcontainer.json +70 -0
  291. package/.devcontainer/docker-compose.memory.yml +42 -0
  292. package/.devcontainer/memory-stack/devcontainer.json +84 -0
  293. package/.devcontainer/post-create.sh +83 -0
  294. package/.dockerignore +23 -0
  295. package/.env.act.example +15 -0
  296. package/.env.example +171 -0
  297. package/.eslintrc.json +16 -0
  298. package/.git-blame-ignore-revs +10 -0
  299. package/.gitattributes +2 -0
  300. package/.gitguardian.yaml +50 -0
  301. package/.githooks/pre-commit +6 -0
  302. package/.pre-commit-config.yaml +30 -0
  303. package/.release-please-config-xithead.json +22 -0
  304. package/.release-please-config.json +44 -0
  305. package/.release-please-manifest-xithead.json +3 -0
  306. package/.release-please-manifest.json +3 -0
  307. package/CODE_OF_CONDUCT.md +133 -0
  308. package/CONTRIBUTING.md +133 -0
  309. package/Cargo.lock +5557 -0
  310. package/Cargo.toml +121 -0
  311. package/Dockerfile +38 -0
  312. package/Dockerfile.proxy +48 -0
  313. package/ENTERPRISE.md +5 -0
  314. package/FEATURES_ADVANCED.md +311 -0
  315. package/Headroom-2.gif +0 -0
  316. package/HeadroomDemo-Fast.gif +0 -0
  317. package/MANIFEST.in +4 -0
  318. package/MODERNIZATION_GUIDE.md +358 -0
  319. package/Makefile +140 -0
  320. package/NOTICE +43 -0
  321. package/NPM_TOKEN_SETUP.md +81 -0
  322. package/PR.md +170 -0
  323. package/PUBLISH.md +77 -0
  324. package/README.md +108 -72
  325. package/README_FRONTEND.md +196 -0
  326. package/REALIGNMENT/00-overview.md +53 -0
  327. package/REALIGNMENT/01-bug-list.md +421 -0
  328. package/REALIGNMENT/02-architecture.md +322 -0
  329. package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
  330. package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
  331. package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
  332. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
  333. package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
  334. package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
  335. package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
  336. package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
  337. package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
  338. package/REALIGNMENT/12-decisions-needed.md +196 -0
  339. package/REALIGNMENT/INDEX.md +82 -0
  340. package/REFACTORING_CAMPAIGN.md +277 -0
  341. package/RESTRUCTURE_PLAN.md +100 -0
  342. package/RUST_DEV.md +361 -0
  343. package/SECURITY.md +65 -0
  344. package/SETUP_AUTO_PUBLISH.md +164 -0
  345. package/TESTING-copilot-subscription.md +153 -0
  346. package/app/api/config/route.ts +22 -0
  347. package/app/api/export/route.ts +83 -0
  348. package/app/api/models/route.ts +12 -0
  349. package/app/api/stats/route.ts +46 -0
  350. package/app/dashboard/page.tsx +445 -0
  351. package/app/globals.css +35 -0
  352. package/app/installation/page.tsx +293 -0
  353. package/app/layout.tsx +35 -0
  354. package/app/master-design-system.css +2076 -0
  355. package/app/master-design-system.source.css +8 -0
  356. package/app/page.tsx +187 -0
  357. package/app/rechtliches/agb/page.tsx +165 -0
  358. package/app/rechtliches/datenschutz/page.tsx +128 -0
  359. package/app/rechtliches/impressum/page.tsx +122 -0
  360. package/app/rechtliches/widerruf/page.tsx +185 -0
  361. package/bin/xithead.js +264 -0
  362. package/codecov.yml +34 -0
  363. package/components/layout/AppShell.tsx +25 -0
  364. package/components/layout/Footer.tsx +120 -0
  365. package/components/layout/Header.tsx +145 -0
  366. package/components/marketing/LegalHighlights.tsx +45 -0
  367. package/components/marketing/LegalPageShell.tsx +49 -0
  368. package/components/marketing/LegalPanel.tsx +41 -0
  369. package/components/marketing/index.ts +3 -0
  370. package/crates/headroom-core/Cargo.toml +165 -0
  371. package/crates/headroom-core/benches/auth_mode.rs +74 -0
  372. package/crates/headroom-core/benches/ccr_store.rs +224 -0
  373. package/crates/headroom-core/benches/tokenizer.rs +52 -0
  374. package/crates/headroom-core/config/pipeline.toml +151 -0
  375. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
  376. package/crates/headroom-core/src/auth_mode.rs +250 -0
  377. package/crates/headroom-core/src/cache_control.rs +414 -0
  378. package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
  379. package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
  380. package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
  381. package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
  382. package/crates/headroom-core/src/ccr/mod.rs +119 -0
  383. package/crates/headroom-core/src/compression_policy.rs +505 -0
  384. package/crates/headroom-core/src/lib.rs +33 -0
  385. package/crates/headroom-core/src/relevance/base.rs +139 -0
  386. package/crates/headroom-core/src/relevance/bm25.rs +385 -0
  387. package/crates/headroom-core/src/relevance/embedding.rs +354 -0
  388. package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
  389. package/crates/headroom-core/src/relevance/mod.rs +64 -0
  390. package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
  391. package/crates/headroom-core/src/signals/line_importance.rs +84 -0
  392. package/crates/headroom-core/src/signals/mod.rs +61 -0
  393. package/crates/headroom-core/src/signals/tiered.rs +141 -0
  394. package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
  395. package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
  396. package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
  397. package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
  398. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
  399. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
  400. package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
  401. package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
  402. package/crates/headroom-core/src/transforms/detection.rs +222 -0
  403. package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
  404. package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
  405. package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
  406. package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
  407. package/crates/headroom-core/src/transforms/mod.rs +64 -0
  408. package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
  409. package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
  410. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
  411. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
  412. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
  413. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
  414. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
  415. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
  416. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
  417. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
  418. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
  419. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
  420. package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
  421. package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
  422. package/crates/headroom-core/src/transforms/safety.rs +215 -0
  423. package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
  424. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
  425. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
  426. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
  427. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
  428. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
  429. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
  430. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
  431. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
  432. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
  433. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
  434. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
  435. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
  436. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
  437. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
  438. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
  439. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
  440. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
  441. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
  442. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
  443. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
  444. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
  445. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
  446. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
  447. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
  448. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
  449. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
  450. package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
  451. package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
  452. package/crates/headroom-parity/Cargo.toml +26 -0
  453. package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
  454. package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
  455. package/crates/headroom-parity/src/lib.rs +613 -0
  456. package/crates/headroom-proxy/Cargo.toml +119 -0
  457. package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
  458. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
  459. package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
  460. package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
  461. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
  462. package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
  463. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
  464. package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
  465. package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
  466. package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
  467. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
  468. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
  469. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
  470. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
  471. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
  472. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
  473. package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
  474. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
  475. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
  476. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
  477. package/crates/headroom-proxy/src/compression/mod.rs +127 -0
  478. package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
  479. package/crates/headroom-proxy/src/config.rs +646 -0
  480. package/crates/headroom-proxy/src/error.rs +69 -0
  481. package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
  482. package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
  483. package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
  484. package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
  485. package/crates/headroom-proxy/src/headers.rs +288 -0
  486. package/crates/headroom-proxy/src/health.rs +41 -0
  487. package/crates/headroom-proxy/src/lib.rs +21 -0
  488. package/crates/headroom-proxy/src/main.rs +141 -0
  489. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
  490. package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
  491. package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
  492. package/crates/headroom-proxy/src/observability/mod.rs +68 -0
  493. package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
  494. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
  495. package/crates/headroom-proxy/src/proxy.rs +1619 -0
  496. package/crates/headroom-proxy/src/responses_items.rs +565 -0
  497. package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
  498. package/crates/headroom-proxy/src/sse/framing.rs +366 -0
  499. package/crates/headroom-proxy/src/sse/mod.rs +40 -0
  500. package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
  501. package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
  502. package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
  503. package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
  504. package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
  505. package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
  506. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
  507. package/crates/headroom-proxy/src/websocket.rs +246 -0
  508. package/crates/headroom-py/Cargo.toml +37 -0
  509. package/crates/headroom-py/build.rs +77 -0
  510. package/crates/headroom-py/glibc_compat.c +170 -0
  511. package/crates/headroom-py/src/lib.rs +1655 -0
  512. package/deny.toml +32 -0
  513. package/design-system/base.css +127 -0
  514. package/design-system/components.css +1943 -0
  515. package/design-system/fonts.css +17 -0
  516. package/design-system/tailwind-preset.js +95 -0
  517. package/design-system/tokens.css +48 -0
  518. package/design-system/utilities.css +53 -0
  519. package/docker/differential-network-capture/Dockerfile.runner +14 -0
  520. package/docker/differential-network-capture/docker-compose.yml +142 -0
  521. package/docker/differential-network-capture/run-claude-lane.sh +24 -0
  522. package/docker/docker-compose.native.yml +44 -0
  523. package/docker-bake.hcl +88 -0
  524. package/docker-compose.yml +80 -0
  525. package/e2e/_lib/make_shim.ps1 +24 -0
  526. package/e2e/_lib/make_shim.sh +28 -0
  527. package/e2e/docker-native-install.sh +120 -0
  528. package/e2e/init/Dockerfile +79 -0
  529. package/e2e/wrap/Dockerfile +115 -0
  530. package/examples/07-context-compression.ipynb +279 -0
  531. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
  532. package/examples/deployment/macos-launchagent/install.sh +227 -0
  533. package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
  534. package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
  535. package/headroom-savings.png +0 -0
  536. package/headroom_learn.gif +0 -0
  537. package/lib/config/index.ts +12 -0
  538. package/lib/hooks/index.ts +4 -0
  539. package/lib/hooks/use-mounted.ts +13 -0
  540. package/lib/hooks/use-session.ts +34 -0
  541. package/lib/hooks/use-settings.ts +49 -0
  542. package/lib/utils/index.ts +1 -0
  543. package/lib/utils/settings.ts +162 -0
  544. package/lib/utils/utils.ts +6 -0
  545. package/llms.txt +67 -0
  546. package/middleware.ts +26 -0
  547. package/mkdocs.yml +136 -0
  548. package/next-env.d.ts +7 -0
  549. package/next.config.ts +12 -0
  550. package/npm/bin/xithead.js +366 -366
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.d.ts +57 -57
  553. package/npm/index.js +139 -139
  554. package/npm/package.json +55 -54
  555. package/npm/postinstall.js +43 -43
  556. package/package.json +58 -36
  557. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  558. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  559. package/plugins/headroom-oauth2/LICENSE +3 -0
  560. package/plugins/headroom-oauth2/SPEC.md +115 -0
  561. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  562. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  563. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  564. package/plugins/openclaw/hook-shim/handler.js +3 -0
  565. package/plugins/openclaw/openclaw.plugin.json +98 -0
  566. package/plugins/openclaw/package-lock.json +2692 -0
  567. package/plugins/openclaw/package.json +54 -0
  568. package/plugins/openclaw/prepare-dist.mjs +56 -0
  569. package/plugins/openclaw/src/convert.ts +418 -0
  570. package/plugins/openclaw/src/engine.ts +284 -0
  571. package/plugins/openclaw/src/gateway-config.ts +143 -0
  572. package/plugins/openclaw/src/index.ts +11 -0
  573. package/plugins/openclaw/src/plugin/index.ts +98 -0
  574. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  575. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  576. package/plugins/openclaw/test/convert.test.ts +96 -0
  577. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  578. package/plugins/openclaw/test/engine.test.ts +101 -0
  579. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  580. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  581. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  582. package/plugins/openclaw/tsup.config.ts +9 -0
  583. package/postcss.config.mjs +7 -0
  584. package/pyproject.toml +438 -0
  585. package/rust-toolchain.toml +16 -0
  586. package/sdk/typescript/examples/basic-compress.ts +64 -0
  587. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  588. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  589. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  590. package/sdk/typescript/examples/multi-provider.ts +53 -0
  591. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  592. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  593. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  594. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  595. package/sdk/typescript/examples/structured-output.ts +99 -0
  596. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  597. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  598. package/sdk/typescript/package-lock.json +3437 -0
  599. package/sdk/typescript/package.json +108 -0
  600. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  601. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  602. package/sdk/typescript/src/adapters/openai.ts +77 -0
  603. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  604. package/sdk/typescript/src/client.ts +632 -0
  605. package/sdk/typescript/src/compress.ts +87 -0
  606. package/sdk/typescript/src/errors.ts +114 -0
  607. package/sdk/typescript/src/hooks.ts +113 -0
  608. package/sdk/typescript/src/index.ts +140 -0
  609. package/sdk/typescript/src/paths.ts +272 -0
  610. package/sdk/typescript/src/shared-context.ts +188 -0
  611. package/sdk/typescript/src/simulate.ts +52 -0
  612. package/sdk/typescript/src/types/config.ts +183 -0
  613. package/sdk/typescript/src/types/models.ts +314 -0
  614. package/sdk/typescript/src/types.ts +139 -0
  615. package/sdk/typescript/src/utils/case.ts +34 -0
  616. package/sdk/typescript/src/utils/format.ts +480 -0
  617. package/sdk/typescript/src/utils/stream.ts +50 -0
  618. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  619. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  620. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  621. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  622. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  623. package/sdk/typescript/test/client.test.ts +266 -0
  624. package/sdk/typescript/test/compress.test.ts +118 -0
  625. package/sdk/typescript/test/config.test.ts +275 -0
  626. package/sdk/typescript/test/errors.test.ts +169 -0
  627. package/sdk/typescript/test/format-integration.test.ts +252 -0
  628. package/sdk/typescript/test/hooks.test.ts +265 -0
  629. package/sdk/typescript/test/integration.test.ts +249 -0
  630. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  631. package/sdk/typescript/test/models.test.ts +318 -0
  632. package/sdk/typescript/test/parity.test.ts +337 -0
  633. package/sdk/typescript/test/paths.test.ts +447 -0
  634. package/sdk/typescript/test/shared-context.test.ts +245 -0
  635. package/sdk/typescript/test/simulate.test.ts +84 -0
  636. package/sdk/typescript/test/types.test.ts +244 -0
  637. package/sdk/typescript/test/utils/case.test.ts +129 -0
  638. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  639. package/sdk/typescript/test/utils/format.test.ts +434 -0
  640. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  641. package/sdk/typescript/tsup.config.ts +17 -0
  642. package/tailwind.master.config.cjs +47 -0
  643. package/types/api.ts +12 -0
  644. package/types/config.ts +9 -0
  645. package/types/index.ts +2 -0
  646. package/uv.lock +6951 -0
  647. package/xithead.egg-info/PKG-INFO +22 -0
  648. package/xithead.egg-info/SOURCES.txt +16 -0
  649. package/xithead.egg-info/dependency_links.txt +1 -0
  650. package/xithead.egg-info/entry_points.txt +2 -0
  651. package/xithead.egg-info/requires.txt +10 -0
  652. package/xithead.egg-info/top_level.txt +2 -0
  653. package/xithead.ps1 +136 -0
  654. package/xithead.sh +129 -0
  655. package/xithead_dist/pyproject.toml +39 -0
  656. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  657. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  658. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  659. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  660. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  661. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,1619 @@
1
+ //! Core reverse-proxy router and HTTP forwarding handler.
2
+
3
+ use std::net::SocketAddr;
4
+ use std::sync::Arc;
5
+ use std::time::Instant;
6
+
7
+ use axum::body::{to_bytes, Body};
8
+ use axum::extract::{ConnectInfo, DefaultBodyLimit, State, WebSocketUpgrade};
9
+ use axum::http::{HeaderMap, HeaderName, Request, Response, StatusCode, Uri};
10
+ use axum::response::IntoResponse;
11
+ use axum::routing::{any, get, post};
12
+ use axum::Router;
13
+ #[cfg(test)]
14
+ use bytes::Bytes;
15
+ use futures_util::{StreamExt as _, TryStreamExt};
16
+ #[cfg(test)]
17
+ use http_body_util::BodyExt;
18
+
19
+ use crate::cache_stabilization;
20
+ use crate::cache_stabilization::drift_detector::{
21
+ compute_structural_hash, derive_session_key, observe_drift, ApiKind, DriftState,
22
+ };
23
+ use crate::compression;
24
+ use crate::config::Config;
25
+ use crate::error::ProxyError;
26
+ use crate::headers::{build_forward_request_headers, filter_response_headers};
27
+ use crate::health::{healthz, healthz_upstream};
28
+ use crate::websocket::ws_handler;
29
+ // Phase F PR-F1: imported as `classify_auth_mode` to make the call
30
+ // site self-documenting. `AuthMode` is re-exported under the same
31
+ // path for downstream handlers that read the value back out of
32
+ // `req.extensions()` (Phase F PR-F2/F3/F4).
33
+ use headroom_core::auth_mode::{classify as classify_auth_mode, AuthMode};
34
+ use headroom_core::compression_policy::CompressionPolicy;
35
+
36
+ /// Shared state passed to every handler.
37
+ ///
38
+ /// PR-A1 lockdown: the `IntelligentContextManager` field that used
39
+ /// to live here is gone. The Phase A passthrough doesn't need it,
40
+ /// and Phase B's live-zone dispatcher will introduce its own state
41
+ /// (per-block compressor registry) — the old ICM-shaped field would
42
+ /// not have been reused.
43
+ ///
44
+ /// PR-D4 adds `vertex_token_source`: an `Arc<dyn TokenSource>` used
45
+ /// by the Vertex `:rawPredict` / `:streamRawPredict` handlers to
46
+ /// resolve a GCP ADC bearer token. Production wires
47
+ /// [`crate::vertex::adc::GcpAdcTokenSource`] (lazy ADC chain
48
+ /// resolution + cached tokens with refresh-ahead-of-expiry); tests
49
+ /// inject [`crate::vertex::adc::StaticTokenSource`] so they never
50
+ /// hit real GCP.
51
+ #[derive(Clone)]
52
+ pub struct AppState {
53
+ pub config: Arc<Config>,
54
+ pub client: reqwest::Client,
55
+ /// PR-D1: AWS credentials resolved at startup via the
56
+ /// `aws-config` default chain. `None` when the proxy boots
57
+ /// without AWS creds available (operator running locally
58
+ /// against a non-Bedrock upstream); the Bedrock invoke handler
59
+ /// returns 5xx with a structured `event=bedrock_credentials_missing`
60
+ /// log so failures are LOUD — no silent fallback to unsigned
61
+ /// requests.
62
+ pub bedrock_credentials: Option<Arc<aws_credential_types::Credentials>>,
63
+ /// PR-E6: per-session structural-hash LRU for the cache-bust
64
+ /// drift detector. Bounded to 1000 sessions in production. The
65
+ /// detector is read-only — observing it never mutates the
66
+ /// request body — so this can be cloned freely into every handler
67
+ /// path that buffers the body.
68
+ pub drift_state: DriftState,
69
+ /// PR-D4: GCP ADC bearer-token source for Vertex routes. Default:
70
+ /// [`crate::vertex::adc::GcpAdcTokenSource`] constructed lazily;
71
+ /// the actual ADC chain is only resolved when the first Vertex
72
+ /// route hits `bearer()`. Tests override via
73
+ /// [`AppState::with_token_source`].
74
+ pub vertex_token_source: Arc<dyn crate::vertex::TokenSource>,
75
+ }
76
+
77
+ /// PR-E6: maximum number of sessions tracked by the drift detector
78
+ /// LRU. Picked so that a noisy test fleet of 1000 distinct API keys
79
+ /// stays in cache for at least one full turn before the oldest
80
+ /// evicts. Operators with larger fleets can bump this; the memory
81
+ /// cost per entry is ~150 bytes (key string + 96-byte StructuralHash
82
+ /// + LRU overhead).
83
+ const DRIFT_DETECTOR_CAPACITY: usize = 1000;
84
+
85
+ impl AppState {
86
+ pub fn new(config: Config) -> Result<Self, ProxyError> {
87
+ let client = reqwest::Client::builder()
88
+ .connect_timeout(config.upstream_connect_timeout)
89
+ .timeout(config.upstream_timeout)
90
+ // Don't auto-follow redirects: pass them through verbatim.
91
+ .redirect(reqwest::redirect::Policy::none())
92
+ // Pool needs to be allowed to be idle for long-lived streams.
93
+ .pool_idle_timeout(std::time::Duration::from_secs(90))
94
+ // Both HTTP/1.1 and HTTP/2 negotiated via ALPN.
95
+ .build()
96
+ .map_err(ProxyError::Upstream)?;
97
+
98
+ // PR-D4: lazy ADC token source. Provider resolution is
99
+ // deferred to first `bearer()` call so proxy startup stays
100
+ // cheap when no Vertex route is exercised.
101
+ let vertex_token_source: Arc<dyn crate::vertex::TokenSource> =
102
+ Arc::new(crate::vertex::adc::GcpAdcTokenSource::new());
103
+
104
+ Ok(Self {
105
+ config: Arc::new(config),
106
+ client,
107
+ bedrock_credentials: None,
108
+ drift_state: DriftState::new(DRIFT_DETECTOR_CAPACITY),
109
+ vertex_token_source,
110
+ })
111
+ }
112
+
113
+ /// PR-D1: attach AWS credentials resolved out-of-band (via
114
+ /// `aws-config`'s default chain at startup). Returns the
115
+ /// modified state; intended to be chained off `AppState::new`.
116
+ /// Tests that don't exercise the Bedrock route can leave
117
+ /// credentials unset (the catch-all paths never read them).
118
+ pub fn with_bedrock_credentials(mut self, creds: aws_credential_types::Credentials) -> Self {
119
+ self.bedrock_credentials = Some(Arc::new(creds));
120
+ self
121
+ }
122
+
123
+ /// Test helper: build an `AppState` with an explicit token source.
124
+ /// Lets the integration tests substitute a `StaticTokenSource` so
125
+ /// the test suite never hits real GCP.
126
+ pub fn with_token_source(
127
+ config: Config,
128
+ token_source: Arc<dyn crate::vertex::TokenSource>,
129
+ ) -> Result<Self, ProxyError> {
130
+ let mut s = Self::new(config)?;
131
+ s.vertex_token_source = token_source;
132
+ Ok(s)
133
+ }
134
+ }
135
+
136
+ /// Build the axum app. `/healthz` and `/healthz/upstream` are intercepted;
137
+ /// everything else hits the catch-all forwarder. WebSocket upgrades are
138
+ /// handled inside the catch-all handler when an `Upgrade: websocket` header
139
+ /// is present.
140
+ pub fn build_app(state: AppState) -> Router {
141
+ let mut router = Router::new()
142
+ .route("/healthz", get(healthz))
143
+ .route("/healthz/upstream", get(healthz_upstream))
144
+ // PR-D3: Prometheus scrape endpoint. Renders the global
145
+ // registry in text format. The handler is stateless — no
146
+ // `AppState` needed — and idempotent across concurrent
147
+ // scrapes (`prometheus`'s registry uses internal locking).
148
+ // Mounted unconditionally because it has no dependencies on
149
+ // any feature flag; an operator who doesn't want it scraped
150
+ // simply firewalls the path.
151
+ .route("/metrics", get(crate::observability::handle_metrics))
152
+ // PR-C2: explicit POST route for /v1/chat/completions. The
153
+ // handler buffers the body and re-injects it into
154
+ // `forward_http`, which runs the OpenAI live-zone gate
155
+ // alongside the existing Anthropic dispatcher. Non-POST
156
+ // methods (and other paths) still fall through to
157
+ // `catch_all` so the proxy stays a transparent reverse
158
+ // proxy for everything else.
159
+ .route(
160
+ "/v1/chat/completions",
161
+ post(crate::handlers::chat_completions::handle_chat_completions),
162
+ )
163
+ // PR-C3: explicit POST route for /v1/responses. Same forward
164
+ // pattern as /v1/chat/completions — the handler buffers the
165
+ // body, then `forward_http`'s gate dispatches to the
166
+ // Responses live-zone walker via `compress_openai_responses_request`.
167
+ .route(
168
+ "/v1/responses",
169
+ post(crate::handlers::responses::handle_responses),
170
+ )
171
+ // PR-D4: native Vertex publisher path. The Vertex AI Anthropic
172
+ // publisher endpoints look like
173
+ // `POST /v1beta1/projects/{p}/locations/{l}/publishers/anthropic/models/{m}:rawPredict`
174
+ // (and `:streamRawPredict`). The trailing `:<verb>` is awkward
175
+ // in axum's `:param` syntax, so we capture the entire trailing
176
+ // segment as `:model_action` and split on the last `:` inside
177
+ // the dispatcher. Both verbs share the same axum route shape
178
+ // — matchit can't distinguish two patterns that overlap on the
179
+ // literal parameter. The verb dispatch lives in
180
+ // [`crate::vertex::handle_vertex_predict_dispatch`].
181
+ .route(
182
+ "/v1beta1/projects/:project/locations/:location/publishers/anthropic/models/:model_action",
183
+ post(crate::vertex::handle_vertex_predict_dispatch),
184
+ );
185
+
186
+ // PR-D1: native AWS Bedrock InvokeModel route. Mounts only when
187
+ // `enable_bedrock_native` is on (default). The handler runs the
188
+ // live-zone compressor over Anthropic-shape bodies, signs with
189
+ // SigV4, and forwards to the configured Bedrock endpoint. The
190
+ // `/converse` route mounts the same handler — the wire shape is
191
+ // identical for `anthropic.claude-*` model IDs (Bedrock just
192
+ // accepts both legacy `invoke` and modern `converse` paths).
193
+ if state.config.enable_bedrock_native {
194
+ // PR-D3: Bedrock-scoped auth-mode middleware. Build a
195
+ // sub-router with ONLY the Bedrock routes, attach the
196
+ // auth-mode layer (so it fires before the handler runs and
197
+ // is scoped to these routes alone — `/v1/messages`,
198
+ // `/healthz`, etc. do NOT run through this middleware), and
199
+ // merge it into the parent router. The merge composes
200
+ // routes without changing their layer stacks; the parent's
201
+ // `with_state` (applied at the end) hands `AppState` to the
202
+ // Bedrock handlers identically.
203
+ let bedrock_router: Router<AppState> = Router::new()
204
+ .route(
205
+ "/model/:model_id/invoke",
206
+ post(crate::bedrock::invoke::handle_invoke),
207
+ )
208
+ .route(
209
+ "/model/:model_id/converse",
210
+ post(crate::bedrock::invoke::handle_invoke),
211
+ )
212
+ // PR-D2/PR-D5: streaming counterparts. Bedrock's protocol is
213
+ // binary EventStream; the handler parses incrementally,
214
+ // optionally translates each chunk to an SSE frame, and
215
+ // tees translated frames into AnthropicStreamState for
216
+ // telemetry. `invoke-with-response-stream` and
217
+ // `converse-stream` share the same wire framing and
218
+ // processing pipeline, so both route to the same handler.
219
+ // See `bedrock::invoke_streaming`.
220
+ .route(
221
+ "/model/:model_id/invoke-with-response-stream",
222
+ post(crate::bedrock::invoke_streaming::handle_invoke_streaming),
223
+ )
224
+ .route(
225
+ "/model/:model_id/converse-stream",
226
+ post(crate::bedrock::invoke_streaming::handle_invoke_streaming),
227
+ )
228
+ .route_layer(axum::middleware::from_fn(
229
+ crate::bedrock::classify_and_attach_auth_mode,
230
+ ))
231
+ // Match the explicit body-size cap used by the other proxy handlers.
232
+ // The `Bytes` extractor axum uses for Bedrock would otherwise cap
233
+ // at axum's built-in 2 MiB default, rejecting valid large payloads.
234
+ .layer(DefaultBodyLimit::max(state.config.max_body_bytes as usize));
235
+ router = router.merge(bedrock_router);
236
+ if !state.config.bedrock_validate_eventstream_crc {
237
+ tracing::warn!(
238
+ event = "bedrock_eventstream_crc_validation_disabled",
239
+ "Bedrock EventStream CRC validation is DISABLED — \
240
+ only safe for debugging; production must keep \
241
+ --bedrock-validate-eventstream-crc=true"
242
+ );
243
+ }
244
+ } else {
245
+ tracing::warn!(
246
+ event = "bedrock_native_disabled",
247
+ "Bedrock native InvokeModel route disabled by \
248
+ --enable-bedrock-native=false; Bedrock requests will fall \
249
+ through to the catch-all (no SigV4 re-signing — fails closed)"
250
+ );
251
+ }
252
+
253
+ // PR-C4: Conversations API (passthrough-with-instrumentation).
254
+ // The flag is read once at app-build time so router shape
255
+ // matches the configured policy. When disabled, requests still
256
+ // reach upstream via `catch_all`'s streaming forwarder, but the
257
+ // per-route handlers (and their structured-log breadcrumbs) are
258
+ // NOT mounted — operators flip the toggle to silence logs, not
259
+ // to break the surface. The catch-all preserves byte equivalence.
260
+ if state.config.enable_conversations_passthrough {
261
+ router = router
262
+ .route(
263
+ "/v1/conversations",
264
+ post(crate::handlers::conversations::handle_conversations_create),
265
+ )
266
+ .route(
267
+ "/v1/conversations/:conversation_id",
268
+ get(crate::handlers::conversations::handle_conversations_get)
269
+ .post(crate::handlers::conversations::handle_conversations_update)
270
+ .delete(crate::handlers::conversations::handle_conversations_delete),
271
+ )
272
+ .route(
273
+ "/v1/conversations/:conversation_id/items",
274
+ post(crate::handlers::conversations::handle_conversations_items_create)
275
+ .get(crate::handlers::conversations::handle_conversations_items_list),
276
+ )
277
+ .route(
278
+ "/v1/conversations/:conversation_id/items/:item_id",
279
+ get(crate::handlers::conversations::handle_conversations_item_get)
280
+ .delete(crate::handlers::conversations::handle_conversations_item_delete),
281
+ );
282
+ } else {
283
+ // Mirror the WARN we use elsewhere when a default-on guard
284
+ // is flipped off. Logged at app-build time, not per-request.
285
+ tracing::warn!(
286
+ event = "conversations_passthrough_disabled",
287
+ "Conversations API per-route handlers disabled by \
288
+ --enable-conversations-passthrough=false; requests will \
289
+ still reach upstream via the catch-all (no per-route logs)"
290
+ );
291
+ }
292
+
293
+ router.fallback(any(catch_all)).with_state(state)
294
+ }
295
+
296
+ /// Catch-all handler. If the request is a WebSocket upgrade, hand off to the
297
+ /// ws module; otherwise forward as plain HTTP.
298
+ async fn catch_all(
299
+ State(state): State<AppState>,
300
+ ConnectInfo(client_addr): ConnectInfo<SocketAddr>,
301
+ ws: Option<WebSocketUpgrade>,
302
+ req: Request<Body>,
303
+ ) -> Response<Body> {
304
+ if is_websocket_upgrade(req.headers()) {
305
+ if let Some(ws) = ws {
306
+ return ws_handler(ws, state, client_addr, req).await;
307
+ }
308
+ // Header says websocket but axum didn't extract it (likely missing
309
+ // Sec-WebSocket-Key) — fall through to HTTP forwarding which will
310
+ // surface the upstream error.
311
+ }
312
+ forward_http(state, client_addr, req)
313
+ .await
314
+ .unwrap_or_else(|e| e.into_response())
315
+ }
316
+
317
+ /// True if `Content-Type` is `application/json` (with any optional
318
+ /// parameters like `; charset=utf-8`). Compression only inspects JSON
319
+ /// bodies — multipart uploads, form-encoded posts, and binary
320
+ /// payloads stream through untouched.
321
+ fn is_application_json(headers: &HeaderMap) -> bool {
322
+ headers
323
+ .get(http::header::CONTENT_TYPE)
324
+ .and_then(|v| v.to_str().ok())
325
+ .map(|s| {
326
+ // Take the media-type portion before any ';'. Trim and
327
+ // compare case-insensitively per RFC 7231 §3.1.1.1.
328
+ let media_type = s.split(';').next().unwrap_or("").trim();
329
+ media_type.eq_ignore_ascii_case("application/json")
330
+ })
331
+ .unwrap_or(false)
332
+ }
333
+
334
+ fn is_websocket_upgrade(headers: &HeaderMap) -> bool {
335
+ let upgrade = headers
336
+ .get(http::header::UPGRADE)
337
+ .and_then(|v| v.to_str().ok())
338
+ .map(|s| s.eq_ignore_ascii_case("websocket"))
339
+ .unwrap_or(false);
340
+ let connection = headers
341
+ .get(http::header::CONNECTION)
342
+ .and_then(|v| v.to_str().ok())
343
+ .map(|s| {
344
+ s.split(',')
345
+ .any(|t| t.trim().eq_ignore_ascii_case("upgrade"))
346
+ })
347
+ .unwrap_or(false);
348
+ upgrade && connection
349
+ }
350
+
351
+ /// Build the upstream URL by joining the configured base with the incoming
352
+ /// path-and-query. Preserves '?' and the query string verbatim.
353
+ pub(crate) fn build_upstream_url(base: &url::Url, uri: &Uri) -> Result<url::Url, ProxyError> {
354
+ Ok(join_upstream_path(base, uri.path(), uri.query()))
355
+ }
356
+
357
+ /// Shared path-join helper used by HTTP and WebSocket handlers.
358
+ /// Appends `path` to `base`, preserving any base path prefix, then sets `query`.
359
+ pub(crate) fn join_upstream_path(base: &url::Url, path: &str, query: Option<&str>) -> url::Url {
360
+ let mut joined = base.clone();
361
+ // Strip trailing slash from base path so "http://x:1/api" + "/v1/foo"
362
+ // yields "http://x:1/api/v1/foo" rather than "http://x:1/v1/foo".
363
+ let base_path = joined.path().trim_end_matches('/').to_string();
364
+ let combined = if path.is_empty() || path == "/" {
365
+ if base_path.is_empty() {
366
+ "/".to_string()
367
+ } else {
368
+ base_path
369
+ }
370
+ } else if base_path.is_empty() {
371
+ path.to_string()
372
+ } else {
373
+ format!("{base_path}{path}")
374
+ };
375
+ joined.set_path(&combined);
376
+ joined.set_query(query);
377
+ joined
378
+ }
379
+
380
+ /// Forward an HTTP request to the upstream and stream the response back.
381
+ pub(crate) async fn forward_http(
382
+ state: AppState,
383
+ client_addr: SocketAddr,
384
+ mut req: Request<Body>,
385
+ ) -> Result<Response<Body>, ProxyError> {
386
+ let start = Instant::now();
387
+ let request_id = ensure_request_id(req.headers());
388
+ let method = req.method().clone();
389
+ let uri = req.uri().clone();
390
+ let path_for_log = uri.path().to_string();
391
+ let body_bytes_hint = req
392
+ .headers()
393
+ .get(http::header::CONTENT_LENGTH)
394
+ .and_then(|v| v.to_str().ok())
395
+ .and_then(|s| s.parse::<u64>().ok());
396
+
397
+ // Phase F PR-F1: classify auth mode at request entry. The result
398
+ // is stored in request extensions so downstream handlers (cache
399
+ // gates, header injection, lossy-compressor gates) read it
400
+ // without re-classifying. Pure function, <10us per call —
401
+ // doing it once here is cheaper than threading the result.
402
+ let auth_mode = classify_auth_mode(req.headers());
403
+ req.extensions_mut().insert(auth_mode);
404
+
405
+ // Phase F PR-F2.1, c2/6: derive the per-mode CompressionPolicy at
406
+ // request entry and stash alongside auth_mode. Storing the policy
407
+ // (not just auth_mode) in extensions lets downstream stages read
408
+ // the gate they need directly — no per-stage `for_mode` call.
409
+ //
410
+ // c3/6: when `auth_mode_policy_enforcement` is `Disabled` (default
411
+ // until c6/6), force the policy to PAYG regardless of classifier
412
+ // output. This means c4/6 + c5/6 only ship behaviour change when
413
+ // an operator opts in via the env var, so the PR sequence is
414
+ // safely landed in main without flipping the live wire on default
415
+ // users until the final commit.
416
+ let policy = if state.config.auth_mode_policy_enforcement.is_enabled() {
417
+ CompressionPolicy::for_mode(auth_mode)
418
+ } else {
419
+ CompressionPolicy::for_mode(AuthMode::Payg)
420
+ };
421
+ req.extensions_mut().insert(policy);
422
+
423
+ // Per PR-A1: structured entry log. The `auth_mode` field is now
424
+ // populated with the real classification result (Phase F PR-F1
425
+ // replaces the prior `auth_mode_placeholder = "unknown"`). Body
426
+ // byte count is best-effort from the Content-Length header —
427
+ // the real count is logged at the compression-decision site
428
+ // once buffered.
429
+ tracing::debug!(
430
+ event = "auth_mode_classified",
431
+ request_id = %request_id,
432
+ auth_mode = auth_mode.as_str(),
433
+ method = %method,
434
+ path = %path_for_log,
435
+ content_length_bytes = ?body_bytes_hint,
436
+ "request received"
437
+ );
438
+
439
+ // F2.1 c2/6: emit the policy that the request will run under so
440
+ // F2.2 has bake-time data to tune from. One log per request,
441
+ // structured fields so it joins on auth_mode + request_id.
442
+ // c3/6 adds `enforcement` so the dashboard can split "policy
443
+ // resolved as PAYG because mode is PAYG" from "policy resolved as
444
+ // PAYG because the enforcement flag is off."
445
+ //
446
+ // F2.2 c2/3: extend the structured fields with the three new
447
+ // tuning fields so the bake dashboard has per-mode observability
448
+ // for the F2.2-followup tune. ``volatile_token_threshold`` /
449
+ // ``max_lossy_ratio`` are plumbed-but-unconsumed today, so the
450
+ // log lines are the only signal that the values are flowing
451
+ // correctly through the proxy → handlers → transforms path.
452
+ tracing::debug!(
453
+ event = "policy_selected",
454
+ request_id = %request_id,
455
+ auth_mode = auth_mode.as_str(),
456
+ enforcement = state.config.auth_mode_policy_enforcement.as_str(),
457
+ live_zone_only = policy.live_zone_only,
458
+ cache_aligner_enabled = policy.cache_aligner_enabled,
459
+ volatile_token_threshold = policy.volatile_token_threshold,
460
+ max_lossy_ratio = policy.max_lossy_ratio,
461
+ toin_read_only = policy.toin_read_only,
462
+ "compression policy resolved"
463
+ );
464
+
465
+ let upstream_url = build_upstream_url(&state.config.upstream, &uri)?;
466
+
467
+ // Forwarded-Host: prefer client's Host. Forwarded-Proto: assume http for
468
+ // now (we don't terminate TLS in this binary; if a TLS terminator is in
469
+ // front, it should rewrite this — which we'd handle by not overwriting
470
+ // an existing one in a future change).
471
+ let forwarded_host = req
472
+ .headers()
473
+ .get(http::header::HOST)
474
+ .and_then(|v| v.to_str().ok())
475
+ .map(|s| s.to_string());
476
+
477
+ // Build the outgoing headers off the incoming ones, then optionally drop
478
+ // Host (rewrite_host=true => let reqwest set its own Host for the upstream).
479
+ // PR-A5 (P5-49): strip internal `x-headroom-*` from upstream-bound
480
+ // requests when `Config::strip_internal_headers == Enabled` (default).
481
+ let strip_internal = state.config.strip_internal_headers.is_enabled();
482
+ let pre_strip_internal_count = req
483
+ .headers()
484
+ .iter()
485
+ .filter(|(name, _)| crate::headers::is_internal_header(name))
486
+ .count();
487
+ let mut outgoing_headers = build_forward_request_headers(
488
+ req.headers(),
489
+ client_addr.ip(),
490
+ "http",
491
+ forwarded_host.as_deref(),
492
+ &request_id,
493
+ strip_internal,
494
+ );
495
+ if strip_internal && pre_strip_internal_count > 0 {
496
+ tracing::info!(
497
+ event = "outbound_headers",
498
+ forwarder = "rust_proxy",
499
+ stripped_count = pre_strip_internal_count,
500
+ request_id = %request_id,
501
+ "stripped internal x-headroom-* headers from upstream-bound request"
502
+ );
503
+ } else if !strip_internal && pre_strip_internal_count > 0 {
504
+ tracing::warn!(
505
+ event = "outbound_headers",
506
+ forwarder = "rust_proxy",
507
+ mode = "disabled",
508
+ internal_count = pre_strip_internal_count,
509
+ request_id = %request_id,
510
+ "HEADROOM_PROXY_STRIP_INTERNAL_HEADERS=disabled; \
511
+ internal x-headroom-* headers forwarded to upstream"
512
+ );
513
+ }
514
+ if !state.config.rewrite_host {
515
+ if let Some(h) = req.headers().get(http::header::HOST) {
516
+ outgoing_headers.insert(http::header::HOST, h.clone());
517
+ }
518
+ }
519
+
520
+ // ─── COMPRESSION GATE ──────────────────────────────────────────────
521
+ //
522
+ // PR-A1 lockdown (per `REALIGNMENT/03-phase-A-lockdown.md`): the
523
+ // `/v1/messages` path no longer mutates the body. The gate below
524
+ // still routes JSON bodies on the LLM endpoint into a "buffered"
525
+ // arm, because:
526
+ //
527
+ // 1. We want to log the compression *decision* (passthrough,
528
+ // with mode + reason) per request so operators can tell
529
+ // `off`-mode passthrough from `live_zone`-currently-passthrough.
530
+ // 2. Phase B PR-B2 fills `compress_anthropic_request` with the
531
+ // live-zone dispatcher. Keeping the buffered code path lit
532
+ // now means PR-B2 is a pure body-substitution change, not a
533
+ // gate redesign.
534
+ // 3. The buffered branch issues a `debug_assert!` that the
535
+ // bytes forwarded to upstream are byte-equal to the bytes
536
+ // received — the cache-safety invariant Phase A enforces.
537
+ //
538
+ // Gate criteria (ALL true → buffered passthrough; otherwise stream):
539
+ //
540
+ // - `state.config.compression` master switch on
541
+ // - `method == POST`
542
+ // - path matches a known LLM endpoint
543
+ // - content-type is application/json
544
+ //
545
+ // The new `compression_mode` flag is *not* part of the gate. It
546
+ // controls what the buffered branch does (currently both `Off`
547
+ // and `LiveZone` passthrough); Phase B will branch on it inside
548
+ // `compress_anthropic_request`.
549
+ let should_intercept = state.config.compression
550
+ && method == axum::http::Method::POST
551
+ && compression::is_compressible_path(uri.path())
552
+ && is_application_json(req.headers());
553
+
554
+ // PR-E6: capture a header snapshot BEFORE the body is consumed so
555
+ // the drift detector can derive a per-session key from
556
+ // `Authorization`/`x-api-key`/`User-Agent`. `req` will be moved
557
+ // into either `to_bytes(req.into_body())` (buffered branch) or
558
+ // `req.into_body().into_data_stream()` (streaming branch); both
559
+ // discard the headers along with the body. Snapshot here keeps
560
+ // both branches clean.
561
+ let headers_snapshot = if should_intercept {
562
+ Some(req.headers().clone())
563
+ } else {
564
+ None
565
+ };
566
+
567
+ let reqwest_method = reqwest::Method::from_bytes(method.as_str().as_bytes())
568
+ .map_err(|e| ProxyError::InvalidHeader(e.to_string()))?;
569
+
570
+ let upstream_resp = if should_intercept {
571
+ // Buffer up to `compression_max_body_bytes`. If the body
572
+ // exceeds this, the body is already partially consumed and
573
+ // cannot be resumed as a stream — fail loudly per project
574
+ // no-silent-fallbacks rule. Operators tune
575
+ // `--compression-max-body-bytes` upward if they hit this.
576
+ //
577
+ // PR-A8 / P5-59: pre-check `Content-Length` against the cap
578
+ // BEFORE consuming any body bytes. When the header is
579
+ // present and oversized we return 413 immediately; clients
580
+ // never see a partially-consumed body and don't have to
581
+ // distinguish "header parse error" from "payload too large".
582
+ // For chunked uploads (no Content-Length), we keep the
583
+ // buffer-then-fail path but surface 413 when it trips.
584
+ let max = state.config.compression_max_body_bytes as usize;
585
+ if let Some(len) = body_bytes_hint {
586
+ if len as usize > max {
587
+ tracing::warn!(
588
+ request_id = %request_id,
589
+ path = %path_for_log,
590
+ limit_bytes = max,
591
+ content_length = len,
592
+ "compression: Content-Length exceeds buffer limit; \
593
+ returning 413 without consuming body"
594
+ );
595
+ return Err(ProxyError::PayloadTooLarge(format!(
596
+ "request Content-Length {len} exceeds compression \
597
+ buffer limit ({max} bytes)"
598
+ )));
599
+ }
600
+ }
601
+ let buffered = match to_bytes(req.into_body(), max).await {
602
+ Ok(b) => b,
603
+ Err(e) => {
604
+ tracing::warn!(
605
+ request_id = %request_id,
606
+ path = %path_for_log,
607
+ limit_bytes = max,
608
+ error = %e,
609
+ "compression: body exceeds buffer limit; failing loudly (cannot \
610
+ resume streaming once the body has been partially consumed)"
611
+ );
612
+ return Err(ProxyError::PayloadTooLarge(format!(
613
+ "request body exceeds compression buffer limit ({max} bytes): {e}"
614
+ )));
615
+ }
616
+ };
617
+
618
+ // PR-C2: dispatch on the endpoint classification so each
619
+ // provider hits its own live-zone walker. PR-B2/B3/B4 wired
620
+ // the Anthropic dispatcher; PR-C2 adds the OpenAI Chat
621
+ // Completions sibling. The classification was already
622
+ // computed by `is_compressible_path` above; we re-classify
623
+ // here so a single-source `match` decides which dispatcher
624
+ // runs and what skip rules apply.
625
+ //
626
+ // Skip rules (per spec PR-C2):
627
+ // - OpenAI Chat: `n > 1` skips compression entirely (multiple
628
+ // completions imply non-determinism scenarios). `tool_choice`
629
+ // and `stream_options` are NOT skip conditions — they
630
+ // round-trip byte-equal as a side effect of byte-range surgery.
631
+ // - Anthropic: no extra skip rules at this layer.
632
+ let endpoint = compression::classify_compressible_path(uri.path())
633
+ .expect("is_compressible_path guarded above");
634
+
635
+ // PR-E5 + PR-E6: cache-stabilization observability hooks.
636
+ // Both run READ-ONLY against the buffered body and emit
637
+ // structured logs only — passthrough invariant from Phase A
638
+ // is preserved. Parsing happens once and is shared. Cheap
639
+ // parse failure (malformed JSON) silently skips both
640
+ // detectors; the dispatcher below logs its own parse-error
641
+ // decision. The hooks run regardless of whether the
642
+ // dispatcher returns `NoCompression`, `Compressed`, or
643
+ // `Passthrough`.
644
+ //
645
+ // Bedrock and other shape-mismatched paths skip the drift
646
+ // detector specifically; their wire shape is different
647
+ // enough that a canonical-bytes hash would compare apples
648
+ // to oranges. The volatile detector handles its own
649
+ // shape-dispatch via `ApiKind::from_endpoint`.
650
+ if let Ok(parsed) = serde_json::from_slice::<serde_json::Value>(&buffered) {
651
+ // PR-E5: volatile-content detector. Emits one WARN per
652
+ // finding (capped at 10) for content that busts cache
653
+ // (timestamps, UUIDs, ID-named fields).
654
+ let volatile_kind =
655
+ cache_stabilization::volatile_detector::ApiKind::from_endpoint(endpoint);
656
+ let findings = cache_stabilization::volatile_detector::detect_volatile_content(
657
+ &parsed,
658
+ volatile_kind,
659
+ );
660
+ if !findings.is_empty() {
661
+ cache_stabilization::volatile_detector::emit_volatile_warnings(
662
+ &findings,
663
+ &request_id,
664
+ );
665
+ }
666
+
667
+ // PR-E6: cache-bust drift detector. SHA-256 fingerprints
668
+ // the cache hot zone (system / tools / first 3 messages);
669
+ // a mismatch between consecutive turns of the same session
670
+ // emits a `cache_drift_observed` event so operators see
671
+ // invisible cache busts.
672
+ let drift_kind = match endpoint {
673
+ compression::CompressibleEndpoint::AnthropicMessages => Some(ApiKind::Anthropic),
674
+ compression::CompressibleEndpoint::OpenAiChatCompletions => {
675
+ Some(ApiKind::OpenAiChat)
676
+ }
677
+ compression::CompressibleEndpoint::OpenAiResponses => {
678
+ Some(ApiKind::OpenAiResponses)
679
+ }
680
+ };
681
+ if let (Some(kind), Some(headers)) = (drift_kind, headers_snapshot.as_ref()) {
682
+ let session_key = derive_session_key(headers, &client_addr);
683
+ let hash = compute_structural_hash(&parsed, kind);
684
+ observe_drift(&state.drift_state, &session_key, hash);
685
+ }
686
+ }
687
+ let outcome = match endpoint {
688
+ compression::CompressibleEndpoint::AnthropicMessages => {
689
+ // PR-E3: thread the F1-classified auth_mode into the
690
+ // dispatcher so cache_control auto-placement gates on
691
+ // PAYG only. Pulled from request extensions where it
692
+ // was stashed at request entry (line ~325 above).
693
+ compression::compress_anthropic_request(
694
+ &buffered,
695
+ state.config.compression_mode,
696
+ state.config.cache_control_auto_frozen,
697
+ auth_mode,
698
+ &request_id,
699
+ )
700
+ }
701
+ compression::CompressibleEndpoint::OpenAiChatCompletions => {
702
+ let skip = compression::should_skip_compression(&buffered);
703
+ if skip.is_skip() {
704
+ tracing::info!(
705
+ event = "compression_decision",
706
+ request_id = %request_id,
707
+ path = "/v1/chat/completions",
708
+ method = "POST",
709
+ compression_mode = state.config.compression_mode.as_str(),
710
+ decision = "passthrough",
711
+ reason = skip.as_log_str(),
712
+ body_bytes = buffered.len(),
713
+ "openai chat compression skipped pre-dispatch"
714
+ );
715
+ compression::Outcome::NoCompression
716
+ } else {
717
+ compression::compress_openai_chat_request(
718
+ &buffered,
719
+ state.config.compression_mode,
720
+ auth_mode,
721
+ &request_id,
722
+ )
723
+ }
724
+ }
725
+ // PR-C3: OpenAI Responses (`/v1/responses`). The Responses
726
+ // dispatcher walks an explicitly-typed `input` array and
727
+ // only rewrites the latest of each compressible `*_output`
728
+ // kind plus the latest `message` text. Cache hot zone is
729
+ // every other item type (passthrough verbatim).
730
+ compression::CompressibleEndpoint::OpenAiResponses => {
731
+ compression::compress_openai_responses_request(
732
+ &buffered,
733
+ state.config.compression_mode,
734
+ auth_mode,
735
+ &request_id,
736
+ )
737
+ }
738
+ };
739
+
740
+ // C2 fix: snapshot the original buffered byte-length AND the
741
+ // dispatcher's "is this a passthrough arm?" decision BEFORE
742
+ // `outcome` is consumed by the match below. The
743
+ // passthrough-bytes-modified alarm fires when a path that
744
+ // promised byte-equal passthrough produces a different
745
+ // length downstream.
746
+ let original_buffered_len = buffered.len();
747
+ let outcome_is_passthrough_class = matches!(
748
+ outcome,
749
+ compression::Outcome::NoCompression | compression::Outcome::Passthrough { .. }
750
+ );
751
+ let body_to_send = match outcome {
752
+ compression::Outcome::NoCompression => {
753
+ // PR-B2: forward the *original* buffered bytes. The
754
+ // cache-safety invariant (bytes-in == bytes-out)
755
+ // is the whole point of the live-zone architecture
756
+ // — the dispatcher only mutates body bytes when at
757
+ // least one block compressed.
758
+ buffered
759
+ }
760
+ // PR-B3+ produces `Compressed` from the live-zone
761
+ // dispatcher when at least one per-type compressor
762
+ // mutates a block. Already wired here so the next phase
763
+ // is a pure addition.
764
+ compression::Outcome::Compressed {
765
+ body,
766
+ tokens_before,
767
+ tokens_after,
768
+ strategies_applied,
769
+ markers_inserted,
770
+ per_strategy_tokens,
771
+ } => {
772
+ tracing::info!(
773
+ request_id = %request_id,
774
+ path = %path_for_log,
775
+ tokens_before = tokens_before,
776
+ tokens_after = tokens_after,
777
+ tokens_freed = tokens_before.saturating_sub(tokens_after),
778
+ strategies = ?strategies_applied,
779
+ markers = markers_inserted.len(),
780
+ "compression applied"
781
+ );
782
+ // Phase G PR-G3 + H1: emit one
783
+ // `proxy_compression_ratio_by_strategy` sample per
784
+ // strategy with the *strategy's own* before/after
785
+ // token counts. The pre-H1 code emitted the same
786
+ // aggregate ratio for every strategy in
787
+ // `strategies_applied`, so Phase H per-strategy
788
+ // dashboards read garbage when multiple strategies
789
+ // ran on one body. We now plumb per-strategy tokens
790
+ // from the manifest at the wrapper site
791
+ // (`live_zone_anthropic`, `live_zone_openai`,
792
+ // `live_zone_responses`).
793
+ //
794
+ // Fallback: when `per_strategy_tokens` is empty —
795
+ // i.e. the Outcome came from a Phase E
796
+ // normalization pass that doesn't track per-strategy
797
+ // tokens — we emit one aggregate-labelled sample so
798
+ // dashboards still see *that* a compression ran. We
799
+ // log loudly so this is visible.
800
+ if !per_strategy_tokens.is_empty() {
801
+ for entry in &per_strategy_tokens {
802
+ crate::observability::observe_compression_ratio(
803
+ entry.strategy,
804
+ "aggregate",
805
+ entry.original_tokens,
806
+ entry.compressed_tokens,
807
+ );
808
+ }
809
+ } else if tokens_before > 0 && tokens_after < tokens_before {
810
+ tracing::debug!(
811
+ event = "compression_ratio_emit_aggregate_only",
812
+ request_id = %request_id,
813
+ path = %path_for_log,
814
+ strategies = ?strategies_applied,
815
+ reason = "no_per_strategy_tokens",
816
+ "emitting one aggregate-labelled compression_ratio sample because \
817
+ the dispatcher did not surface per-strategy token counts \
818
+ (Phase E normalization paths)"
819
+ );
820
+ crate::observability::observe_compression_ratio(
821
+ "aggregate",
822
+ "aggregate",
823
+ tokens_before,
824
+ tokens_after,
825
+ );
826
+ }
827
+ body
828
+ }
829
+ compression::Outcome::Passthrough { reason } => {
830
+ tracing::warn!(
831
+ request_id = %request_id,
832
+ path = %path_for_log,
833
+ reason = ?reason,
834
+ "compression: passthrough on parse/serialize"
835
+ );
836
+ buffered
837
+ }
838
+ };
839
+
840
+ // C2 fix: cache-safety alarm. When the dispatcher returned
841
+ // `NoCompression` or `Passthrough`, the post-dispatcher body
842
+ // MUST be byte-length-equal to the original buffered body.
843
+ // Any delta is an accidental cache-poisoning regression and
844
+ // the alarm metric `proxy_passthrough_bytes_modified_total{path}`
845
+ // fires with the byte delta as its increment. We check BEFORE
846
+ // the PR-E4 prompt_cache_key injector runs because that
847
+ // injector is a legitimate, intentional byte mutation gated
848
+ // on PAYG; it must not trip the alarm.
849
+ if outcome_is_passthrough_class && body_to_send.len() != original_buffered_len {
850
+ let delta = body_to_send.len().abs_diff(original_buffered_len) as u64;
851
+ crate::observability::record_passthrough_bytes_modified(
852
+ &path_for_log,
853
+ delta,
854
+ &request_id,
855
+ );
856
+ }
857
+
858
+ // PR-E4: OpenAI `prompt_cache_key` auto-injection.
859
+ //
860
+ // Universal safety contract: only mutate when the caller
861
+ // is on `AuthMode::Payg`. OAuth/Subscription bytes flow
862
+ // through byte-equal — those clients cannot afford
863
+ // synthesised cache keys (OAuth scopes pin to
864
+ // `(account, model, session)` and subscription clients
865
+ // are programmatically fingerprinted by the upstream).
866
+ //
867
+ // The injector also self-skips when the customer has
868
+ // already set a non-empty `prompt_cache_key`. Every skip
869
+ // path emits a structured `e4_skipped` event so cache-hit
870
+ // dashboards can attribute miss rates to gating reasons
871
+ // rather than guessing.
872
+ let body_to_send = match endpoint {
873
+ compression::CompressibleEndpoint::OpenAiChatCompletions
874
+ | compression::CompressibleEndpoint::OpenAiResponses => {
875
+ let shape = match endpoint {
876
+ compression::CompressibleEndpoint::OpenAiResponses => {
877
+ cache_stabilization::openai_cache_key::OpenAiShape::Responses
878
+ }
879
+ _ => cache_stabilization::openai_cache_key::OpenAiShape::ChatCompletions,
880
+ };
881
+ maybe_inject_openai_prompt_cache_key(
882
+ body_to_send,
883
+ shape,
884
+ auth_mode,
885
+ &request_id,
886
+ &path_for_log,
887
+ )
888
+ }
889
+ compression::CompressibleEndpoint::AnthropicMessages => body_to_send,
890
+ };
891
+
892
+ // Forward the (Phase A: identical) buffered bytes. reqwest
893
+ // sets its own Content-Length from the body bytes — the
894
+ // existing `build_forward_request_headers` already strips
895
+ // the client-supplied Content-Length for us.
896
+ state
897
+ .client
898
+ .request(reqwest_method, upstream_url.clone())
899
+ .headers(outgoing_headers)
900
+ .body(body_to_send)
901
+ .send()
902
+ .await?
903
+ } else {
904
+ // Pure streaming path — the original passthrough behaviour.
905
+ let body_stream =
906
+ TryStreamExt::map_err(req.into_body().into_data_stream(), std::io::Error::other);
907
+ let reqwest_body = reqwest::Body::wrap_stream(body_stream);
908
+ state
909
+ .client
910
+ .request(reqwest_method, upstream_url.clone())
911
+ .headers(outgoing_headers)
912
+ .body(reqwest_body)
913
+ .send()
914
+ .await?
915
+ };
916
+
917
+ let upstream_status = upstream_resp.status();
918
+ let status = StatusCode::from_u16(upstream_status.as_u16()).unwrap_or(StatusCode::BAD_GATEWAY);
919
+
920
+ // PR-A8 / P5-57: capture the upstream request id BEFORE we move
921
+ // `upstream_resp.headers()` into the response filter. Anthropic
922
+ // emits `request-id` (lowercase, no `x-`); OpenAI emits
923
+ // `x-request-id`. We forward both to the client unchanged in
924
+ // `resp_headers` and additionally surface a side-channel
925
+ // `headroom-request-id` header so callers can correlate proxy
926
+ // logs without conflating with the proxy's own `x-request-id`.
927
+ let upstream_request_id_anthropic = upstream_resp
928
+ .headers()
929
+ .get("request-id")
930
+ .and_then(|v| v.to_str().ok())
931
+ .map(str::to_owned);
932
+ let upstream_request_id_openai = upstream_resp
933
+ .headers()
934
+ .get("x-request-id")
935
+ .and_then(|v| v.to_str().ok())
936
+ .map(str::to_owned);
937
+ // Prefer the provider-specific id whichever was set. Both
938
+ // present is unusual but legal; prefer Anthropic since it's the
939
+ // path-shape we lockdown with cache invariants.
940
+ let upstream_request_id = upstream_request_id_anthropic
941
+ .clone()
942
+ .or_else(|| upstream_request_id_openai.clone());
943
+
944
+ // PR-C1: detect SSE responses so the state machine can run in
945
+ // parallel with the byte-passthrough. We classify ONCE here and
946
+ // pick the response provider arm based on the request path —
947
+ // bytes flow to the client unchanged; the state machine sinks
948
+ // bytes into a `tokio::sync::mpsc` and runs in a spawned task
949
+ // that can never block the byte path.
950
+ //
951
+ // PR-C4: the OpenAI Responses arm is gated by
952
+ // `enable_responses_streaming`. When that flag is false the
953
+ // tee is short-circuited to `None` so the framer + state
954
+ // machine don't spin up and bytes flow opaquely. Other
955
+ // providers' state machines are unaffected.
956
+ let is_sse = is_sse_response(upstream_resp.headers());
957
+ let sse_kind = if is_sse {
958
+ let kind = SseStreamKind::for_request_path(&path_for_log);
959
+ if matches!(kind, SseStreamKind::OpenAiResponses)
960
+ && !state.config.enable_responses_streaming
961
+ {
962
+ tracing::info!(
963
+ request_id = %request_id,
964
+ path = %path_for_log,
965
+ event = "responses_streaming_state_machine_skipped",
966
+ reason = "enable_responses_streaming=false",
967
+ "PR-C4 streaming pipeline disabled; SSE bytes pass through without telemetry"
968
+ );
969
+ SseStreamKind::None
970
+ } else {
971
+ kind
972
+ }
973
+ } else {
974
+ SseStreamKind::None
975
+ };
976
+
977
+ let resp_headers = filter_response_headers(upstream_resp.headers());
978
+
979
+ // Phase G PR-G3: extract upstream rate-limit headers from this
980
+ // response and record them as gauges. The `provider` label is
981
+ // chosen by which of the upstream `request-id` shapes we saw
982
+ // (Anthropic vs OpenAI). When neither shape was detected we
983
+ // skip emission rather than guessing — per realignment build-
984
+ // constraint "no silent fallbacks".
985
+ let rate_limit_snapshot =
986
+ crate::observability::extract_rate_limit_snapshot(upstream_resp.headers());
987
+ let rate_limit_provider: Option<&'static str> = if upstream_request_id_anthropic.is_some() {
988
+ Some(crate::observability::cache_hit_rate_provider::ANTHROPIC)
989
+ } else if upstream_request_id_openai.is_some() {
990
+ // We can't distinguish chat vs responses purely from the
991
+ // request-id header; the `path_for_log` is more specific.
992
+ Some(if path_for_log.contains("/v1/responses") {
993
+ crate::observability::cache_hit_rate_provider::OPENAI_RESPONSES
994
+ } else {
995
+ crate::observability::cache_hit_rate_provider::OPENAI_CHAT
996
+ })
997
+ } else {
998
+ None
999
+ };
1000
+ if let Some(provider) = rate_limit_provider {
1001
+ crate::observability::record_rate_limit_snapshot(
1002
+ provider,
1003
+ &rate_limit_snapshot,
1004
+ &request_id,
1005
+ );
1006
+ } else if rate_limit_snapshot.remaining_requests.is_some()
1007
+ || rate_limit_snapshot.remaining_tokens.is_some()
1008
+ || rate_limit_snapshot.remaining_input_tokens.is_some()
1009
+ || rate_limit_snapshot.remaining_output_tokens.is_some()
1010
+ {
1011
+ // Headers present but provider unattributable. Log loud so
1012
+ // operators see the wire-format drift; do not emit unlabelled
1013
+ // metrics.
1014
+ tracing::debug!(
1015
+ event = "rate_limit_snapshot_unattributable",
1016
+ request_id = %request_id,
1017
+ path = %path_for_log,
1018
+ "rate-limit headers present but provider couldn't be inferred; skipping gauge emit"
1019
+ );
1020
+ }
1021
+
1022
+ // Stream response body back without buffering. Wrap errors so mid-stream
1023
+ // upstream failures are logged rather than silently truncating the client.
1024
+ //
1025
+ // PR-C1: when this is an SSE response, tee each chunk into a
1026
+ // bounded mpsc so the spawned state-machine task can update
1027
+ // telemetry without ever holding up the client. The mpsc is
1028
+ // bounded; if the parser falls behind, `try_send` fails and we
1029
+ // log + drop — the byte path is not affected. This is the
1030
+ // explicit "never block on parser readiness" contract.
1031
+ let rid = request_id.clone();
1032
+ let parser_tx = if !matches!(sse_kind, SseStreamKind::None) {
1033
+ let (tx, rx) = tokio::sync::mpsc::channel::<bytes::Bytes>(SSE_PARSER_QUEUE_DEPTH);
1034
+ let rid_for_parser = request_id.clone();
1035
+ tokio::spawn(run_sse_state_machine(sse_kind, rx, rid_for_parser));
1036
+ Some(tx)
1037
+ } else {
1038
+ None
1039
+ };
1040
+ let resp_stream = upstream_resp.bytes_stream().map(move |r| match r {
1041
+ Ok(b) => {
1042
+ if let Some(tx) = &parser_tx {
1043
+ // Best-effort tee. Bounded channel; the state
1044
+ // machine never blocks the client byte path.
1045
+ if let Err(e) = tx.try_send(b.clone()) {
1046
+ tracing::debug!(
1047
+ request_id = %rid,
1048
+ error = %e,
1049
+ "sse parser queue full or closed; skipping telemetry chunk"
1050
+ );
1051
+ }
1052
+ }
1053
+ Ok(b)
1054
+ }
1055
+ Err(e) => {
1056
+ tracing::warn!(request_id = %rid, error = %e, "upstream stream error mid-response");
1057
+ Err(e)
1058
+ }
1059
+ });
1060
+ let body = Body::from_stream(resp_stream);
1061
+
1062
+ let mut response = Response::builder().status(status);
1063
+ {
1064
+ let h = response.headers_mut().expect("builder has headers");
1065
+ h.extend(resp_headers);
1066
+ // Echo X-Request-Id back to the client.
1067
+ if let Ok(v) = http::HeaderValue::from_str(&request_id) {
1068
+ h.insert(HeaderName::from_static("x-request-id"), v);
1069
+ }
1070
+ // PR-A8 / P5-57: surface the upstream id in a distinct
1071
+ // header so it's never conflated with the proxy's own.
1072
+ if let Some(uid) = upstream_request_id.as_deref() {
1073
+ if let Ok(v) = http::HeaderValue::from_str(uid) {
1074
+ h.insert(HeaderName::from_static("headroom-upstream-request-id"), v);
1075
+ }
1076
+ }
1077
+ }
1078
+ let response = response
1079
+ .body(body)
1080
+ .map_err(|e| ProxyError::InvalidHeader(e.to_string()))?;
1081
+
1082
+ tracing::info!(
1083
+ request_id = %request_id,
1084
+ upstream_request_id = upstream_request_id.as_deref().unwrap_or(""),
1085
+ upstream_request_id_anthropic =
1086
+ upstream_request_id_anthropic.as_deref().unwrap_or(""),
1087
+ upstream_request_id_openai =
1088
+ upstream_request_id_openai.as_deref().unwrap_or(""),
1089
+ method = %method,
1090
+ path = %path_for_log,
1091
+ upstream_status = upstream_status.as_u16(),
1092
+ latency_ms = start.elapsed().as_millis() as u64,
1093
+ protocol = "http",
1094
+ "forwarded"
1095
+ );
1096
+
1097
+ Ok(response)
1098
+ }
1099
+
1100
+ /// Bound on the in-flight queue between the byte-passthrough and the
1101
+ /// SSE state-machine task. Picked so that under steady-state streaming
1102
+ /// load (~5 events/100ms typical) the parser is never blocked on
1103
+ /// queue space, yet a stalled parser can't grow memory unboundedly.
1104
+ /// Tunable via `proxy.toml` if a deployment finds this insufficient.
1105
+ const SSE_PARSER_QUEUE_DEPTH: usize = 256;
1106
+
1107
+ /// Which provider's state machine should run on this stream. Picked
1108
+ /// from the *request* path because the response content-type
1109
+ /// (`text/event-stream`) is identical across providers.
1110
+ #[derive(Debug, Clone, Copy)]
1111
+ enum SseStreamKind {
1112
+ None,
1113
+ Anthropic,
1114
+ OpenAiChat,
1115
+ OpenAiResponses,
1116
+ }
1117
+
1118
+ impl SseStreamKind {
1119
+ fn for_request_path(path: &str) -> Self {
1120
+ match path {
1121
+ "/v1/messages" => Self::Anthropic,
1122
+ "/v1/chat/completions" => Self::OpenAiChat,
1123
+ "/v1/responses" => Self::OpenAiResponses,
1124
+ // No telemetry parser registered for this endpoint.
1125
+ // We still pass bytes through unchanged.
1126
+ _ => Self::None,
1127
+ }
1128
+ }
1129
+ }
1130
+
1131
+ /// True if the upstream response is an SSE stream. Compares
1132
+ /// `content-type` against `text/event-stream` (with optional
1133
+ /// parameters). RFC 7231 §3.1.1.1: media types compare
1134
+ /// case-insensitive on the type/subtype tokens.
1135
+ fn is_sse_response(headers: &http::HeaderMap) -> bool {
1136
+ headers
1137
+ .get(http::header::CONTENT_TYPE)
1138
+ .and_then(|v| v.to_str().ok())
1139
+ .map(|s| {
1140
+ let media_type = s.split(';').next().unwrap_or("").trim();
1141
+ media_type.eq_ignore_ascii_case("text/event-stream")
1142
+ })
1143
+ .unwrap_or(false)
1144
+ }
1145
+
1146
+ /// PR-E4: OpenAI `prompt_cache_key` auto-injection helper.
1147
+ ///
1148
+ /// Gates on [`AuthMode::Payg`] and the in-body
1149
+ /// `prompt_cache_key` skip rule, parses the body once, mutates if
1150
+ /// appropriate, and re-serialises. Returns the original `body` on
1151
+ /// any non-applicable path — every error / skip leaves the bytes
1152
+ /// untouched (Phase A passthrough invariant).
1153
+ ///
1154
+ /// Logs `e4_skipped` for each skip reason and `e4_applied` with
1155
+ /// only the first [`KEY_PREFIX_LOG_LEN`] hex chars of the key
1156
+ /// (never the full key, which is identifying material).
1157
+ ///
1158
+ /// [`KEY_PREFIX_LOG_LEN`]: cache_stabilization::openai_cache_key::KEY_PREFIX_LOG_LEN
1159
+ fn maybe_inject_openai_prompt_cache_key(
1160
+ body: bytes::Bytes,
1161
+ shape: cache_stabilization::openai_cache_key::OpenAiShape,
1162
+ auth_mode: AuthMode,
1163
+ request_id: &str,
1164
+ path: &str,
1165
+ ) -> bytes::Bytes {
1166
+ use cache_stabilization::openai_cache_key::{
1167
+ inject_prompt_cache_key, InjectOutcome, SkipReason,
1168
+ };
1169
+
1170
+ // Auth-mode gate: only PAYG bodies are eligible. OAuth /
1171
+ // Subscription requests pass through byte-equal — synthesised
1172
+ // cache keys would look like cache-evasion to the upstream
1173
+ // and could void OAuth scopes pinned to `(account, model,
1174
+ // session)`.
1175
+ if !matches!(auth_mode, AuthMode::Payg) {
1176
+ tracing::info!(
1177
+ event = "e4_skipped",
1178
+ request_id = %request_id,
1179
+ path = %path,
1180
+ reason = "auth_mode",
1181
+ auth_mode = auth_mode.as_str(),
1182
+ "PR-E4: skipped prompt_cache_key injection (non-PAYG auth mode)"
1183
+ );
1184
+ return body;
1185
+ }
1186
+
1187
+ // Parse for the inject step. Failure here is silent — the
1188
+ // dispatcher above already logged the parse outcome on its
1189
+ // own decision path; we don't want to double-log. The body
1190
+ // round-trips unchanged.
1191
+ let mut parsed: serde_json::Value = match serde_json::from_slice(&body) {
1192
+ Ok(v) => v,
1193
+ Err(_) => {
1194
+ return body;
1195
+ }
1196
+ };
1197
+
1198
+ match inject_prompt_cache_key(&mut parsed, shape) {
1199
+ InjectOutcome::Applied { key_prefix } => {
1200
+ // Re-serialise. If serialization fails (would be very
1201
+ // unusual — we just successfully parsed), fall back
1202
+ // to the original bytes. No-silent-fallback rule: log
1203
+ // it loudly so a regression can't hide.
1204
+ match serde_json::to_vec(&parsed) {
1205
+ Ok(buf) => {
1206
+ tracing::info!(
1207
+ event = "e4_applied",
1208
+ request_id = %request_id,
1209
+ path = %path,
1210
+ key_prefix = %key_prefix,
1211
+ body_bytes_in = body.len(),
1212
+ body_bytes_out = buf.len(),
1213
+ "PR-E4: injected prompt_cache_key"
1214
+ );
1215
+ bytes::Bytes::from(buf)
1216
+ }
1217
+ Err(e) => {
1218
+ tracing::error!(
1219
+ event = "e4_serialize_error",
1220
+ request_id = %request_id,
1221
+ path = %path,
1222
+ error = %e,
1223
+ "PR-E4: re-serialize after injection failed; forwarding original bytes"
1224
+ );
1225
+ body
1226
+ }
1227
+ }
1228
+ }
1229
+ InjectOutcome::Skipped { reason } => {
1230
+ // Log only the customer-visible KeyPresent skip; the
1231
+ // NotAnObject skip is structurally impossible past
1232
+ // the dispatcher gate but is surfaced separately for
1233
+ // operators chasing pathological inputs.
1234
+ match reason {
1235
+ SkipReason::KeyPresent => {
1236
+ tracing::info!(
1237
+ event = "e4_skipped",
1238
+ request_id = %request_id,
1239
+ path = %path,
1240
+ reason = SkipReason::KeyPresent.as_str(),
1241
+ "PR-E4: skipped prompt_cache_key injection (customer-set value preserved)"
1242
+ );
1243
+ }
1244
+ SkipReason::NotAnObject => {
1245
+ tracing::warn!(
1246
+ event = "e4_skipped",
1247
+ request_id = %request_id,
1248
+ path = %path,
1249
+ reason = SkipReason::NotAnObject.as_str(),
1250
+ "PR-E4: body is not a JSON object; passthrough"
1251
+ );
1252
+ }
1253
+ }
1254
+ body
1255
+ }
1256
+ }
1257
+ }
1258
+
1259
+ /// Drive the per-provider state machine over a stream of byte chunks.
1260
+ /// Lives in its own task; the byte path never waits on it.
1261
+ async fn run_sse_state_machine(
1262
+ kind: SseStreamKind,
1263
+ mut rx: tokio::sync::mpsc::Receiver<bytes::Bytes>,
1264
+ request_id: String,
1265
+ ) {
1266
+ use crate::sse::framing::SseFramer;
1267
+
1268
+ let mut framer = SseFramer::new();
1269
+ // The state machines are different types; rather than introducing
1270
+ // a trait object dance, run each variant in its own arm. The dead
1271
+ // branches compile out cleanly and the hot path stays monomorphic.
1272
+ match kind {
1273
+ SseStreamKind::Anthropic => {
1274
+ let mut state = crate::sse::anthropic::AnthropicStreamState::new();
1275
+ while let Some(chunk) = rx.recv().await {
1276
+ framer.push(&chunk);
1277
+ while let Some(ev_result) = framer.next_event() {
1278
+ match ev_result {
1279
+ Ok(ev) => {
1280
+ if let Err(e) = state.apply(ev) {
1281
+ tracing::warn!(
1282
+ request_id = %request_id,
1283
+ error = %e,
1284
+ "sse anthropic state-machine apply error"
1285
+ );
1286
+ }
1287
+ }
1288
+ Err(e) => {
1289
+ tracing::warn!(
1290
+ request_id = %request_id,
1291
+ error = %e,
1292
+ "sse framer error"
1293
+ );
1294
+ }
1295
+ }
1296
+ }
1297
+ }
1298
+ // Phase G PR-G3 + H2: emit per-session cache-hit-rate
1299
+ // ONLY when the stream completed cleanly with
1300
+ // `message_stop`. The gate is encapsulated by the
1301
+ // pure function `compute_anthropic_session_hit_rate`
1302
+ // so the H2 contract has a unit-testable surface.
1303
+ match crate::observability::cache_hit_rate::compute_anthropic_session_hit_rate(&state) {
1304
+ Some(rate) => {
1305
+ crate::observability::observe_cache_hit_rate(
1306
+ crate::observability::cache_hit_rate_provider::ANTHROPIC,
1307
+ &request_id,
1308
+ rate,
1309
+ );
1310
+ }
1311
+ None => {
1312
+ tracing::debug!(
1313
+ event = "cache_hit_rate_skipped",
1314
+ request_id = %request_id,
1315
+ provider = "anthropic",
1316
+ status = ?state.status,
1317
+ input_tokens = state.usage.input_tokens,
1318
+ cache_read_input_tokens = state.usage.cache_read_input_tokens,
1319
+ cache_creation_input_tokens = state.usage.cache_creation_input_tokens,
1320
+ "skipping proxy_cache_hit_rate_per_session: H2 gate or zero denominator"
1321
+ );
1322
+ }
1323
+ }
1324
+ tracing::info!(
1325
+ request_id = %request_id,
1326
+ provider = "anthropic",
1327
+ input_tokens = state.usage.input_tokens,
1328
+ output_tokens = state.usage.output_tokens,
1329
+ cache_creation_input_tokens = state.usage.cache_creation_input_tokens,
1330
+ cache_read_input_tokens = state.usage.cache_read_input_tokens,
1331
+ stop_reason = state.stop_reason.as_deref().unwrap_or(""),
1332
+ blocks = state.blocks.len(),
1333
+ "sse stream closed"
1334
+ );
1335
+ }
1336
+ SseStreamKind::OpenAiChat => {
1337
+ let mut state = crate::sse::openai_chat::ChunkState::new();
1338
+ while let Some(chunk) = rx.recv().await {
1339
+ framer.push(&chunk);
1340
+ while let Some(ev_result) = framer.next_event() {
1341
+ match ev_result {
1342
+ Ok(ev) => {
1343
+ if let Err(e) = state.apply(ev) {
1344
+ tracing::warn!(
1345
+ request_id = %request_id,
1346
+ error = %e,
1347
+ "sse openai_chat state-machine apply error"
1348
+ );
1349
+ }
1350
+ }
1351
+ Err(e) => {
1352
+ tracing::warn!(
1353
+ request_id = %request_id,
1354
+ error = %e,
1355
+ "sse framer error"
1356
+ );
1357
+ }
1358
+ }
1359
+ }
1360
+ }
1361
+ // Phase G PR-G3: emit cache-hit-rate from the final usage
1362
+ // chunk. OpenAI only emits this when
1363
+ // `stream_options.include_usage = true`; absence is a
1364
+ // signal, not a fallback condition — `usage = None` →
1365
+ // skip. The H2 gate is implicit here: the final usage
1366
+ // chunk only arrives when the stream completed (it's
1367
+ // OpenAI's terminal-status equivalent).
1368
+ if let Some(usage) = &state.usage {
1369
+ let input_tokens = usage
1370
+ .get("prompt_tokens")
1371
+ .and_then(|v| v.as_u64())
1372
+ .unwrap_or(0);
1373
+ let cached_tokens = usage
1374
+ .get("prompt_tokens_details")
1375
+ .and_then(|d| d.get("cached_tokens"))
1376
+ .and_then(|v| v.as_u64())
1377
+ .unwrap_or(0);
1378
+ // M1: `cached_tokens > input_tokens` is a wire-
1379
+ // format pathology — log + skip instead of silently
1380
+ // clamping (saturating_sub would yield 0 → fake 1.0
1381
+ // hit-rate sample).
1382
+ if cached_tokens > input_tokens {
1383
+ tracing::warn!(
1384
+ event = "cache_hit_rate_skipped",
1385
+ request_id = %request_id,
1386
+ provider = "openai_chat",
1387
+ reason = "cached_gt_input",
1388
+ input_tokens = input_tokens,
1389
+ cached_tokens = cached_tokens,
1390
+ "skipping proxy_cache_hit_rate_per_session: cached_tokens > prompt_tokens \
1391
+ (wire-format pathology; clamping would synthesise a bad sample)"
1392
+ );
1393
+ } else {
1394
+ // OpenAI's `prompt_tokens` already INCLUDES cached
1395
+ // tokens (per Chat Completions API docs), so the
1396
+ // denominator is `prompt_tokens`, not the sum. The
1397
+ // numerator is `cached_tokens`; `input_tokens` arg
1398
+ // to `compute_cache_hit_rate` carries the
1399
+ // *non-cached* portion (denom-only), so we
1400
+ // synthesise that here.
1401
+ let non_cached = input_tokens - cached_tokens;
1402
+ match crate::observability::compute_cache_hit_rate(non_cached, cached_tokens, 0)
1403
+ {
1404
+ Some(rate) => {
1405
+ crate::observability::observe_cache_hit_rate(
1406
+ crate::observability::cache_hit_rate_provider::OPENAI_CHAT,
1407
+ &request_id,
1408
+ rate,
1409
+ );
1410
+ }
1411
+ None => {
1412
+ tracing::debug!(
1413
+ event = "cache_hit_rate_skipped",
1414
+ request_id = %request_id,
1415
+ provider = "openai_chat",
1416
+ reason = "zero_denominator",
1417
+ "skipping proxy_cache_hit_rate_per_session: no input tokens"
1418
+ );
1419
+ }
1420
+ }
1421
+ }
1422
+ } else {
1423
+ tracing::debug!(
1424
+ event = "cache_hit_rate_skipped",
1425
+ request_id = %request_id,
1426
+ provider = "openai_chat",
1427
+ reason = "no_usage_chunk",
1428
+ "skipping proxy_cache_hit_rate_per_session: stream_options.include_usage=false"
1429
+ );
1430
+ }
1431
+ tracing::info!(
1432
+ request_id = %request_id,
1433
+ provider = "openai_chat",
1434
+ choices = state.choices.len(),
1435
+ has_usage = state.usage.is_some(),
1436
+ "sse stream closed"
1437
+ );
1438
+ }
1439
+ SseStreamKind::OpenAiResponses => {
1440
+ let mut state = crate::sse::openai_responses::ResponseState::new();
1441
+ while let Some(chunk) = rx.recv().await {
1442
+ framer.push(&chunk);
1443
+ while let Some(ev_result) = framer.next_event() {
1444
+ match ev_result {
1445
+ Ok(ev) => {
1446
+ if let Err(e) = state.apply(ev) {
1447
+ tracing::warn!(
1448
+ request_id = %request_id,
1449
+ error = %e,
1450
+ "sse openai_responses state-machine apply error"
1451
+ );
1452
+ }
1453
+ }
1454
+ Err(e) => {
1455
+ tracing::warn!(
1456
+ request_id = %request_id,
1457
+ error = %e,
1458
+ "sse framer error"
1459
+ );
1460
+ }
1461
+ }
1462
+ }
1463
+ }
1464
+ // Phase G PR-G3 + H2: cache hit rate + service_tier +
1465
+ // response status emit ONLY when the stream reached a
1466
+ // terminal status (`response.completed/failed/incomplete`).
1467
+ // Mid-stream client disconnects close the channel without
1468
+ // a terminal — `terminal_status().is_none()` then guards
1469
+ // emit so we don't observe garbage samples.
1470
+ //
1471
+ // The Responses API uses `input_tokens` /
1472
+ // `cached_input_tokens` shape (Responses-specific —
1473
+ // distinct from Chat Completions' `prompt_tokens`).
1474
+ let stream_completed = state.terminal_status().is_some();
1475
+ if stream_completed {
1476
+ if let Some(usage) = &state.usage {
1477
+ let input_tokens = usage
1478
+ .get("input_tokens")
1479
+ .and_then(|v| v.as_u64())
1480
+ .unwrap_or(0);
1481
+ let cached_tokens = usage
1482
+ .get("input_tokens_details")
1483
+ .and_then(|d| d.get("cached_tokens"))
1484
+ .and_then(|v| v.as_u64())
1485
+ .unwrap_or(0);
1486
+ // M1: a cached count greater than input is a
1487
+ // wire-format pathology — usage shouldn't have
1488
+ // `cached > input` for OpenAI Responses. Per
1489
+ // "no silent fallbacks", log + skip the emit
1490
+ // instead of silently clamping.
1491
+ if cached_tokens > input_tokens {
1492
+ tracing::warn!(
1493
+ event = "cache_hit_rate_skipped",
1494
+ request_id = %request_id,
1495
+ provider = "openai_responses",
1496
+ reason = "cached_gt_input",
1497
+ input_tokens = input_tokens,
1498
+ cached_tokens = cached_tokens,
1499
+ "skipping proxy_cache_hit_rate_per_session: cached_tokens > input_tokens \
1500
+ (wire-format pathology; clamping would synthesise a bad sample)"
1501
+ );
1502
+ } else {
1503
+ // Like Chat, `input_tokens` already INCLUDES cached
1504
+ // tokens, so split for the helper.
1505
+ let non_cached = input_tokens - cached_tokens;
1506
+ match crate::observability::compute_cache_hit_rate(
1507
+ non_cached,
1508
+ cached_tokens,
1509
+ 0,
1510
+ ) {
1511
+ Some(rate) => {
1512
+ crate::observability::observe_cache_hit_rate(
1513
+ crate::observability::cache_hit_rate_provider::OPENAI_RESPONSES,
1514
+ &request_id,
1515
+ rate,
1516
+ );
1517
+ }
1518
+ None => {
1519
+ tracing::debug!(
1520
+ event = "cache_hit_rate_skipped",
1521
+ request_id = %request_id,
1522
+ provider = "openai_responses",
1523
+ reason = "zero_denominator",
1524
+ "skipping proxy_cache_hit_rate_per_session: no input tokens"
1525
+ );
1526
+ }
1527
+ }
1528
+ }
1529
+ }
1530
+ } else {
1531
+ tracing::debug!(
1532
+ event = "cache_hit_rate_skipped",
1533
+ request_id = %request_id,
1534
+ provider = "openai_responses",
1535
+ reason = "stream_did_not_complete",
1536
+ "skipping proxy_cache_hit_rate_per_session: no terminal status seen"
1537
+ );
1538
+ }
1539
+ // Service tier + status are sourced from
1540
+ // `state.last_response_envelope` populated by the
1541
+ // ResponseState on `response.completed/failed/incomplete`.
1542
+ //
1543
+ // C1 fix: the tier value comes from the upstream response
1544
+ // body; even though the upstream is more trustworthy than
1545
+ // a client-side header, an unrecognised value would still
1546
+ // grow the metric vector unboundedly. We bucket through
1547
+ // the same validator the request-side handler uses.
1548
+ if let Some(tier) = state.service_tier.as_deref() {
1549
+ let bucketed = crate::observability::metric_names::service_tier::validate(tier);
1550
+ crate::observability::record_service_tier(bucketed, &request_id);
1551
+ }
1552
+ if let Some(status) = state.terminal_status() {
1553
+ crate::observability::record_response_status(
1554
+ status,
1555
+ state.incomplete_reason.as_deref(),
1556
+ &request_id,
1557
+ );
1558
+ }
1559
+ tracing::info!(
1560
+ request_id = %request_id,
1561
+ provider = "openai_responses",
1562
+ items = state.items.len(),
1563
+ has_usage = state.usage.is_some(),
1564
+ service_tier = state.service_tier.as_deref().unwrap_or(""),
1565
+ terminal_status = state.terminal_status().unwrap_or(""),
1566
+ incomplete_reason = state.incomplete_reason.as_deref().unwrap_or(""),
1567
+ "sse stream closed"
1568
+ );
1569
+ }
1570
+ SseStreamKind::None => {}
1571
+ }
1572
+ }
1573
+
1574
+ fn ensure_request_id(headers: &HeaderMap) -> String {
1575
+ headers
1576
+ .get("x-request-id")
1577
+ .and_then(|v| v.to_str().ok())
1578
+ .map(|s| s.to_string())
1579
+ .unwrap_or_else(|| uuid::Uuid::new_v4().to_string())
1580
+ }
1581
+
1582
+ /// Test-only helper: drain a body to bytes (uses BodyExt).
1583
+ #[cfg(test)]
1584
+ pub async fn body_to_bytes(body: Body) -> Result<Bytes, axum::Error> {
1585
+ use axum::Error;
1586
+ body.collect()
1587
+ .await
1588
+ .map(|c| c.to_bytes())
1589
+ .map_err(Error::new)
1590
+ }
1591
+
1592
+ #[cfg(test)]
1593
+ mod tests {
1594
+ use super::*;
1595
+
1596
+ #[test]
1597
+ fn url_build_basic() {
1598
+ let base: url::Url = "http://up:8080".parse().unwrap();
1599
+ let uri: Uri = "/v1/messages?stream=true".parse().unwrap();
1600
+ let out = build_upstream_url(&base, &uri).unwrap();
1601
+ assert_eq!(out.as_str(), "http://up:8080/v1/messages?stream=true");
1602
+ }
1603
+
1604
+ #[test]
1605
+ fn url_build_with_base_path() {
1606
+ let base: url::Url = "http://up:8080/api".parse().unwrap();
1607
+ let uri: Uri = "/v1/messages".parse().unwrap();
1608
+ let out = build_upstream_url(&base, &uri).unwrap();
1609
+ assert_eq!(out.as_str(), "http://up:8080/api/v1/messages");
1610
+ }
1611
+
1612
+ #[test]
1613
+ fn url_build_root() {
1614
+ let base: url::Url = "http://up:8080/".parse().unwrap();
1615
+ let uri: Uri = "/".parse().unwrap();
1616
+ let out = build_upstream_url(&base, &uri).unwrap();
1617
+ assert_eq!(out.as_str(), "http://up:8080/");
1618
+ }
1619
+ }