Opções do cliente, erros, novas tentativas e tempos limite

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // a chave pública
)

createClient(url, key, options?) usa o URL do projeto e uma chave. O projeto é identificado pelo host da URL, portanto não há ID do projeto para passar. Em uma pilha local, use uma URL com o subdomínio do projeto, como http://my-app-ab12.localhost:8080; com um http://localhost:8080 simples, o cliente imprime um aviso, porque o gateway não consegue dizer a qual projeto você se refere.

Use a chave pública (aura_anon_…) em navegadores e aplicativos. Uma chave service_role (aura_sk_…) pertence apenas ao seu servidor e o cliente a aplica:

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

// Somente servidor: ignora a segurança em nível de linha.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

Em um navegador, createClient lança quando recebe uma chave service_role, portanto, uma chave vazada não pode ser enviada acidentalmente. Defina refuseServiceRoleInBrowser: false para fazer o downgrade do erro para um aviso; não faça isso na produção.

Cada serviço fica suspenso no cliente: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications e aura.from('table') como um atalho para aura.db.from('table'). Consulte a referência do cliente.

Para renderização no lado do servidor, use os clientes baseados em cookies descritos em Next.js App Router e SSR.

Cada chamada retorna { data, error } e nunca é lançada. Quando falha, error é um 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 quando a falha está no cliente
  console.log(error.code)    // 'INTERNO', 'tempo limite', 'erro_de_rede',…
  console.log(error.message) // legível por humanos
  console.log(error.details) // o corpo bruto, incluindo error.request_id do servidor
  isAuraError(error)         // verdade
}

Uma chamada com falha real foi retornada:

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

Códigos produzidos pelo próprio cliente (status 0): timeout, network_error, invalid_response (um sucesso cujo corpo não é JSON), no_session, refresh_discarded, invalid_path, invalid_body. A autenticação adiciona códigos como invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked e rate_limit_exceeded. Um 429 sempre carrega rate_limit_exceeded.

Teste data em vez de error quando precisar do valor. Algumas chamadas são bem-sucedidas sem conteúdo (204) e então data e error são null.

Novas tentativas. O cliente tenta novamente uma solicitação automaticamente somente quando todos estes itens são válidos:

• o método é GET ou HEAD (um POST, PUT, PATCH ou DELETE nunca é reproduzido, então nada é executado duas vezes);
• o status da resposta é 408, 429, 502, 503 ou 504, ou a rede falhou;
• menos de 3 novas tentativas aconteceram.

O atraso é aleatório entre 0 e min(500 ms × 2^attempt, 10 s). Um cabeçalho Retry-After vence, limitado a 60 segundos. Solicitações repetidas carregam um cabeçalho X-Retry-Count. Um tempo limite não é repetido.

Medido em relação a um servidor que respondeu 503 duas vezes e depois 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

Tempos limite. Uma solicitação que não obtém resposta dentro de requestTimeoutMs (30 s por padrão) termina com status: 0 e code: 'timeout'. A leitura do corpo é limitada pelo mesmo limite, portanto, um servidor que envia cabeçalhos e depois paralisa não pode interromper a chamada. Uma solicitação a um servidor que nunca atendeu, com limite de 400 ms, retornou o erro após 405 ms.

Dois casos não utilizam esse limite porque gerenciam o seu próprio: uma chamada onde você passa um AbortSignal e uploads. As funções usam sua própria opção timeout, consulte Erros, tempos limite e novas tentativas.

onEvent recebe um evento por coisa notável que o cliente faz. Nunca faz uma solicitação falhar: uma exceção lançada pelo seu gancho é ignorada.

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

URLs em eventos têm sua string de consulta e fragmento removidos, porque podem conter segredos (?apikey=, links assinados).

• O cliente envia apikey em cada solicitação e Authorization: Bearer <access token> quando um usuário faz login.
• Ele atualiza o token de acesso quando restam menos de 30 segundos. As atualizações simultâneas são mescladas em uma só, portanto, um token de atualização rotativo é usado uma vez.
• Um 401 aciona uma atualização e uma repetição da solicitação e, em seguida, para.
• Em um navegador, as atualizações são coordenadas entre guias.
• aura.auth.onAuthStateChange(callback) fala sobre SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED e MFA_CHALLENGE. Consulte o guia de autenticação.