Opzioni client, errori, tentativi e timeout

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://mia-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // la chiave pubblica
)

createClient(url, key, options?) accetta l'URL del progetto e una chiave. Il progetto è identificato dall'host dell'URL, quindi non c'è alcun ID progetto da passare. In uno stack locale, utilizza un URL con il sottodominio del progetto, ad esempio http://my-app-ab12.localhost:8080; con un semplice http://localhost:8080 il client stampa un avviso, perché il gateway non può dire a quale progetto ti riferisci.

Utilizza la chiave pubblica (aura_anon_…) nei browser e nelle app. Una chiave service_role (aura_sk_…) appartiene solo al tuo server e il client la applica:

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

// Solo server: ignora la sicurezza a livello di riga.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

In un browser, createClient genera quando riceve una chiave service_role, quindi una chiave trapelata non può essere spedita per sbaglio. Imposta refuseServiceRoleInBrowser: false per declassare l'errore a avviso; non farlo in produzione.

Ogni servizio si blocca dal client: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications e aura.from('table') come scorciatoia per aura.db.from('table'). Vedi il riferimento del client.

Per il rendering lato server, utilizzare i client basati su cookie descritti in Next.js App Router e SSR.

Ogni chiamata restituisce { data, error } e non genera mai un'eccezione. Quando fallisce, error è un AuraError:

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

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500 o 0 quando l'errore è sul client
  console.log(error.code)    // 'INTERNO', 'timeout', 'errore_rete', …
  console.log(error.message) // leggibile dall'uomo
  console.log(error.details) // il corpo non elaborato, incluso error.request_id dal server
  isAuraError(error)         // vero
}

È stata restituita una vera chiamata fallita:

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

Codici prodotti dal client stesso (stato 0): timeout, network_error, invalid_response (un successo il cui corpo non è JSON), no_session, refresh_discarded, invalid_path, invalid_body. L'autenticazione aggiunge codici come invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked e rate_limit_exceeded. A 429 trasporta sempre rate_limit_exceeded.

Prova data anziché error quando ti serve il valore. Alcune chiamate hanno esito positivo senza contenuto (204), quindi sia data che error sono null.

Tentativi. Il client ritenta automaticamente una richiesta solo quando tutti questi valori sono validi:

• il metodo è GET o HEAD (a POST, PUT, PATCH o DELETE non viene mai riprodotto, quindi nulla viene eseguito due volte);
• lo stato della risposta è 408, 429, 502, 503 o 504 oppure la rete non è riuscita;
• si sono verificati meno di 3 tentativi.

Il ritardo è casuale tra 0 e min(500 ms × 2^attempt, 10 s). Un colpo di testa Retry-After vince su di esso, limitato a 60 secondi. Le richieste riprovate portano un'intestazione X-Retry-Count. Un timeout non viene ripetuto.

Misurato rispetto a un server che ha risposto 503 due volte, quindi 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

Timeout. Una richiesta che non ottiene risposta entro requestTimeoutMs (30 s per impostazione predefinita) termina con status: 0 e code: 'timeout'. La lettura del corpo è limitata dallo stesso limite, quindi un server che invia intestazioni e poi si blocca non può interrompere la chiamata. Una richiesta ad un server che non ha mai risposto, con un limite di 400 ms, restituiva l'errore dopo 405 ms.

Due casi non utilizzano questo limite perché gestiscono da soli: una chiamata in cui si passa un AbortSignal e i caricamenti. Le funzioni utilizzano la propria opzione timeout, vedere Errori, timeout e tentativi.

onEvent riceve un evento per ogni cosa notevole fatta dal client. Non fa mai fallire una richiesta: un'eccezione lanciata dal tuo hook viene ignorata.

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

Agli URL negli eventi viene rimossa la stringa di query e il frammento, poiché possono contenere segreti (?apikey=, collegamenti firmati).

• Il client invia apikey su ogni richiesta e Authorization: Bearer <access token> una volta che l'utente ha effettuato l'accesso.
• Aggiorna il token di accesso quando rimangono meno di 30 secondi. Gli aggiornamenti simultanei vengono uniti in uno solo, quindi un token di aggiornamento a rotazione viene utilizzato una volta.
• Un 401 attiva un aggiornamento e una riproduzione della richiesta, quindi si interrompe.
• In un browser, gli aggiornamenti sono coordinati tra le schede.
• aura.auth.onAuthStateChange(callback) ti parla di SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED e MFA_CHALLENGE. Vedi la guida all'autenticazione.