Opcje klienta, błędy, ponowne próby i przekroczenia limitu czasu
Zachowanie wspólne dla każdej usługi pakietu SDK i opcje, które je zmieniają.
Utwórz klienta#
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!, // klucz publiczny
)
createClient(url, key, options?) pobiera adres URL projektu i jeden klucz. Projekt jest identyfikowany przez hosta adresu URL, więc nie ma identyfikatora projektu do przekazania. W stosie lokalnym użyj adresu URL z subdomeną projektu, na przykład http://my-app-ab12.localhost:8080; z pustym http://localhost:8080 klient drukuje ostrzeżenie, ponieważ brama nie jest w stanie określić, który projekt masz na myśli.
Użyj klucza publicznego (aura_anon_…) w przeglądarkach i aplikacjach. Klucz service_role (aura_sk_…) należy tylko do Twojego serwera i klient go wymusza:
import { createAdminClient } from '@aurabase/aurabase-js'
// Tylko serwer: omija zabezpieczenia na poziomie wiersza.
export const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)
W przeglądarce createClient zgłasza po odebraniu klucza service_role, więc klucz, który wyciekł, nie może zostać przypadkowo wysłany. Ustaw refuseServiceRoleInBrowser: false, aby zmienić błąd na ostrzeżenie; nie rób tego na produkcji.
Każda usługa zawiesza się na kliencie: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications i aura.from('table') jako skrót do aura.from('table'). Zobacz referencje klienta.
Opcje#
| Opcja | Domyślny | Efekt |
|---|---|---|
auth.persistSession | true w przeglądarce | Utrzymuj sesję pomiędzy ładowaniami stron |
auth.storage | localStorage w przeglądarce, pamięć gdzie indziej | Gdzie mieszka sesja: przekaż własny sklep (cookies dla SSR) |
auth.autoRefresh | true | Odśwież token dostępu, zanim wygaśnie, i synchronizuj karty |
auth.detectSessionInUrl | true w przeglądarce | Przeczytaj sesję z adresu URL po przekierowaniu OAuth, a następnie wyczyść adres URL |
fetch | globalThis.fetch | Twój własny fetch do testów lub serwerów proxy |
retry | true | Ponów próbę odczytu błędów przejściowych. false wyłącza lub { enabled, maxRetries } |
requestTimeoutMs | 30000 | Termin żądania. 0 wyłącza to. |
onEvent | nic | Odbiera zdarzenia obserwowalności, patrz poniżej |
debug | false | Wydrukuj także każde zdarzenie za pomocą console.debug('[aurabase]', event) |
refuseServiceRoleInBrowser | true | Zgłaszaj, gdy klucz service_role dotrze do przeglądarki |
Do renderowania po stronie serwera użyj klientów opartych na plikach cookie opisanych w Next.js App Router i SSR.
Obiekt błędu#
Każde wywołanie zwraca { data, error } i nigdy nie powoduje zgłoszenia. W przypadku niepowodzenia error jest AuraError:
import { isAuraError } from '@aurabase/aurabase-js'
const { data, error } = await aura.from('posts').select('*')
if (error) {
console.log(error.status) // 500 lub 0, gdy awaria występuje po stronie klienta
console.log(error.code) // „INTERNAL_ERROR”, „TIMEOUT”, „NETWORK_ERROR”, …
console.log(error.message) // czytelne dla człowieka
console.log(error.details) // surowa treść, w tym error.request_id z serwera
isAuraError(error) // PRAWDA
}
Zwrócono prawdziwe nieudane połączenie:
{ "error": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }
| Pole | Oznaczający |
|---|---|
status | Stan HTTP. 0 oznacza, że awaria wystąpiła przed jakąkolwiek odpowiedzią: siecią, przekroczeniem limitu czasu lub odmową ze strony klienta. |
code | Stabilny identyfikator. Kody serwerów zachowują swoją wartość; klient dodaje poniższe kody. |
message | Czytelne wyjaśnienie |
details | Surowa treść odpowiedzi |
retryAfter | Sekundy oczekiwania z nagłówka Retry-After na 429 |
isNotFound, isUnauthorized, isForbidden, isRateLimited | Skróty na status |
Wszystkie kody błędów znajdują się w SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$), niezależnie od tego, czy wygenerował je serwer, czy klient (error.legacyCode zwraca poprzednią formę małych liter i jest przestarzały). Kody wygenerowane przez samego klienta (status 0): TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE (sukces, którego treścią nie jest JSON), NO_SESSION, REFRESH_DISCARDED, INVALID_PATH, INVALID_BODY. Uwierzytelnianie dodaje kody takie jak INVALID_CREDENTIALS, WEAK_PASSWORD, EMAIL_ALREADY_IN_USE, USER_NOT_FOUND, INVALID_OTP, SESSION_EXPIRED, SESSION_REVOKED i RATE_LIMITED. 429 zawsze przenosi RATE_LIMITED, a error.retryAfter utrzymuje opóźnienie Retry-After w sekundach, kiedy serwer je wysłał.
Jeśli potrzebujesz wartości, przetestuj data zamiast error. Niektóre wywołania powiodą się bez treści (204), a następnie zarówno data, jak i error są null.
Ponowne próby i przekroczenia limitu czasu#
Ponowne próby. Klient automatycznie ponawia żądanie tylko wtedy, gdy wszystkie z nich spełniają:
- metoda to
GETlubHEAD(aPOST,PUT,PATCHlubDELETEnigdy nie jest odtwarzane, więc nic nie działa dwukrotnie); - status odpowiedzi to
408,429,502,503lub504lub awaria sieci; - miały miejsce mniej niż 3 ponowne próby.
Opóźnienie jest losowe i mieści się w przedziale od 0 do min(500 ms × 2^attempt, 10 s). Zwycięża nagłówek Retry-After, ograniczony do 60 sekund. Ponowione żądania zawierają nagłówek X-Retry-Count. Limit czasu nie jest ponawiany.
Zmierzono w porównaniu z serwerem, który dwukrotnie odpowiedział 503, a następnie 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
Limity czasu. Żądanie, na które nie otrzymano odpowiedzi w ciągu requestTimeoutMs (domyślnie 30 s), kończy się status: 0 i code: 'TIMEOUT'. Odczyt treści jest ograniczony tym samym limitem, więc serwer, który wysyła nagłówki, a następnie zatrzymuje się, nie może zawiesić połączenia. Żądanie skierowane do serwera, który nigdy nie odpowiedział, z limitem 400 ms, zwróciło błąd po 405 ms.
Dwa przypadki nie korzystają z tego limitu, ponieważ zarządzają własnymi: wywołaniem, w którym przekazujesz AbortSignal i przesyłaniem. Funkcje używają własnej opcji timeout, zobacz Błędy, przekroczenia limitu czasu i ponowne próby.
Obserwuj klienta#
onEvent otrzymuje jedno zdarzenie na każdą godną uwagi rzecz, którą robi klient. Nigdy nie powoduje to niepowodzenia żądania: wyjątek zgłoszony przez hak jest ignorowany.
kind | Pola | Gdy |
|---|---|---|
retry | attempt, status?, url | Przed ponowną próbą |
timeout | url | Żądanie trafiło requestTimeoutMs |
refresh-success | nic | Odświeżenie sesji powiodło się |
refresh-discarded | reason | Odświeżanie zostało przerwane, ponieważ w międzyczasie sesja uległa zmianie |
jwks-fetch-failed | baseUrl | Nie można pobrać kluczy podpisujących (lokalne sprawdzanie tokenów) |
storage-blocked | op | Przeglądarka odmówiła dostępu do pamięci |
const aura = createClient(url, key, {
onEvent: (e) => metrics.increment(`aurabase.${e.kind}`),
})
Adresy URL w zdarzeniach mają usunięty ciąg zapytania i fragment, ponieważ mogą zawierać sekrety (?apikey=, podpisane linki).
Sesje i tokeny#
- Klient wysyła
apikeyprzy każdym żądaniu iAuthorization: Bearer <access token>po zalogowaniu użytkownika. - Odświeża token dostępu, gdy pozostało mniej niż 30 sekund. Równoczesne odświeżenia są łączone w jedno, więc rotacyjny token odświeżania jest używany tylko raz.
401wyzwala jedno odświeżenie i jedno powtórzenie żądania, a następnie zatrzymuje się.- W przeglądarce odświeżania są koordynowane na różnych kartach.
aura.auth.onAuthStateChange(callback)informuje oSIGNED_IN,SIGNED_OUT,TOKEN_REFRESHED,USER_UPDATEDiMFA_CHALLENGE. Zobacz przewodnik autoryzacji.