Clientoptionen, Fehler, Wiederholungsversuche und Zeitüberschreitungen
Das Verhalten aller Dienste des SDK und die Optionen, die es ändern.
Erstellen Sie den Client#
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!, // 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'
// Nur Server: Umgeht die Sicherheit auf Zeilenebene.
export const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_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. Tun Sie dies nicht in der Produktion.
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.from('table'). Siehe die Client-Referenz.
Optionen#
| Option | Standard | Wirkung |
|---|---|---|
auth.persistSession | true in einem Browser | Halten Sie die Sitzung zwischen dem Laden der Seite aufrecht |
auth.storage | localStorage in einem Browser, Speicher woanders | Wo die Sitzung lebt: Passieren Sie Ihren eigenen Shop (Cookies für SSR) |
auth.autoRefresh | true | Aktualisieren Sie das Zugriffstoken, bevor es abläuft, und halten Sie die Tabs synchron |
auth.detectSessionInUrl | true in einem Browser | Lesen Sie eine Sitzung von der URL nach einer OAuth-Umleitung und bereinigen Sie dann die URL |
fetch | globalThis.fetch | Ihr eigenes fetch für Tests oder Proxys |
retry | true | Wiederholen Sie den Lesevorgang bei vorübergehenden Fehlern. false deaktiviert oder { enabled, maxRetries } |
requestTimeoutMs | 30000 | Zeitlimit einer Anfrage. 0 deaktiviert es. |
onEvent | keine | Empfängt Beobachtbarkeitsereignisse, siehe unten |
debug | false | Drucken Sie außerdem jedes Ereignis mit console.debug('[aurabase]', event) aus. |
refuseServiceRoleInBrowser | true | Wird ausgelöst, wenn ein service_role-Schlüssel einen Browser erreicht |
Verwenden Sie für das serverseitige Rendering die in Next.js App Router und SSR beschriebenen Cookie-basierten Clients.
Das Fehlerobjekt#
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.from('posts').select('*')
if (error) {
console.log(error.status) // 500 oder 0, wenn der Fehler auf dem Client liegt
console.log(error.code) // „INTERNAL_ERROR“, „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" } }
| Feld | Bedeutung |
|---|---|
status | Der HTTP-Status. 0 bedeutet, dass der Fehler vor irgendeiner Reaktion aufgetreten ist: Netzwerk, Zeitüberschreitung oder eine Ablehnung durch den Client. |
code | Eine stabile Kennung. Servercodes behalten ihren Wert; Der Kunde fügt die folgenden Codes hinzu. |
message | Eine lesbare Erklärung |
details | Der rohe Antworttext |
retryAfter | Sekunden Wartezeit, von einem Retry-After-Header bis zu einem 429 |
isNotFound, isUnauthorized, isForbidden, isRateLimited | Verknüpfungen auf status |
Alle Fehlercodes sind in SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$), unabhängig davon, ob der Server oder der Client sie erzeugt hat (error.legacyCode gibt die frühere Kleinbuchstabenform zurück und ist veraltet). 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_LIMITED hinzugefügt. Ein 429 trägt immer RATE_LIMITED und error.retryAfter enthält die Retry-After-Verzögerung in Sekunden, als der Server eine gesendet hat.
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 und Zeitüberschreitungen#
Wiederholungsversuche. Der Client wiederholt eine Anfrage nur dann automatisch, wenn alle folgenden Punkte erfüllt sind:
- die Methode ist
GEToderHEAD(einPOST,PUT,PATCHoderDELETEwird nie wiederholt, sodass nichts zweimal ausgeführt wird); - der Antwortstatus ist
408,429,502,503oder504, 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.
Beobachten Sie den Kunden#
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.
kind | Felder | Wann |
|---|---|---|
retry | attempt, status?, url | Vor einem erneuten Versuch |
timeout | url | Eine Anfrage traf requestTimeoutMs |
refresh-success | keine | Eine Sitzungsaktualisierung war erfolgreich |
refresh-discarded | reason | Eine Aktualisierung wurde verworfen, da sich die Sitzung zwischenzeitlich geändert hat |
jwks-fetch-failed | baseUrl | Die Signaturschlüssel konnten nicht abgerufen werden (lokale Tokenprüfungen) |
storage-blocked | op | Der Browser verweigerte den Speicherzugriff |
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).
Sitzungen und Token#
- Der Client sendet
apikeybei jeder Anfrage undAuthorization: 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
401lö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 überSIGNED_IN,SIGNED_OUT,TOKEN_REFRESHED,USER_UPDATEDundMFA_CHALLENGE. Siehe im Authentifizierungshandbuch.