客户端选项、错误、重试和超时

import { createClient } from '@aurabase/aurabase-js'

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // 公钥
)

createClient(url, key, options?) 采用 项目 URL 和一键。该项目由 URL 的主机标识，因此无需传递项目 id。在本地堆栈中，使用带有项目子域的 URL，例如 http://my-app-ab12.localhost:8080；使用裸的 http://localhost:8080 客户端会打印一条警告，因为网关无法判断您指的是哪个项目。

在浏览器和应用程序中使用公钥 (aura_anon_…)。 service_role 密钥 (aura_sk_…) 仅属于您的服务器，并且客户端强制执行它：

import { createAdminClient } from '@aurabase/aurabase-js'

// 仅服务器：绕过行级安全性。
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

在浏览器中，createClient 在收到 service_role 密钥时会抛出，因此泄漏的密钥不会意外发送。设置 refuseServiceRoleInBrowser: false 将错误降级为警告；不要在生产中这样做。

每个服务都挂在客户端上： aura.auth、 aura.db、 aura.storage、 aura.realtime、 aura.functions、 aura.ai、 aura.notifications和 aura.from('table') 作为 aura.db.from('table')的快捷方式。请参阅 客户端参考。

对于服务器端渲染，请使用 Next.js App Router 和 SSR中描述的基于 cookie 的客户端。

每次调用都会返回 { data, error } 并且不会抛出异常。当失败时， error 是 AuraError：

import { isAuraError } from '@aurabase/aurabase-js'

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500，如果客户端故障则为 0
  console.log(error.code)    // “内部”、“超时”、“网络错误”……
  console.log(error.message) // 人类可读的
  console.log(error.details) // 原始正文，包括来自服务器的 error.request_id
  isAuraError(error)         // 真实
}

返回了一个真正失败的调用：

{ "error": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }

客户端自己生成的代码（状态 0）： timeout、 network_error、 invalid_response （主体不是 JSON 的成功）、 no_session、 refresh_discarded、 invalid_path、 invalid_body。身份验证添加了 invalid_credentials、 weak_password、 email_already_in_use、 user_not_found、 invalid_otp、 session_expired、 session_revoked 和 rate_limit_exceeded等代码。 429 始终带有 rate_limit_exceeded。

当您需要该值时，测试 data 而不是 error。有些调用在没有内容的情况下成功 (204)，然后 data 和 error 都是 null。

重试。 仅当所有这些都成立时，客户端才会自动重试请求：

• 该方法是 GET 或 HEAD （POST、 PUT、 PATCH 或 DELETE 永远不会重播，因此不会运行两次）；
• 响应状态为 408、 429、 502、 503 或 504，或者网络失败；
• 重试次数少于 3 次。

延迟在 0 和 min(500 ms × 2^attempt, 10 s)之间随机。 Retry-After 标头胜过它，上限为 60 秒。重试的请求带有 X-Retry-Count 标头。超时不会重试。

针对先回答 503 两次，然后回答 200的服务器进行测量：

GET  /flaky   590 ms  { data: [...] }          events: retry#1:503, retry#2:503
POST /flaky     5 ms  { error: SERVICE_UNAVAILABLE }   (not retried)
GET  /flaky     1 ms  { error: SERVICE_UNAVAILABLE }   with retry: false

超时。 在 requestTimeoutMs （默认为 30 秒）内没有得到答复的请求以 status: 0 和 code: 'timeout'结束。读取正文受到相同限制的限制，因此发送标头然后停止的服务器无法挂起调用。对从未应答的服务器的请求（限制为 400 毫秒）会在 405 毫秒后返回错误。

有两种情况不使用此限制，因为它们管理自己的限制：传递 AbortSignal的调用和上传。函数使用自己的 timeout 选项，请参阅 错误、超时和重试。

onEvent 客户端所做的每一件值得注意的事情都会收到一个事件。它永远不会使请求失败：钩子抛出的异常将被忽略。

const aura = createClient(url, key, {
  onEvent: (e) => metrics.increment(`aurabase.${e.kind}`),
})

事件中的 URL 的查询字符串和片段已被删除，因为它们可以携带秘密（?apikey=，签名链接）。

• 客户端在每次请求时发送 apikey，并在用户登录后发送 Authorization: Bearer <access token>。
• 当剩余时间少于 30 秒时，它会刷新访问令牌。并发刷新合并为一次，因此循环刷新令牌仅使用一次。
• 401 触发请求的一次刷新和一次重播，然后停止。
• 在浏览器中，刷新是跨选项卡协调的。
• aura.auth.onAuthStateChange(callback) 告诉您有关 SIGNED_IN、 SIGNED_OUT、 TOKEN_REFRESHED、 USER_UPDATED 和 MFA_CHALLENGE的信息。请参阅 身份验证指南。