コンテンツへスキップ
オーラベースのロゴ
オーラベース

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

SDK のすべてのサービスで共有される動作と、それを変更するオプション。

リファレンス9 分 読み取りレベル 中間2026/10/12 に改訂

このページは自動翻訳されました。英語版が正式です。

クライアントを作成する#

src/lib/aurabase.tstypescript
import { createClient } from '@aurabase/aurabase-js'

export const aura = createClient(
  process.env.NEXT_PUBLIC_AURABASE_URL!,       // https://my-app.aurabase.cloud
  process.env.NEXT_PUBLIC_AURABASE_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_…) はサーバーにのみ属し、クライアントはそれを強制します。

server/admin.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

// サーバーのみ: 行レベルのセキュリティをバイパスします。
export const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_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.from('table') 。 クライアントリファレンスを参照してください。

オプション#

オプションデフォルト効果
auth.persistSessionブラウザ内の trueページの読み込み間でセッションを維持する
auth.storageブラウザ内では localStorage、メモリは別の場所にセッションが存在する場所: 独自のストアを渡します (SSR の Cookie)
auth.autoRefreshtrue有効期限が切れる前にアクセス トークンを更新し、タブの同期を維持します
auth.detectSessionInUrlブラウザ内の trueOAuth リダイレクト後に URL からセッションを読み取り、URL をクリーンアップします。
fetchglobalThis.fetch独自の fetch、テストまたはプロキシ用
retrytrue一時的なエラーが発生した場合は読み取りを再試行します。 false を無効にするか、{ enabled, maxRetries }
requestTimeoutMs30000リクエストの制限時間。 0 はそれを無効にします。
onEventなし可観測性イベントを受信します。以下を参照してください。
debugfalseまた、console.debug('[aurabase]', event) を使用して各イベントを出力します。
refuseServiceRoleInBrowsertrueservice_role キーがブラウザに到達したときにスローします

サーバー側レンダリングの場合は、 Next.js App Router および SSRで説明されている Cookie ベースのクライアントを使用します。

エラーオブジェクト#

すべての呼び出しは { data, error } を返し、スローされることはありません。失敗すると、 error は AuraErrorになります。

errors.tstypescript
import { isAuraError } from '@aurabase/aurabase-js'

const { data, error } = await aura.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500、またはクライアントに障害がある場合は 0
  console.log(error.code)    // 'INTERNAL_ERROR'、'TIMEOUT'、'NETWORK_ERROR'、…
  console.log(error.message) // 人間が読める
  console.log(error.details) // サーバーからの error.request_id を含む生の本文
  isAuraError(error)         // 本当の
}

実際に失敗した呼び出しが返されました。

error.detailsjson
{ "error": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }
フィールド意味
statusHTTP ステータス。 0 は、ネットワーク、タイムアウト、またはクライアントによる拒否などの応答の前に障害が発生したことを意味します。
code安定した識別子。サーバーコードはその値を保持します。クライアントは以下のコードを追加します。
message読みやすい説明
details生のレスポンスボディ
retryAfter429 での Retry-After ヘッダーからの待機秒数
isNotFound、 isUnauthorized、 isForbidden、 isRateLimitedstatus のショートカット

すべてのエラー コードは、サーバーまたはクライアントが生成したかどうかに関係なく、SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$) にあります (error.legacyCode は以前の小文字形式を返し、非推奨です)。クライアント自体によって生成されたコード (ステータス 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_LIMITEDなどのコードが追加されます。 429 は常に RATE_LIMITEDを保持し、 error.retryAfter はサーバーが送信したときの Retry-After 遅延を秒単位で保持します。

値が必要な場合は、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を応答したサーバーに対して測定されます。

text
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 つのイベントを受け取ります。リクエストが失敗することはありません。フックによってスローされた例外は無視されます。

kindフィールドいつ
retryattempt、 status?、 url再試行の前に
timeouturlリクエストが requestTimeoutMs にヒットしました
refresh-successなしセッションの更新が成功しました
refresh-discardedreasonセッションが途中で変更されたため、更新が削除されました
jwks-fetch-failedbaseUrl署名キーを取得できませんでした (ローカル トークン チェック)
storage-blockedopブラウザがストレージへのアクセスを拒否しました
observe.tstypescript
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について説明します。 認証ガイドを参照してください。