クライアントのオプション、エラー、再試行、タイムアウト
SDK のすべてのサービスで共有される動作と、それを変更するオプション。
クライアントを作成する#
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_…) はサーバーにのみ属し、クライアントはそれを強制します。
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.autoRefresh | true | 有効期限が切れる前にアクセス トークンを更新し、タブの同期を維持します |
auth.detectSessionInUrl | ブラウザ内の true | OAuth リダイレクト後に URL からセッションを読み取り、URL をクリーンアップします。 |
fetch | globalThis.fetch | 独自の fetch、テストまたはプロキシ用 |
retry | true | 一時的なエラーが発生した場合は読み取りを再試行します。 false を無効にするか、{ enabled, maxRetries } |
requestTimeoutMs | 30000 | リクエストの制限時間。 0 はそれを無効にします。 |
onEvent | なし | 可観測性イベントを受信します。以下を参照してください。 |
debug | false | また、console.debug('[aurabase]', event) を使用して各イベントを出力します。 |
refuseServiceRoleInBrowser | true | service_role キーがブラウザに到達したときにスローします |
サーバー側レンダリングの場合は、 Next.js App Router および SSRで説明されている Cookie ベースのクライアントを使用します。
エラーオブジェクト#
すべての呼び出しは { data, error } を返し、スローされることはありません。失敗すると、 error は AuraErrorになります。
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": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }
| フィールド | 意味 |
|---|---|
status | HTTP ステータス。 0 は、ネットワーク、タイムアウト、またはクライアントによる拒否などの応答の前に障害が発生したことを意味します。 |
code | 安定した識別子。サーバーコードはその値を保持します。クライアントは以下のコードを追加します。 |
message | 読みやすい説明 |
details | 生のレスポンスボディ |
retryAfter | 429 での Retry-After ヘッダーからの待機秒数 |
isNotFound、 isUnauthorized、 isForbidden、 isRateLimited | status のショートカット |
すべてのエラー コードは、サーバーまたはクライアントが生成したかどうかに関係なく、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を応答したサーバーに対して測定されます。
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 | フィールド | いつ |
|---|---|---|
retry | attempt、 status?、 url | 再試行の前に |
timeout | url | リクエストが requestTimeoutMs にヒットしました |
refresh-success | なし | セッションの更新が成功しました |
refresh-discarded | reason | セッションが途中で変更されたため、更新が削除されました |
jwks-fetch-failed | baseUrl | 署名キーを取得できませんでした (ローカル トークン チェック) |
storage-blocked | op | ブラウザがストレージへのアクセスを拒否しました |
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について説明します。 認証ガイドを参照してください。