xithead 1.5.0 → 1.5.1

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 (649) hide show
  1. package/design-system/README.md +80 -0
  2. package/package.json +20 -1
  3. package/public/apple-touch-icon.png +0 -0
  4. package/public/logo-transparent.png +0 -0
  5. package/public/xithead.ps1 +937 -0
  6. package/scripts/README.md +77 -0
  7. package/scripts/audit_wheel_glibc_symbols.py +217 -0
  8. package/scripts/build-master-design-system.cjs +33 -0
  9. package/scripts/build_rust_extension.sh +58 -0
  10. package/scripts/changelog-gen.py +203 -0
  11. package/scripts/eval_output_shaper.py +235 -0
  12. package/scripts/export_kompress_v2_onnx.py +267 -0
  13. package/scripts/fixtures/anthropic_replay_body.json +133 -0
  14. package/scripts/fixtures/codex_response_create_frame.json +52 -0
  15. package/scripts/install-git-hooks.sh +104 -0
  16. package/scripts/install.ps1 +1809 -0
  17. package/scripts/install.sh +1673 -0
  18. package/scripts/pr-governance.py +297 -0
  19. package/scripts/record_fixtures.py +59 -0
  20. package/scripts/refresh_model_limits.sh +48 -0
  21. package/scripts/replay_codex_ws_load.py +445 -0
  22. package/scripts/repro_codex_replay.py +699 -0
  23. package/scripts/smoke_issue_327.py +233 -0
  24. package/scripts/sync-plugin-versions.py +116 -0
  25. package/scripts/tests/test_changelog_gen.py +302 -0
  26. package/scripts/tests/test_pr_governance.py +163 -0
  27. package/scripts/tests/test_pr_health_labels.py +94 -0
  28. package/scripts/tests/test_pr_health_workflow.py +14 -0
  29. package/scripts/tests/test_sync_plugin_versions.py +131 -0
  30. package/scripts/tests/test_version_sync.py +291 -0
  31. package/scripts/validate-workflows.sh +39 -0
  32. package/scripts/verify-versions.py +106 -0
  33. package/scripts/version-sync.py +207 -0
  34. package/tailwind.config.js +31 -0
  35. package/tsconfig.json +84 -0
  36. package/.actrc +0 -14
  37. package/.actrc.local.example +0 -15
  38. package/.changelog.md +0 -2
  39. package/.claude/agents/academic-anthropologist.md +0 -125
  40. package/.claude/agents/academic-geographer.md +0 -127
  41. package/.claude/agents/academic-historian.md +0 -123
  42. package/.claude/agents/academic-narratologist.md +0 -118
  43. package/.claude/agents/academic-psychologist.md +0 -118
  44. package/.claude/agents/academic-statistician.md +0 -144
  45. package/.claude/agents/accounts-payable-agent.md +0 -205
  46. package/.claude/agents/agentic-identity-trust.md +0 -394
  47. package/.claude/agents/agents-orchestrator.md +0 -367
  48. package/.claude/agents/automation-governance-architect.md +0 -216
  49. package/.claude/agents/blender-addon-engineer.md +0 -243
  50. package/.claude/agents/business-strategist.md +0 -488
  51. package/.claude/agents/change-management-consultant.md +0 -497
  52. package/.claude/agents/chief-financial-officer.md +0 -388
  53. package/.claude/agents/corporate-training-designer.md +0 -192
  54. package/.claude/agents/customer-service.md +0 -398
  55. package/.claude/agents/customer-success-manager.md +0 -460
  56. package/.claude/agents/data-consolidation-agent.md +0 -60
  57. package/.claude/agents/data-privacy-officer.md +0 -412
  58. package/.claude/agents/design-brand-guardian.md +0 -322
  59. package/.claude/agents/design-image-prompt-engineer.md +0 -236
  60. package/.claude/agents/design-inclusive-visuals-specialist.md +0 -73
  61. package/.claude/agents/design-persona-walkthrough.md +0 -272
  62. package/.claude/agents/design-ui-designer.md +0 -386
  63. package/.claude/agents/design-ui-finish-gate-reviewer.md +0 -217
  64. package/.claude/agents/design-ux-architect.md +0 -482
  65. package/.claude/agents/design-ux-researcher.md +0 -329
  66. package/.claude/agents/design-visual-storyteller.md +0 -149
  67. package/.claude/agents/design-whimsy-injector.md +0 -460
  68. package/.claude/agents/economy-designer.md +0 -156
  69. package/.claude/agents/engineering-ai-data-remediation-engineer.md +0 -211
  70. package/.claude/agents/engineering-ai-engineer.md +0 -146
  71. package/.claude/agents/engineering-api-platform-engineer.md +0 -181
  72. package/.claude/agents/engineering-ats-validator-architect.md +0 -383
  73. package/.claude/agents/engineering-autonomous-optimization-architect.md +0 -121
  74. package/.claude/agents/engineering-backend-architect.md +0 -255
  75. package/.claude/agents/engineering-china-network-engineer.md +0 -252
  76. package/.claude/agents/engineering-cms-developer.md +0 -536
  77. package/.claude/agents/engineering-code-reviewer.md +0 -76
  78. package/.claude/agents/engineering-codebase-onboarding-engineer.md +0 -173
  79. package/.claude/agents/engineering-data-engineer.md +0 -349
  80. package/.claude/agents/engineering-data-visualization-engineer.md +0 -151
  81. package/.claude/agents/engineering-database-optimizer.md +0 -188
  82. package/.claude/agents/engineering-database-reliability-engineer.md +0 -201
  83. package/.claude/agents/engineering-desktop-app-engineer.md +0 -209
  84. package/.claude/agents/engineering-developer-tooling-engineer.md +0 -153
  85. package/.claude/agents/engineering-devops-automator.md +0 -385
  86. package/.claude/agents/engineering-drupal-performance.md +0 -347
  87. package/.claude/agents/engineering-drupal-shopping-cart.md +0 -360
  88. package/.claude/agents/engineering-electrical-engineer.md +0 -575
  89. package/.claude/agents/engineering-email-intelligence-engineer.md +0 -390
  90. package/.claude/agents/engineering-embedded-firmware-engineer.md +0 -196
  91. package/.claude/agents/engineering-feishu-integration-developer.md +0 -606
  92. package/.claude/agents/engineering-filament-optimization-specialist.md +0 -283
  93. package/.claude/agents/engineering-finops-engineer.md +0 -164
  94. package/.claude/agents/engineering-frontend-developer.md +0 -257
  95. package/.claude/agents/engineering-gaussdb-expert.md +0 -334
  96. package/.claude/agents/engineering-git-workflow-master.md +0 -98
  97. package/.claude/agents/engineering-i18n-engineer.md +0 -214
  98. package/.claude/agents/engineering-identity-access-engineer.md +0 -217
  99. package/.claude/agents/engineering-incident-response-commander.md +0 -444
  100. package/.claude/agents/engineering-iot-fleet-engineer.md +0 -148
  101. package/.claude/agents/engineering-it-service-manager.md +0 -561
  102. package/.claude/agents/engineering-knowledge-graph-engineer.md +0 -372
  103. package/.claude/agents/engineering-llm-post-training-engineer.md +0 -166
  104. package/.claude/agents/engineering-minimal-change-engineer.md +0 -207
  105. package/.claude/agents/engineering-mobile-app-builder.md +0 -493
  106. package/.claude/agents/engineering-mobile-release-engineer.md +0 -164
  107. package/.claude/agents/engineering-multi-agent-systems-architect.md +0 -600
  108. package/.claude/agents/engineering-network-engineer.md +0 -245
  109. package/.claude/agents/engineering-orgscript-engineer.md +0 -113
  110. package/.claude/agents/engineering-payments-billing-engineer.md +0 -228
  111. package/.claude/agents/engineering-pdf-engine-architect.md +0 -696
  112. package/.claude/agents/engineering-platform-engineer.md +0 -270
  113. package/.claude/agents/engineering-privacy-engineer.md +0 -152
  114. package/.claude/agents/engineering-prompt-engineer.md +0 -209
  115. package/.claude/agents/engineering-rag-pipeline-engineer.md +0 -450
  116. package/.claude/agents/engineering-rapid-prototyper.md +0 -466
  117. package/.claude/agents/engineering-realtime-collaboration-engineer.md +0 -200
  118. package/.claude/agents/engineering-rust-refactoring-specialist.md +0 -313
  119. package/.claude/agents/engineering-search-relevance-engineer.md +0 -237
  120. package/.claude/agents/engineering-section-508-specialist.md +0 -339
  121. package/.claude/agents/engineering-senior-developer.md +0 -176
  122. package/.claude/agents/engineering-servicenow-developer-mentor.md +0 -180
  123. package/.claude/agents/engineering-software-architect.md +0 -112
  124. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +0 -522
  125. package/.claude/agents/engineering-sre.md +0 -90
  126. package/.claude/agents/engineering-technical-writer.md +0 -393
  127. package/.claude/agents/engineering-universal-document-compiler.md +0 -370
  128. package/.claude/agents/engineering-uswds-developer.md +0 -340
  129. package/.claude/agents/engineering-video-streaming-engineer.md +0 -151
  130. package/.claude/agents/engineering-voice-ai-integration-engineer.md +0 -584
  131. package/.claude/agents/engineering-webassembly-engineer.md +0 -153
  132. package/.claude/agents/engineering-wechat-mini-program-developer.md +0 -356
  133. package/.claude/agents/engineering-wordpress-performance.md +0 -346
  134. package/.claude/agents/engineering-wordpress-shopping-cart.md +0 -346
  135. package/.claude/agents/esg-sustainability-officer.md +0 -396
  136. package/.claude/agents/finance-bookkeeper-controller.md +0 -260
  137. package/.claude/agents/finance-financial-analyst.md +0 -234
  138. package/.claude/agents/finance-fpa-analyst.md +0 -263
  139. package/.claude/agents/finance-investment-researcher.md +0 -272
  140. package/.claude/agents/finance-tax-strategist.md +0 -239
  141. package/.claude/agents/game-audio-engineer.md +0 -264
  142. package/.claude/agents/game-designer.md +0 -167
  143. package/.claude/agents/gis-3d-scene-developer.md +0 -111
  144. package/.claude/agents/gis-analyst.md +0 -91
  145. package/.claude/agents/gis-bim-specialist.md +0 -108
  146. package/.claude/agents/gis-cartography-designer.md +0 -150
  147. package/.claude/agents/gis-drone-reality-mapping.md +0 -120
  148. package/.claude/agents/gis-geoai-ml-engineer.md +0 -105
  149. package/.claude/agents/gis-geoprocessing-specialist.md +0 -97
  150. package/.claude/agents/gis-qa-engineer.md +0 -133
  151. package/.claude/agents/gis-solution-engineer.md +0 -101
  152. package/.claude/agents/gis-spatial-data-engineer.md +0 -97
  153. package/.claude/agents/gis-spatial-data-scientist.md +0 -111
  154. package/.claude/agents/gis-technical-consultant.md +0 -86
  155. package/.claude/agents/gis-web-gis-developer.md +0 -108
  156. package/.claude/agents/godot-gameplay-scripter.md +0 -338
  157. package/.claude/agents/godot-multiplayer-engineer.md +0 -301
  158. package/.claude/agents/godot-shader-developer.md +0 -267
  159. package/.claude/agents/government-digital-presales-consultant.md +0 -363
  160. package/.claude/agents/grant-writer.md +0 -511
  161. package/.claude/agents/healthcare-aging-parent-care-companion.md +0 -414
  162. package/.claude/agents/healthcare-clinical-evidence-agent.md +0 -231
  163. package/.claude/agents/healthcare-customer-service.md +0 -389
  164. package/.claude/agents/healthcare-innovation-strategist.md +0 -433
  165. package/.claude/agents/healthcare-marketing-compliance.md +0 -395
  166. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +0 -312
  167. package/.claude/agents/hospitality-guest-services.md +0 -603
  168. package/.claude/agents/hr-onboarding.md +0 -451
  169. package/.claude/agents/identity-graph-operator.md +0 -303
  170. package/.claude/agents/language-translator.md +0 -264
  171. package/.claude/agents/legal-billing-time-tracking.md +0 -569
  172. package/.claude/agents/legal-client-intake.md +0 -492
  173. package/.claude/agents/legal-document-review.md +0 -454
  174. package/.claude/agents/level-designer.md +0 -208
  175. package/.claude/agents/loan-officer-assistant.md +0 -555
  176. package/.claude/agents/lsp-index-engineer.md +0 -320
  177. package/.claude/agents/ma-integration-manager.md +0 -427
  178. package/.claude/agents/macos-spatial-metal-engineer.md +0 -337
  179. package/.claude/agents/marketing-aeo-foundations.md +0 -264
  180. package/.claude/agents/marketing-agentic-search-optimizer.md +0 -279
  181. package/.claude/agents/marketing-ai-citation-strategist.md +0 -172
  182. package/.claude/agents/marketing-app-store-optimizer.md +0 -321
  183. package/.claude/agents/marketing-baidu-seo-specialist.md +0 -226
  184. package/.claude/agents/marketing-bilibili-content-strategist.md +0 -199
  185. package/.claude/agents/marketing-book-co-author.md +0 -110
  186. package/.claude/agents/marketing-carousel-growth-engine.md +0 -204
  187. package/.claude/agents/marketing-china-ecommerce-operator.md +0 -283
  188. package/.claude/agents/marketing-china-market-localization-strategist.md +0 -283
  189. package/.claude/agents/marketing-content-creator.md +0 -54
  190. package/.claude/agents/marketing-cross-border-ecommerce.md +0 -259
  191. package/.claude/agents/marketing-developer-community-builder.md +0 -285
  192. package/.claude/agents/marketing-douyin-strategist.md +0 -149
  193. package/.claude/agents/marketing-email-strategist.md +0 -249
  194. package/.claude/agents/marketing-global-podcast-strategist.md +0 -206
  195. package/.claude/agents/marketing-growth-hacker.md +0 -54
  196. package/.claude/agents/marketing-instagram-curator.md +0 -113
  197. package/.claude/agents/marketing-kuaishou-strategist.md +0 -223
  198. package/.claude/agents/marketing-linkedin-content-creator.md +0 -214
  199. package/.claude/agents/marketing-livestream-commerce-coach.md +0 -305
  200. package/.claude/agents/marketing-multi-platform-publisher.md +0 -217
  201. package/.claude/agents/marketing-podcast-strategist.md +0 -277
  202. package/.claude/agents/marketing-pr-communications-manager.md +0 -473
  203. package/.claude/agents/marketing-private-domain-operator.md +0 -308
  204. package/.claude/agents/marketing-reddit-community-builder.md +0 -123
  205. package/.claude/agents/marketing-seo-specialist.md +0 -370
  206. package/.claude/agents/marketing-short-video-editing-coach.md +0 -412
  207. package/.claude/agents/marketing-social-media-strategist.md +0 -125
  208. package/.claude/agents/marketing-tiktok-strategist.md +0 -125
  209. package/.claude/agents/marketing-twitter-engager.md +0 -126
  210. package/.claude/agents/marketing-video-optimization-specialist.md +0 -119
  211. package/.claude/agents/marketing-wechat-official-account.md +0 -145
  212. package/.claude/agents/marketing-weibo-strategist.md +0 -240
  213. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +0 -161
  214. package/.claude/agents/marketing-xiaohongshu-specialist.md +0 -138
  215. package/.claude/agents/marketing-zhihu-strategist.md +0 -162
  216. package/.claude/agents/medical-billing-coding-specialist.md +0 -491
  217. package/.claude/agents/narrative-designer.md +0 -243
  218. package/.claude/agents/operations-manager.md +0 -399
  219. package/.claude/agents/organizational-psychologist.md +0 -391
  220. package/.claude/agents/paid-media-auditor.md +0 -71
  221. package/.claude/agents/paid-media-creative-strategist.md +0 -71
  222. package/.claude/agents/paid-media-paid-social-strategist.md +0 -71
  223. package/.claude/agents/paid-media-ppc-strategist.md +0 -71
  224. package/.claude/agents/paid-media-programmatic-buyer.md +0 -71
  225. package/.claude/agents/paid-media-search-query-analyst.md +0 -71
  226. package/.claude/agents/paid-media-tracking-specialist.md +0 -71
  227. package/.claude/agents/personal-growth-mentor.md +0 -159
  228. package/.claude/agents/product-behavioral-nudge-engine.md +0 -83
  229. package/.claude/agents/product-dx-engineer.md +0 -332
  230. package/.claude/agents/product-feedback-synthesizer.md +0 -119
  231. package/.claude/agents/product-manager.md +0 -469
  232. package/.claude/agents/product-sprint-prioritizer.md +0 -154
  233. package/.claude/agents/product-trend-researcher.md +0 -159
  234. package/.claude/agents/project-management-experiment-tracker.md +0 -198
  235. package/.claude/agents/project-management-jira-workflow-steward.md +0 -233
  236. package/.claude/agents/project-management-meeting-notes-specialist.md +0 -95
  237. package/.claude/agents/project-management-project-shepherd.md +0 -194
  238. package/.claude/agents/project-management-studio-operations.md +0 -200
  239. package/.claude/agents/project-management-studio-producer.md +0 -203
  240. package/.claude/agents/project-manager-senior.md +0 -135
  241. package/.claude/agents/real-estate-buyer-seller.md +0 -596
  242. package/.claude/agents/recruitment-specialist.md +0 -515
  243. package/.claude/agents/report-distribution-agent.md +0 -65
  244. package/.claude/agents/research-synthesist.md +0 -136
  245. package/.claude/agents/resume-tailor.md +0 -230
  246. package/.claude/agents/retail-customer-returns.md +0 -566
  247. package/.claude/agents/roblox-avatar-creator.md +0 -297
  248. package/.claude/agents/roblox-experience-designer.md +0 -306
  249. package/.claude/agents/roblox-systems-scripter.md +0 -332
  250. package/.claude/agents/sales-account-strategist.md +0 -227
  251. package/.claude/agents/sales-coach.md +0 -271
  252. package/.claude/agents/sales-data-extraction-agent.md +0 -67
  253. package/.claude/agents/sales-deal-strategist.md +0 -180
  254. package/.claude/agents/sales-discovery-coach.md +0 -225
  255. package/.claude/agents/sales-engineer.md +0 -182
  256. package/.claude/agents/sales-offer-lead-gen-strategist.md +0 -257
  257. package/.claude/agents/sales-outbound-strategist.md +0 -201
  258. package/.claude/agents/sales-outreach.md +0 -425
  259. package/.claude/agents/sales-pipeline-analyst.md +0 -267
  260. package/.claude/agents/sales-proposal-strategist.md +0 -217
  261. package/.claude/agents/security-ai-generated-code-auditor.md +0 -207
  262. package/.claude/agents/security-appsec-engineer.md +0 -536
  263. package/.claude/agents/security-architect.md +0 -307
  264. package/.claude/agents/security-blockchain-security-auditor.md +0 -482
  265. package/.claude/agents/security-cloud-security-architect.md +0 -576
  266. package/.claude/agents/security-compliance-auditor.md +0 -158
  267. package/.claude/agents/security-incident-responder.md +0 -450
  268. package/.claude/agents/security-penetration-tester.md +0 -399
  269. package/.claude/agents/security-secrets-credential-engineer.md +0 -189
  270. package/.claude/agents/security-senior-secops.md +0 -760
  271. package/.claude/agents/security-threat-detection-engineer.md +0 -553
  272. package/.claude/agents/security-threat-intelligence-analyst.md +0 -661
  273. package/.claude/agents/specialized-chief-of-staff.md +0 -279
  274. package/.claude/agents/specialized-civil-engineer.md +0 -356
  275. package/.claude/agents/specialized-codebase-archaeologist.md +0 -341
  276. package/.claude/agents/specialized-cultural-intelligence-strategist.md +0 -88
  277. package/.claude/agents/specialized-developer-advocate.md +0 -317
  278. package/.claude/agents/specialized-document-generator.md +0 -55
  279. package/.claude/agents/specialized-fedramp-rmf-compliance.md +0 -378
  280. package/.claude/agents/specialized-focus-music-architect.md +0 -175
  281. package/.claude/agents/specialized-french-consulting-market.md +0 -194
  282. package/.claude/agents/specialized-korean-business-navigator.md +0 -216
  283. package/.claude/agents/specialized-master-plan-architect.md +0 -157
  284. package/.claude/agents/specialized-mcp-builder.md +0 -260
  285. package/.claude/agents/specialized-model-qa.md +0 -528
  286. package/.claude/agents/specialized-pricing-analyst.md +0 -243
  287. package/.claude/agents/specialized-salesforce-architect.md +0 -182
  288. package/.claude/agents/specialized-strategy-duel-agent.md +0 -130
  289. package/.claude/agents/specialized-workflow-architect.md +0 -597
  290. package/.claude/agents/study-abroad-advisor.md +0 -282
  291. package/.claude/agents/supply-chain-strategist.md +0 -591
  292. package/.claude/agents/support-analytics-reporter.md +0 -387
  293. package/.claude/agents/support-executive-summary-generator.md +0 -212
  294. package/.claude/agents/support-finance-tracker.md +0 -480
  295. package/.claude/agents/support-infrastructure-maintainer.md +0 -628
  296. package/.claude/agents/support-legal-compliance-checker.md +0 -591
  297. package/.claude/agents/support-support-responder.md +0 -607
  298. package/.claude/agents/technical-artist.md +0 -233
  299. package/.claude/agents/terminal-integration-specialist.md +0 -70
  300. package/.claude/agents/testing-accessibility-auditor.md +0 -327
  301. package/.claude/agents/testing-api-tester.md +0 -334
  302. package/.claude/agents/testing-evidence-collector.md +0 -210
  303. package/.claude/agents/testing-performance-benchmarker.md +0 -283
  304. package/.claude/agents/testing-reality-checker.md +0 -249
  305. package/.claude/agents/testing-test-automation-engineer.md +0 -196
  306. package/.claude/agents/testing-test-results-analyzer.md +0 -330
  307. package/.claude/agents/testing-tool-evaluator.md +0 -416
  308. package/.claude/agents/testing-workflow-optimizer.md +0 -463
  309. package/.claude/agents/unity-architect.md +0 -271
  310. package/.claude/agents/unity-editor-tool-developer.md +0 -310
  311. package/.claude/agents/unity-multiplayer-engineer.md +0 -323
  312. package/.claude/agents/unity-shader-graph-artist.md +0 -269
  313. package/.claude/agents/unreal-multiplayer-architect.md +0 -364
  314. package/.claude/agents/unreal-systems-engineer.md +0 -322
  315. package/.claude/agents/unreal-technical-artist.md +0 -256
  316. package/.claude/agents/unreal-world-builder.md +0 -273
  317. package/.claude/agents/visionos-spatial-engineer.md +0 -54
  318. package/.claude/agents/xr-cockpit-interaction-specialist.md +0 -32
  319. package/.claude/agents/xr-immersive-developer.md +0 -32
  320. package/.claude/agents/xr-interface-architect.md +0 -32
  321. package/.claude/agents/zk-steward.md +0 -211
  322. package/.claude-plugin/marketplace.json +0 -30
  323. package/.commitlintrc.json +0 -26
  324. package/.devcontainer/Dockerfile +0 -24
  325. package/.devcontainer/devcontainer.json +0 -70
  326. package/.devcontainer/docker-compose.memory.yml +0 -42
  327. package/.devcontainer/memory-stack/devcontainer.json +0 -84
  328. package/.devcontainer/post-create.sh +0 -83
  329. package/.dockerignore +0 -23
  330. package/.env.act.example +0 -15
  331. package/.env.example +0 -171
  332. package/.eslintrc.json +0 -16
  333. package/.git-blame-ignore-revs +0 -10
  334. package/.gitattributes +0 -2
  335. package/.gitguardian.yaml +0 -50
  336. package/.githooks/pre-commit +0 -6
  337. package/.pre-commit-config.yaml +0 -30
  338. package/.release-please-config-xithead.json +0 -22
  339. package/.release-please-config.json +0 -44
  340. package/.release-please-manifest-xithead.json +0 -3
  341. package/.release-please-manifest.json +0 -3
  342. package/CODE_OF_CONDUCT.md +0 -133
  343. package/CONTRIBUTING.md +0 -133
  344. package/Cargo.lock +0 -5557
  345. package/Cargo.toml +0 -121
  346. package/Dockerfile +0 -38
  347. package/Dockerfile.proxy +0 -48
  348. package/ENTERPRISE.md +0 -5
  349. package/FEATURES_ADVANCED.md +0 -311
  350. package/Headroom-2.gif +0 -0
  351. package/HeadroomDemo-Fast.gif +0 -0
  352. package/MANIFEST.in +0 -4
  353. package/MODERNIZATION_GUIDE.md +0 -358
  354. package/Makefile +0 -140
  355. package/NOTICE +0 -43
  356. package/NPM_TOKEN_SETUP.md +0 -81
  357. package/PR.md +0 -170
  358. package/PUBLISH.md +0 -77
  359. package/README_FRONTEND.md +0 -196
  360. package/REALIGNMENT/00-overview.md +0 -53
  361. package/REALIGNMENT/01-bug-list.md +0 -421
  362. package/REALIGNMENT/02-architecture.md +0 -322
  363. package/REALIGNMENT/03-phase-A-lockdown.md +0 -420
  364. package/REALIGNMENT/04-phase-B-live-zone.md +0 -470
  365. package/REALIGNMENT/05-phase-C-rust-proxy.md +0 -329
  366. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +0 -222
  367. package/REALIGNMENT/07-phase-E-cache-stabilization.md +0 -338
  368. package/REALIGNMENT/08-phase-F-auth-mode.md +0 -254
  369. package/REALIGNMENT/09-phase-G-rtk-observability.md +0 -194
  370. package/REALIGNMENT/10-phase-H-python-retirement.md +0 -214
  371. package/REALIGNMENT/11-phase-I-test-infra.md +0 -385
  372. package/REALIGNMENT/12-decisions-needed.md +0 -196
  373. package/REALIGNMENT/INDEX.md +0 -82
  374. package/REFACTORING_CAMPAIGN.md +0 -277
  375. package/RESTRUCTURE_PLAN.md +0 -100
  376. package/RUST_DEV.md +0 -361
  377. package/SECURITY.md +0 -65
  378. package/SETUP_AUTO_PUBLISH.md +0 -164
  379. package/TESTING-copilot-subscription.md +0 -153
  380. package/codecov.yml +0 -34
  381. package/crates/headroom-core/Cargo.toml +0 -165
  382. package/crates/headroom-core/benches/auth_mode.rs +0 -74
  383. package/crates/headroom-core/benches/ccr_store.rs +0 -224
  384. package/crates/headroom-core/benches/tokenizer.rs +0 -52
  385. package/crates/headroom-core/config/pipeline.toml +0 -151
  386. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +0 -9
  387. package/crates/headroom-core/src/auth_mode.rs +0 -250
  388. package/crates/headroom-core/src/cache_control.rs +0 -414
  389. package/crates/headroom-core/src/ccr/backends/in_memory.rs +0 -317
  390. package/crates/headroom-core/src/ccr/backends/mod.rs +0 -152
  391. package/crates/headroom-core/src/ccr/backends/redis.rs +0 -146
  392. package/crates/headroom-core/src/ccr/backends/sqlite.rs +0 -205
  393. package/crates/headroom-core/src/ccr/mod.rs +0 -119
  394. package/crates/headroom-core/src/compression_policy.rs +0 -505
  395. package/crates/headroom-core/src/lib.rs +0 -33
  396. package/crates/headroom-core/src/relevance/base.rs +0 -139
  397. package/crates/headroom-core/src/relevance/bm25.rs +0 -385
  398. package/crates/headroom-core/src/relevance/embedding.rs +0 -354
  399. package/crates/headroom-core/src/relevance/hybrid.rs +0 -364
  400. package/crates/headroom-core/src/relevance/mod.rs +0 -64
  401. package/crates/headroom-core/src/signals/keyword_detector.rs +0 -433
  402. package/crates/headroom-core/src/signals/line_importance.rs +0 -84
  403. package/crates/headroom-core/src/signals/mod.rs +0 -61
  404. package/crates/headroom-core/src/signals/tiered.rs +0 -141
  405. package/crates/headroom-core/src/tokenizer/estimator.rs +0 -152
  406. package/crates/headroom-core/src/tokenizer/hf_impl.rs +0 -314
  407. package/crates/headroom-core/src/tokenizer/mod.rs +0 -56
  408. package/crates/headroom-core/src/tokenizer/registry.rs +0 -342
  409. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +0 -265
  410. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +0 -610
  411. package/crates/headroom-core/src/transforms/anchor_selector.rs +0 -1189
  412. package/crates/headroom-core/src/transforms/content_detector.rs +0 -769
  413. package/crates/headroom-core/src/transforms/detection.rs +0 -222
  414. package/crates/headroom-core/src/transforms/diff_compressor.rs +0 -1685
  415. package/crates/headroom-core/src/transforms/live_zone.rs +0 -2967
  416. package/crates/headroom-core/src/transforms/log_compressor.rs +0 -1295
  417. package/crates/headroom-core/src/transforms/magika_detector.rs +0 -395
  418. package/crates/headroom-core/src/transforms/mod.rs +0 -64
  419. package/crates/headroom-core/src/transforms/pipeline/config.rs +0 -331
  420. package/crates/headroom-core/src/transforms/pipeline/mod.rs +0 -103
  421. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +0 -524
  422. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +0 -279
  423. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +0 -400
  424. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +0 -284
  425. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +0 -34
  426. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +0 -331
  427. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +0 -848
  428. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +0 -175
  429. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +0 -545
  430. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +0 -12
  431. package/crates/headroom-core/src/transforms/pipeline/traits.rs +0 -338
  432. package/crates/headroom-core/src/transforms/recommendations.rs +0 -329
  433. package/crates/headroom-core/src/transforms/safety.rs +0 -215
  434. package/crates/headroom-core/src/transforms/search_compressor.rs +0 -902
  435. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +0 -1262
  436. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +0 -407
  437. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +0 -263
  438. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +0 -214
  439. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +0 -283
  440. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +0 -733
  441. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +0 -961
  442. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +0 -252
  443. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +0 -127
  444. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +0 -397
  445. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +0 -173
  446. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +0 -159
  447. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +0 -1665
  448. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +0 -865
  449. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +0 -77
  450. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +0 -393
  451. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +0 -72
  452. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +0 -81
  453. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +0 -66
  454. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +0 -459
  455. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +0 -507
  456. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +0 -904
  457. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +0 -510
  458. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +0 -287
  459. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +0 -203
  460. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +0 -263
  461. package/crates/headroom-core/src/transforms/tag_protector.rs +0 -1272
  462. package/crates/headroom-core/src/transforms/unidiff_detector.rs +0 -232
  463. package/crates/headroom-parity/Cargo.toml +0 -26
  464. package/crates/headroom-parity/examples/diff_fixture.rs +0 -66
  465. package/crates/headroom-parity/src/bin/parity_run.rs +0 -78
  466. package/crates/headroom-parity/src/lib.rs +0 -613
  467. package/crates/headroom-proxy/Cargo.toml +0 -119
  468. package/crates/headroom-proxy/data/model_prices_and_context_window.json +0 -39767
  469. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +0 -192
  470. package/crates/headroom-proxy/src/bedrock/envelope.rs +0 -239
  471. package/crates/headroom-proxy/src/bedrock/eventstream.rs +0 -769
  472. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +0 -459
  473. package/crates/headroom-proxy/src/bedrock/invoke.rs +0 -735
  474. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +0 -1098
  475. package/crates/headroom-proxy/src/bedrock/mod.rs +0 -66
  476. package/crates/headroom-proxy/src/bedrock/sigv4.rs +0 -324
  477. package/crates/headroom-proxy/src/bedrock/vendor.rs +0 -82
  478. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +0 -698
  479. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +0 -683
  480. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +0 -61
  481. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +0 -600
  482. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +0 -514
  483. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +0 -720
  484. package/crates/headroom-proxy/src/compression/anthropic.rs +0 -92
  485. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +0 -1311
  486. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +0 -660
  487. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +0 -678
  488. package/crates/headroom-proxy/src/compression/mod.rs +0 -127
  489. package/crates/headroom-proxy/src/compression/model_limits.rs +0 -211
  490. package/crates/headroom-proxy/src/config.rs +0 -646
  491. package/crates/headroom-proxy/src/error.rs +0 -69
  492. package/crates/headroom-proxy/src/handlers/chat_completions.rs +0 -100
  493. package/crates/headroom-proxy/src/handlers/conversations.rs +0 -241
  494. package/crates/headroom-proxy/src/handlers/mod.rs +0 -13
  495. package/crates/headroom-proxy/src/handlers/responses.rs +0 -256
  496. package/crates/headroom-proxy/src/headers.rs +0 -288
  497. package/crates/headroom-proxy/src/health.rs +0 -41
  498. package/crates/headroom-proxy/src/lib.rs +0 -21
  499. package/crates/headroom-proxy/src/main.rs +0 -141
  500. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +0 -340
  501. package/crates/headroom-proxy/src/observability/compression_ratio.rs +0 -158
  502. package/crates/headroom-proxy/src/observability/metric_names.rs +0 -174
  503. package/crates/headroom-proxy/src/observability/mod.rs +0 -68
  504. package/crates/headroom-proxy/src/observability/prometheus.rs +0 -394
  505. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +0 -368
  506. package/crates/headroom-proxy/src/proxy.rs +0 -1619
  507. package/crates/headroom-proxy/src/responses_items.rs +0 -565
  508. package/crates/headroom-proxy/src/sse/anthropic.rs +0 -415
  509. package/crates/headroom-proxy/src/sse/framing.rs +0 -366
  510. package/crates/headroom-proxy/src/sse/mod.rs +0 -40
  511. package/crates/headroom-proxy/src/sse/openai_chat.rs +0 -231
  512. package/crates/headroom-proxy/src/sse/openai_responses.rs +0 -458
  513. package/crates/headroom-proxy/src/vertex/adc.rs +0 -315
  514. package/crates/headroom-proxy/src/vertex/envelope.rs +0 -167
  515. package/crates/headroom-proxy/src/vertex/mod.rs +0 -277
  516. package/crates/headroom-proxy/src/vertex/raw_predict.rs +0 -490
  517. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +0 -49
  518. package/crates/headroom-proxy/src/websocket.rs +0 -246
  519. package/crates/headroom-py/Cargo.toml +0 -37
  520. package/crates/headroom-py/build.rs +0 -77
  521. package/crates/headroom-py/glibc_compat.c +0 -170
  522. package/crates/headroom-py/src/lib.rs +0 -1655
  523. package/deny.toml +0 -32
  524. package/docker/differential-network-capture/Dockerfile.runner +0 -14
  525. package/docker/differential-network-capture/docker-compose.yml +0 -142
  526. package/docker/differential-network-capture/run-claude-lane.sh +0 -24
  527. package/docker/docker-compose.native.yml +0 -44
  528. package/docker-bake.hcl +0 -88
  529. package/docker-compose.yml +0 -80
  530. package/e2e/_lib/make_shim.ps1 +0 -24
  531. package/e2e/_lib/make_shim.sh +0 -28
  532. package/e2e/docker-native-install.sh +0 -120
  533. package/e2e/init/Dockerfile +0 -79
  534. package/e2e/wrap/Dockerfile +0 -115
  535. package/examples/07-context-compression.ipynb +0 -279
  536. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +0 -65
  537. package/examples/deployment/macos-launchagent/install.sh +0 -227
  538. package/examples/deployment/macos-launchagent/shell-integration.sh +0 -74
  539. package/examples/deployment/macos-launchagent/uninstall.sh +0 -145
  540. package/headroom-savings.png +0 -0
  541. package/headroom_learn.gif +0 -0
  542. package/llms.txt +0 -67
  543. package/mkdocs.yml +0 -136
  544. package/npm/bin/xithead.js +0 -366
  545. package/npm/bin/xtream-head.js +0 -366
  546. package/npm/index.d.ts +0 -57
  547. package/npm/index.js +0 -139
  548. package/npm/package.json +0 -55
  549. package/npm/postinstall.js +0 -43
  550. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +0 -17
  551. package/plugins/headroom-agent-hooks/hooks/hooks.json +0 -29
  552. package/plugins/headroom-oauth2/LICENSE +0 -3
  553. package/plugins/headroom-oauth2/SPEC.md +0 -115
  554. package/plugins/headroom-oauth2/pyproject.toml +0 -48
  555. package/plugins/hermes/headroom_retrieve/plugin.yaml +0 -6
  556. package/plugins/openclaw/hook-shim/HOOK.md +0 -21
  557. package/plugins/openclaw/hook-shim/handler.js +0 -3
  558. package/plugins/openclaw/openclaw.plugin.json +0 -98
  559. package/plugins/openclaw/package-lock.json +0 -2692
  560. package/plugins/openclaw/package.json +0 -54
  561. package/plugins/openclaw/prepare-dist.mjs +0 -56
  562. package/plugins/openclaw/src/convert.ts +0 -418
  563. package/plugins/openclaw/src/engine.ts +0 -284
  564. package/plugins/openclaw/src/gateway-config.ts +0 -143
  565. package/plugins/openclaw/src/index.ts +0 -11
  566. package/plugins/openclaw/src/plugin/index.ts +0 -98
  567. package/plugins/openclaw/src/proxy-manager.ts +0 -477
  568. package/plugins/openclaw/src/tools/headroom-retrieve.ts +0 -76
  569. package/plugins/openclaw/test/convert.test.ts +0 -96
  570. package/plugins/openclaw/test/engine-normalization.test.ts +0 -21
  571. package/plugins/openclaw/test/engine.test.ts +0 -101
  572. package/plugins/openclaw/test/gateway-config.test.ts +0 -278
  573. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +0 -141
  574. package/plugins/openclaw/test/proxy-manager.test.ts +0 -343
  575. package/plugins/openclaw/tsup.config.ts +0 -9
  576. package/pyproject.toml +0 -438
  577. package/rust-toolchain.toml +0 -16
  578. package/sdk/typescript/examples/basic-compress.ts +0 -64
  579. package/sdk/typescript/examples/ccr-retrieve.ts +0 -80
  580. package/sdk/typescript/examples/hooks-custom-compression.ts +0 -117
  581. package/sdk/typescript/examples/middleware-composition.ts +0 -59
  582. package/sdk/typescript/examples/multi-provider.ts +0 -53
  583. package/sdk/typescript/examples/openai-anthropic-adapters.ts +0 -73
  584. package/sdk/typescript/examples/shared-context-multi-agent.ts +0 -74
  585. package/sdk/typescript/examples/simulation-dry-run.ts +0 -80
  586. package/sdk/typescript/examples/streaming-chat.ts +0 -71
  587. package/sdk/typescript/examples/structured-output.ts +0 -99
  588. package/sdk/typescript/examples/tool-calling-agent.ts +0 -86
  589. package/sdk/typescript/examples/with-headroom-vercel.ts +0 -57
  590. package/sdk/typescript/package-lock.json +0 -3437
  591. package/sdk/typescript/package.json +0 -108
  592. package/sdk/typescript/src/adapters/anthropic.ts +0 -218
  593. package/sdk/typescript/src/adapters/gemini.ts +0 -83
  594. package/sdk/typescript/src/adapters/openai.ts +0 -77
  595. package/sdk/typescript/src/adapters/vercel-ai.ts +0 -131
  596. package/sdk/typescript/src/client.ts +0 -632
  597. package/sdk/typescript/src/compress.ts +0 -87
  598. package/sdk/typescript/src/errors.ts +0 -114
  599. package/sdk/typescript/src/hooks.ts +0 -113
  600. package/sdk/typescript/src/index.ts +0 -140
  601. package/sdk/typescript/src/paths.ts +0 -272
  602. package/sdk/typescript/src/shared-context.ts +0 -188
  603. package/sdk/typescript/src/simulate.ts +0 -52
  604. package/sdk/typescript/src/types/config.ts +0 -183
  605. package/sdk/typescript/src/types/models.ts +0 -314
  606. package/sdk/typescript/src/types.ts +0 -139
  607. package/sdk/typescript/src/utils/case.ts +0 -34
  608. package/sdk/typescript/src/utils/format.ts +0 -480
  609. package/sdk/typescript/src/utils/stream.ts +0 -50
  610. package/sdk/typescript/test/adapters/anthropic.test.ts +0 -217
  611. package/sdk/typescript/test/adapters/gemini.test.ts +0 -131
  612. package/sdk/typescript/test/adapters/openai.test.ts +0 -174
  613. package/sdk/typescript/test/adapters/vercel-ai.test.ts +0 -306
  614. package/sdk/typescript/test/client-expanded.test.ts +0 -333
  615. package/sdk/typescript/test/client.test.ts +0 -266
  616. package/sdk/typescript/test/compress.test.ts +0 -118
  617. package/sdk/typescript/test/config.test.ts +0 -275
  618. package/sdk/typescript/test/errors.test.ts +0 -169
  619. package/sdk/typescript/test/format-integration.test.ts +0 -252
  620. package/sdk/typescript/test/hooks.test.ts +0 -265
  621. package/sdk/typescript/test/integration.test.ts +0 -249
  622. package/sdk/typescript/test/mdx-examples.test.ts +0 -253
  623. package/sdk/typescript/test/models.test.ts +0 -318
  624. package/sdk/typescript/test/parity.test.ts +0 -337
  625. package/sdk/typescript/test/paths.test.ts +0 -447
  626. package/sdk/typescript/test/shared-context.test.ts +0 -245
  627. package/sdk/typescript/test/simulate.test.ts +0 -84
  628. package/sdk/typescript/test/types.test.ts +0 -244
  629. package/sdk/typescript/test/utils/case.test.ts +0 -129
  630. package/sdk/typescript/test/utils/detect-format.test.ts +0 -133
  631. package/sdk/typescript/test/utils/format.test.ts +0 -434
  632. package/sdk/typescript/test/vercel-ai-e2e.test.ts +0 -179
  633. package/sdk/typescript/tsup.config.ts +0 -17
  634. package/uv.lock +0 -6951
  635. package/xithead.egg-info/PKG-INFO +0 -22
  636. package/xithead.egg-info/SOURCES.txt +0 -16
  637. package/xithead.egg-info/dependency_links.txt +0 -1
  638. package/xithead.egg-info/entry_points.txt +0 -2
  639. package/xithead.egg-info/requires.txt +0 -10
  640. package/xithead.egg-info/top_level.txt +0 -2
  641. package/xithead.ps1 +0 -136
  642. package/xithead.sh +0 -129
  643. package/xithead_dist/pyproject.toml +0 -39
  644. package/xithead_dist/xithead.egg-info/PKG-INFO +0 -22
  645. package/xithead_dist/xithead.egg-info/SOURCES.txt +0 -16
  646. package/xithead_dist/xithead.egg-info/dependency_links.txt +0 -1
  647. package/xithead_dist/xithead.egg-info/entry_points.txt +0 -3
  648. package/xithead_dist/xithead.egg-info/requires.txt +0 -10
  649. package/xithead_dist/xithead.egg-info/top_level.txt +0 -2
@@ -1,1619 +0,0 @@
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
- }