Aller au contenu
Logo Aurabase
aurabase

Options client, erreurs, tentatives et délais d'attente

Le comportement partagé par chaque service du SDK et les options qui le modifient.

Référence9 min de lectureNiveau intermédiaireRévisé le 12 oct. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

Créer le client#

src/lib/aurabase.tstypescript
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!,  // la clé publique
)

createClient(url, key, options?) prend l'URL du projet et une clé. Le projet est identifié par l'hôte de l'URL, il n'y a donc aucun identifiant de projet à transmettre. Dans une pile locale, utilisez une URL avec le sous-domaine du projet, telle que http://my-app-ab12.localhost:8080; avec un simple http://localhost:8080, le client imprime un avertissement, car la passerelle ne peut pas savoir de quel projet vous parlez.

Utilisez la clé publique (aura_anon_…) dans les navigateurs et les applications. Une clé service_role (aura_sk_…) appartient uniquement à votre serveur et le client l'applique :

server/admin.tstypescript
import { createAdminClient } from '@aurabase/aurabase-js'

// Serveur uniquement : contourne la sécurité au niveau des lignes.
export const admin = createAdminClient(process.env.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_SERVICE_ROLE_KEY!)

Dans un navigateur, createClient lance lorsqu'il reçoit une clé service_role, de sorte qu'une clé divulguée ne peut pas être expédiée par accident. Définissez refuseServiceRoleInBrowser: false pour rétrograder l'erreur en avertissement ; ne faites pas cela en production.

Chaque service est suspendu au client : aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications et aura.from('table') comme raccourci pour aura.from('table'). Voir la référence client.

Possibilités#

OptionsPar défautEffet
auth.persistSessiontrue dans un navigateurConserver la session entre les chargements de pages
auth.storagelocalStorage dans un navigateur, mémoire ailleursOù vit la session : passez votre propre boutique (cookies pour SSR)
auth.autoRefreshtrueActualisez le jeton d'accès avant son expiration et gardez les onglets synchronisés
auth.detectSessionInUrltrue dans un navigateurLire une session à partir de l'URL après une redirection OAuth, puis nettoyer l'URL
fetchglobalThis.fetchVotre propre fetch, pour les tests ou les proxys
retrytrueRéessayez de lire les erreurs passagères. false désactive, ou { enabled, maxRetries }
requestTimeoutMs30000Délai d'une demande. 0 le désactive.
onEventaucunReçoit les événements d'observabilité, voir ci-dessous
debugfalseImprimez également chaque événement avec console.debug('[aurabase]', event)
refuseServiceRoleInBrowsertrueLancer lorsqu'une clé service_role atteint un navigateur

Pour le rendu côté serveur, utilisez les clients basés sur les cookies décrits dans Next.js App Router et SSR.

L'objet d'erreur#

Chaque appel renvoie { data, error } et ne lance jamais. En cas d'échec, error est un AuraError:

errors.tstypescript
import { isAuraError } from '@aurabase/aurabase-js'

const { data, error } = await aura.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500, ou 0 lorsque la panne est sur le client
  console.log(error.code)    // 'INTERNAL_ERROR', 'TIMEOUT', 'NETWORK_ERROR', …
  console.log(error.message) // lisible par l'homme
  console.log(error.details) // le corps brut, y compris error.request_id du serveur
  isAuraError(error)         // vrai
}

Un véritable appel échoué est revenu :

error.detailsjson
{ "error": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }
ChampSignification
statusLe statut HTTP. 0 signifie que la panne s'est produite avant toute réponse : réseau, timeout ou refus du client.
codeUn identifiant stable. Les codes serveur gardent leur valeur ; le client ajoute les codes ci-dessous.
messageUne explication lisible
detailsLe corps de réponse brut
retryAfterSecondes à attendre, à partir d'un en-tête Retry-After, sur un 429
isNotFound, isUnauthorized, isForbidden, isRateLimitedRaccourcis sur status

Tous les codes d'erreur sont en SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$), que le serveur ou le client les ait produits (error.legacyCode renvoie l'ancienne forme minuscule et est obsolète). Codes produits par le client lui-même (statut 0) : TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE (un succès dont le corps n'est pas JSON), NO_SESSION, REFRESH_DISCARDED, INVALID_PATH, INVALID_BODY. L'authentification ajoute des codes tels que INVALID_CREDENTIALS, WEAK_PASSWORD, EMAIL_ALREADY_IN_USE, USER_NOT_FOUND, INVALID_OTP, SESSION_EXPIRED, SESSION_REVOKED et RATE_LIMITED. Un 429 transporte toujours RATE_LIMITED, et error.retryAfter détient le délai Retry-After en secondes lorsque le serveur en envoie un.

Testez data plutôt que error lorsque vous avez besoin de la valeur. Certains appels réussissent sans contenu (204), puis data et error sont null.

Nouvelles tentatives et délais d'attente#

Nouvelles tentatives. Le client réessaye automatiquement une demande uniquement lorsque tous ces éléments sont satisfaits :

  • la méthode est GET ou HEAD (un POST, PUT, PATCH ou DELETE n'est jamais relu, donc rien ne s'exécute deux fois) ;
  • l'état de la réponse est 408, 429, 502, 503 ou 504, ou le réseau est en panne ;
  • moins de 3 tentatives ont eu lieu.

Le délai est aléatoire entre 0 et min(500 ms × 2^attempt, 10 s). Un en-tête Retry-After l'emporte, plafonné à 60 secondes. Les requêtes réessayées portent un en-tête X-Retry-Count. Un délai d'attente n'est pas retenté.

Mesuré par rapport à un serveur qui a répondu deux fois à 503, puis à 200:

text
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

Délais d'attente. Une requête qui n'obtient aucune réponse dans un délai de requestTimeoutMs (30 s par défaut) se termine par status: 0 et code: 'TIMEOUT'. La lecture du corps est limitée par la même limite, donc un serveur qui envoie des en-têtes puis bloque ne peut pas raccrocher l'appel. Une requête adressée à un serveur qui n'a jamais répondu, avec une limite de 400 ms, a renvoyé l'erreur au bout de 405 ms.

Deux cas n'utilisent pas cette limite car ils gèrent le leur : un appel où l'on passe un AbortSignal, et des uploads. Les fonctions utilisent leur propre option timeout, voir Erreurs, délais d'attente et tentatives.

Observer le client#

onEvent reçoit un événement pour chaque action notable effectuée par le client. Cela ne fait jamais échouer une requête : une exception levée par votre hook est ignorée.

kindChampsQuand
retryattempt, status?, urlAvant une nouvelle tentative
timeouturlUne requête a atteint requestTimeoutMs
refresh-successaucunUne actualisation de session a réussi
refresh-discardedreasonUne actualisation a été abandonnée car la session a changé entre-temps
jwks-fetch-failedbaseUrlLes clés de signature n'ont pas pu être récupérées (vérifications de jetons locaux)
storage-blockedopLe navigateur a refusé l'accès au stockage
observe.tstypescript
const aura = createClient(url, key, {
  onEvent: (e) => metrics.increment(`aurabase.${e.kind}`),
})

Les URL dans les événements voient leur chaîne de requête et leur fragment supprimés, car ils peuvent contenir des secrets (?apikey=, liens signés).

Sessions et jetons#

  • Le client envoie apikey à chaque demande et Authorization: Bearer <access token> une fois qu'un utilisateur est connecté.
  • Il actualise le jeton d'accès lorsqu'il reste moins de 30 secondes. Les actualisations simultanées sont fusionnées en une seule, de sorte qu'un jeton d'actualisation rotatif est utilisé une seule fois.
  • Un 401 déclenche une actualisation et une relecture de la requête, puis s'arrête.
  • Dans un navigateur, les actualisations sont coordonnées entre les onglets.
  • aura.auth.onAuthStateChange(callback) vous parle de SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED et MFA_CHALLENGE. Voir le guide d'authentification.