클라이언트 옵션, 오류, 재시도 및 시간 초과
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의 호스트로 식별되므로 전달할 프로젝트 ID가 없습니다. 로컬 스택에서는 http://my-app-ab12.localhost:8080와 같은 프로젝트 하위 도메인이 있는 URL을 사용합니다. 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.from('table')에 대한 바로 가기로 aura.auth, aura.db, aura.storage, aura.realtime, aura.functions, aura.ai, aura.notifications및 aura.from('table')와 같이 클라이언트에서 중단됩니다. 클라이언트 참조를 참조하세요.
옵션#
| 옵션 | 기본값 | 효과 |
|---|---|---|
auth.persistSession | 브라우저의 true | 페이지 로드 사이에 세션 유지 |
auth.storage | 브라우저에서는 localStorage, 다른 곳에서는 메모리 | 세션이 있는 곳: 자신만의 스토어를 전달하세요(SSR용 쿠키) |
auth.autoRefresh | true | 만료되기 전에 액세스 토큰을 새로 고치고 탭을 동기화 상태로 유지하세요. |
auth.detectSessionInUrl | 브라우저의 true | OAuth 리디렉션 후 URL에서 세션을 읽은 다음 URL을 정리합니다. |
fetch | globalThis.fetch | 테스트 또는 프록시를 위한 나만의 fetch |
retry | true | 일시적인 오류에 대해 읽기를 다시 시도합니다. false 비활성화 또는 { enabled, maxRetries } |
requestTimeoutMs | 30000 | 요청 시간 제한. 0는 이를 비활성화합니다. |
onEvent | 없음 | 관찰 가능성 이벤트를 수신합니다. 아래를 참조하세요. |
debug | false | 또한 console.debug('[aurabase]', event)를 사용하여 각 이벤트를 인쇄합니다. |
refuseServiceRoleInBrowser | true | service_role 키가 브라우저에 도달하면 발생합니다. |
서버 측 렌더링의 경우 Next.js 앱 라우터 및 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) // '내부_ERROR', '시간 초과', '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에 대한 바로가기 |
All error codes are in SCREAMING_SNAKE (^[A-Z][A-Z0-9_]+$), whether the server or the client produced them (error.legacyCode returns the former lowercase form and is deprecated). Codes produced by the client itself (status 0): TIMEOUT, NETWORK_ERROR, INVALID_RESPONSE (a success whose body is not JSON), NO_SESSION, REFRESH_DISCARDED, INVALID_PATH, INVALID_BODY. Authentication adds codes such as INVALID_CREDENTIALS, WEAK_PASSWORD, EMAIL_ALREADY_IN_USE, USER_NOT_FOUND, INVALID_OTP, SESSION_EXPIRED, SESSION_REVOKED and RATE_LIMITED. A 429 always carries RATE_LIMITED, and error.retryAfter holds the Retry-After delay in seconds when the server sent one.
값이 필요할 때 error 대신 data를 테스트하세요. 일부 호출은 내용 없이 성공하고(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'로 끝납니다. 본문 읽기도 동일한 제한으로 제한되므로 헤더를 보낸 다음 정지되는 서버는 호출을 중단할 수 없습니다. 400ms 제한으로 응답하지 않은 서버에 대한 요청은 405ms 후에 오류를 반환했습니다.
두 가지 경우는 자체적으로 관리하기 때문에 이 제한을 사용하지 않습니다: 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에 대해 알려줍니다. 인증 가이드를 참조하세요.