http-endpoints

HTTP Endpoints 是一份面向 Val Town 平台的开发指引，适用于构建 web 端点、API 路由、webhook 接收器，或任何需要响应 HTTP 请求的 val。\n\n用途与基本结构：HTTP val 的文件类型为 "http"，需要导出一个请求处理函数，在每个传入的 HTTP 请求时运行。每个 HTTP 文件都会分配一个实时 URL，不应自行拼接，而应从 list_files 或 create_file 响应的 links.endpoint 读取，或调用 fetch_val_endpoint 获取。文件必须带有 export，处理函数使用 export default。\n\n访问控制：该 URL 默认对所有人开放；若限制了 val 的应用访问（httpPrivacy），未认证调用方会收到 302 跳转到登录页，而不是正常响应，可参阅 restricted-access 技能。\n\nHono 用法：使用 Hono 时应导出 app.fetch 而非 app。示例中引入了 npm:hono 与 std/utils，定义了根路由、用于不可变资源缓存的 /__immutable/* 路由（配合 serveImmutableFile）、/source 重定向路由，并通过 app.onError 返回完整错误堆栈。Hono 的 serveStatic 在 Val Town 上不可用，静态文件应使用 std/utils 中的 serveFile 或 staticHTTPServer；完整 API 可查看 https://utilities.val.run/docs.md。\n\nCORS：Val Town 默认添加宽松的 CORS 头（Access-Control-Allow-Origin: *），绝大多数情况下无需自行处理，通常也不必使用 Hono 的 cors 中间件。一旦自行设置任何 CORS 头，平台将停止添加全部默认头，因此要么完全自行处理，要么完全不碰。\n\n重定向：Response.redirect 在 Val Town 上不可用，应改为返回带 status 302 和 Location 头的 Response，或在 Hono 中使用 c.redirect。\n\n不可用能力：不支持接收传入的 WebSocket 连接，可改用轮询、长轮询或服务器发送事件；无文件系统访问，持久状态应使用 std/sqlite 或 std/blob。\n\n错误上报与验证：对 HTML 响应可加入 <script src="https://esm.town/v/std/catch"></script>，将浏览器端错误发送回 val 日志（可通过 get_logs 查看）。修改 HTTP val 后，应实际请求确认返回预期的 HTTP 响应，未验证前不应报告完成。