خيارات العميل والأخطاء وإعادة المحاولة والمهلة

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'). راجع مرجع العميل.

بالنسبة للعرض من جانب الخادم، استخدم العملاء المستندين إلى ملفات تعريف الارتباط الموضحين في 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. راجع دليل المصادقة.