النظام والسلامة

التحقق من العمل والجاهزية، والمقاييس، ومستند OpenAPI، وإمكانات الخادم.

عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).

العمليات

فحص الجاهزية التفصيلي

GET HEAD /health/ready

الوصول: أي مفتاح أو جلسة صالحة · إعادة المحاولة: آمن للتكرار (قراءة)

يردّ بالقيمة ready عندما تستجيب قاعدة البيانات والتخزين، ومعها role لهذه العقدة (api أو reader)، وما إذا كانت تقبل الكتابة الآن (تكون قيمة writable هي false على بوابة القراءة وما دام القرص يحتفظ باحتياطي المساحة الحرة)، وخانة التنزيل المشتركة لبوابة القراءة، وعدّادات إجمالية لقبول الرفع والتنزيل وعرض النطاق الترددي. وأثناء إفراغ الخادم لطلباته الجارية (draining) أو عند عدم توفّر إحدى التبعيات يردّ بالرمز 503 مع Retry-After. ولا يُحتسب هذا الطلب ضمن ميزانية الطلبات؛ ولموازن الأحمال الذي لا يملك مفتاحًا استخدم getReadinessStatus.

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
role	string	نعم	إحدى القيم: api, reader
sharedDownloads	object	نعم	يمكن أن يكون null
sharedDownloads.slot	integer	نعم	0 على الأقل
sharedDownloads.slots	integer	نعم	0 على الأقل
sharedDownloads.active	boolean	نعم	—
sharedDownloads.leaseSeconds	integer	نعم	0 على الأقل
status	string	نعم	إحدى القيم: ready
writable	boolean	نعم	—
replication	object	لا	يمكن أن يكون null
replication.copies	integer	نعم	0–16
replication.required	integer	نعم	1–16
replication.singleCopyUntil	string (date-time)	نعم	يمكن أن يكون null
replication.node	string	لا	عدد الأحرف: 63 كحد أقصى
replication.profile	string	لا	إحدى القيم: ha-2, ha-3
replication.peers	مصفوفة من object	لا	عدد العناصر: 16 كحد أقصى
replication.peers[].name	string	نعم	عدد الأحرف: 63 كحد أقصى
replication.peers[].connected	boolean	نعم	—
replication.peers[].disk	string	نعم	عدد الأحرف: 24 كحد أقصى
replication.peers[].complete	boolean	نعم	—
replication.peers[].witness	boolean	نعم	—
transfers	object	نعم	—
transfers.uploads	object	نعم	—
transfers.uploads.admission	object	نعم	—
transfers.uploads.bandwidth	object	نعم	—
transfers.uploads.sessions	object	لا	—
transfers.downloads	object	نعم	—
transfers.downloads.admission	object	نعم	—
transfers.downloads.bandwidth	object	نعم	—
transfers.downloads.sessions	object	لا	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

curl -X GET "$ARKVORY_URL/health/ready" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

الحصول على إمكانات الخادم وحدوده

GET HEAD /api/v1/capabilities

الوصول: أي مفتاح أو جلسة صالحة · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد إصدارات واجهة API، ودور البوابة، وأعلام الميزات (مثل selfRegistration أو mirrorFeed)، والحدود التي يتكيّف معها العميل: أكبر كائن (maxObjectBytes، سلسلة نصية عشرية)، وأصغر جزء وأكبر جزء في الرفع متعدد الأجزاء، وأكبر عدد من الأجزاء، وأكبر حجم للصفحة. اقرأه مرة واحدة عند بدء تشغيل العميل؛ فهو لا يسرد أي موارد.

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
apiVersions	مصفوفة من string	نعم	—
gatewayRole	string	نعم	إحدى القيم: api, reader
features	قاموس من boolean	نعم	—
limits	object	نعم	—
limits.maxObjectBytes	string	لا	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
limits.partBytes	integer	لا	أصغر جزء في الرفع متعدد الأجزاء.
limits.maxPartBytes	integer	لا	—
limits.maxParts	integer	لا	—
limits.maxPageSize	integer	لا	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

curl -X GET "$ARKVORY_URL/api/v1/capabilities" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

فحص الجاهزية لموازن الأحمال

GET HEAD /health/status

الوصول: أي شخص، دون مفتاح · إعادة المحاولة: آمن للتكرار (قراءة)

لا يحتاج إلى مفتاح ولا يعيد أي تفاصيل: إما 200 مع {"status":"ready"}، وإما 503 مع القيمة unavailable أو draining ومع Retry-After. يُشارَك فحص التبعيات ويُخزَّن مؤقتًا لمدة ثانية واحدة، لذا لا تُثقِل الفحوص المتكررة قاعدة البيانات، ولا يُحتسب الفحص ضمن ميزانية الطلبات.

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
status	string	نعم	إحدى القيم: ready, unavailable, draining

الاستجابات: 200, 400, 403, 503

مثال

curl -X GET "$ARKVORY_URL/health/status"

التحقق من أن العملية حيّة

GET HEAD /health/live

الوصول: أي شخص، دون مفتاح · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد 200 مع {"status":"ok"} ما دامت العملية تردّ على HTTP. ولا يفحص أي تبعية، لذا استخدمه لاتخاذ قرار إعادة التشغيل، واستخدم getReadinessStatus لاتخاذ قرار توجيه الحركة.

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
status	string	نعم	إحدى القيم: ok

الاستجابات: 200, 400, 403, 503

مثال

curl -X GET "$ARKVORY_URL/health/live"

الحصول على وثيقة OpenAPI

GET HEAD /api/v1/openapi.json

الوصول: أي مفتاح أو جلسة صالحة · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد وثيقة OpenAPI 3.0 الخاصة بهذا النشر، مع امتدادات x-arkvory-* التي تصف قواعد الوصول وإعادة المحاولة والبوابة لكل عملية. تعيد القيمة surface (discovery أو identity أو catalog أو transfers أو administration أو operations) ذلك المجال وحده؛ أما معامل استعلام غير معروف أو مكرر فينتج عنه الخطأ 400. الوثيقة واحدة لكل المستدعين ولا تمنح أي صلاحية: لمعرفة ما يجوز لبيانات الاعتماد هذه استدعاؤه استخدم listVisibleOperations.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
surface	الاستعلام	string	لا	إحدى القيم: discovery, identity, catalog, transfers, administration, operations; Documentation view only; not filtered by caller permissions.

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
openapi	string	نعم	إحدى القيم: 3.0.3
info	object	نعم	—
paths	object	نعم	—

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

curl -X GET "$ARKVORY_URL/api/v1/openapi.json" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

الحصول على مقاييس Prometheus

GET HEAD /health/metrics

الوصول: أي مفتاح أو جلسة صالحة · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد مقاييس العملية بتنسيق Prometheus النصي (text/plain; version=0.0.4) لأداة الجمع (scraper). تخص العدّادات والمدرّجات التكرارية (histograms) هذه العملية وتبدأ من الصفر بعد إعادة التشغيل (انظر arkvory_process_start_time_seconds)؛ وتقتصر التسميات على قالب المسار والطريقة وفئة الحالة واتجاه النقل، ولا تذكر أبدًا اسم مُخرَج أو مفتاح أو حساب. ولا يُحتسب الجمع ضمن ميزانية الطلبات.

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

curl -X GET "$ARKVORY_URL/health/metrics" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -o file

عرض قائمة العمليات التي يجوز لبيانات الاعتماد استدعاؤها

GET HEAD /api/v1/operations

الوصول: أي مفتاح أو جلسة صالحة · إعادة المحاولة: آمن للتكرار (قراءة)

يسرد عمليات هذه البوابة التي يجوز لبيانات الاعتماد استدعاؤها، مرتبةً حسب operationId، مع مجال كل عملية (surface) وقاعدة إعادة المحاولة والإجراءات المطلوبة وconditions التي لا تُفحص إلا وقت الاستدعاء (مثل resource-state أو upload-owner). تضيف repository عمليات ذلك المستودع (مستودع غير معروف أو غير متاح للمستدعي يعني 404)، وتحصر surface القائمة في مجال واحد؛ وتحتوي الصفحة على limit عنصرًا (من 1 إلى 100، والافتراضي 50)، وللمتابعة اضبط after على قيمة next. الإجابة استشارية: ابنِ منها القوائم، لكن كل طلب فعلي يُفوَّض من جديد، ولا تسرد بوابة القراءة أي طرق تغيّر الحالة.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
repository	الاستعلام	string	لا	يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$
surface	الاستعلام	string	لا	إحدى القيم: discovery, identity, catalog, transfers, administration, operations
after	الاستعلام	string	لا	يطابق النمط ^[A-Za-z][A-Za-z0-9]{0,95}$
limit	الاستعلام	integer	لا	1–100; القيمة الافتراضية 50

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
apiVersion	string	نعم	إحدى القيم: v1
documentVersion	string	نعم	يطابق النمط ^\d+\.\d+\.\d+$
gatewayRole	string	نعم	إحدى القيم: api, reader
repository	string	نعم	يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$; يمكن أن يكون null
advisory	boolean	نعم	إحدى القيم: true
items	مصفوفة من object	نعم	عدد العناصر: 100 كحد أقصى
items[].operationId	string	نعم	يطابق النمط ^[A-Za-z][A-Za-z0-9]{0,95}$
items[].method	string	نعم	إحدى القيم: get, head, post, put, patch, delete
items[].path	string	نعم	يطابق النمط ^/; عدد الأحرف: 512 كحد أقصى
items[].summary	string	نعم	عدد الأحرف: 1024 كحد أقصى
items[].surface	string	نعم	إحدى القيم: discovery, identity, catalog, transfers, administration, operations
items[].visibility	string	نعم	إحدى القيم: public, authenticated, self, repository, owned-resource, delegated, bootstrap, administrator
items[].retry	string	نعم	إحدى القيم: read, never-automatic, idempotent, idempotency-key, compare-and-swap, reconcile-upload, reconcile-job
items[].requiredActions	مصفوفة من string	نعم	عدد العناصر: 33 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: repository.read, storage.read, storage.manage, diagnostics.read, artifact.read, artifact.list, artifact.delete, artifact.promote, content.read, upload.create, upload.read, upload.write, upload.complete, upload.cancel, job.read, package.read, package.publish, asset.read, asset.write, asset.restore, annotation.read, annotation.write, reference.write, audit.read, service-account.read, service-account.manage, policy.read, policy.manage, credential.read, credential.manage, service-audit.read, backup.read, backup.manage
items[].conditions	مصفوفة من string	نعم	عدد العناصر: 6 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: إحدى القيم: resource-state, upload-owner, job-owner, reference-owner, delegation-target-and-ceiling, own-key
next	string	نعم	يطابق النمط ^[A-Za-z][A-Za-z0-9]{0,95}$; يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

curl -X GET "$ARKVORY_URL/api/v1/operations" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"