حِزم SDK
SDK جافاسكريبت
في هذه الصفحة
نظرة عامة
npm install @nanoflags/sdk| الاستيراد | الاستخدام |
|---|---|
@nanoflags/sdk | Node والمتصفحات وبيئات تشغيل الحافة: createClient والأنواع. |
@nanoflags/sdk/react | روابط React (بالإنجليزية): NanoFlagsProvider وuseFlag وuseFlagsStatus. |
@nanoflags/sdk/node | نقل جلسات الاختبار (بالإنجليزية) عبر AsyncLocalStorage. |
بصيغتي ESM وCommonJS مع أنواع TypeScript، ومن دون أي اعتماديات وقت التشغيل (محرك التقييم في NanoFlags مضمّن في الحزمة). وReact اعتمادية نظيرة اختيارية (الإصدار 18 أو أحدث).
خيارات createClient
import { createClient } from "@nanoflags/sdk";
const flags = createClient({
sdkKey: process.env.NANOFLAGS_SDK_KEY!,
baseUrl: "https://edge.nanoflags.io",
service: "checkout-api",
pollIntervalMs: 30_000,
streaming: true,
live: true,
events: { sampleRate: 0.1 },
});| الخيار | الافتراضي | الوصف |
|---|---|---|
sdkKey | إلزامي | nf_srv_… على الخوادم، وnf_pub_… في المتصفحات. لا تضع مفتاح خادم في متصفح أبدًا. |
baseUrl | إلزامي | عنوان الحافة، https://edge.nanoflags.io. |
service | "unknown" | الاسم الذي تُبلغ به هذه العملية («أي نسخة تشغّل هذه الخدمة»). |
pollIntervalMs | 30000 | فترة الاستطلاع المشروط (± 20 % تذبذب). القيمة 0 تعطّل الاستطلاع، بما فيه استطلاع الأمان. |
streaming | true | استلام التحديثات دون انتظار استطلاع (اتصال حي، وإلا SSE). false = استطلاع فقط. |
live | true | false يتخطى WebSocket ويستخدم SSE مع الاستطلاع. |
livePollIntervalMs | 300000 | فترة استطلاع الأمان أثناء سلامة الاتصال الحي. |
webSocket | WebSocket العام | منشئ WebSocket، مثل require("ws") على Node الأقدم من 22. ومن دونه يستخدم الـ SDK SSE مع الاستطلاع. |
bootstrap | لا شيء | حزمة حُصل عليها من مكان آخر (مضمّنة وقت البناء، أو ممرَّرة من خادمك للعرض على الخادم). تُعامل كما هي دون تحقق. |
store | IndexedDB في المتصفحات، ولا شيء في غيرها | أي مخزن نصي غير متزامن { get(), set(v) }؛ وfalse يعطّل التخزين. |
events | {} | enabled (true)، sampleRate (0.1)، flushIntervalMs (10000)، reportIntervalMs (60000)، redact(ctx). وfalse يعطّل القياس. انظر القياس. |
verify | مفعّل لـ https://edge.nanoflags.io (منذ 0.4.0)، ومعطّل في غيره | { publicKeys: JsonWebKey[] | "fetch", require?: boolean }، أو false لتعطيل التحقق. انظر التحقق من التوقيع. |
fetch | fetch العام | تنفيذ fetch مخصّص. |
الدوال والخصائص
| العضو | الوصف |
|---|---|
ready(): Promise<void> | يُحَلّ عند تحميل حزمة صالحة (من الشبكة أو المخزن أو التهيئة المسبقة)، أو عند انتهاء محاولة التحميل الأولى دون حزمة. لا يُرفض أبدًا: افحص status. |
boolean · string · number · json (key, fallback, ctx?) | قيمة العلم، أو قيمة الاحتياط. متزامنة. |
evaluate(key, fallback, ctx?) | النتيجة كاملة: value وreason وruleIndex وruleId وinRollout وbucket وrevision وtrace. دون فحص للنوع. |
status | "not-ready" · "ready" · "stale"، انظر الحالة. |
revision | نسخة الحزمة المستخدمة؛ وnull من دونها. |
transport | كيف تصل التحديثات إلى العميل الآن: "live" (WebSocket مفتوح)، "stream" (SSE)، "poll". |
on("update" | "error", cb) | اشتراك؛ يعيد دالة لإلغاء الاشتراك. |
session(token, { service? }) | مقيّم لجلسة اختبار. لا يُرفض أبدًا. |
useSession(token | null) · sessionHeaders() | في المتصفح فقط: الانضمام إلى جلسة اختبار أو مغادرتها لهذه العلامة؛ وترويسات للطلبات اللاحقة. |
refresh() | إعادة التحقق الآن. يُحَلّ عند الانتهاء، نجح أو لم ينجح. |
flush() | إرسال القياس المنتظر الآن. |
close() | إيقاف المؤقتات والاتصال الحي والقياس. ويواصل التقييم العمل على آخر حزمة. |
السياق كائن بسيط من قيم JSON. وkey هو الهوية الثابتة المستخدمة في توزيع الطرح التدريجي.
الحالة
تصف status الحزمة لا الأعلام منفردة:
not-ready: لا توجد حزمة. كل دالة قراءة تعيد قيمة الاحتياط.ready: أكّدت الحافة الحزمة في آخر محاولة (أو قُدّمت كـbootstrapولم تفشل أي محاولة بعد).stale: حزمة قيد الاستخدام لكن لا يُعرف أنها الحالية: استُعيدت من المخزن ولم يُعَد التحقق منها بعد، أو فشلت آخر إعادة تحقق (دون اتصال، أو خطأ في الحافة، أو مفتاح مرفوض)، أو قدّمت الحافة آخر نسخة سليمة لديها. ويستمر التقييم على تلك الحزمة بينما يعيد الـ SDK المحاولة (بعد الفشل: 1 ث، 2 ث، 4 ث … حتى فترة الاستطلاع).
لا يتخلى الـ SDK أبدًا عن حزمة صالحة بسبب خطأ، ولا يستبدل حزمة بأقدم منها. وإن أُلغي المفتاح، يطلق العميل error (unauthorized) ويواصل تقييم آخر حزمة بحالة stale: الإلغاء يوقف التحديثات ولا يمحو الإعداد الذي وصل فعلًا إلى العملية.
الأحداث
update
flags.on("update", (e) => {
e.revision; // new revision
e.previousRevision; // number | null
e.checksum; // string | null
e.source; // "network" | "store" | "bootstrap"
e.transport; // "live" (pushed) | "stream" (fetched after an SSE notification) | "poll" (everything else)
e.latencyMs; // commit → this event, only for pushed revisions with a commit time; otherwise null
});يقارن latencyMs ساعة قاعدة البيانات بالساعة المحلية، فدقّته بقدر اتفاق الساعتين. وقياسات الانتشار الحالية في صفحة الحالة.
error
يستلم NanoFlagsError له code (وhttpStatus عند الحاجة). والأخطاء لا تقطع التقييم أبدًا.
| code | المعنى |
|---|---|
network | تعذّر الوصول إلى الحافة. |
unauthorized | رُفض المفتاح (مجهول أو ملغى، HTTP 401/403). |
http | حالة HTTP أخرى غير متوقعة. |
invalid_bundle | الإجابة لم تكن حزمة صالحة. |
store | فشلت القراءة من مخزن التخزين أو الكتابة إليه. |
config | خيارات غير صالحة، مثل تمرير JWK خاص إلى verify. |
signature | فشل التحقق من توقيع حزمة فلم تُستخدم. |
session | فشل البحث عن جلسة اختبار. |
engine | الحزمة تحتاج محرك تقييم أحدث مما في هذا الـ SDK. لم تُستخدم؛ حدّث الـ SDK. |
environment_deleted | حُذفت بيئة هذا المفتاح. انظر البيئات المحذوفة. |
قيم الاحتياط
تُعاد قيمة fallback عندما لا تستطيع NanoFlags الإجابة:
| الحالة | reason |
|---|---|
لم تُحمَّل حزمة بعد (not-ready) | flag_not_found |
| العلم ليس في الحزمة (مجهول، أو مؤرشف، أو غير مكشوف للعميل مع مفتاح عميل) | flag_not_found |
نوع قيمة العلم يختلف عن دالة القراءة (boolean() على علم نصي) | error |
| الإعداد مشوّه | error |
العلم المعطّل ليس حالة احتياط: فهو يعيد قيمة off المضبوطة له (السبب off).
وسائل النقل
- الدفع الحي (الافتراضي): اتصال WebSocket واحد إلى
GET /v1/live. عند نشر نسخة ترسل الحافة رسالةrevتحمل الحزمة الموقّعة نفسها، فتُطبَّق دون طلب آخر؛ وعند الاتصال (أو إعادة الاتصال) تحمل رسالةhelloالنسخة الحالية. ينتقل المفتاح في قائمة البروتوكولات الفرعية لـ WebSocket، لا في العنوان أبدًا. يرسل الـ SDK إشارة ping نحو كل 30 ثانية، ويستبدل الاتصال نحو كل 50 دقيقة (فيُتحقَّق من المفتاح مجددًا)، ويعيد الاتصال بتراجع أسّي مع تذبذب (1 ث، 2 ث، 4 ث … حتى 5 دقائق كحد أقصى، كلٌّ × 0.5–1.5). وأثناء سلامة الاتصال لا يُفتح SSE، وينخفض الاستطلاع إلىlivePollIntervalMs. - المجرى (احتياطي): عندما يتعذّر إنشاء الاتصال (لا
WebSocketفي بيئة التشغيل، أو وسيط يحجب الترقية، أو تجيب الحافة بـ503 live_unavailable)، يفتح الـ SDK مجرى أحداث من الخادم لا يحمل إلا{ revision, checksum }ويجلب الحزمة بشكل مشروط. تستخدم مفاتيح العميلEventSourceمع?key=؛ ويستخدم غيرها مجرى fetch مع ترويسةAuthorization. ويواصل الـ SDK محاولة الاتصال الحي ويغلق المجرى حالما يُفتح اتصال. - الاستطلاع (شبكة أمان):
GET /v1/bundleمشروط كلpollIntervalMs± 20 %. وعلامات التبويب المخفية في المتصفح لا تستطلع، وتلحق بالتحديثات حين تظهر.
live: false يُبقي المجرى والاستطلاع؛ وstreaming: false لا يُبقي إلا الاستطلاع. وتحلّ الحزمة الجديدة محل القديمة في عملية إسناد واحدة، فيرى التقييم نسخة واحدة كاملة لا خليطًا أبدًا. ولا ينتقل الـ SDK أبدًا إلى نسخة أقدم من نسخة دُفعت إليه.
التحقق من التوقيع
يفحص الـ SDK توقيع Ed25519 قبل أن تحلّ حزمة جديدة محل المستخدمة، للحزم المجلوبة والمدفوعة على حد سواء.
- الافتراضي منذ 0.4.0: عندما يكون
baseUrlهوhttps://edge.nanoflags.io، يتحقق الـ SDK من كل حزمة مقابل مفاتيح توقيع NanoFlags المضمّنة فيه (ويحمّلGET /v1/keysمرة واحدة عندما تذكر حزمة معرّف مفتاح لا يعرفه) ويرفض الحزم غير الموقّعة. ومع أيbaseUrlآخر لا يُتحقق من شيء ما لم تضبطverify. - تعيد
GET /v1/keysقائمة مفاتيح عامة بأسلوب JWKS، لكل منهاkidوstatus: active(يوقّع الحزم الجديدة) أوretiring(ما زال صالحًا للحزم الموقّعة قبل التدوير). انظر التواقيع. - يحتاج التحقق إلى Ed25519 في WebCrypto: Node.js 20+، والمتصفحات الحالية، وCloudflare Workers، وDeno، وBun. وعلى بيئة تشغيل لا تدعمه اضبط
verify: false؛ وإلا تُرفض الحزم الموقّعة لتعذّر فحصها.
لتثبيت نسختك الخاصة من المفاتيح (مثلًا للتحقق من حزم مجلوبة عبر وسيطك أو مخزنك المؤقت):
const flags = createClient({
sdkKey, baseUrl,
verify: {
publicKeys: [{ kty: "OKP", crv: "Ed25519", x: "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U", kid: "k1" }],
require: true,
},
});- توقيع خاطئ: يُرفض التحديث، وتبقى الحزمة السابقة قيد الاستخدام، ولا تتغير
status، ويُطلقerrorبالرمزsignature. والحزمة المدفوعة التي لا تجتاز التحقق تجعل الـ SDK يسأل الحافة عبر HTTP عمّا هو حالي. - الحزم غير الموقّعة (
X-NanoFlags-Signed: false، تُقدَّم لفترة وجيزة ريثما يلحق التوقيع بعد النشر) تُرفض بالإعدادات الافتراضية على حافة NanoFlags؛ ويعيد الـ SDK الجلب بعد قليل. ومعverifyمخصّص تُقبل ما لم يُضبطrequire: true. ومن دونrequireيستطيع من يعدّل الإجابات أن يزيل التوقيع أيضًا. publicKeys: "fetch"يحمّل المفاتيح مرة واحدة منGET /v1/keys(ويعيد تحميلها مرة في الدقيقة على الأكثر عندما تذكر حزمة معرّف مفتاح مجهولًا). وهذا يكشف التلف والعبث في التخزين والمخازن المؤقتة، لكن المفاتيح موثوقة بقدر الحافة التي قدّمتها فقط. ثبّت المفاتيح في البناء إن كانت الحافة ضمن نموذج التهديد لديك.- بعد أول حزمة مُتحقَّق منها يتذكر العميل معرّف البيئة ويرفض الحزم الموقّعة لبيئة أخرى.
- لا تُقبل إلا المفاتيح العامة؛ وJWK الذي يحوي جزءًا خاصًا (
d) يُتجاهل ويُبلَّغ كخطأconfig. - غير مشمول: حزم جلسات الاختبار غير موقّعة، والتوقيع لا يقول شيئًا عن الحداثة؛ فهو لا يمنع أحدًا من حجب التحديثات.
إصدار المحرك
كل حزمة تذكر إصدار محرك التقييم الذي كُتبت له (engine). ويرفض الـ SDK حزمة من محرك أحدث مما يدعمه: فيُبقي إعداده السابق، ولا يغيّر status بسببها، ويطلق error بالرمز engine. حدّث الـ SDK لتستلم ذلك الإعداد.
البيئات المحذوفة
عند حذف بيئة أو مشروعها، تغلق الحافة الاتصالات الحيّة برمز إغلاق WebSocket 4004 وتتوقف عن قبول مفاتيح البيئة خلال نحو دقيقة. عندها يتوقف الـ SDK عن إعادة الاتصال، ويواصل تقييم آخر إعداد لديه بحالة stale، ويطلق error بالرمز environment_deleted. أزل المفتاح من تطبيقك أو استبدله.
التخزين والتهيئة المسبقة
- المتصفح: IndexedDB عند توفره (الأوضاع الخاصة والتخزين المحجوب تتصرف كمخزن فارغ). Node وبيئات تشغيل الحافة: لا تخزين افتراضيًا، وهذا آمن لأنظمة الملفات للقراءة فقط والمؤقتة.
storeيقبل أي مخزن نصي غير متزامن؛ وfalseيعطّله.- القيمة المخزّنة تحتوي على الحزمة (قواعد الأعلام)، لا على مفتاح الـ SDK أبدًا. وهي مربوطة بالمفتاح و
baseUrl، فتُتجاهل نسخة كُتبت لبيئة أخرى. وتبدأ الحزمة المستعادة بحالةstaleحتى يُعاد التحقق منها. - مع
verifyتُحفظ الحزمة المخزّنة مع توقيعها ويُتحقق منها مجددًا عند الاستعادة؛ ومعrequireتُتجاهل النسخة المخزّنة غير الموقّعة. ومعpublicKeys: "fetch"لا يستطيع البدء دون اتصال التحقق (المفاتيح لم تُحمَّل)، فلا تُستعاد النسخة المخزّنة؛ والمفاتيح المثبّتة لا تعاني هذا القيد. bootstrapيُعامل كما هو. وللعرض على الخادم مرّر الحزمة التي قيّمت بها على الخادم ليتطابق أول عرض لدى العميل.
import { readFile, writeFile } from "node:fs/promises";
const flags = createClient({
sdkKey, baseUrl,
store: {
get: () => readFile("/var/cache/nanoflags.json", "utf8").catch(() => null),
set: (v) => writeFile("/var/cache/nanoflags.json", v),
},
});القياس
كل flushIntervalMs (10 ث) أثناء وجود تقييمات منتظرة، يرسل الـ SDK طلب POST /v1/events واحدًا؛ وحين لا يوجد شيء منتظر يرسل بلاغ الخدمة وحده كل reportIntervalMs (60 ث). يحمل الطلب بلاغ خدمة ({ service, sdk: "js/<version>", revision }) وحتى 50 حدث تقييم مأخوذًا كعيّنة (sampleRate، افتراضيًا 10 %): مفتاح العلم، والقيمة، والسبب، ورقم القاعدة، والنسخة، والوقت، وسياقًا مُخفًى.
{ "region": "string", "signedIn": "boolean", "key": "string" }. وتُسقط الخصائص التي لا تستخدمها أي قاعدة.events.redact(ctx)يحلّ محل الافتراضي؛ وما يعيده يُرسل كما هو.- قيم الأعلام تُرسل (النصوص فوق 1 KB تُقتطع، وقيم JSON الأكبر تُستبدل بـ
null). فلا تضع أسرارًا في قيم الأعلام. - القياس خارج مسار التقييم: تذهب الأحداث إلى طابور محدود في الذاكرة (500 مدخل، ثم تُسقط). والدفعات الفاشلة تُسقط ولا يُعاد إرسالها. و
events: falseيعطّل كل شيء، بما في ذلك بلاغات الخدمات.
ما الذي تثبته الإشارة المُبلَّغ عنها، وما لا تثبته
- بلاغ الخدمة يثبت أن عملية تستخدم مفتاح الـ SDK هذا، وتسمّي نفسها
service، كانت قد حمّلت النسخة N لحظة الإبلاغ. ولا يثبت أن كل النسخ العاملة على تلك النسخة، ولا أن الخدمة سليمة، ولا أنها ما زالت تعمل: إنه «آخر ظهور». وغياب البلاغ لا يثبت شيئًا: قد يكون القياس معطّلًا أو محجوبًا أو مستبعدًا من العيّنة أو مفقودًا. serviceتُعلنه العملية عن نفسها ولا يصادق عليه إلا مفتاح الـ SDK. ومع مفتاح العميل يستطيع أي أحد إرسال البلاغات والأحداث. تعامل معها كأداة رصد، لا كسجل تدقيق.- الحدث المأخوذ كعيّنة يثبت أن تقييمًا بتلك النتيجة حدث في عملية ما. ولا يثبت أن المستخدم رأى الميزة، وغياب الأحداث لا يثبت أن العلم غير مستخدم: مع عيّنة 10 % قد تبقى الأعلام النادرة التقييم غير مرئية مدة طويلة.
- الأعداد تقديرات: العيّنة لكل تقييم، والأحداث تُسقط تحت الضغط أو عند فشل الشبكة أو عند بلوغ الحد اليومي، وقد تقيّم مكونات React مرة لكل تغيير ذي صلة لا لكل إجراء من المستخدم.