क्लाइंट विकल्प, त्रुटियाँ, पुनः प्रयास और टाइमआउट
एसडीके की प्रत्येक सेवा द्वारा साझा किया जाने वाला व्यवहार और इसे बदलने वाले विकल्प।
ग्राहक बनाएँ#
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 का उपयोग करें, जैसे 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, मेमोरी अन्यत्र | सत्र कहाँ रहता है: अपना स्वयं का स्टोर पास करें (एसएसआर के लिए कुकीज़) |
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) // 'आंतरिक_त्रुटि', 'समय समाप्त', 'नेटवर्क_त्रुटि', ...
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 विलंब को रोक देता है।
जब आपको मूल्य की आवश्यकता हो तो 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' के साथ समाप्त होता है। बॉडी को पढ़ना उसी सीमा से बंधा हुआ है, इसलिए एक सर्वर जो हेडर भेजता है और फिर रुक जाता है वह कॉल को हैंग नहीं कर सकता है। 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के बारे में बताता है। प्रामाणिक मार्गदर्शिका देखें।