Параметры клиента, ошибки, повторы и тайм-ауты

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

export const aura = createClient(
  process.env.AURA_URL!,       // https://my-app.aurabase.cloud
  process.env.AURA_ANON_KEY!,  // открытый ключ
)

createClient(url, key, options?) принимает URL-адрес проекта и один ключ. Проект идентифицируется хостом URL-адреса, поэтому идентификатор проекта не требуется передавать. В локальном стеке используйте URL-адрес с поддоменом проекта, например http://my-app-ab12.localhost:8080; с голым http://localhost:8080 клиент печатает предупреждение, потому что шлюз не может определить, какой проект вы имеете в виду.

Используйте открытый ключ (aura_anon_…) в браузерах и приложениях. Ключ service_role (aura_sk_…) принадлежит только вашему серверу, и клиент применяет его:

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

// Только сервер: обходит безопасность на уровне строк.
export const admin = createAdminClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

В браузере createClient выдает при получении ключа service_role, поэтому утечка ключа не может быть доставлена ​​случайно. Установите refuseServiceRoleInBrowser: false, чтобы перевести ошибку в предупреждение; не делайте этого на производстве.

Каждая служба зависает на клиенте: aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications и aura.from('table') как ярлык для aura.db.from('table'). См. ссылку на клиента.

Для рендеринга на стороне сервера используйте клиенты на основе файлов cookie, описанные в Next.js App Router и SSR.

Каждый вызов возвращает { data, error } и никогда не выдает ошибку. В случае сбоя error становится AuraError:

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

const { data, error } = await aura.db.from('posts').select('*')
if (error) {
  console.log(error.status)  // 500 или 0, если сбой произошел на клиенте.
  console.log(error.code)    // «ВНУТРЕННИЙ», «тайм-аут», «сетевая_ошибка»,…
  console.log(error.message) // человекочитаемый
  console.log(error.details) // необработанное тело, включая error.request_id с сервера
  isAuraError(error)         // истинный
}

Настоящий неудачный вызов вернулся:

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

Коды, созданные самим клиентом (статус 0): timeout, network_error, invalid_response (успех, тело которого не является JSON), no_session, refresh_discarded, invalid_path, invalid_body. Аутентификация добавляет такие коды, как invalid_credentials, weak_password, email_already_in_use, user_not_found, invalid_otp, session_expired, session_revoked и rate_limit_exceeded. 429 всегда содержит rate_limit_exceeded.

Проверяйте data вместо error, когда вам нужно значение. Некоторые вызовы завершаются успешно без содержимого (204), и тогда и data, и error становятся null.

Повторные попытки. Клиент автоматически повторяет запрос только в том случае, если выполняются все следующие условия:

• метод — GET или HEAD (POST, PUT, PATCH или DELETE никогда не воспроизводится повторно, поэтому ничего не выполняется дважды);
• статус ответа — 408, 429, 502, 503 или 504, или произошел сбой в сети;
• произошло менее 3 повторных попыток.

Задержка является случайной в диапазоне от 0 до min(500 ms × 2^attempt, 10 s). Заголовок Retry-After побеждает его, его продолжительность ограничена 60 секундами. Повторные запросы содержат заголовок X-Retry-Count. Тайм-аут не повторяется.

Измерено на сервере, который дважды ответил на 503, а затем на 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

Тайм-ауты. Запрос, на который не получен ответ в течение requestTimeoutMs (по умолчанию 30 с), заканчивается status: 0 и code: 'timeout'. Чтение тела ограничено тем же пределом, поэтому сервер, который отправляет заголовки, а затем останавливается, не может прервать вызов. Запрос к серверу, который так и не ответил, с ограничением в 400 мс, вернул ошибку через 405 мс.

В двух случаях это ограничение не используется, поскольку они управляются самостоятельно: вызов, в котором вы передаете AbortSignal, и загрузка. Функции используют собственную опцию timeout, см. Ошибки, таймауты и повторы.

onEvent получает одно событие на каждое заметное действие клиента. Он никогда не приводит к сбою запроса: исключение, вызванное вашим перехватчиком, игнорируется.

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

Из URL-адресов в событиях удаляются строка запроса и фрагмент, поскольку они могут содержать секреты (?apikey=, подписанные ссылки).

• Клиент отправляет apikey при каждом запросе и Authorization: Bearer <access token> после входа пользователя в систему.
• Он обновляет токен доступа, когда остается менее 30 секунд. Параллельные обновления объединяются в одно, поэтому токен ротационного обновления используется один раз.
• 401 запускает одно обновление и одно повторение запроса, а затем останавливается.
• В браузере обновления координируются по вкладкам.
• aura.auth.onAuthStateChange(callback) расскажет вам о SIGNED_IN, SIGNED_OUT, TOKEN_REFRESHED, USER_UPDATED и MFA_CHALLENGE. См. руководство по аутентификации.