انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

حِزم SDK

SDK جافاسكريبت

تُقيَّم الأعلام محليًا وبشكل متزامن على حزمة إعداد في الذاكرة. ولا تُستخدم الشبكة إلا في الخلفية: لتحميل الحزمة، ولمعرفة النسخ الجديدة، ولإرسال قياس مأخوذ كعيّنات. ودالة القراءة لا تُجري أي عملية إدخال/إخراج ولا ترمي استثناءً أبدًا.

نظرة عامة

sh
npm install @nanoflags/sdk
الاستيرادالاستخدام
@nanoflags/sdkNode والمتصفحات وبيئات تشغيل الحافة: createClient والأنواع.
@nanoflags/sdk/reactروابط React (بالإنجليزية): NanoFlagsProvider وuseFlag وuseFlagsStatus.
@nanoflags/sdk/nodeنقل جلسات الاختبار (بالإنجليزية) عبر AsyncLocalStorage.

بصيغتي ESM وCommonJS مع أنواع TypeScript، ومن دون أي اعتماديات وقت التشغيل (محرك التقييم في NanoFlags مضمّن في الحزمة). وReact اعتمادية نظيرة اختيارية (الإصدار 18 أو أحدث).

خيارات createClient

ts
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"الاسم الذي تُبلغ به هذه العملية («أي نسخة تشغّل هذه الخدمة»).
pollIntervalMs30000فترة الاستطلاع المشروط (± 20 % تذبذب). القيمة 0 تعطّل الاستطلاع، بما فيه استطلاع الأمان.
streamingtrueاستلام التحديثات دون انتظار استطلاع (اتصال حي، وإلا SSE). false = استطلاع فقط.
livetruefalse يتخطى WebSocket ويستخدم SSE مع الاستطلاع.
livePollIntervalMs300000فترة استطلاع الأمان أثناء سلامة الاتصال الحي.
webSocketWebSocket العاممنشئ WebSocket، مثل require("ws") على Node الأقدم من 22. ومن دونه يستخدم الـ SDK ‏SSE مع الاستطلاع.
bootstrapلا شيءحزمة حُصل عليها من مكان آخر (مضمّنة وقت البناء، أو ممرَّرة من خادمك للعرض على الخادم). تُعامل كما هي دون تحقق.
storeIndexedDB في المتصفحات، ولا شيء في غيرهاأي مخزن نصي غير متزامن { 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 لتعطيل التحقق. انظر التحقق من التوقيع.
fetchfetch العامتنفيذ 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

ts
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).

وسائل النقل

  1. الدفع الحي (الافتراضي): اتصال WebSocket واحد إلى GET /v1/live. عند نشر نسخة ترسل الحافة رسالة rev تحمل الحزمة الموقّعة نفسها، فتُطبَّق دون طلب آخر؛ وعند الاتصال (أو إعادة الاتصال) تحمل رسالة hello النسخة الحالية. ينتقل المفتاح في قائمة البروتوكولات الفرعية لـ WebSocket، لا في العنوان أبدًا. يرسل الـ SDK إشارة ping نحو كل 30 ثانية، ويستبدل الاتصال نحو كل 50 دقيقة (فيُتحقَّق من المفتاح مجددًا)، ويعيد الاتصال بتراجع أسّي مع تذبذب (1 ث، 2 ث، 4 ث … حتى 5 دقائق كحد أقصى، كلٌّ × 0.5–1.5). وأثناء سلامة الاتصال لا يُفتح SSE، وينخفض الاستطلاع إلى livePollIntervalMs.
  2. المجرى (احتياطي): عندما يتعذّر إنشاء الاتصال (لا WebSocket في بيئة التشغيل، أو وسيط يحجب الترقية، أو تجيب الحافة بـ 503 live_unavailable)، يفتح الـ SDK مجرى أحداث من الخادم لا يحمل إلا { revision, checksum } ويجلب الحزمة بشكل مشروط. تستخدم مفاتيح العميل EventSource مع ?key=؛ ويستخدم غيرها مجرى fetch مع ترويسة Authorization. ويواصل الـ SDK محاولة الاتصال الحي ويغلق المجرى حالما يُفتح اتصال.
  3. الاستطلاع (شبكة أمان): ‏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؛ وإلا تُرفض الحزم الموقّعة لتعذّر فحصها.

لتثبيت نسختك الخاصة من المفاتيح (مثلًا للتحقق من حزم مجلوبة عبر وسيطك أو مخزنك المؤقت):

ts
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 يُعامل كما هو. وللعرض على الخادم مرّر الحزمة التي قيّمت بها على الخادم ليتطابق أول عرض لدى العميل.
custom store (Node)
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 %): مفتاح العلم، والقيمة، والسبب، ورقم القاعدة، والنسخة، والوقت، وسياقًا مُخفًى.

الإخفاء الافتراضي لا يرسل قيم الخصائص
لكل حدث مأخوذ كعيّنة لا يرسل الـ SDK إلا أسماء خصائص السياق التي تشير إليها قواعد العلم المقيَّم وكانت موجودة، كلٌّ مقرونًا بنوع قيمته، مثل { "region": "string", "signedIn": "boolean", "key": "string" }. وتُسقط الخصائص التي لا تستخدمها أي قاعدة.
  • events.redact(ctx) يحلّ محل الافتراضي؛ وما يعيده يُرسل كما هو.
  • قيم الأعلام تُرسل (النصوص فوق 1 KB تُقتطع، وقيم JSON الأكبر تُستبدل بـ null). فلا تضع أسرارًا في قيم الأعلام.
  • القياس خارج مسار التقييم: تذهب الأحداث إلى طابور محدود في الذاكرة (500 مدخل، ثم تُسقط). والدفعات الفاشلة تُسقط ولا يُعاد إرسالها. وevents: false يعطّل كل شيء، بما في ذلك بلاغات الخدمات.

ما الذي تثبته الإشارة المُبلَّغ عنها، وما لا تثبته

  • بلاغ الخدمة يثبت أن عملية تستخدم مفتاح الـ SDK هذا، وتسمّي نفسها service، كانت قد حمّلت النسخة N لحظة الإبلاغ. ولا يثبت أن كل النسخ العاملة على تلك النسخة، ولا أن الخدمة سليمة، ولا أنها ما زالت تعمل: إنه «آخر ظهور». وغياب البلاغ لا يثبت شيئًا: قد يكون القياس معطّلًا أو محجوبًا أو مستبعدًا من العيّنة أو مفقودًا.
  • service تُعلنه العملية عن نفسها ولا يصادق عليه إلا مفتاح الـ SDK. ومع مفتاح العميل يستطيع أي أحد إرسال البلاغات والأحداث. تعامل معها كأداة رصد، لا كسجل تدقيق.
  • الحدث المأخوذ كعيّنة يثبت أن تقييمًا بتلك النتيجة حدث في عملية ما. ولا يثبت أن المستخدم رأى الميزة، وغياب الأحداث لا يثبت أن العلم غير مستخدم: مع عيّنة 10 % قد تبقى الأعلام النادرة التقييم غير مرئية مدة طويلة.
  • الأعداد تقديرات: العيّنة لكل تقييم، والأحداث تُسقط تحت الضغط أو عند فشل الشبكة أو عند بلوغ الحد اليومي، وقد تقيّم مكونات React مرة لكل تغيير ذي صلة لا لكل إجراء من المستخدم.