Skip to content

fix: add timeout protection and AUTH_SECRET fail-fast to Vercel serverless bootstrap to prevent 60s hangs#296

Merged
hotlong merged 4 commits intomainfrom
copilot/fix-vercel-login-timeout
Mar 19, 2026
Merged

fix: add timeout protection and AUTH_SECRET fail-fast to Vercel serverless bootstrap to prevent 60s hangs#296
hotlong merged 4 commits intomainfrom
copilot/fix-vercel-login-timeout

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Mar 19, 2026

Description

The Vercel serverless handler hangs for the full 60s function limit when any plugin's init/start returns a never-resolving promise. This adds 3-layer timeout protection, diagnostic logging, and environment variable fail-fast checks so hangs fail fast with an actionable error instead of silently timing out.

Type of Change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Code refactoring
  • Performance improvement
  • CI/CD update

Related Issues

Related to #62

Changes Made

api/[[...route]].ts

  • Add withTimeout<T>(promise, ms, label) utility that races a promise against a deadline
  • Wrap every kernel.use() with 10s per-plugin timeout
  • Wrap kernel.bootstrap() with 30s timeout
  • Wrap the entire bootstrap() with 50s budget (10s margin for Vercel's 60s limit)
  • Return 503 with JSON body on bootstrap failure instead of hanging
  • Add timestamped [HotCRM] [<elapsed>ms] diagnostic logs at each step — identifies the blocking plugin from Vercel Function Logs
  • Add AUTH_SECRET fail-fast check on Vercel — when the VERCEL env var is set, missing AUTH_SECRET now throws immediately with an actionable error pointing to Vercel Dashboard settings, instead of silently falling back to an insecure dev placeholder
// Before: hangs forever if any plugin never resolves
await kernel.use(new AuthPlugin({ ... }));

// After: fails fast with "[HotCRM] Timeout after 10000ms: AuthPlugin"
await withTimeout(kernel.use(new AuthPlugin({ ... })), PLUGIN_TIMEOUT_MS, 'AuthPlugin');

CHANGELOG.md / docs/DEPLOYMENT.md — document timeout architecture and AUTH_SECRET fail-fast behavior

Testing

  • Unit tests pass (npm test)
  • Linting passes (npm run lint)
  • Build succeeds (npm run build)
  • Manual testing completed
  • New tests added (if applicable)

All 196 test files / 4036 tests pass unchanged.

Screenshots

N/A

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • Any dependent changes have been merged and published

Additional Notes

No tests added for the handler itself — the api/ directory is outside the vitest test root (packages/**) and the handler requires the full @objectstack/runtime kernel to bootstrap. The timeout utility is straightforward enough to verify by inspection.

Original prompt

This section details on the original issue you should resolve

<issue_title>fix: Vercel 登录超时 60s(Serverless Handler 卡死)��查与修复</issue_title>
<issue_description>## 问题描述

目前 HotCRM 在 Vercel 上偶发或持续出现登录(或首页)请求超时,表现为 60s serverless 函数超时(Error: Function Timeout after 60s)。同样基于 ObjectStack 的 Studio/Spec 项目则没有此问题。


已确认的非根因

  • rewrite(所有路由进函数)和静态文件同步 IO 虽然慢,但无法导致稳定 60s 函数卡死。
  • AuthPlugin 逻辑正常时不会阻塞。
  • 绝大多数业务插件为本地 require 并非外部依赖。

可能原因与待排查点

  1. 插件初始化有 Promise 永久 pending/死锁
    • 某业务插件内有网络、数据库、第三方或编码失误导致的 await 未 resolve。
  2. 依赖包或 dist 缺失,导致 require/readFileSync fallback 死等
    • node_modules 或 packages/*/dist、@object-ui/console/dist 等目录丢失时,fs fallback 或 require 失败未抛错。
  3. 环境变量未配置或拼写出错
    • AUTH_SECRET、Vercel 特有 URL 环境变量缺失未 failfast,卡在 fetch/discovery 环节。
  4. Vercel Function 配置被仪表盘覆盖
    • 项目设置或 Build Output/Install/Build Command 被 UI 配置覆盖,导致实际部署内容与代码预期不符。
  5. 插件 (init/start) 实现有漏掉异常捕获
    • init、start 任何 await 未 reject/resolve 都直接表达为 60s 无响应。

推荐排查/修复策略

  1. api/[[...route]].ts 及每个 kernel.use/插件 init/use 前后插入详细日志,观察卡死点。
  2. 检查 pnpm/turbo workspace 构建输出,确保所有 packages/*/dist 和 node_modules 内容完整。
  3. 在 Vercel 部署流程 (install, build, deploy) 日志中检查 missing module、require fallback 等异常。
  4. 加强环境变量(如 AUTH_SECRET)failfast 检查,缺失或错误直接 throw。
  5. 优化所有插件的 init/start,必要时支持 5s 超时保护 + 抛错。
  6. 参考 Studio 的最简初始化流程,尝试最小复现 + 逐步加回业务插件定位。

目标

  • 找到实际阻塞点,移除导致整个 cold start/fn handler 永久等待的隐患。
  • 确保登录等核心 API 可用性和函数响应时间稳定 < 10s。

如需辅助撰写日志插桩代码、调试方案可进一步提出。</issue_description>

Comments on the Issue (you are @copilot in this section)


🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 19, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
hotcrm Ready Ready Preview, Comment Mar 19, 2026 11:00am
hotcrm-demo Ready Ready Preview, Comment Mar 19, 2026 11:00am

Request Review

Copilot AI and others added 2 commits March 19, 2026 10:39
…ss bootstrap

- Wrap each kernel.use() with 10s per-plugin timeout
- Wrap kernel.bootstrap() with 30s timeout
- Wrap overall bootstrap() with 50s budget (10s margin for Vercel 60s limit)
- Return 503 Service Unavailable on bootstrap failure instead of hanging
- Add timestamped [HotCRM] diagnostic logs at every bootstrap step
- Update CHANGELOG.md and DEPLOYMENT.md

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
…from business plugin loop

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Copilot AI changed the title [WIP] [ISSUE-123] Fix Vercel login timeout after 60 seconds fix: add timeout protection to Vercel serverless bootstrap to prevent 60s hangs Mar 19, 2026
Copilot AI requested a review from hotlong March 19, 2026 10:43
@hotlong hotlong marked this pull request as ready for review March 19, 2026 10:53
Copilot AI review requested due to automatic review settings March 19, 2026 10:53
@hotlong
Copy link
Copy Markdown
Contributor

hotlong commented Mar 19, 2026

@copilot 评估是否已经完成了任务中要求的所有开发

Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds fail-fast timeout protection and diagnostic logging around the Vercel serverless kernel bootstrap so permanently-pending plugin initialization doesn’t consume the full 60s function limit, and documents the new behavior.

Changes:

  • Added withTimeout() plus 10s per-plugin, 30s kernel.bootstrap(), and 50s overall bootstrap budgets with timestamped logs in the Vercel handler.
  • Updated handler behavior to return 503 Service Unavailable with JSON when bootstrap fails.
  • Documented the timeout architecture in docs/DEPLOYMENT.md and recorded the fix in CHANGELOG.md.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File Description
api/[[...route]].ts Wraps bootstrap phases in layered timeouts and adds step-by-step elapsed-time logs; returns 503 on bootstrap failure.
docs/DEPLOYMENT.md Documents the timeout protection and diagnostics for Vercel deployments.
CHANGELOG.md Adds an Unreleased “Fixed” entry describing the Vercel bootstrap hang mitigation.

Comment thread api/[[...route]].ts
Comment on lines 309 to 316
@@ -243,10 +315,12 @@ async function bootstrap(): Promise<Hono> {
...(process.env.VERCEL_PROJECT_PRODUCTION_URL ? [`https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`] : []),
...(process.env.AUTH_TRUSTED_ORIGINS ? process.env.AUTH_TRUSTED_ORIGINS.split(',').map(s => s.trim()) : []),
… missing

On Vercel (VERCEL env var set), AUTH_SECRET is now required. Without it,
the handler throws with an actionable error pointing to Vercel Dashboard
settings, instead of silently falling back to an insecure dev placeholder.

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Mar 19, 2026

@copilot 评估是否已经完成了任务中要求的所有开发

已完成 issue 中所有可通过代码修改实现的任务,具体对照如下:

Issue 推荐策略 → 完成情况:

# 策略 状态
1 在每个 kernel.use/插件 init/use 前后插入详细日志 ✅ 已完成 — [HotCRM] [<elapsed>ms] 时间戳日志
2 检查 pnpm/turbo 构建输出完整性 ⬜ 运维排查项,非代码变更
3 检查 Vercel 部署日志中 missing module 等异常 ⬜ 运维排查项,#1 的日志会辅助定位
4 加强环境变量 failfast 检查(AUTH_SECRET) ✅ 已完成 — Vercel 上缺失 AUTH_SECRET 立即 throw(b816be4)
5 插件 init/start 超时保护 + 抛错 ✅ 已完成 — 每个 kernel.use() 10s 超时,kernel.bootstrap() 30s 超时,总预算 50s
6 参考 Studio 最简流程做最小复现 ⬜ 调试方法论,非代码变更

额外完成:

  • Handler bootstrap 失败时返回 503 JSON 而非挂死
  • 更新 CHANGELOG.md 和 DEPLOYMENT.md
  • 全部 196 test files / 4036 tests 通过

Copilot AI changed the title fix: add timeout protection to Vercel serverless bootstrap to prevent 60s hangs fix: add timeout protection and AUTH_SECRET fail-fast to Vercel serverless bootstrap to prevent 60s hangs Mar 19, 2026
@hotlong hotlong merged commit 0c1ae88 into main Mar 19, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

fix: Vercel 登录超时 60s(Serverless Handler 卡死)��查与修复

3 participants