Opciones del cliente, errores, reintentos y tiempos de espera

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://mi-aplicación.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // la clave pública
)

createClient(url, key, options?) toma la URL del proyecto y una clave. El proyecto se identifica mediante el host de la URL, por lo que no hay ningún ID de proyecto que pasar. En una pila local, use una URL con el subdominio del proyecto, como http://my-app-ab12.localhost:8080; con un http://localhost:8080 desnudo, el cliente imprime una advertencia, porque la puerta de enlace no puede decir a qué proyecto se refiere.

Utilice la clave pública (aura_anon_…) en navegadores y aplicaciones. Una clave service_role (aura_sk_…) pertenece únicamente a su servidor y el cliente la aplica:

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

// Solo servidor: omite la seguridad a nivel de fila.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

En un navegador, createClient arroja cuando recibe una clave service_role, por lo que una clave filtrada no se puede enviar por accidente. Configure refuseServiceRoleInBrowser: false para reducir el error a una advertencia; no hagas esto en producción.

Cada servicio cuelga del cliente: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications y aura.from('table') como acceso directo para aura.db.from('table'). Consulte la referencia del cliente.

Para la representación del lado del servidor, utilice los clientes basados en cookies que se describen en Next.js App Router y SSR.

Cada llamada devuelve { data, error } y nunca se devuelve. Cuando falla, error es 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 cuando la falla está en el cliente
  console.log(error.code)    // 'INTERNO', 'tiempo de espera', 'error_red',…
  console.log(error.message) // legible por humanos
  console.log(error.details) // el cuerpo sin formato, incluido error.request_id del servidor
  isAuraError(error)         // cierto
}

Se devolvió una llamada realmente fallida:

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

Códigos producidos por el propio cliente (estado 0): timeout, network_error, invalid_response (un éxito cuyo cuerpo no es JSON), no_session, refresh_discarded, invalid_path, invalid_body. La autenticación agrega códigos como invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked y rate_limit_exceeded. Un 429 siempre lleva rate_limit_exceeded.

Pruebe data en lugar de error cuando necesite el valor. Algunas llamadas se realizan correctamente sin contenido (204), y luego tanto data como error son null.

Reintentos. El cliente reintenta una solicitud automáticamente solo cuando todas estas se mantienen:

• el método es GET o HEAD (un POST, PUT, PATCH o DELETE nunca se reproduce, por lo que nada se ejecuta dos veces);
• el estado de respuesta es 408, 429, 502, 503 o 504, o la red falló;
• Han ocurrido menos de 3 reintentos.

El retraso es aleatorio entre 0 y min(500 ms × 2^attempt, 10 s). Un encabezado Retry-After lo supera, con un límite de 60 segundos. Las solicitudes reintentadas llevan un encabezado X-Retry-Count. No se reintenta un tiempo de espera.

Medido con un servidor que respondió 503 dos veces, luego 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

Tiempos de espera. Una solicitud que no recibe respuesta dentro de requestTimeoutMs (30 s de forma predeterminada) finaliza con status: 0 y code: 'timeout'. La lectura del cuerpo está limitada por el mismo límite, por lo que un servidor que envía encabezados y luego se detiene no puede colgar la llamada. Una solicitud a un servidor que nunca respondió, con un límite de 400 ms, devolvió el error después de 405 ms.

Dos casos no utilizan este límite porque administran el suyo propio: una llamada en la que pasa un AbortSignal y las cargas. Las funciones usan su propia opción timeout, consulte Errores, tiempos de espera y reintentos.

onEvent recibe un evento por cada cosa notable que hace el cliente. Nunca hace que una solicitud falle: se ignora una excepción lanzada por su gancho.

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

A las URL en eventos se les elimina la cadena de consulta y el fragmento, porque pueden contener secretos (?apikey=, enlaces firmados).

• El cliente envía apikey en cada solicitud y Authorization: Bearer <access token> una vez que el usuario inicia sesión.
• Actualiza el token de acceso cuando quedan menos de 30 segundos. Las actualizaciones simultáneas se fusionan en una, por lo que se utiliza una vez un token de actualización rotativo.
• Un 401 activa una actualización y una repetición de la solicitud, luego se detiene.
• En un navegador, las actualizaciones se coordinan entre pestañas.
• aura.auth.onAuthStateChange(callback) le informa sobre SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED y MFA_CHALLENGE. Consulte la guía de autenticación.