क्लाइंट विकल्प, त्रुटियाँ, पुनः प्रयास और टाइमआउट

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 का उपयोग करें, जैसे 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') के शॉर्टकट के रूप में। ग्राहक संदर्भ देखें।

सर्वर-साइड रेंडरिंग के लिए, Next.js ऐप राउटर और 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 रखता है।

जब आपको मूल्य की आवश्यकता हो तो 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 को ग्राहक द्वारा किए गए प्रत्येक उल्लेखनीय कार्य के लिए एक ईवेंट प्राप्त होता है। यह कभी भी किसी अनुरोध को विफल नहीं करता है: आपके हुक द्वारा फेंके गए अपवाद को अनदेखा कर दिया जाता है।

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 के बारे में बताता है। प्रामाणिक मार्गदर्शिका देखें।