Client options, errors, retries and timeouts

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // der öffentliche Schlüssel
)

createClient(url, key, options?) benötigt die Projekt-URL und einen Schlüssel. Das Projekt wird durch den Host der URL identifiziert, daher muss keine Projekt-ID übergeben werden. Verwenden Sie in einem lokalen Stack eine URL mit der Projekt-Subdomäne, z. B. http://my-app-ab12.localhost:8080; Bei einem bloßen http://localhost:8080 gibt der Client eine Warnung aus, da das Gateway nicht erkennen kann, welches Projekt Sie meinen.

Verwenden Sie den öffentlichen Schlüssel (aura_anon_…) in Browsern und Apps. Ein service_role-Schlüssel (aura_sk_…) gehört nur zu Ihrem Server und wird vom Client erzwungen:

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

// Server only: bypasses row-level security.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

In einem Browser löst createClient aus, wenn er einen service_role-Schlüssel empfängt, sodass ein durchgesickerter Schlüssel nicht versehentlich versendet werden kann. Legen Sie refuseServiceRoleInBrowser: false fest, um den Fehler auf eine Warnung herabzustufen. do not do this in production.

Jeder Dienst hängt vom Client ab: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications und aura.from('table') als Verknüpfung für aura.db.from('table'). Siehe die Client-Referenz.

Verwenden Sie für das serverseitige Rendering die in Next.js App Router und SSR beschriebenen Cookie-basierten Clients.

Jeder Aufruf gibt { data, error } zurück und löst nie aus. Wenn dies fehlschlägt, ist error ein AuraError:

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

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500 oder 0, wenn der Fehler auf dem Client liegt
  console.log(error.code)    // 'INTERNAL', 'timeout', 'network_error', …
  console.log(error.message) // für Menschen lesbar
  console.log(error.details) // der Rohtext, einschließlich error.request_id vom Server
  isAuraError(error)         // wahr
}

Ein wirklich fehlgeschlagener Anruf ergab Folgendes:

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

Vom Client selbst erstellte Codes (Status 0): timeout, network_error, invalid_response (ein Erfolg, dessen Körper nicht JSON ist), no_session, refresh_discarded, invalid_path, invalid_body. Bei der Authentifizierung werden Codes wie invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked und rate_limit_exceeded hinzugefügt. Ein 429 trägt immer rate_limit_exceeded.

Testen Sie data anstelle von error, wenn Sie den Wert benötigen. Einige Aufrufe sind ohne Inhalt erfolgreich (204), und dann sind sowohl data als auch error null.

Wiederholungsversuche. Der Client wiederholt eine Anfrage nur dann automatisch, wenn alle folgenden Punkte erfüllt sind:

• die Methode ist GET oder HEAD (ein POST, PUT, PATCH oder DELETE wird nie wiederholt, sodass nichts zweimal ausgeführt wird);
• der Antwortstatus ist 408, 429, 502, 503 oder 504, oder das Netzwerk ist ausgefallen;
• Es sind weniger als drei Wiederholungsversuche erfolgt.

Die Verzögerung liegt zufällig zwischen 0 und min(500 ms × 2^attempt, 10 s). Ein Retry-After-Kopfball gewinnt, die Höchstdauer beträgt 60 Sekunden. Wiederholte Anfragen tragen einen X-Retry-Count-Header. Eine Zeitüberschreitung wird nicht wiederholt.

Gemessen an einem Server, der zweimal 503 geantwortet hat, dann 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

Zeitüberschreitungen. Eine Anfrage, die innerhalb von requestTimeoutMs (standardmäßig 30 s) keine Antwort erhält, endet mit status: 0 und code: 'timeout'. Das Lesen des Textkörpers unterliegt derselben Beschränkung, sodass ein Server, der Header sendet und dann anhält, den Anruf nicht abbrechen kann. Eine Anfrage an einen Server, die nie antwortete, mit einem Limit von 400 ms, gab den Fehler nach 405 ms zurück.

In zwei Fällen wird dieses Limit nicht verwendet, da sie ihr eigenes Limit verwalten: ein Anruf, bei dem Sie ein AbortSignal übergeben, und Uploads. Funktionen verwenden ihre eigene Option timeout, siehe Fehler, Zeitüberschreitungen und Wiederholungsversuche.

onEvent empfängt ein Ereignis pro bemerkenswerter Aktion des Clients. Es führt nie dazu, dass eine Anfrage fehlschlägt: Eine von Ihrem Hook ausgelöste Ausnahme wird ignoriert.

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

Bei URLs in Ereignissen werden die Abfragezeichenfolge und das Fragment entfernt, da sie Geheimnisse enthalten können (?apikey=, signierte Links).

• Der Client sendet apikey bei jeder Anfrage und Authorization: Bearer <access token>, sobald ein Benutzer angemeldet ist.
• Es aktualisiert das Zugriffstoken, wenn weniger als 30 Sekunden verbleiben. Gleichzeitige Aktualisierungen werden zu einer zusammengefasst, sodass ein rotierendes Aktualisierungstoken einmal verwendet wird.
• Ein 401 löst eine Aktualisierung und eine Wiederholung der Anforderung aus und stoppt dann.
• In einem Browser werden Aktualisierungen über mehrere Registerkarten hinweg koordiniert.
• aura.auth.onAuthStateChange(callback) informiert Sie über SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED und MFA_CHALLENGE. Siehe im Authentifizierungshandbuch.