クライアントのオプション、エラー、再試行、タイムアウト

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 と 1 つのキーを受け取ります。プロジェクトは URL のホストによって識別されるため、渡すプロジェクト ID はありません。ローカル スタックでは、 http://my-app-ab12.localhost:8080などのプロジェクト サブドメインを含む URL を使用します。裸の 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.db.from('table')のショートカットとしての aura.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を持ちます。

値が必要な場合は、error ではなく data をテストしてください。一部の呼び出しはコンテンツなしで成功します (204)。その場合、 data と error は両方とも nullになります。

再試行します。 クライアントは、次のすべてが満たされる場合にのみ、リクエストを自動的に再試行します。

• メソッドは GET または HEAD です ( POST、 PUT、 PATCH または DELETE は再実行されないため、何も 2 回実行されることはありません)。
• 応答ステータスは 408、 429、 502、 503 または 504、またはネットワーク障害です。
• 再試行は 3 回未満です。

遅延は 0 から min(500 ms × 2^attempt, 10 s)の間でランダムです。 Retry-After ヘッダーはこれに勝ち、制限時間は 60 秒です。再試行されたリクエストには X-Retry-Count ヘッダーが含まれます。タイムアウトは再試行されません。

503 を 2 回応答し、次に 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を渡す呼び出しとアップロードの 2 つのケースでは、独自の制限を管理するため、この制限は使用されません。関数は独自の timeout オプションを使用します。 エラー、タイムアウト、および再試行を参照してください。

onEvent は、クライアントの注目すべき動作ごとに 1 つのイベントを受け取ります。リクエストが失敗することはありません。フックによってスローされた例外は無視されます。

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

イベント内の URL にはシークレット (?apikey=、署名付きリンク) が含まれる可能性があるため、クエリ文字列とフラグメントが削除されます。

• クライアントはリクエストごとに apikey を送信し、ユーザーがサインインすると Authorization: Bearer <access token> を送信します。
• 残り 30 秒未満になると、アクセス トークンが更新されます。同時リフレッシュは 1 つにマージされるため、循環リフレッシュ トークンは 1 回使用されます。
• 401 は、リクエストの 1 回の更新と 1 回の再生をトリガーし、その後停止します。
• ブラウザでは、更新はタブ間で調整されます。
• aura.auth.onAuthStateChange(callback) は、 SIGNED_IN、 SIGNED_OUT、 TOKEN_REFRESHED、 USER_UPDATED 、および MFA_CHALLENGEについて説明します。 認証ガイドを参照してください。