sbarbase
English
المحتويات

واجهة API

هذه المسارات يخدمها خادم الحلقة المحلية (lab/upstream-server.ts). كل مسار يبدأ بـ/management/ ينتمي إلى واجهة الإدارة، والمساران /v1/ و/mcp للوكلاء، وما عدا ذلك ينتمي إلى بوابة التطبيقات. قُرئت من الكود في 2026-10-19، والكود هو المرجع:

تُخدم لوحة الإدارة وملفاتها الثابتة إلى جانب هذه المسارات عبر lab/ui-static.ts. يرفض خادم الحلقة المحلية أي ترويسة Host غير 127.0.0.1 أو localhost، والوصول العام يمر عبر وكيل TLS (انظر نشر الخادم).

دخول الإدارة

تُمرَّر هذه الطلبات إلى نطاق الإدارة، أي نسخة Auth المخصصة للمشغّلين، بمفتاح التوجيه العام sb_publishable_sbarbase_local_management. وجّه Supabase SDK إلى <base URL>/management.

الطريقة المسار الغرض
POST /management/auth/v1/token تسجيل الدخول (password grant) أو تجديد الرمز
GET /management/auth/v1/user المشغّل الحالي
POST /management/auth/v1/logout تسجيل الخروج
GET /management/auth/v1/settings إعدادات Auth
GET, PATCH /management/auth/v1/policy هل يفرض التثبيت المصادقة الثنائية (MFA)، وهل ما زال المتصل يحتاج إلى رمز. لا يغيّرها إلا مالك للتثبيت تحقق من رمز تطبيق المصادقة في آخر خمس دقائق، بالجسم {"mfa_required": bool}
POST /management/auth/v1/factors تسجيل تطبيق مصادقة (TOTP) للحساب الذي سجّل دخوله
POST /management/auth/v1/factors/{id}/challenge، /management/auth/v1/factors/{id}/verify طلب رمز ثم التحقق منه
DELETE /management/auth/v1/factors/{id} إزالة تطبيق مصادقة

أي مسار آخر تحت /management/auth/... يعيد 404، والطريقة الخاطئة تعيد 405. لمحاولات الدخول حدّ، وما يتجاوزه يُرد بـ429.

واجهة الإدارة

كل المسارات تحتاج Authorization: Bearer <management access token>. هوية الفاعل تؤخذ من هذا الرمز، ولا تؤخذ أبدًا من جسم الطلب. المعرّفات من نوع UUID. رموز الأخطاء: 400 مدخل غير صالح، و401 لا رمز صالح، و403 غير مسموح (وتُعاد أيضًا لمعرّف مجهول)، و404 مسار مجهول، و405 طريقة خاطئة، و409 تعارض (البيئة غير جاهزة، أو الاسم مستخدم في العميل أو المشروع نفسه، أو بلغ عدد البيئات حده، أو الطلب لا يقبل الإعادة، أو ما زالت فيه مشاريع أو بيئات، أو ما زال التجهيز أو إحدى الخدمات نشطًا)، ولا يتغير شيء، و503 فحص الهوية غير متاح، و500 خطأ داخلي منقّى من التفاصيل.

الطريقة المسار من يستطيع النتيجة
GET /management/v1/organizations أي مشغّل عملاء المستدعي (المنظمات) بالمعرّف والاسم والدور، مع operator: true إذا كان يحق له إنشاء عملاء
POST /management/v1/organizations مالك أو مدير العميل الذي أُنشئ عند الإعداد الأولي الجسم {"name": "..."}. يعيد 201 مع {id}، ويصبح المستدعي مالكه
PATCH /management/v1/organizations/{id} مالك الجسم {"name": "..."}. يغيّر اسم العميل
DELETE /management/v1/organizations/{id} مالك يحذف عميلًا فارغًا مع عضوياته ودعواته المعلقة. يُرجع 409 ما دامت فيه مشاريع، ودائمًا للعميل الذي أُنشئ عند التهيئة
GET /management/v1/organizations/{id}/members مالك، مدير أعضاء ذلك العميل مع أدوارهم
PUT /management/v1/organizations/{id}/members/{member} مالك الجسم `{"role": "owner"
DELETE /management/v1/organizations/{id}/members/{member} مالك يزيل العضو، وينتهي وصوله إلى الإدارة وStudio من الطلب التالي. يُرجع 409 للمالك الأخير
GET /management/v1/organizations/{id}/invitations مالك، مدير الدعوات المعلّقة: البريد والدور ومن دعا وموعد الانتهاء، دون الرمز أبدًا
POST /management/v1/organizations/{id}/invitations مالك، مدير الجسم {"email": "...", "role": "..."}، ولا يدعو المدير مالكًا. يُرجع 201 مع {id, token, expires_at}؛ يُعرض الرمز مرة واحدة ويصلح 7 أيام
DELETE /management/v1/organizations/{id}/invitations/{invitation} مالك، مدير يلغي دعوة معلّقة
POST /management/invitations/redeem كل من يحمل الرمز الجسم {"token": "...", "password": "..."} ينشئ الحساب (كلمة مرور من 12 حرفًا أو أكثر) وينضم؛ ومع جلسة للبريد المدعو يكفي {"token": "..."}. يُرجع 400 This invitation is not valid لأي رمز مجهول أو مستعمل أو ملغى أو منتهٍ، و409 إن وُجد حساب وعليه تسجيل الدخول أولًا، و429 بعد 20 محاولة فاشلة في دقيقة
GET /management/v1/organizations/{id}/projects عضو مشاريع ذلك العميل
POST /management/v1/organizations/{id}/projects مالك، مدير الجسم {"name": "..."}. يعيد 201 مع {id, state: "metadata_only"}
PATCH /management/v1/projects/{id} مالك، مدير الجسم {"name": "..."}. يُرجع 409 إن كان الاسم مستخدمًا في ذلك العميل
DELETE /management/v1/projects/{id} مالك يحذف مشروعًا لا بيئة فيه، ويُرجع 409 في غير ذلك
POST /management/v1/projects/{id}/move مالك في العميلين الجسم {"organization": "<id>"}. ينقل المشروع مع بقاء معرّفاته ومعرّفات التشغيل. يُلغى التجهيز المنتظر (أعده في العميل الجديد)، وتُلغى كل مفاتيح API لبيئاته. يُرجع 200 مع {organization, cancelled, revoked}، و409 إن تعارض الاسم في العميل الهدف أو كان التجهيز جاريًا
GET /management/v1/projects/{id}/environments عضو بيئات ذلك المشروع
POST /management/v1/projects/{id}/environments مالك، مدير الجسم {"name": "..."}. يعيد 202 مع {id, state: "queued"}، ثم يجهّزها العامل
PATCH /management/v1/environments/{id} مالك، مدير الجسم {"name": "..."}. يُرجع 409 إن كان الاسم مستخدمًا في ذلك المشروع
DELETE /management/v1/environments/{id} مالك يخرج البيئة من الإدارة ويلغي مفاتيحها، ومن بعدها تجيب البوابة 401 لمعرّف تشغيلها. تبقى قاعدة بياناتها وحاوياتها وملفاتها على الخادم، محفوظة سبعة أيام. يُرجع 200 {deleted, revoked, retentionUntil}. ويُرجع 409 ما دام التجهيز منتظرًا أو جاريًا، أو ما دام Studio أو Realtime أو Edge Functions أو الوصول المباشر إلى قاعدة البيانات أو تغيير في تسجيل الدخول أو تدوير لمفتاح التوقيع أو توجيه موقوف أو منقول، مشغّلًا أو قيد التنفيذ، وكذلك حين لم تُسجَّل قط القائمة الدقيقة لموارد البيئة، وهذا حال كل بيئة في التثبيت العادي (انظر أدناه)
GET /management/v1/environments/{id}/lifecycle مالك، مدير سجل الحذف: state (active أو deleting أو deleted أو restoring أو purging أو purged)، وretain_until، والموارد وما جرى لكل منها
POST /management/v1/environments/{id}/restore مالك الجسم {"operation": "<new uuid>"}. يعيد بيئة محذوفة ما دامت محفوظة. يُرجع 202، و409 بعد انتهاء مدة الحفظ
POST /management/v1/environments/{id}/purge مالك هو مشغّل للتثبيت الجسم {"operation": "<new uuid>"}. يزيل موارد بيئة محذوفة نهائيًا، بعد انتهاء مدة الحفظ فقط ومع دليل استعادة كامل. يُرجع 202
POST /management/v1/environments/{id}/resume مالك الجسم {"operation": "<uuid>"} لعملية الحذف أو الاستعادة أو الإزالة الجارية. يجدد تفويضها لتكمل
GET /management/v1/projects/{id}/retained-environments مالك، مدير بيئات المشروع المحذوفة أو التي في طريقها إلى الحذف
POST /management/v1/relink مشغّل التثبيت الجسم {"runtime": "e_...", "ownership": {...}}، والحقل ownership كما يسجله بيان النسخة الاحتياطية. يعيد إنشاء ذلك العميل والمشروع والبيئة هنا بالمعرّفات نفسها ومعرّف التشغيل نفسه، ويضع التجهيز في الانتظار؛ يستدعيه sbarbase relink (النسخ الاحتياطي والاستعادة). يُرجع 409 لأي تعارض: عميل بهذا الاسم لكن بمعرّف آخر، أو معرّف يخص شيئًا آخر هنا، أو معرّف تشغيل مستعمل أو محذوف هنا
GET /management/v1/environments/{id}/provision عضو حالة التجهيز state ورقم المحاولة attempt، والسبب failure إن وُجد
POST /management/v1/environments/{id}/retry مالك، مدير بلا جسم. يعيد 202 {state: "queued"} لبيئة فشلت أو أُلغيت، و409 في غير ذلك أو عند بلوغ حد البيئات
GET /management/v1/environments/{id}/connection عضو، حين تجهز البيئة {environment, apiPath: "/<runtime>", services}
GET /management/v1/environments/{id}/keys مالك، مدير البيانات الوصفية للمفاتيح، ومعها token للمفتاح العام الفعّال المنشأ منذ 0.5.0؛ ولا يُعاد المفتاح السري أبدًا
POST /management/v1/environments/{id}/keys مالك، مدير جسم اختياري {type: "publishable"|"secret", name}، وبدونه يُنشأ مفتاح عام اسمه default. يعيد 201 {id, token, type, name}، والمفتاح السري لا يظهر إلا هنا (مفاتيح API)
GET /management/v1/access-tokens من سجّل دخوله رموز الوصول الخاصة به، دون الرموز نفسها
POST /management/v1/access-tokens من سجّل دخوله {name, scope?: {kind: "all"|"organization"|"project", id?}, read_only?, days?} (من 1 إلى 365، و90 افتراضيًا). يعيد 201 {data, token}، والرمز يظهر مرة واحدة (وكلاء الذكاء الاصطناعي)
DELETE /management/v1/access-tokens/{id} من سجّل دخوله يلغي رمزًا من رموزه
POST /management/v1/access-tokens/revoke-all من سجّل دخوله يلغي كل رموزه
DELETE /management/v1/environments/{id}/keys/{keyId} مالك، مدير يعيد 200 {revoked: true}، أو 404 إذا لم يكن مفتاحًا فعّالًا لهذه البيئة
GET /management/v1/environments/{id}/metrics عضو، عندما تكون جاهزة آخر ساعة عند البوابة: window (requests وclientErrors وserverErrors، وp50 وp95 بالميلي ثانية، وعدد الطلبات لكل خدمة في services)، وperMinute (60 صفًا)، وsince، وservices (استهلاك الذاكرة والمعالج لـ Auth وREST وRealtime وEdge Functions). في الذاكرة، وتفرغ بعد إعادة التشغيل (السجلات والمقاييس)
GET /management/v1/environments/{id}/logs?source=requests|auth|rest|storage|realtime|functions&lines=1-1000&errors=1 مالك، مدير، عندما تكون جاهزة requests: آخر طلبات البوابة، الأحدث أولًا، بلا نصوص الاستعلام. المصادر الأخرى: lines، آخر أسطر الخدمة، الأقدم أولًا، مع استبدال المفاتيح والرموز وكلمات المرور بـ [redacted]؛ وأسطر Storage فقط إن ذكرت هذه البيئة. 503 إذا تعذّر الوصول إلى Docker
GET /management/v1/environments/{id}/functions مالك، مدير، عندما تكون جاهزة حالة Edge Functions في state وdesired (كما في Realtime)، والدوال المنشورة في functions مع verify_jwt وupdated_at وsize وpath، وأسماء الأسرار في secrets (لا قيمها أبدًا)
PUT /management/v1/environments/{id}/functions مالك، مدير، عندما تكون جاهزة {"enabled": true|false}. يأخذ 202، ويشغّل المشرف بيئة تشغيل البيئة أو يوقفها
PUT /management/v1/environments/{id}/functions/{name} مالك، مدير، عندما تكون جاهزة النشر: {"files": {"index.ts": "..."}, "shared"?: {...}, "verify_jwt"?: bool}، ملفات نصية بمسارات نسبية، حتى 500 ملف و10 MiB. يأخذ 201، وأول نشر يشغّل Edge Functions
DELETE /management/v1/environments/{id}/functions/{name} مالك، مدير، عندما تكون جاهزة يحذف الدالة، و404 إن لم تكن موجودة
PUT /management/v1/environments/{id}/function-secrets مالك، مدير، عندما تكون جاهزة {"secrets": {"NAME": "value" | null}}، وnull يحذف. الأسماء من A-Z والأرقام و_، ولا تبدأ بـ SUPABASE_ أو SB_. يردّ بالأسماء فقط
GET /management/v1/environments/{id}/database مالك، مدير، عندما تكون جاهزة حالة الوصول المباشر إلى قاعدة البيانات في state وdesired، وبيانات الاتصال في connection (المضيف والمنفذ والمستخدم وقاعدة البيانات)، وurl بمكان محجوز لكلمة المرور
PUT /management/v1/environments/{id}/database مالك، مدير، عندما تكون جاهزة {"enabled": true|false}. يأخذ 202، والتشغيل يردّ مرة واحدة بكلمة مرور جديدة في password وurl كامل
POST /management/v1/environments/{id}/database/password مالك، مدير، عندما تكون جاهزة كلمة مرور جديدة تُعرض مرة واحدة، وتتوقف القديمة. يأخذ 409 إن كان الوصول مطفأً
GET /management/v1/environments/{id}/signing-key مالك، مدير، عندما تكون جاهزة حالة مفتاح توقيع JWT في state (never أو pending أو done أو failed)، وfailure وrotatedAt؛ ولا يردّ بالمفتاح أبدًا
POST /management/v1/environments/{id}/signing-key/rotate مالك، مدير، عندما تكون جاهزة مفتاح توقيع جديد (مفتاح التوقيع). يأخذ 202، و409 إن كان تغيير سابق قيد التنفيذ
GET /management/v1/environments/{id}/mail عضو حالة البريد غير السرية للبيئة، بلا أي حقل لبيانات الاعتماد
GET /management/v1/notifications مالك أو مدير أي عميل عدد التنبيهات غير المسلّمة وأحدث أحداث المشغّل لعملاء المستدعي وحدهم. الأحداث التي لا تخص عميلًا (بدء التثبيت، إعادة تشغيل العامل) تذهب إلى مالكي ومديري العميل الذي أُنشئ عند الإعداد الأولي
GET /management/v1/organizations/{id}/audit مالك، مدير ما حدث في هذا العميل، الأحدث أولًا (حتى 100): الوقت، ومن فعله، والفعل، واسم ما جرى عليه، وتفصيل قصير. المشروع المنقول من عميل آخر لا يظهر منه إلا ما حدث بعد وصوله
GET /management/v1/environments/{id}/share عضو حصة البيئة المضمونة في البوابة، والقيمة الافتراضية، والسقف؛ ويحصل مشغّلو التثبيت أيضًا على total وallocated
PUT /management/v1/environments/{id}/share مشغّل التثبيت الجسم {"share": n}، من 1 إلى 24. يُرجع 409 إذا تجاوزت حصص كل البيئات الجاهزة 64. يُطبَّق من الطلب التالي
GET /management/v1/environments/{id}/realtime مالك، مدير، عندما تكون جاهزة حالة Realtime في state وdesired (Realtime)
PUT /management/v1/environments/{id}/realtime مالك، مدير، عندما تكون جاهزة {"enabled": true|false}. يُرجع 202، ويشغّله المشرف أو يوقفه. و409 ما دام تغيير سابق جاريًا
GET /management/v1/environments/{id}/sign-in مالك، مدير، عندما تكون جاهزة إعدادات تسجيل الدخول دون أسرار المزوّدين، وحالتها، وcallback_url الذي يُعطى لمزوّدي OAuth (تسجيل الدخول)
PUT /management/v1/environments/{id}/sign-in مالك، مدير، عندما تكون جاهزة إعدادات جديدة. يُرجع 202، ويعيد المشرف إنشاء Auth لهذه البيئة وحدها. و400 يسمّي الإعداد الذي يجب التحقق منه
GET /management/v1/environments/{id}/studio مالك، مدير، عندما تكون جاهزة حالة Studio في state، وهل ضُبط عنوان عام لـStudio في public (Studio)
POST, DELETE /management/v1/environments/{id}/studio مالك، مدير، عندما تكون جاهزة دون جسم. يشغّل Studio أو يوقفه، ويُرجع 202
POST /management/v1/environments/{id}/studio/session مالك، مدير، عندما تكون جاهزة دون جسم. يُرجع 201 {host, public, path}: عنوان Studio وتذكرة دخول تصلح مرة واحدة. و409 ما دام Studio لا يعمل
GET, POST, PUT /management/v1/environments/{id}/deployment-setup مشغّل التثبيت، عندما تكون جاهزة خطة نشر عام مُعدّة (العنوان، وسجلات DNS، وTLS، وعنوان الموقع، وعناوين إعادة التوجيه). POST يعرض معاينة، وPUT مع If-Match: <revision> يحفظ (202). هي إعداد فقط، ولا يُطبَّق منها شيء على طبقة التشغيل
GET /management/v1/server مشغّل التثبيت لقطة الخادم التي تعرضها لوحة الإدارة: أنوية المعالج، والحمل، ومدة التشغيل، والذاكرة، والتبديل (swap)، والقرص (تصميم لوحة الإدارة). لا تُخزَّن مؤقتًا
GET /management/v1/notifications/telegram مشغّل التثبيت state (off أو pending أو linked)، وآخر أربعة أحرف من الرمز، وowner؛ ولا يرى رابط الربط المعلّق إلا المالك
PUT /management/v1/notifications/telegram مالك التثبيت الجسم {"token": "..."}. يتحقق من رمز البوت لدى Telegram ويحفظه (الإعدادات)
POST /management/v1/notifications/telegram/link، /management/v1/notifications/telegram/test مالك التثبيت دون جسم. يربط المحادثة التي فتحت الرابط ذا الاستعمال الواحد، أو يرسل رسالة تجريبية
DELETE /management/v1/notifications/telegram مالك التثبيت يفصل Telegram وينسى الرمز

أجسام الطلبات لا تقبل إلا الحقول المذكورة لكل مسار، بحجم أقصاه 4 KiB، وتُقرأ خلال خمس ثوانٍ. مسارات المفاتيح والاتصال وكل طلبات DELETE ترفض أي جسم. الردود غير قابلة للتخزين المؤقت. نقل المشروع يلغي مفاتيح API، لكنه لا يدوّر مفتاح توقيع JWT لبيئاته ولا كلمة مرور الوصول المباشر إلى قاعدة البيانات؛ دوّرهما (مفتاح التوقيع) إذا كان على أشخاص العميل القديم أن يفقدوا كل وصول. وحذف البيئة لا يحرر مكانها في حد البيئات عند العامل، لأن طبقة تشغيلها تبقى. وفي التثبيت العادي يُرد على حذف أي بيئة دائمًا بـ409 ومعه "Exact ownership inventory unavailable"، ولا يتغير شيء. فالتجهيز لا يسجّل القائمة الدقيقة لموارد البيئة، ولا يمكن تسجيلها بصدق أصلًا: كل البيئات تتشارك عنقود PostgreSQL وعملية Storage، ولا شيء بعدُ يثبت أن قاعدة البيانات وملفات Storage التابعة لها لا تكتب فيها إلا بيئتها، لذلك ترفض دورة الحياة أي قائمة تذكرها. ولا يصل إلى حذف ناجح إلا الفحوص الحية لدورة الحياة، على بيئات تجريبية تُنشأ لتُزال. والاستعادة والإزالة النهائية تبدآن من بيئة محذوفة، فلا سبيل إليهما كذلك.

الوكلاء: الواجهة المتوافقة مع Supabase وMCP

برمز وصول في Authorization: Bearer sbp_...، تجيب /v1/... على الجزء الذي تستعمله الوكلاء والأدوات من واجهة الإدارة في Supabase، ويشغّل POST /mcp خادم MCP الرسمي من Supabase فوقها. ما يفعله كل مسار هنا وحدوده في وكلاء الذكاء الاصطناعي والواجهة البرمجية. ويُرفض رمز الوصول في كل مسارات /management/. المشروع ذو المعرّف {ref} بيئة واحدة، ومعرّفه 20 حرفًا لاتينيًا صغيرًا.

الطريقة المسار
GET /v1/organizations، /v1/organizations/{id}
GET, POST /v1/projects
GET /v1/projects/{ref}، /v1/projects/{ref}/health، /v1/projects/{ref}/api-keys/legacy
GET, POST /v1/projects/{ref}/api-keys
DELETE /v1/projects/{ref}/api-keys/{id}
POST /v1/projects/{ref}/database/query
GET, POST /v1/projects/{ref}/database/migrations
GET /v1/projects/{ref}/advisors/security، و/v1/projects/{ref}/advisors/performance (فارغ دائمًا)، و/v1/projects/{ref}/analytics/endpoints/logs
GET, PUT, PATCH /v1/projects/{ref}/functions
POST /v1/projects/{ref}/functions/deploy
GET, DELETE /v1/projects/{ref}/functions/{name}؛ وGET /v1/projects/{ref}/functions/{name}/body
GET, POST, DELETE /v1/projects/{ref}/secrets
GET /v1/projects/{ref}/config/storage؛ ويجيب /v1/projects/{ref}/config/database/pooler و/v1/projects/{ref}/branches بقائمة فارغة
POST /mcp

حذف مشروع أو إيقافه مؤقتًا أو استعادته وتوليد الأنواع تُرد كلها بـ501 مع ما يُفعل بدلًا منها، وأي مسار آخر تحت /v1 يُرد بـ404.

التحديثات

مسارات قناة التحديث (الترقيات)، في src/control/http.ts وsrc/control/updates.ts. لا يستدعيها إلا مشغّل التثبيت (مالك أو مدير في العميل الذي أُنشئ عند الإعداد)؛ ويتلقى غيره 403. لوحة الإدارة تقرأ وتطلب فقط: ينفّذ المشرف كل طلب بعد أن يحكم عليه من جديد، وينشر أحكامه في .lab/upgrades/current.json.

الطريقة المسار النتيجة
GET /management/v1/updates {data} وفيها current (version، commit)، وavailable (الإصدار المعروض: version، tag، commit، وclass بقيمة safe أو attended أو rebuild أو manual، وsigned، وreasons، وnotes بالحقلين en وar، وchanges) أو null، وrefusals، وskipped وnewest (الإصدارات الأحدث التي تخطّاها الفحص)، وcheckedAt، وcheckError، وsettings، وtimezone (name، offset)، وlast (آخر ترقية ومرحلتها)، وrequest (الطلب قيد التنفيذ، وإلا فآخر طلب انتهى)، وinstall (possible، reason، acknowledgement، أو null حين لا يُعرض شيء)، وcanRollback
PUT /management/v1/updates/settings الجسم {"check": bool, "automatic": bool, "window": {"start": "HH:MM", "end": "HH:MM"}} بنظام 24 ساعة وبالتوقيت المحلي للخادم. يُرجع 200 مع data المحفوظة وtimezone. ويُرجع 400 مع جملة للإعدادات غير الصالحة، وحين يكون automatic مفعّلًا دون check
POST /management/v1/updates/check بلا جسم. يُرجع 202 {state: "requested"}: يشغّل المشرف فحصًا واحدًا
POST /management/v1/updates/apply الجسم {"version": "X.Y.Z", "acknowledged"?: bool}. يُرجع 202 {state: "requested"}. و400 دون إصدار صالح. و409 مع جملة حين لم يحكم المشرف على الإصدار بعد، أو لا يُعرض شيء، أو ليس الإصدار هو المعروض، أو يقول الحكم إنه لا يمكن تثبيته الآن (مع سبب الحكم)، أو كان إصدار attended وacknowledged ليست true
POST /management/v1/updates/rollback بلا جسم. يُرجع 202 {state: "requested"}، أو 409 مع السبب حين لا يمكن التراجع عن آخر ترقية

كل مسار طلب يُرجع 409 مع "Another update request is still in progress" ما دام طلب آخر يشغل المكان. وبينما ينتظر إصدار جديد فحوص السلامة، تمر القراءة، وتسجيل الدخول إلى الإدارة، وcheck، وsettings، وrollback؛ ويُرجع كل تغيير إداري آخر 409 مع جملة تقول إن التغييرات متوقفة مؤقتًا، وتُرجع مسارات التطبيقات 503 مع Retry-After: 5. ولا يمر من الحجز إلا فحص السلامة الخاص بالمشرف، على REST وAuth فقط، برمز خاص بكل تشغيل، ولا يمر أبدًا مع ترويسات x-forwarded-* (src/gateway/hold-bypass.ts).

فحص السلامة المحلي

المسار GET /health (أو HEAD) على المستمع المحلي، للعنوانين 127.0.0.1 وlocalhost فقط، لا يحتاج رمزًا. يُرجع 200 {"status": "ok", "held": bool} حين تعمل العملية ويُقرأ فهرس التحكم ومخزن المفاتيح كلاهما، و503 {"status": "unavailable"} في غير ذلك؛ وأي طريقة أخرى تُرجع 405. تقول held هل حركة التطبيقات محجوزة لأجل تحديث. وتبدأ جولة فحوص السلامة التي يجريها المشرف بعد تحديث بهذا المسار (src/http/health.ts).

بوابة التطبيقات

{METHOD} /{runtime}/auth/v1/{path}
{METHOD} /{runtime}/rest/v1/{path}
{METHOD} /{runtime}/storage/v1/{path}

القيمة {runtime} هي معرّف التشغيل للبيئة، ويعيده المسار السابق في الحقل apiPath. وجّه supabase-js إلى <base URL>/{runtime} مع مفتاح عام.

الرمز المعنى
401 مفتاح API مفقود أو غير صالح، أو ترويسة Authorization مشوّهة، أو بيئة محذوفة
404 بيئة أو مسار مجهول، أو خدمة غير مُعدّة
408 ألغى العميل الطلب
413 الجسم أكبر من 1 MiB، أو الملف المرفوع أكبر من حد الرفع
429 بلغت هذه البيئة حصتها ولا تستطيع الاستعارة الآن، أو بلغت سقفها؛ أعد المحاولة لاحقًا
503 البيئة في الصيانة، أو بلغ الخادم حده الكلي للطلبات، أو التوجيه غير متاح. يُرسل retry-after: 1 حين تفيد إعادة المحاولة
504 تجاوزت الخدمة الأصلية مهلتها

حدود القبول تخص كل عملية بوابة وحدها، ولا طابور لها.

Realtime

عندما يكون Realtime مشغّلًا لبيئة (Realtime):

المسار المعنى
GET /{runtime}/realtime/v1/websocket?apikey=<publishable key>&vsn=1.0.0 مع Upgrade: websocket اتصال Realtime الذي يفتحه supabase-js. يُفحص المفتاح أولًا، ثم يستلم Realtime الرمز المجهول الخاص بالبيئة بدلًا منه، أو رمز service_role لمفتاح سري أُرسل من خادم
POST /{runtime}/realtime/v1/api/broadcast البث من خادم، مع الترويسة apikey

إذا كان Realtime مطفأً يأخذ الاتصال الرد 404. المفتاح الخاطئ أو الملغى يأخذ 401. وكل مسار آخر في Realtime يأخذ 404.

Edge Functions

عندما تكون لبيئة دوال منشورة (Edge Functions):

المسار المعنى
ANY /{runtime}/functions/v1/{name}[/...] يشغّل الدالة. مع apikey يُفحص المفتاح كما في كل خدمة؛ ودونه لا تعمل إلا دالة منشورة مع إطفاء verify_jwt، وتصلها ترويسات المستدعي كما هي

الاسم حروف وأرقام و- و_، حتى 64، ويبدأ بحرف أو رقم؛ وأي اسم آخر، أو دالة مجهولة، أو Edge Functions مطفأة، يأخذ 404. الدالة التي تفحص JWT تردّ بـ 401 على رمز مفقود أو غير صالح. المهلة 150 ثانية، وتمر الأجسام كما تصل حتى حد الرفع.

عدّل على GitHub