Opcje klienta, błędy, ponowne próby i przekroczenia limitu czasu

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_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.AURA_URL!, process.env.AURA_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.db.from('table'). Zobacz referencje klienta.

Do renderowania po stronie serwera użyj klientów opartych na plikach cookie opisanych w Next.js App Router i SSR.

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.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500 lub 0, gdy awaria występuje po stronie klienta
  console.log(error.code)    // „WEWNĘTRZNY”, „limit czasu”, „błąd_sieci”, …
  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" } }

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_limit_exceeded. 429 zawsze zawiera rate_limit_exceeded.

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. Klient automatycznie ponawia żądanie tylko wtedy, gdy wszystkie z nich spełniają:

• metoda to GET lub HEAD (a POST, PUT, PATCH lub DELETE nigdy nie jest odtwarzane, więc nic nie działa dwukrotnie);
• status odpowiedzi to 408, 429, 502, 503 lub 504 lub 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.

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.

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).

• Klient wysyła apikey przy każdym żądaniu i Authorization: Bearer <access token> po zalogowaniu się 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.
• 401 wyzwala 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 o SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED i MFA_CHALLENGE. Zobacz przewodnik autoryzacji.