xithead 1.4.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (661) hide show
  1. package/.actrc +14 -0
  2. package/.actrc.local.example +15 -0
  3. package/.changelog.md +2 -0
  4. package/.claude/agents/academic-anthropologist.md +125 -0
  5. package/.claude/agents/academic-geographer.md +127 -0
  6. package/.claude/agents/academic-historian.md +123 -0
  7. package/.claude/agents/academic-narratologist.md +118 -0
  8. package/.claude/agents/academic-psychologist.md +118 -0
  9. package/.claude/agents/academic-statistician.md +144 -0
  10. package/.claude/agents/accounts-payable-agent.md +205 -0
  11. package/.claude/agents/agentic-identity-trust.md +394 -0
  12. package/.claude/agents/agents-orchestrator.md +367 -0
  13. package/.claude/agents/automation-governance-architect.md +216 -0
  14. package/.claude/agents/blender-addon-engineer.md +243 -0
  15. package/.claude/agents/business-strategist.md +488 -0
  16. package/.claude/agents/change-management-consultant.md +497 -0
  17. package/.claude/agents/chief-financial-officer.md +388 -0
  18. package/.claude/agents/corporate-training-designer.md +192 -0
  19. package/.claude/agents/customer-service.md +398 -0
  20. package/.claude/agents/customer-success-manager.md +460 -0
  21. package/.claude/agents/data-consolidation-agent.md +60 -0
  22. package/.claude/agents/data-privacy-officer.md +412 -0
  23. package/.claude/agents/design-brand-guardian.md +322 -0
  24. package/.claude/agents/design-image-prompt-engineer.md +236 -0
  25. package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
  26. package/.claude/agents/design-persona-walkthrough.md +272 -0
  27. package/.claude/agents/design-ui-designer.md +386 -0
  28. package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
  29. package/.claude/agents/design-ux-architect.md +482 -0
  30. package/.claude/agents/design-ux-researcher.md +329 -0
  31. package/.claude/agents/design-visual-storyteller.md +149 -0
  32. package/.claude/agents/design-whimsy-injector.md +460 -0
  33. package/.claude/agents/economy-designer.md +156 -0
  34. package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
  35. package/.claude/agents/engineering-ai-engineer.md +146 -0
  36. package/.claude/agents/engineering-api-platform-engineer.md +181 -0
  37. package/.claude/agents/engineering-ats-validator-architect.md +383 -0
  38. package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
  39. package/.claude/agents/engineering-backend-architect.md +255 -0
  40. package/.claude/agents/engineering-china-network-engineer.md +252 -0
  41. package/.claude/agents/engineering-cms-developer.md +536 -0
  42. package/.claude/agents/engineering-code-reviewer.md +76 -0
  43. package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
  44. package/.claude/agents/engineering-data-engineer.md +349 -0
  45. package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
  46. package/.claude/agents/engineering-database-optimizer.md +188 -0
  47. package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
  48. package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
  49. package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
  50. package/.claude/agents/engineering-devops-automator.md +385 -0
  51. package/.claude/agents/engineering-drupal-performance.md +347 -0
  52. package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
  53. package/.claude/agents/engineering-electrical-engineer.md +575 -0
  54. package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
  55. package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
  56. package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
  57. package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
  58. package/.claude/agents/engineering-finops-engineer.md +164 -0
  59. package/.claude/agents/engineering-frontend-developer.md +257 -0
  60. package/.claude/agents/engineering-gaussdb-expert.md +334 -0
  61. package/.claude/agents/engineering-git-workflow-master.md +98 -0
  62. package/.claude/agents/engineering-i18n-engineer.md +214 -0
  63. package/.claude/agents/engineering-identity-access-engineer.md +217 -0
  64. package/.claude/agents/engineering-incident-response-commander.md +444 -0
  65. package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
  66. package/.claude/agents/engineering-it-service-manager.md +561 -0
  67. package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
  68. package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
  69. package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
  70. package/.claude/agents/engineering-mobile-app-builder.md +493 -0
  71. package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
  72. package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
  73. package/.claude/agents/engineering-network-engineer.md +245 -0
  74. package/.claude/agents/engineering-orgscript-engineer.md +113 -0
  75. package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
  76. package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
  77. package/.claude/agents/engineering-platform-engineer.md +270 -0
  78. package/.claude/agents/engineering-privacy-engineer.md +152 -0
  79. package/.claude/agents/engineering-prompt-engineer.md +209 -0
  80. package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
  81. package/.claude/agents/engineering-rapid-prototyper.md +466 -0
  82. package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
  83. package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
  84. package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
  85. package/.claude/agents/engineering-section-508-specialist.md +339 -0
  86. package/.claude/agents/engineering-senior-developer.md +176 -0
  87. package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
  88. package/.claude/agents/engineering-software-architect.md +112 -0
  89. package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
  90. package/.claude/agents/engineering-sre.md +90 -0
  91. package/.claude/agents/engineering-technical-writer.md +393 -0
  92. package/.claude/agents/engineering-universal-document-compiler.md +370 -0
  93. package/.claude/agents/engineering-uswds-developer.md +340 -0
  94. package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
  95. package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
  96. package/.claude/agents/engineering-webassembly-engineer.md +153 -0
  97. package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
  98. package/.claude/agents/engineering-wordpress-performance.md +346 -0
  99. package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
  100. package/.claude/agents/esg-sustainability-officer.md +396 -0
  101. package/.claude/agents/finance-bookkeeper-controller.md +260 -0
  102. package/.claude/agents/finance-financial-analyst.md +234 -0
  103. package/.claude/agents/finance-fpa-analyst.md +263 -0
  104. package/.claude/agents/finance-investment-researcher.md +272 -0
  105. package/.claude/agents/finance-tax-strategist.md +239 -0
  106. package/.claude/agents/game-audio-engineer.md +264 -0
  107. package/.claude/agents/game-designer.md +167 -0
  108. package/.claude/agents/gis-3d-scene-developer.md +111 -0
  109. package/.claude/agents/gis-analyst.md +91 -0
  110. package/.claude/agents/gis-bim-specialist.md +108 -0
  111. package/.claude/agents/gis-cartography-designer.md +150 -0
  112. package/.claude/agents/gis-drone-reality-mapping.md +120 -0
  113. package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
  114. package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
  115. package/.claude/agents/gis-qa-engineer.md +133 -0
  116. package/.claude/agents/gis-solution-engineer.md +101 -0
  117. package/.claude/agents/gis-spatial-data-engineer.md +97 -0
  118. package/.claude/agents/gis-spatial-data-scientist.md +111 -0
  119. package/.claude/agents/gis-technical-consultant.md +86 -0
  120. package/.claude/agents/gis-web-gis-developer.md +108 -0
  121. package/.claude/agents/godot-gameplay-scripter.md +338 -0
  122. package/.claude/agents/godot-multiplayer-engineer.md +301 -0
  123. package/.claude/agents/godot-shader-developer.md +267 -0
  124. package/.claude/agents/government-digital-presales-consultant.md +363 -0
  125. package/.claude/agents/grant-writer.md +511 -0
  126. package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
  127. package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
  128. package/.claude/agents/healthcare-customer-service.md +389 -0
  129. package/.claude/agents/healthcare-innovation-strategist.md +433 -0
  130. package/.claude/agents/healthcare-marketing-compliance.md +395 -0
  131. package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
  132. package/.claude/agents/hospitality-guest-services.md +603 -0
  133. package/.claude/agents/hr-onboarding.md +451 -0
  134. package/.claude/agents/identity-graph-operator.md +303 -0
  135. package/.claude/agents/language-translator.md +264 -0
  136. package/.claude/agents/legal-billing-time-tracking.md +569 -0
  137. package/.claude/agents/legal-client-intake.md +492 -0
  138. package/.claude/agents/legal-document-review.md +454 -0
  139. package/.claude/agents/level-designer.md +208 -0
  140. package/.claude/agents/loan-officer-assistant.md +555 -0
  141. package/.claude/agents/lsp-index-engineer.md +320 -0
  142. package/.claude/agents/ma-integration-manager.md +427 -0
  143. package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
  144. package/.claude/agents/marketing-aeo-foundations.md +264 -0
  145. package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
  146. package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
  147. package/.claude/agents/marketing-app-store-optimizer.md +321 -0
  148. package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
  149. package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
  150. package/.claude/agents/marketing-book-co-author.md +110 -0
  151. package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
  152. package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
  153. package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
  154. package/.claude/agents/marketing-content-creator.md +54 -0
  155. package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
  156. package/.claude/agents/marketing-developer-community-builder.md +285 -0
  157. package/.claude/agents/marketing-douyin-strategist.md +149 -0
  158. package/.claude/agents/marketing-email-strategist.md +249 -0
  159. package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
  160. package/.claude/agents/marketing-growth-hacker.md +54 -0
  161. package/.claude/agents/marketing-instagram-curator.md +113 -0
  162. package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
  163. package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
  164. package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
  165. package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
  166. package/.claude/agents/marketing-podcast-strategist.md +277 -0
  167. package/.claude/agents/marketing-pr-communications-manager.md +473 -0
  168. package/.claude/agents/marketing-private-domain-operator.md +308 -0
  169. package/.claude/agents/marketing-reddit-community-builder.md +123 -0
  170. package/.claude/agents/marketing-seo-specialist.md +370 -0
  171. package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
  172. package/.claude/agents/marketing-social-media-strategist.md +125 -0
  173. package/.claude/agents/marketing-tiktok-strategist.md +125 -0
  174. package/.claude/agents/marketing-twitter-engager.md +126 -0
  175. package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
  176. package/.claude/agents/marketing-wechat-official-account.md +145 -0
  177. package/.claude/agents/marketing-weibo-strategist.md +240 -0
  178. package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
  179. package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
  180. package/.claude/agents/marketing-zhihu-strategist.md +162 -0
  181. package/.claude/agents/medical-billing-coding-specialist.md +491 -0
  182. package/.claude/agents/narrative-designer.md +243 -0
  183. package/.claude/agents/operations-manager.md +399 -0
  184. package/.claude/agents/organizational-psychologist.md +391 -0
  185. package/.claude/agents/paid-media-auditor.md +71 -0
  186. package/.claude/agents/paid-media-creative-strategist.md +71 -0
  187. package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
  188. package/.claude/agents/paid-media-ppc-strategist.md +71 -0
  189. package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
  190. package/.claude/agents/paid-media-search-query-analyst.md +71 -0
  191. package/.claude/agents/paid-media-tracking-specialist.md +71 -0
  192. package/.claude/agents/personal-growth-mentor.md +159 -0
  193. package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
  194. package/.claude/agents/product-dx-engineer.md +332 -0
  195. package/.claude/agents/product-feedback-synthesizer.md +119 -0
  196. package/.claude/agents/product-manager.md +469 -0
  197. package/.claude/agents/product-sprint-prioritizer.md +154 -0
  198. package/.claude/agents/product-trend-researcher.md +159 -0
  199. package/.claude/agents/project-management-experiment-tracker.md +198 -0
  200. package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
  201. package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
  202. package/.claude/agents/project-management-project-shepherd.md +194 -0
  203. package/.claude/agents/project-management-studio-operations.md +200 -0
  204. package/.claude/agents/project-management-studio-producer.md +203 -0
  205. package/.claude/agents/project-manager-senior.md +135 -0
  206. package/.claude/agents/real-estate-buyer-seller.md +596 -0
  207. package/.claude/agents/recruitment-specialist.md +515 -0
  208. package/.claude/agents/report-distribution-agent.md +65 -0
  209. package/.claude/agents/research-synthesist.md +136 -0
  210. package/.claude/agents/resume-tailor.md +230 -0
  211. package/.claude/agents/retail-customer-returns.md +566 -0
  212. package/.claude/agents/roblox-avatar-creator.md +297 -0
  213. package/.claude/agents/roblox-experience-designer.md +306 -0
  214. package/.claude/agents/roblox-systems-scripter.md +332 -0
  215. package/.claude/agents/sales-account-strategist.md +227 -0
  216. package/.claude/agents/sales-coach.md +271 -0
  217. package/.claude/agents/sales-data-extraction-agent.md +67 -0
  218. package/.claude/agents/sales-deal-strategist.md +180 -0
  219. package/.claude/agents/sales-discovery-coach.md +225 -0
  220. package/.claude/agents/sales-engineer.md +182 -0
  221. package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
  222. package/.claude/agents/sales-outbound-strategist.md +201 -0
  223. package/.claude/agents/sales-outreach.md +425 -0
  224. package/.claude/agents/sales-pipeline-analyst.md +267 -0
  225. package/.claude/agents/sales-proposal-strategist.md +217 -0
  226. package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
  227. package/.claude/agents/security-appsec-engineer.md +536 -0
  228. package/.claude/agents/security-architect.md +307 -0
  229. package/.claude/agents/security-blockchain-security-auditor.md +482 -0
  230. package/.claude/agents/security-cloud-security-architect.md +576 -0
  231. package/.claude/agents/security-compliance-auditor.md +158 -0
  232. package/.claude/agents/security-incident-responder.md +450 -0
  233. package/.claude/agents/security-penetration-tester.md +399 -0
  234. package/.claude/agents/security-secrets-credential-engineer.md +189 -0
  235. package/.claude/agents/security-senior-secops.md +760 -0
  236. package/.claude/agents/security-threat-detection-engineer.md +553 -0
  237. package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
  238. package/.claude/agents/specialized-chief-of-staff.md +279 -0
  239. package/.claude/agents/specialized-civil-engineer.md +356 -0
  240. package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
  241. package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
  242. package/.claude/agents/specialized-developer-advocate.md +317 -0
  243. package/.claude/agents/specialized-document-generator.md +55 -0
  244. package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
  245. package/.claude/agents/specialized-focus-music-architect.md +175 -0
  246. package/.claude/agents/specialized-french-consulting-market.md +194 -0
  247. package/.claude/agents/specialized-korean-business-navigator.md +216 -0
  248. package/.claude/agents/specialized-master-plan-architect.md +157 -0
  249. package/.claude/agents/specialized-mcp-builder.md +260 -0
  250. package/.claude/agents/specialized-model-qa.md +528 -0
  251. package/.claude/agents/specialized-pricing-analyst.md +243 -0
  252. package/.claude/agents/specialized-salesforce-architect.md +182 -0
  253. package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
  254. package/.claude/agents/specialized-workflow-architect.md +597 -0
  255. package/.claude/agents/study-abroad-advisor.md +282 -0
  256. package/.claude/agents/supply-chain-strategist.md +591 -0
  257. package/.claude/agents/support-analytics-reporter.md +387 -0
  258. package/.claude/agents/support-executive-summary-generator.md +212 -0
  259. package/.claude/agents/support-finance-tracker.md +480 -0
  260. package/.claude/agents/support-infrastructure-maintainer.md +628 -0
  261. package/.claude/agents/support-legal-compliance-checker.md +591 -0
  262. package/.claude/agents/support-support-responder.md +607 -0
  263. package/.claude/agents/technical-artist.md +233 -0
  264. package/.claude/agents/terminal-integration-specialist.md +70 -0
  265. package/.claude/agents/testing-accessibility-auditor.md +327 -0
  266. package/.claude/agents/testing-api-tester.md +334 -0
  267. package/.claude/agents/testing-evidence-collector.md +210 -0
  268. package/.claude/agents/testing-performance-benchmarker.md +283 -0
  269. package/.claude/agents/testing-reality-checker.md +249 -0
  270. package/.claude/agents/testing-test-automation-engineer.md +196 -0
  271. package/.claude/agents/testing-test-results-analyzer.md +330 -0
  272. package/.claude/agents/testing-tool-evaluator.md +416 -0
  273. package/.claude/agents/testing-workflow-optimizer.md +463 -0
  274. package/.claude/agents/unity-architect.md +271 -0
  275. package/.claude/agents/unity-editor-tool-developer.md +310 -0
  276. package/.claude/agents/unity-multiplayer-engineer.md +323 -0
  277. package/.claude/agents/unity-shader-graph-artist.md +269 -0
  278. package/.claude/agents/unreal-multiplayer-architect.md +364 -0
  279. package/.claude/agents/unreal-systems-engineer.md +322 -0
  280. package/.claude/agents/unreal-technical-artist.md +256 -0
  281. package/.claude/agents/unreal-world-builder.md +273 -0
  282. package/.claude/agents/visionos-spatial-engineer.md +54 -0
  283. package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
  284. package/.claude/agents/xr-immersive-developer.md +32 -0
  285. package/.claude/agents/xr-interface-architect.md +32 -0
  286. package/.claude/agents/zk-steward.md +211 -0
  287. package/.claude-plugin/marketplace.json +30 -0
  288. package/.commitlintrc.json +26 -0
  289. package/.devcontainer/Dockerfile +24 -0
  290. package/.devcontainer/devcontainer.json +70 -0
  291. package/.devcontainer/docker-compose.memory.yml +42 -0
  292. package/.devcontainer/memory-stack/devcontainer.json +84 -0
  293. package/.devcontainer/post-create.sh +83 -0
  294. package/.dockerignore +23 -0
  295. package/.env.act.example +15 -0
  296. package/.env.example +171 -0
  297. package/.eslintrc.json +16 -0
  298. package/.git-blame-ignore-revs +10 -0
  299. package/.gitattributes +2 -0
  300. package/.gitguardian.yaml +50 -0
  301. package/.githooks/pre-commit +6 -0
  302. package/.pre-commit-config.yaml +30 -0
  303. package/.release-please-config-xithead.json +22 -0
  304. package/.release-please-config.json +44 -0
  305. package/.release-please-manifest-xithead.json +3 -0
  306. package/.release-please-manifest.json +3 -0
  307. package/CODE_OF_CONDUCT.md +133 -0
  308. package/CONTRIBUTING.md +133 -0
  309. package/Cargo.lock +5557 -0
  310. package/Cargo.toml +121 -0
  311. package/Dockerfile +38 -0
  312. package/Dockerfile.proxy +48 -0
  313. package/ENTERPRISE.md +5 -0
  314. package/FEATURES_ADVANCED.md +311 -0
  315. package/Headroom-2.gif +0 -0
  316. package/HeadroomDemo-Fast.gif +0 -0
  317. package/MANIFEST.in +4 -0
  318. package/MODERNIZATION_GUIDE.md +358 -0
  319. package/Makefile +140 -0
  320. package/NOTICE +43 -0
  321. package/NPM_TOKEN_SETUP.md +81 -0
  322. package/PR.md +170 -0
  323. package/PUBLISH.md +77 -0
  324. package/README.md +108 -72
  325. package/README_FRONTEND.md +196 -0
  326. package/REALIGNMENT/00-overview.md +53 -0
  327. package/REALIGNMENT/01-bug-list.md +421 -0
  328. package/REALIGNMENT/02-architecture.md +322 -0
  329. package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
  330. package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
  331. package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
  332. package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
  333. package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
  334. package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
  335. package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
  336. package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
  337. package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
  338. package/REALIGNMENT/12-decisions-needed.md +196 -0
  339. package/REALIGNMENT/INDEX.md +82 -0
  340. package/REFACTORING_CAMPAIGN.md +277 -0
  341. package/RESTRUCTURE_PLAN.md +100 -0
  342. package/RUST_DEV.md +361 -0
  343. package/SECURITY.md +65 -0
  344. package/SETUP_AUTO_PUBLISH.md +164 -0
  345. package/TESTING-copilot-subscription.md +153 -0
  346. package/app/api/config/route.ts +22 -0
  347. package/app/api/export/route.ts +83 -0
  348. package/app/api/models/route.ts +12 -0
  349. package/app/api/stats/route.ts +46 -0
  350. package/app/dashboard/page.tsx +445 -0
  351. package/app/globals.css +35 -0
  352. package/app/installation/page.tsx +293 -0
  353. package/app/layout.tsx +35 -0
  354. package/app/master-design-system.css +2076 -0
  355. package/app/master-design-system.source.css +8 -0
  356. package/app/page.tsx +187 -0
  357. package/app/rechtliches/agb/page.tsx +165 -0
  358. package/app/rechtliches/datenschutz/page.tsx +128 -0
  359. package/app/rechtliches/impressum/page.tsx +122 -0
  360. package/app/rechtliches/widerruf/page.tsx +185 -0
  361. package/bin/xithead.js +264 -0
  362. package/codecov.yml +34 -0
  363. package/components/layout/AppShell.tsx +25 -0
  364. package/components/layout/Footer.tsx +120 -0
  365. package/components/layout/Header.tsx +145 -0
  366. package/components/marketing/LegalHighlights.tsx +45 -0
  367. package/components/marketing/LegalPageShell.tsx +49 -0
  368. package/components/marketing/LegalPanel.tsx +41 -0
  369. package/components/marketing/index.ts +3 -0
  370. package/crates/headroom-core/Cargo.toml +165 -0
  371. package/crates/headroom-core/benches/auth_mode.rs +74 -0
  372. package/crates/headroom-core/benches/ccr_store.rs +224 -0
  373. package/crates/headroom-core/benches/tokenizer.rs +52 -0
  374. package/crates/headroom-core/config/pipeline.toml +151 -0
  375. package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
  376. package/crates/headroom-core/src/auth_mode.rs +250 -0
  377. package/crates/headroom-core/src/cache_control.rs +414 -0
  378. package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
  379. package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
  380. package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
  381. package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
  382. package/crates/headroom-core/src/ccr/mod.rs +119 -0
  383. package/crates/headroom-core/src/compression_policy.rs +505 -0
  384. package/crates/headroom-core/src/lib.rs +33 -0
  385. package/crates/headroom-core/src/relevance/base.rs +139 -0
  386. package/crates/headroom-core/src/relevance/bm25.rs +385 -0
  387. package/crates/headroom-core/src/relevance/embedding.rs +354 -0
  388. package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
  389. package/crates/headroom-core/src/relevance/mod.rs +64 -0
  390. package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
  391. package/crates/headroom-core/src/signals/line_importance.rs +84 -0
  392. package/crates/headroom-core/src/signals/mod.rs +61 -0
  393. package/crates/headroom-core/src/signals/tiered.rs +141 -0
  394. package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
  395. package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
  396. package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
  397. package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
  398. package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
  399. package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
  400. package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
  401. package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
  402. package/crates/headroom-core/src/transforms/detection.rs +222 -0
  403. package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
  404. package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
  405. package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
  406. package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
  407. package/crates/headroom-core/src/transforms/mod.rs +64 -0
  408. package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
  409. package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
  410. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
  411. package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
  412. package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
  413. package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
  414. package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
  415. package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
  416. package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
  417. package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
  418. package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
  419. package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
  420. package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
  421. package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
  422. package/crates/headroom-core/src/transforms/safety.rs +215 -0
  423. package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
  424. package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
  425. package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
  426. package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
  427. package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
  428. package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
  429. package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
  430. package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
  431. package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
  432. package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
  433. package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
  434. package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
  435. package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
  436. package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
  437. package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
  438. package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
  439. package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
  440. package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
  441. package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
  442. package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
  443. package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
  444. package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
  445. package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
  446. package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
  447. package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
  448. package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
  449. package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
  450. package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
  451. package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
  452. package/crates/headroom-parity/Cargo.toml +26 -0
  453. package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
  454. package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
  455. package/crates/headroom-parity/src/lib.rs +613 -0
  456. package/crates/headroom-proxy/Cargo.toml +119 -0
  457. package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
  458. package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
  459. package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
  460. package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
  461. package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
  462. package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
  463. package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
  464. package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
  465. package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
  466. package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
  467. package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
  468. package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
  469. package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
  470. package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
  471. package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
  472. package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
  473. package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
  474. package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
  475. package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
  476. package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
  477. package/crates/headroom-proxy/src/compression/mod.rs +127 -0
  478. package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
  479. package/crates/headroom-proxy/src/config.rs +646 -0
  480. package/crates/headroom-proxy/src/error.rs +69 -0
  481. package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
  482. package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
  483. package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
  484. package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
  485. package/crates/headroom-proxy/src/headers.rs +288 -0
  486. package/crates/headroom-proxy/src/health.rs +41 -0
  487. package/crates/headroom-proxy/src/lib.rs +21 -0
  488. package/crates/headroom-proxy/src/main.rs +141 -0
  489. package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
  490. package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
  491. package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
  492. package/crates/headroom-proxy/src/observability/mod.rs +68 -0
  493. package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
  494. package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
  495. package/crates/headroom-proxy/src/proxy.rs +1619 -0
  496. package/crates/headroom-proxy/src/responses_items.rs +565 -0
  497. package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
  498. package/crates/headroom-proxy/src/sse/framing.rs +366 -0
  499. package/crates/headroom-proxy/src/sse/mod.rs +40 -0
  500. package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
  501. package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
  502. package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
  503. package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
  504. package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
  505. package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
  506. package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
  507. package/crates/headroom-proxy/src/websocket.rs +246 -0
  508. package/crates/headroom-py/Cargo.toml +37 -0
  509. package/crates/headroom-py/build.rs +77 -0
  510. package/crates/headroom-py/glibc_compat.c +170 -0
  511. package/crates/headroom-py/src/lib.rs +1655 -0
  512. package/deny.toml +32 -0
  513. package/design-system/base.css +127 -0
  514. package/design-system/components.css +1943 -0
  515. package/design-system/fonts.css +17 -0
  516. package/design-system/tailwind-preset.js +95 -0
  517. package/design-system/tokens.css +48 -0
  518. package/design-system/utilities.css +53 -0
  519. package/docker/differential-network-capture/Dockerfile.runner +14 -0
  520. package/docker/differential-network-capture/docker-compose.yml +142 -0
  521. package/docker/differential-network-capture/run-claude-lane.sh +24 -0
  522. package/docker/docker-compose.native.yml +44 -0
  523. package/docker-bake.hcl +88 -0
  524. package/docker-compose.yml +80 -0
  525. package/e2e/_lib/make_shim.ps1 +24 -0
  526. package/e2e/_lib/make_shim.sh +28 -0
  527. package/e2e/docker-native-install.sh +120 -0
  528. package/e2e/init/Dockerfile +79 -0
  529. package/e2e/wrap/Dockerfile +115 -0
  530. package/examples/07-context-compression.ipynb +279 -0
  531. package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
  532. package/examples/deployment/macos-launchagent/install.sh +227 -0
  533. package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
  534. package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
  535. package/headroom-savings.png +0 -0
  536. package/headroom_learn.gif +0 -0
  537. package/lib/config/index.ts +12 -0
  538. package/lib/hooks/index.ts +4 -0
  539. package/lib/hooks/use-mounted.ts +13 -0
  540. package/lib/hooks/use-session.ts +34 -0
  541. package/lib/hooks/use-settings.ts +49 -0
  542. package/lib/utils/index.ts +1 -0
  543. package/lib/utils/settings.ts +162 -0
  544. package/lib/utils/utils.ts +6 -0
  545. package/llms.txt +67 -0
  546. package/middleware.ts +26 -0
  547. package/mkdocs.yml +136 -0
  548. package/next-env.d.ts +7 -0
  549. package/next.config.ts +12 -0
  550. package/npm/bin/xithead.js +366 -366
  551. package/npm/bin/xtream-head.js +366 -0
  552. package/npm/index.d.ts +57 -57
  553. package/npm/index.js +139 -139
  554. package/npm/package.json +55 -54
  555. package/npm/postinstall.js +43 -43
  556. package/package.json +58 -36
  557. package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
  558. package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
  559. package/plugins/headroom-oauth2/LICENSE +3 -0
  560. package/plugins/headroom-oauth2/SPEC.md +115 -0
  561. package/plugins/headroom-oauth2/pyproject.toml +48 -0
  562. package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
  563. package/plugins/openclaw/hook-shim/HOOK.md +21 -0
  564. package/plugins/openclaw/hook-shim/handler.js +3 -0
  565. package/plugins/openclaw/openclaw.plugin.json +98 -0
  566. package/plugins/openclaw/package-lock.json +2692 -0
  567. package/plugins/openclaw/package.json +54 -0
  568. package/plugins/openclaw/prepare-dist.mjs +56 -0
  569. package/plugins/openclaw/src/convert.ts +418 -0
  570. package/plugins/openclaw/src/engine.ts +284 -0
  571. package/plugins/openclaw/src/gateway-config.ts +143 -0
  572. package/plugins/openclaw/src/index.ts +11 -0
  573. package/plugins/openclaw/src/plugin/index.ts +98 -0
  574. package/plugins/openclaw/src/proxy-manager.ts +477 -0
  575. package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
  576. package/plugins/openclaw/test/convert.test.ts +96 -0
  577. package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
  578. package/plugins/openclaw/test/engine.test.ts +101 -0
  579. package/plugins/openclaw/test/gateway-config.test.ts +278 -0
  580. package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
  581. package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
  582. package/plugins/openclaw/tsup.config.ts +9 -0
  583. package/postcss.config.mjs +7 -0
  584. package/pyproject.toml +438 -0
  585. package/rust-toolchain.toml +16 -0
  586. package/sdk/typescript/examples/basic-compress.ts +64 -0
  587. package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
  588. package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
  589. package/sdk/typescript/examples/middleware-composition.ts +59 -0
  590. package/sdk/typescript/examples/multi-provider.ts +53 -0
  591. package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
  592. package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
  593. package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
  594. package/sdk/typescript/examples/streaming-chat.ts +71 -0
  595. package/sdk/typescript/examples/structured-output.ts +99 -0
  596. package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
  597. package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
  598. package/sdk/typescript/package-lock.json +3437 -0
  599. package/sdk/typescript/package.json +108 -0
  600. package/sdk/typescript/src/adapters/anthropic.ts +218 -0
  601. package/sdk/typescript/src/adapters/gemini.ts +83 -0
  602. package/sdk/typescript/src/adapters/openai.ts +77 -0
  603. package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
  604. package/sdk/typescript/src/client.ts +632 -0
  605. package/sdk/typescript/src/compress.ts +87 -0
  606. package/sdk/typescript/src/errors.ts +114 -0
  607. package/sdk/typescript/src/hooks.ts +113 -0
  608. package/sdk/typescript/src/index.ts +140 -0
  609. package/sdk/typescript/src/paths.ts +272 -0
  610. package/sdk/typescript/src/shared-context.ts +188 -0
  611. package/sdk/typescript/src/simulate.ts +52 -0
  612. package/sdk/typescript/src/types/config.ts +183 -0
  613. package/sdk/typescript/src/types/models.ts +314 -0
  614. package/sdk/typescript/src/types.ts +139 -0
  615. package/sdk/typescript/src/utils/case.ts +34 -0
  616. package/sdk/typescript/src/utils/format.ts +480 -0
  617. package/sdk/typescript/src/utils/stream.ts +50 -0
  618. package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
  619. package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
  620. package/sdk/typescript/test/adapters/openai.test.ts +174 -0
  621. package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
  622. package/sdk/typescript/test/client-expanded.test.ts +333 -0
  623. package/sdk/typescript/test/client.test.ts +266 -0
  624. package/sdk/typescript/test/compress.test.ts +118 -0
  625. package/sdk/typescript/test/config.test.ts +275 -0
  626. package/sdk/typescript/test/errors.test.ts +169 -0
  627. package/sdk/typescript/test/format-integration.test.ts +252 -0
  628. package/sdk/typescript/test/hooks.test.ts +265 -0
  629. package/sdk/typescript/test/integration.test.ts +249 -0
  630. package/sdk/typescript/test/mdx-examples.test.ts +253 -0
  631. package/sdk/typescript/test/models.test.ts +318 -0
  632. package/sdk/typescript/test/parity.test.ts +337 -0
  633. package/sdk/typescript/test/paths.test.ts +447 -0
  634. package/sdk/typescript/test/shared-context.test.ts +245 -0
  635. package/sdk/typescript/test/simulate.test.ts +84 -0
  636. package/sdk/typescript/test/types.test.ts +244 -0
  637. package/sdk/typescript/test/utils/case.test.ts +129 -0
  638. package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
  639. package/sdk/typescript/test/utils/format.test.ts +434 -0
  640. package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
  641. package/sdk/typescript/tsup.config.ts +17 -0
  642. package/tailwind.master.config.cjs +47 -0
  643. package/types/api.ts +12 -0
  644. package/types/config.ts +9 -0
  645. package/types/index.ts +2 -0
  646. package/uv.lock +6951 -0
  647. package/xithead.egg-info/PKG-INFO +22 -0
  648. package/xithead.egg-info/SOURCES.txt +16 -0
  649. package/xithead.egg-info/dependency_links.txt +1 -0
  650. package/xithead.egg-info/entry_points.txt +2 -0
  651. package/xithead.egg-info/requires.txt +10 -0
  652. package/xithead.egg-info/top_level.txt +2 -0
  653. package/xithead.ps1 +136 -0
  654. package/xithead.sh +129 -0
  655. package/xithead_dist/pyproject.toml +39 -0
  656. package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
  657. package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
  658. package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
  659. package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
  660. package/xithead_dist/xithead.egg-info/requires.txt +10 -0
  661. package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
@@ -0,0 +1,769 @@
1
+ //! Incremental binary EventStream parser — Phase D PR-D2.
2
+ //!
3
+ //! # What this parses
4
+ //!
5
+ //! AWS Bedrock's streaming surface (`/model/{id}/invoke-with-response-stream`)
6
+ //! returns `application/vnd.amazon.eventstream` framed messages, NOT
7
+ //! Server-Sent Events. Each message is:
8
+ //!
9
+ //! ```text
10
+ //! +------------------+----------------------+------------------+
11
+ //! | prelude (12B) | headers (N1 B) | payload (N2 B) | + 4-byte CRC32
12
+ //! +------------------+----------------------+------------------+
13
+ //! ```
14
+ //!
15
+ //! Where the prelude is three big-endian u32s:
16
+ //!
17
+ //! - `total_length` (bytes from start-of-message up to AND including
18
+ //! the trailing message CRC32),
19
+ //! - `headers_length` (bytes occupied by the headers block),
20
+ //! - `prelude_crc32` (CRC32 of the first 8 bytes of the prelude).
21
+ //!
22
+ //! The payload length is computed: `total_length - 12 - headers_length - 4`.
23
+ //!
24
+ //! Each header is `[name_len: u8][name (UTF-8)][value_type: u8][value]`.
25
+ //! AWS defines 10 value types but Bedrock in practice only emits a handful:
26
+ //!
27
+ //! - `7` — UTF-8 string with `[u16 BE length][bytes]`
28
+ //! - `6` — byte array with `[u16 BE length][bytes]`
29
+ //!
30
+ //! We support both because Bedrock's `:event-type`, `:content-type`,
31
+ //! and `:message-type` come through as type-7 strings, and the payload
32
+ //! carries an embedded JSON document as a UTF-8 string AT THE PAYLOAD
33
+ //! LEVEL (not as a header value).
34
+ //!
35
+ //! # Why a stateful struct
36
+ //!
37
+ //! TCP delivers chunks at unpredictable boundaries — a single
38
+ //! EventStream message can arrive in any number of pieces, and one
39
+ //! `Bytes` chunk can also contain multiple complete messages plus a
40
+ //! partial trailing one. The parser MUST resume across chunks without
41
+ //! losing bytes; we accumulate into an internal buffer and yield
42
+ //! complete messages as they materialise. Same incremental contract
43
+ //! as `sse::framing::SseFramer` (Phase C) — that's the model.
44
+ //!
45
+ //! # No panics, no fallbacks
46
+ //!
47
+ //! Per `feedback_no_silent_fallbacks.md`: this parser ALWAYS returns a
48
+ //! `Result`. CRC mismatch → [`ParseError::PreludeCrcMismatch`] /
49
+ //! [`ParseError::MessageCrcMismatch`]; truncated prelude with absurd
50
+ //! lengths → [`ParseError::ImplausiblePreludeLengths`]. The handler
51
+ //! turns errors into 5xx responses — we never silently swallow a
52
+ //! malformed frame and forward zeros to the client.
53
+
54
+ use std::collections::HashMap;
55
+
56
+ use bytes::{Buf, Bytes, BytesMut};
57
+ use thiserror::Error;
58
+
59
+ /// AWS-defined header value types. Bedrock today only uses `7`
60
+ /// (string) and `6` (byte buffer); the others are listed for
61
+ /// completeness so a future Bedrock surface that emits them does
62
+ /// not require a parser revision.
63
+ mod header_type {
64
+ pub const TRUE: u8 = 0;
65
+ pub const FALSE: u8 = 1;
66
+ pub const BYTE: u8 = 2;
67
+ pub const SHORT: u8 = 3;
68
+ pub const INTEGER: u8 = 4;
69
+ pub const LONG: u8 = 5;
70
+ pub const BYTE_ARRAY: u8 = 6;
71
+ pub const STRING: u8 = 7;
72
+ pub const TIMESTAMP: u8 = 8;
73
+ pub const UUID: u8 = 9;
74
+ }
75
+
76
+ /// Length of the 3-u32 prelude in bytes.
77
+ const PRELUDE_LEN: usize = 12;
78
+
79
+ /// CRC32 trails the message and is itself 4 bytes, NOT counted in
80
+ /// `headers_length` but counted in `total_length`.
81
+ const MESSAGE_CRC_LEN: usize = 4;
82
+
83
+ /// Sanity ceiling for `total_length`. AWS's documented maximum is
84
+ /// 16 MiB. We refuse anything beyond ~32 MiB (2× headroom for future
85
+ /// limit raises) so a truncated stream that decoded a garbage length
86
+ /// does not allocate gigabytes. Configurable via the public
87
+ /// [`EventStreamParser::with_max_message_bytes`] constructor.
88
+ const DEFAULT_MAX_MESSAGE_BYTES: usize = 32 * 1024 * 1024;
89
+
90
+ /// One value carried in an EventStream header. AWS defines 10 wire
91
+ /// types; today Bedrock emits two (string + byte-buffer). We expose
92
+ /// the variants we actually parse and surface a structured error for
93
+ /// any other type so the caller can log it loudly.
94
+ #[derive(Debug, Clone, PartialEq, Eq)]
95
+ pub enum HeaderValue {
96
+ /// `header_type::STRING` — UTF-8 string.
97
+ String(String),
98
+ /// `header_type::BYTE_ARRAY` — opaque bytes.
99
+ Bytes(Bytes),
100
+ }
101
+
102
+ impl HeaderValue {
103
+ /// Cheap accessor for the common `event_name == "chunk"` style
104
+ /// dispatch. Returns `Some` only for [`HeaderValue::String`].
105
+ pub fn as_str(&self) -> Option<&str> {
106
+ match self {
107
+ HeaderValue::String(s) => Some(s.as_str()),
108
+ HeaderValue::Bytes(_) => None,
109
+ }
110
+ }
111
+ }
112
+
113
+ /// One complete EventStream message.
114
+ #[derive(Debug, Clone)]
115
+ pub struct EventStreamMessage {
116
+ /// Headers, lower-cased keys for stable lookup. Bedrock spec
117
+ /// headers (`:event-type`, `:content-type`, `:message-type`) are
118
+ /// already lower-case but we normalise defensively.
119
+ pub headers: HashMap<String, HeaderValue>,
120
+ /// Raw payload bytes. The semantic meaning depends on
121
+ /// `:event-type` — for Bedrock Anthropic streaming responses each
122
+ /// `chunk` payload is a UTF-8 JSON string carrying one Anthropic
123
+ /// SSE event.
124
+ pub payload: Bytes,
125
+ }
126
+
127
+ impl EventStreamMessage {
128
+ /// Read the `:event-type` header as a string. Convenience for the
129
+ /// translator. Returns `None` if missing or not a string.
130
+ pub fn event_type(&self) -> Option<&str> {
131
+ self.headers.get(":event-type").and_then(|v| v.as_str())
132
+ }
133
+
134
+ /// Read the `:message-type` header as a string. Bedrock uses
135
+ /// `event` (data frames) vs `exception` (synchronous errors).
136
+ pub fn message_type(&self) -> Option<&str> {
137
+ self.headers.get(":message-type").and_then(|v| v.as_str())
138
+ }
139
+ }
140
+
141
+ /// Errors surfaced by the parser. Per project rules these are
142
+ /// structured (not `String`) so the handler can dispatch on them.
143
+ #[derive(Debug, Error)]
144
+ pub enum ParseError {
145
+ /// `total_length` smaller than the minimum a well-formed message
146
+ /// requires (12-byte prelude, headers block, 4-byte trailing CRC).
147
+ /// Wire-format violation; AWS would never emit this. Surfaced
148
+ /// loudly so the handler can 5xx and log it.
149
+ #[error(
150
+ "implausible prelude lengths: total_length={total_length}, headers_length={headers_length}"
151
+ )]
152
+ ImplausiblePreludeLengths {
153
+ total_length: u32,
154
+ headers_length: u32,
155
+ },
156
+ /// `total_length` exceeds the configured `max_message_bytes` cap.
157
+ /// The cap defaults to 32 MiB; configurable via
158
+ /// [`EventStreamParser::with_max_message_bytes`].
159
+ #[error("message too large: total_length={total_length} cap={cap}")]
160
+ MessageTooLarge { total_length: u32, cap: usize },
161
+ /// CRC32 of the first 8 bytes of the prelude did not match the
162
+ /// 9th-12th bytes. Indicates corruption (in-flight bit-flip,
163
+ /// truncated chunk, or — if persistent — wire-format version skew).
164
+ #[error("prelude CRC mismatch: expected={expected:#010x} got={got:#010x}")]
165
+ PreludeCrcMismatch { expected: u32, got: u32 },
166
+ /// CRC32 of the entire message body did not match the trailing
167
+ /// 4-byte CRC. Indicates the message bytes were corrupted in
168
+ /// flight.
169
+ #[error("message CRC mismatch: expected={expected:#010x} got={got:#010x}")]
170
+ MessageCrcMismatch { expected: u32, got: u32 },
171
+ /// A header's `name_len` extended past the declared end of the
172
+ /// headers block.
173
+ #[error("truncated header at offset {offset}: needs {needed} more bytes")]
174
+ TruncatedHeader { offset: usize, needed: usize },
175
+ /// A header's name was not valid UTF-8.
176
+ #[error("header name not valid UTF-8 at offset {offset}: {source}")]
177
+ HeaderNameNotUtf8 {
178
+ offset: usize,
179
+ #[source]
180
+ source: std::str::Utf8Error,
181
+ },
182
+ /// A string-typed header value was not valid UTF-8.
183
+ #[error("header value not valid UTF-8 at offset {offset}: {source}")]
184
+ HeaderValueNotUtf8 {
185
+ offset: usize,
186
+ #[source]
187
+ source: std::str::Utf8Error,
188
+ },
189
+ /// Header value type not in the AWS spec (the spec defines 0..=9).
190
+ /// `value_type` is the literal byte we read.
191
+ #[error("unsupported header value type {value_type} at offset {offset}")]
192
+ UnsupportedHeaderType { value_type: u8, offset: usize },
193
+ }
194
+
195
+ /// Whether to validate CRCs. Defaults to `Yes`; tests + the
196
+ /// `--bedrock-validate-eventstream-crc=false` debug flag flip it off.
197
+ #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
198
+ pub enum CrcValidation {
199
+ #[default]
200
+ Yes,
201
+ No,
202
+ }
203
+
204
+ /// Stateful parser. Feed `Bytes` chunks via [`EventStreamParser::push`]
205
+ /// and pull complete messages via [`EventStreamParser::next_message`].
206
+ /// Mirrors the API shape of `sse::framing::SseFramer` deliberately so
207
+ /// callers familiar with the SSE side find the EventStream side
208
+ /// identical in spirit.
209
+ #[derive(Debug)]
210
+ pub struct EventStreamParser {
211
+ buf: BytesMut,
212
+ crc_validation: CrcValidation,
213
+ max_message_bytes: usize,
214
+ }
215
+
216
+ impl Default for EventStreamParser {
217
+ fn default() -> Self {
218
+ Self {
219
+ buf: BytesMut::new(),
220
+ crc_validation: CrcValidation::Yes,
221
+ max_message_bytes: DEFAULT_MAX_MESSAGE_BYTES,
222
+ }
223
+ }
224
+ }
225
+
226
+ impl EventStreamParser {
227
+ pub fn new() -> Self {
228
+ Self::default()
229
+ }
230
+
231
+ /// Construct with explicit CRC validation policy. Operators flip
232
+ /// to `No` only for debugging — production must validate.
233
+ pub fn with_crc_validation(mut self, crc: CrcValidation) -> Self {
234
+ self.crc_validation = crc;
235
+ self
236
+ }
237
+
238
+ /// Configurable hard cap on `total_length`. Above this the parser
239
+ /// refuses (returns [`ParseError::MessageTooLarge`]) so a corrupted
240
+ /// stream cannot allocate unbounded memory.
241
+ pub fn with_max_message_bytes(mut self, cap: usize) -> Self {
242
+ self.max_message_bytes = cap;
243
+ self
244
+ }
245
+
246
+ /// Append a chunk of inbound bytes. Zero-length chunks are no-ops.
247
+ pub fn push(&mut self, chunk: &[u8]) {
248
+ if !chunk.is_empty() {
249
+ self.buf.extend_from_slice(chunk);
250
+ }
251
+ }
252
+
253
+ /// Number of bytes currently buffered (un-framed). Useful for tests.
254
+ pub fn buffered_len(&self) -> usize {
255
+ self.buf.len()
256
+ }
257
+
258
+ /// Pull the next complete message. Returns:
259
+ ///
260
+ /// - `Ok(None)` — the buffer doesn't yet contain a full message;
261
+ /// caller should `push` more bytes.
262
+ /// - `Ok(Some(msg))` — one complete message; caller may call
263
+ /// again to drain further messages from the buffer.
264
+ /// - `Err(_)` — wire-format violation. Per project policy, the
265
+ /// handler 5xx's and logs `event=bedrock_eventstream_*_mismatch`.
266
+ pub fn next_message(&mut self) -> Result<Option<EventStreamMessage>, ParseError> {
267
+ // Need at least the prelude before we can decide.
268
+ if self.buf.len() < PRELUDE_LEN {
269
+ return Ok(None);
270
+ }
271
+ let total_length = u32::from_be_bytes(self.buf[0..4].try_into().expect("4 bytes"));
272
+ let headers_length = u32::from_be_bytes(self.buf[4..8].try_into().expect("4 bytes"));
273
+ let prelude_crc_expected = u32::from_be_bytes(self.buf[8..12].try_into().expect("4 bytes"));
274
+
275
+ // Validate plausibility BEFORE we wait for the rest of the
276
+ // bytes. If the prelude lengths are absurd we want to fail
277
+ // immediately rather than buffer a multi-GB stream.
278
+ if (total_length as usize) < PRELUDE_LEN + headers_length as usize + MESSAGE_CRC_LEN {
279
+ return Err(ParseError::ImplausiblePreludeLengths {
280
+ total_length,
281
+ headers_length,
282
+ });
283
+ }
284
+ if (total_length as usize) > self.max_message_bytes {
285
+ return Err(ParseError::MessageTooLarge {
286
+ total_length,
287
+ cap: self.max_message_bytes,
288
+ });
289
+ }
290
+
291
+ // Validate prelude CRC over the first 8 bytes (lengths only,
292
+ // NOT the prelude_crc itself).
293
+ if matches!(self.crc_validation, CrcValidation::Yes) {
294
+ let computed = crc32fast::hash(&self.buf[0..8]);
295
+ if computed != prelude_crc_expected {
296
+ return Err(ParseError::PreludeCrcMismatch {
297
+ expected: prelude_crc_expected,
298
+ got: computed,
299
+ });
300
+ }
301
+ }
302
+
303
+ // Need the entire message before we yield.
304
+ if self.buf.len() < total_length as usize {
305
+ return Ok(None);
306
+ }
307
+
308
+ // Validate trailing message CRC over bytes [0..total_length-4].
309
+ let message_crc_expected = u32::from_be_bytes(
310
+ self.buf[total_length as usize - MESSAGE_CRC_LEN..total_length as usize]
311
+ .try_into()
312
+ .expect("4 bytes"),
313
+ );
314
+ if matches!(self.crc_validation, CrcValidation::Yes) {
315
+ let computed = crc32fast::hash(&self.buf[0..total_length as usize - MESSAGE_CRC_LEN]);
316
+ if computed != message_crc_expected {
317
+ return Err(ParseError::MessageCrcMismatch {
318
+ expected: message_crc_expected,
319
+ got: computed,
320
+ });
321
+ }
322
+ }
323
+
324
+ // Slice the message off the buffer.
325
+ let message_bytes = self.buf.split_to(total_length as usize).freeze();
326
+
327
+ let headers_start = PRELUDE_LEN;
328
+ let headers_end = PRELUDE_LEN + headers_length as usize;
329
+ let payload_start = headers_end;
330
+ let payload_end = total_length as usize - MESSAGE_CRC_LEN;
331
+
332
+ let headers_slice = message_bytes.slice(headers_start..headers_end);
333
+ let payload = message_bytes.slice(payload_start..payload_end);
334
+ let headers = parse_headers(&headers_slice)?;
335
+
336
+ Ok(Some(EventStreamMessage { headers, payload }))
337
+ }
338
+ }
339
+
340
+ /// One-shot helper. Convenience for callers that already have all the
341
+ /// bytes of one message in hand (e.g. wiremock test fixtures). Returns
342
+ /// `Err` if the bytes are not exactly one well-formed message.
343
+ ///
344
+ /// Per the property test invariant, this never panics on adversarial
345
+ /// input — every malformed-bytes path returns a [`ParseError`].
346
+ pub fn parse(bytes: &[u8]) -> Result<EventStreamMessage, ParseError> {
347
+ let mut parser = EventStreamParser::new();
348
+ parser.push(bytes);
349
+ match parser.next_message()? {
350
+ Some(msg) => Ok(msg),
351
+ None => Err(ParseError::ImplausiblePreludeLengths {
352
+ total_length: 0,
353
+ headers_length: 0,
354
+ }),
355
+ }
356
+ }
357
+
358
+ /// Parse a headers-block byte slice.
359
+ fn parse_headers(slice: &Bytes) -> Result<HashMap<String, HeaderValue>, ParseError> {
360
+ let mut out: HashMap<String, HeaderValue> = HashMap::new();
361
+ let mut cursor = 0usize;
362
+ let total = slice.len();
363
+ while cursor < total {
364
+ // [name_len: u8][name][value_type: u8][value]
365
+ if cursor + 1 > total {
366
+ return Err(ParseError::TruncatedHeader {
367
+ offset: cursor,
368
+ needed: 1,
369
+ });
370
+ }
371
+ let name_len = slice[cursor] as usize;
372
+ cursor += 1;
373
+ if cursor + name_len > total {
374
+ return Err(ParseError::TruncatedHeader {
375
+ offset: cursor,
376
+ needed: name_len,
377
+ });
378
+ }
379
+ let name = std::str::from_utf8(&slice[cursor..cursor + name_len])
380
+ .map_err(|e| ParseError::HeaderNameNotUtf8 {
381
+ offset: cursor,
382
+ source: e,
383
+ })?
384
+ .to_ascii_lowercase();
385
+ cursor += name_len;
386
+ if cursor + 1 > total {
387
+ return Err(ParseError::TruncatedHeader {
388
+ offset: cursor,
389
+ needed: 1,
390
+ });
391
+ }
392
+ let value_type = slice[cursor];
393
+ cursor += 1;
394
+ let value = match value_type {
395
+ header_type::STRING => {
396
+ if cursor + 2 > total {
397
+ return Err(ParseError::TruncatedHeader {
398
+ offset: cursor,
399
+ needed: 2,
400
+ });
401
+ }
402
+ let value_len =
403
+ u16::from_be_bytes(slice[cursor..cursor + 2].try_into().expect("2 bytes"))
404
+ as usize;
405
+ cursor += 2;
406
+ if cursor + value_len > total {
407
+ return Err(ParseError::TruncatedHeader {
408
+ offset: cursor,
409
+ needed: value_len,
410
+ });
411
+ }
412
+ let s = std::str::from_utf8(&slice[cursor..cursor + value_len]).map_err(|e| {
413
+ ParseError::HeaderValueNotUtf8 {
414
+ offset: cursor,
415
+ source: e,
416
+ }
417
+ })?;
418
+ cursor += value_len;
419
+ HeaderValue::String(s.to_string())
420
+ }
421
+ header_type::BYTE_ARRAY => {
422
+ if cursor + 2 > total {
423
+ return Err(ParseError::TruncatedHeader {
424
+ offset: cursor,
425
+ needed: 2,
426
+ });
427
+ }
428
+ let value_len =
429
+ u16::from_be_bytes(slice[cursor..cursor + 2].try_into().expect("2 bytes"))
430
+ as usize;
431
+ cursor += 2;
432
+ if cursor + value_len > total {
433
+ return Err(ParseError::TruncatedHeader {
434
+ offset: cursor,
435
+ needed: value_len,
436
+ });
437
+ }
438
+ let v = slice.slice(cursor..cursor + value_len);
439
+ cursor += value_len;
440
+ HeaderValue::Bytes(v)
441
+ }
442
+ // The TRUE/FALSE flags carry no value bytes; we surface
443
+ // them as a single-byte payload `Bytes` for completeness
444
+ // even though Bedrock never emits them. Other types that
445
+ // DO carry payload but we have no use for fall through to
446
+ // the "unsupported" arm — better a structured error than
447
+ // a silently-skipped header.
448
+ header_type::TRUE => HeaderValue::Bytes(Bytes::from_static(&[1])),
449
+ header_type::FALSE => HeaderValue::Bytes(Bytes::from_static(&[0])),
450
+ header_type::BYTE => {
451
+ if cursor + 1 > total {
452
+ return Err(ParseError::TruncatedHeader {
453
+ offset: cursor,
454
+ needed: 1,
455
+ });
456
+ }
457
+ let v = slice.slice(cursor..cursor + 1);
458
+ cursor += 1;
459
+ HeaderValue::Bytes(v)
460
+ }
461
+ header_type::SHORT => {
462
+ if cursor + 2 > total {
463
+ return Err(ParseError::TruncatedHeader {
464
+ offset: cursor,
465
+ needed: 2,
466
+ });
467
+ }
468
+ let v = slice.slice(cursor..cursor + 2);
469
+ cursor += 2;
470
+ HeaderValue::Bytes(v)
471
+ }
472
+ header_type::INTEGER => {
473
+ if cursor + 4 > total {
474
+ return Err(ParseError::TruncatedHeader {
475
+ offset: cursor,
476
+ needed: 4,
477
+ });
478
+ }
479
+ let v = slice.slice(cursor..cursor + 4);
480
+ cursor += 4;
481
+ HeaderValue::Bytes(v)
482
+ }
483
+ header_type::LONG | header_type::TIMESTAMP => {
484
+ if cursor + 8 > total {
485
+ return Err(ParseError::TruncatedHeader {
486
+ offset: cursor,
487
+ needed: 8,
488
+ });
489
+ }
490
+ let v = slice.slice(cursor..cursor + 8);
491
+ cursor += 8;
492
+ HeaderValue::Bytes(v)
493
+ }
494
+ header_type::UUID => {
495
+ if cursor + 16 > total {
496
+ return Err(ParseError::TruncatedHeader {
497
+ offset: cursor,
498
+ needed: 16,
499
+ });
500
+ }
501
+ let v = slice.slice(cursor..cursor + 16);
502
+ cursor += 16;
503
+ HeaderValue::Bytes(v)
504
+ }
505
+ other => {
506
+ return Err(ParseError::UnsupportedHeaderType {
507
+ value_type: other,
508
+ offset: cursor.saturating_sub(1),
509
+ });
510
+ }
511
+ };
512
+ out.insert(name, value);
513
+ }
514
+ // Sanity: cursor must equal total or we have a parse-loop bug.
515
+ let _ = (cursor, total, header_type::TRUE, Buf::remaining(&&[][..])); // pin unused-import
516
+ Ok(out)
517
+ }
518
+
519
+ // ────────────────────────────────────────────────────────────────────
520
+ // Test-only helpers for synthesising bytes. Living here (vs in the
521
+ // integration test crate) so unit tests in this module can exercise
522
+ // the parser end-to-end and the integration tests have the same builder
523
+ // available via `pub(crate)`.
524
+ // ────────────────────────────────────────────────────────────────────
525
+
526
+ /// Builder for synthesising a well-formed EventStream message. Used by
527
+ /// tests and by [`build_chunk_message`]. Producing valid bytes is much
528
+ /// more delicate than parsing them — this helper centralises the CRC
529
+ /// math.
530
+ #[derive(Debug, Default)]
531
+ pub struct MessageBuilder {
532
+ headers: Vec<(String, HeaderValue)>,
533
+ payload: Bytes,
534
+ }
535
+
536
+ impl MessageBuilder {
537
+ pub fn new() -> Self {
538
+ Self::default()
539
+ }
540
+
541
+ pub fn header_string(mut self, name: &str, value: &str) -> Self {
542
+ self.headers
543
+ .push((name.to_string(), HeaderValue::String(value.to_string())));
544
+ self
545
+ }
546
+
547
+ pub fn header_bytes(mut self, name: &str, value: Bytes) -> Self {
548
+ self.headers
549
+ .push((name.to_string(), HeaderValue::Bytes(value)));
550
+ self
551
+ }
552
+
553
+ pub fn payload(mut self, payload: Bytes) -> Self {
554
+ self.payload = payload;
555
+ self
556
+ }
557
+
558
+ /// Serialize to the wire format. Computes both CRCs.
559
+ pub fn build(self) -> Bytes {
560
+ let mut headers_bytes = BytesMut::new();
561
+ for (name, value) in &self.headers {
562
+ // name_len + name
563
+ assert!(name.len() <= u8::MAX as usize, "header name too long");
564
+ headers_bytes.extend_from_slice(&[name.len() as u8]);
565
+ headers_bytes.extend_from_slice(name.as_bytes());
566
+ match value {
567
+ HeaderValue::String(s) => {
568
+ headers_bytes.extend_from_slice(&[header_type::STRING]);
569
+ let len = s.len() as u16;
570
+ headers_bytes.extend_from_slice(&len.to_be_bytes());
571
+ headers_bytes.extend_from_slice(s.as_bytes());
572
+ }
573
+ HeaderValue::Bytes(b) => {
574
+ headers_bytes.extend_from_slice(&[header_type::BYTE_ARRAY]);
575
+ let len = b.len() as u16;
576
+ headers_bytes.extend_from_slice(&len.to_be_bytes());
577
+ headers_bytes.extend_from_slice(b);
578
+ }
579
+ }
580
+ }
581
+ let headers_len = headers_bytes.len() as u32;
582
+ let payload_len = self.payload.len() as u32;
583
+ let total_len = PRELUDE_LEN as u32 + headers_len + payload_len + MESSAGE_CRC_LEN as u32;
584
+
585
+ let mut out = BytesMut::with_capacity(total_len as usize);
586
+ out.extend_from_slice(&total_len.to_be_bytes());
587
+ out.extend_from_slice(&headers_len.to_be_bytes());
588
+ let prelude_crc = crc32fast::hash(&out[..]);
589
+ out.extend_from_slice(&prelude_crc.to_be_bytes());
590
+ out.extend_from_slice(&headers_bytes);
591
+ out.extend_from_slice(&self.payload);
592
+ let message_crc = crc32fast::hash(&out[..]);
593
+ out.extend_from_slice(&message_crc.to_be_bytes());
594
+ out.freeze()
595
+ }
596
+ }
597
+
598
+ /// Build a minimal Anthropic-on-Bedrock `chunk` message. The payload
599
+ /// is the JSON bytes for an Anthropic SSE event, as Bedrock emits.
600
+ pub fn build_chunk_message(payload_json: &str) -> Bytes {
601
+ MessageBuilder::new()
602
+ .header_string(":event-type", "chunk")
603
+ .header_string(":content-type", "application/json")
604
+ .header_string(":message-type", "event")
605
+ .payload(Bytes::copy_from_slice(payload_json.as_bytes()))
606
+ .build()
607
+ }
608
+
609
+ #[cfg(test)]
610
+ mod tests {
611
+ use super::*;
612
+
613
+ #[test]
614
+ fn round_trip_single_message() {
615
+ let bytes = build_chunk_message(r#"{"type":"message_start","message":{"id":"msg_a"}}"#);
616
+ let mut parser = EventStreamParser::new();
617
+ parser.push(&bytes);
618
+ let msg = parser.next_message().unwrap().unwrap();
619
+ assert_eq!(msg.event_type(), Some("chunk"));
620
+ assert_eq!(msg.message_type(), Some("event"));
621
+ let payload_str = std::str::from_utf8(&msg.payload).unwrap();
622
+ assert!(payload_str.starts_with(r#"{"type":"message_start""#));
623
+ assert!(parser.next_message().unwrap().is_none());
624
+ }
625
+
626
+ #[test]
627
+ fn round_trip_multi_message_one_chunk() {
628
+ let mut combined = BytesMut::new();
629
+ combined.extend_from_slice(&build_chunk_message(r#"{"a":1}"#));
630
+ combined.extend_from_slice(&build_chunk_message(r#"{"b":2}"#));
631
+ let mut parser = EventStreamParser::new();
632
+ parser.push(&combined);
633
+ let m1 = parser.next_message().unwrap().unwrap();
634
+ let m2 = parser.next_message().unwrap().unwrap();
635
+ assert_eq!(std::str::from_utf8(&m1.payload).unwrap(), r#"{"a":1}"#);
636
+ assert_eq!(std::str::from_utf8(&m2.payload).unwrap(), r#"{"b":2}"#);
637
+ assert!(parser.next_message().unwrap().is_none());
638
+ }
639
+
640
+ #[test]
641
+ fn one_byte_at_a_time_no_loss() {
642
+ // Drip-feed a complete message one byte at a time. Parser
643
+ // must yield exactly one message at the very end.
644
+ let bytes = build_chunk_message(r#"{"type":"message_stop"}"#);
645
+ let mut parser = EventStreamParser::new();
646
+ for b in bytes.iter() {
647
+ parser.push(std::slice::from_ref(b));
648
+ // For all but the last byte, no message yet.
649
+ }
650
+ let msg = parser.next_message().unwrap().unwrap();
651
+ assert_eq!(
652
+ std::str::from_utf8(&msg.payload).unwrap(),
653
+ r#"{"type":"message_stop"}"#,
654
+ );
655
+ }
656
+
657
+ #[test]
658
+ fn prelude_crc_mismatch_loud() {
659
+ // Build a valid message, then corrupt the prelude CRC.
660
+ let mut bytes: Vec<u8> = build_chunk_message(r#"{"x":1}"#).to_vec();
661
+ bytes[8] ^= 0xff;
662
+ let mut parser = EventStreamParser::new();
663
+ parser.push(&bytes);
664
+ let err = parser.next_message().unwrap_err();
665
+ assert!(
666
+ matches!(err, ParseError::PreludeCrcMismatch { .. }),
667
+ "got {err:?}"
668
+ );
669
+ }
670
+
671
+ #[test]
672
+ fn message_crc_mismatch_loud() {
673
+ let mut bytes: Vec<u8> = build_chunk_message(r#"{"y":2}"#).to_vec();
674
+ // Corrupt the trailing CRC (last 4 bytes).
675
+ let n = bytes.len();
676
+ bytes[n - 1] ^= 0xff;
677
+ let mut parser = EventStreamParser::new();
678
+ parser.push(&bytes);
679
+ let err = parser.next_message().unwrap_err();
680
+ assert!(
681
+ matches!(err, ParseError::MessageCrcMismatch { .. }),
682
+ "got {err:?}"
683
+ );
684
+ }
685
+
686
+ #[test]
687
+ fn implausible_lengths_loud() {
688
+ // Forge a prelude where total < headers + 12 + 4. Caller never
689
+ // gets a chance to even compute the CRC.
690
+ let mut bytes = BytesMut::new();
691
+ bytes.extend_from_slice(&8u32.to_be_bytes()); // total = 8 (impossible)
692
+ bytes.extend_from_slice(&0u32.to_be_bytes()); // headers = 0
693
+ bytes.extend_from_slice(&0u32.to_be_bytes()); // bogus crc
694
+ let mut parser = EventStreamParser::new();
695
+ parser.push(&bytes);
696
+ let err = parser.next_message().unwrap_err();
697
+ assert!(
698
+ matches!(err, ParseError::ImplausiblePreludeLengths { .. }),
699
+ "got {err:?}"
700
+ );
701
+ }
702
+
703
+ #[test]
704
+ fn message_too_large_loud() {
705
+ // Forge a prelude with an enormous total_length and observe
706
+ // the cap rejection (we never even allocate the payload).
707
+ let mut bytes = BytesMut::new();
708
+ bytes.extend_from_slice(&(64u32 * 1024 * 1024).to_be_bytes()); // 64 MiB
709
+ bytes.extend_from_slice(&0u32.to_be_bytes());
710
+ let valid_crc = crc32fast::hash(&bytes[0..8]);
711
+ bytes.extend_from_slice(&valid_crc.to_be_bytes());
712
+ let mut parser = EventStreamParser::new().with_max_message_bytes(32 * 1024 * 1024);
713
+ parser.push(&bytes);
714
+ let err = parser.next_message().unwrap_err();
715
+ assert!(
716
+ matches!(err, ParseError::MessageTooLarge { .. }),
717
+ "got {err:?}"
718
+ );
719
+ }
720
+
721
+ #[test]
722
+ fn crc_validation_off_accepts_corrupt_prelude() {
723
+ // With CrcValidation::No, prelude+message CRCs are ignored.
724
+ let mut bytes: Vec<u8> = build_chunk_message(r#"{"a":3}"#).to_vec();
725
+ bytes[8] ^= 0xff; // corrupt prelude crc
726
+ let n = bytes.len();
727
+ bytes[n - 1] ^= 0xff; // corrupt message crc
728
+ let mut parser = EventStreamParser::new().with_crc_validation(CrcValidation::No);
729
+ parser.push(&bytes);
730
+ let msg = parser.next_message().unwrap().unwrap();
731
+ assert_eq!(std::str::from_utf8(&msg.payload).unwrap(), r#"{"a":3}"#);
732
+ }
733
+
734
+ #[test]
735
+ fn header_bytes_round_trip() {
736
+ let payload_bytes = Bytes::from_static(b"\x01\x02\x03");
737
+ let bytes = MessageBuilder::new()
738
+ .header_string(":event-type", "chunk")
739
+ .header_bytes(":custom-bytes", payload_bytes.clone())
740
+ .payload(Bytes::from_static(b"{}"))
741
+ .build();
742
+ let parsed = parse(&bytes).unwrap();
743
+ match parsed.headers.get(":custom-bytes").unwrap() {
744
+ HeaderValue::Bytes(b) => assert_eq!(b, &payload_bytes),
745
+ _ => panic!("expected bytes header"),
746
+ }
747
+ }
748
+
749
+ #[test]
750
+ fn parse_one_shot_helper() {
751
+ let bytes = build_chunk_message(r#"{"k":"v"}"#);
752
+ let m = parse(&bytes).unwrap();
753
+ assert_eq!(m.event_type(), Some("chunk"));
754
+ }
755
+
756
+ #[test]
757
+ fn parse_one_shot_returns_err_on_partial() {
758
+ // 4 bytes only — never enough for a prelude.
759
+ let bytes = vec![0u8, 0, 0, 8];
760
+ let err = parse(&bytes).unwrap_err();
761
+ assert!(matches!(err, ParseError::ImplausiblePreludeLengths { .. }));
762
+ }
763
+
764
+ #[test]
765
+ fn empty_buffer_yields_none() {
766
+ let mut parser = EventStreamParser::new();
767
+ assert!(parser.next_message().unwrap().is_none());
768
+ }
769
+ }