Clientopties, fouten, nieuwe pogingen en time-outs

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://mijn-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // de publieke sleutel
)

createClient(url, key, options?) neemt de project-URL en één sleutel. Het project wordt geïdentificeerd door de host van de URL, er hoeft dus geen project-ID door te geven. Gebruik in een lokale stapel een URL met het projectsubdomein, zoals http://my-app-ab12.localhost:8080; met een kale http://localhost:8080 drukt de client een waarschuwing af, omdat de gateway niet kan zien welk project u bedoelt.

Gebruik de openbare sleutel (aura_anon_…) in browsers en apps. Een service_role sleutel (aura_sk_…) hoort alleen op uw server en de client dwingt deze af:

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

// Alleen server: omzeilt beveiliging op rijniveau.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

In een browser genereert createClient wanneer er een service_role-sleutel wordt ontvangen, zodat een gelekte sleutel niet per ongeluk kan worden verzonden. Stel refuseServiceRoleInBrowser: false in om de fout te downgraden naar een waarschuwing; doe dit niet in de productie.

Elke service hangt buiten de client: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications en aura.from('table') als snelkoppeling voor aura.db.from('table'). Zie de clientreferentie.

Voor weergave op de server gebruikt u de op cookies gebaseerde clients die worden beschreven in Next.js App Router en SSR.

Elke oproep retourneert { data, error } en gooit nooit. Als het mislukt, is error een AuraError:

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

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500 of 0 als de fout op de client ligt
  console.log(error.code)    // 'INTERNAL', 'time-out', 'netwerkfout', …
  console.log(error.message) // voor mensen leesbaar
  console.log(error.details) // de onbewerkte body, inclusief error.request_id van de server
  isAuraError(error)         // waar
}

Er kwam een echte mislukte oproep terug:

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

Codes geproduceerd door de klant zelf (status 0): timeout, network_error, invalid_response (een succes waarvan de hoofdtekst geen JSON is), no_session, refresh_discarded, invalid_path, invalid_body. Authenticatie voegt codes toe zoals invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked en rate_limit_exceeded. Een 429 bevat altijd rate_limit_exceeded.

Test data in plaats van error wanneer u de waarde nodig heeft. Sommige oproepen slagen zonder inhoud (204), en dan zijn zowel data als error null.

Nieuwe pogingen. De client probeert een verzoek alleen automatisch opnieuw als deze allemaal geldig zijn:

• de methode is GET of HEAD (een POST, PUT, PATCH of DELETE wordt nooit opnieuw afgespeeld, dus niets wordt tweemaal uitgevoerd);
• de reactiestatus is 408, 429, 502, 503 of 504, of het netwerk is mislukt;
• Er zijn minder dan 3 nieuwe pogingen gedaan.

De vertraging is willekeurig tussen 0 en min(500 ms × 2^attempt, 10 s). Een kopbal van Retry-After wint ervan, met een maximum van 60 seconden. Opnieuw geprobeerde verzoeken hebben een header X-Retry-Count. Een time-out wordt niet opnieuw geprobeerd.

Gemeten tegen een server die tweemaal 503 antwoordde, daarna 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

Time-outs. Een verzoek dat geen antwoord krijgt binnen requestTimeoutMs (standaard 30 s) eindigt met status: 0 en code: 'timeout'. Het lezen van de hoofdtekst wordt begrensd door dezelfde limiet, dus een server die headers verzendt en vervolgens vastloopt, kan het gesprek niet ophangen. Een verzoek aan een server die nooit antwoordde, met een limiet van 400 ms, retourneerde de fout na 405 ms.

In twee gevallen wordt deze limiet niet gebruikt omdat ze hun eigen limiet beheren: een oproep waarbij u een AbortSignal doorgeeft en uploadt. Functies gebruiken hun eigen timeout optie, zie Fouten, time-outs en nieuwe pogingen.

onEvent ontvangt één gebeurtenis per opmerkelijk ding dat de client doet. Het zorgt er nooit voor dat een verzoek mislukt: een uitzondering die door je hook wordt gegenereerd, wordt genegeerd.

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

Van URL's in gebeurtenissen zijn de queryreeks en het fragment verwijderd, omdat ze geheimen kunnen bevatten (?apikey=, ondertekende links).

• De client verzendt apikey bij elk verzoek en Authorization: Bearer <access token> zodra een gebruiker is aangemeld.
• Het vernieuwt het toegangstoken als er minder dan 30 seconden resteren. Gelijktijdige vernieuwingen worden samengevoegd tot één vernieuwingstoken, zodat er één keer een roterend vernieuwingstoken wordt gebruikt.
• Een 401 activeert één keer vernieuwen en één keer opnieuw afspelen van het verzoek en stopt vervolgens.
• In een browser worden vernieuwingen over de tabbladen heen gecoördineerd.
• aura.auth.onAuthStateChange(callback) vertelt je over SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED en MFA_CHALLENGE. Zie de auth-gids.