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

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_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 :

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

// Serveur uniquement : contourne la sécurité au niveau des lignes.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_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.db.from('table'). Voir la référence client.

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

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

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

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500, ou 0 lorsque la panne est sur le client
  console.log(error.code)    // 'INTERNE', '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": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }

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_limit_exceeded. Un 429 porte toujours rate_limit_exceeded.

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

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.

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.

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

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