Параметры клиента, ошибки, повторы и тайм-ауты
Поведение, общее для каждой службы SDK, и параметры, которые его меняют.
Создать клиент#
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!, // открытый ключ
)
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.NEXT_PUBLIC_AURABASE_URL!, process.env.AURABASE_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.from('table'). См. ссылку на клиента.
Параметры#
| Вариант | По умолчанию | Эффект |
|---|---|---|
auth.persistSession | true в браузере | Сохраняйте сеанс между загрузками страниц |
auth.storage | localStorage в браузере, память в другом месте | Где живет сессия: передайте свой собственный магазин (куки для SSR) |
auth.autoRefresh | true | Обновляйте токен доступа до истечения срока его действия и синхронизируйте вкладки. |
auth.detectSessionInUrl | true в браузере | Прочитайте сеанс по URL-адресу после перенаправления OAuth, затем очистите URL-адрес. |
fetch | globalThis.fetch | Ваш собственный fetch для тестов или прокси. |
retry | true | Повторить чтение при временных ошибках. false отключает или { enabled, maxRetries } |
requestTimeoutMs | 30000 | Срок рассмотрения запроса. 0 отключает его. |
onEvent | никто | Получает события наблюдения, см. ниже. |
debug | false | Также распечатайте каждое событие с помощью console.debug('[aurabase]', event). |
refuseServiceRoleInBrowser | true | Выдавать, когда ключ service_role достигает браузера |
Для рендеринга на стороне сервера используйте клиенты на основе файлов cookie, описанные в Next.js App Router и SSR.
Объект ошибки#
Каждый вызов возвращает { data, error } и никогда не выдает ошибку. В случае сбоя error становится AuraError:
import { isAuraError } from '@aurabase/aurabase-js'
const { data, error } = await aura.from('posts').select('*')
if (error) {
console.log(error.status) // 500 или 0, если сбой произошел на клиенте.
console.log(error.code) // «ВНУТРЕННЯ_ОШИБКА», «ВРЕМЯ АУТА», «NETWORK_ERROR», …
console.log(error.message) // человекочитаемый
console.log(error.details) // необработанное тело, включая error.request_id с сервера
isAuraError(error) // истинный
}
Настоящий неудачный вызов вернулся:
{ "error": { "code": "INTERNAL", "message": "boom", "request_id": "req-123" } }
| Поле | Значение |
|---|---|
status | HTTP-статус. 0 означает, что сбой произошел до какого-либо ответа: сети, тайм-аута или отказа клиента. |
code | Стабильный идентификатор. Коды серверов сохраняют свою ценность; клиент добавляет коды ниже. |
message | Читабельное объяснение |
details | Необработанное тело ответа |
retryAfter | Секунды ожидания из заголовка Retry-After на 429 |
isNotFound, isUnauthorized, isForbidden, isRateLimited | Ярлыки на status |
Все коды ошибок находятся в SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$), независимо от того, создали ли их сервер или клиент (error.legacyCode возвращает прежнюю форму в нижнем регистре и считается устаревшей). Коды, создаваемые самим клиентом (статус 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_LIMITED. 429 всегда содержит RATE_LIMITED, а error.retryAfter удерживает задержку Retry-After в секундах, когда сервер отправил его.
Проверяйте 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 получает одно событие на каждое заметное действие клиента. Он никогда не приводит к сбою запроса: исключение, вызванное вашим перехватчиком, игнорируется.
kind | Поля | Когда |
|---|---|---|
retry | attempt, status?, url | Перед повторной попыткой |
timeout | url | Запрос хит requestTimeoutMs |
refresh-success | никто | Обновление сеанса выполнено успешно |
refresh-discarded | reason | Обновление было прекращено, поскольку сеанс тем временем изменился. |
jwks-fetch-failed | baseUrl | Не удалось получить ключи подписи (локальная проверка токена). |
storage-blocked | op | Браузер отказал в доступе к хранилищу |
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. См. руководство по аутентификации.