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

المطورون

قيّم محليًا.وتحقّق من كل شيء.

حزم SDK أصلية لـ JavaScript/TypeScript وPython وGo مع مزوّدات OpenFeature، وأي لغة أخرى عبر OpenFeature (OFREP). وأداة CLI وتكاملات GitHub لـ CI وطلبات الدمج. الشيفرة التي تعمل داخل تطبيقك مرخّصة بـ Apache-2.0، وكل حزمة إعدادات تستقبلها موقّعة.

@nanoflags/sdk 0.4.0nanoflags 0.1.0 (Python)Go SDK v0.1.0Apache-2.0

اللغات

أصلي في ثلاث لغات، ومفتوح لكل لغة أخرى.

تحمّل حزم الـ SDK الأصلية الإعدادات الموقّعة مرة واحدة، وتتحقق منها، وتقيّم داخل العملية نفسها مع تحديثات حية. وأي لغة أخرى تقرأ الأعلام نفسها عبر مزوّد OpenFeature OFREP.

حزم SDK أصلية

الحزم الثلاث تشغّل محرك التقييم نفسه، وتُختبر على 21,998 حالة تقييم مشتركة مولّدة من المحرك المرجعي: المدخلات نفسها تعطي النتائج نفسها في JavaScript وPython وGo.

أي لغة عبر OpenFeature (OFREP)

يطبّق الـ edge في NanoFlags بروتوكول OpenFeature Remote Evaluation Protocol. وتتوفر مزوّدات OFREP رسمية لهذه اللغات وغيرها، فتستطيع الفرق التي تستخدمها الاتصال بـ NanoFlags اليوم:

دليل OFREP
  • Java
  • .NET
  • PHP
  • Ruby
  • Swift
  • Kotlin
  • وغيرها

البدء السريع

ثلاث خطوات إلى علمك الأول.

أنشئ مشروعًا مجانيًا، وانسخ مفتاح SDK من Settings → Keys، ثم:

  1. ثبّت الـ SDK

    إصداران ESM وCommonJS مع أنواع TypeScript، وReact اعتمادية نظيرة اختيارية.

    terminal
    npm install @nanoflags/sdk
  2. أنشئ عميلًا واحدًا

    عميل واحد لكل عملية. يحمّل الحزمة، ويفتح الاتصال الحي، ويتحقق من التوقيعات في الخلفية.

    flags.ts
    import { createClient } from "@nanoflags/sdk";
    
    export const flags = createClient({
      sdkKey: process.env.NANOFLAGS_SDK_KEY!,   // nf_srv_… (server) or nf_pub_… (browser)
      baseUrl: "https://edge.nanoflags.io",
      service: "checkout-api",
    });
    
    await flags.ready(); // never rejects
  3. اقرأ علمًا

    الاستدعاءات محلية ومتزامنة، لا تُجري أي إدخال أو إخراج ولا ترمي استثناءً: دون حزمة تُرجع القيمة الاحتياطية.

    checkout.ts
    const on = flags.boolean("checkout-v2", false, { key: user.id, region: "EU" });
    // Local and synchronous. Returns false only if no configuration has ever loaded.
دليل البدء السريع الكامل

الـ SDK

المحرك نفسه في كل بيئة تشغيل.

تشغّل كل حزمة SDK محرك التقييم نفسه الذي يشغّله الـ edge والـ CLI وCI، فالنتيجة في اختبارك هي النتيجة في الإنتاج. اختر بيئة التشغيل:

  • التحقق من التوقيعات مفعّل افتراضيًا على الـ edge الرسمي، مع مفاتيح الإنتاج مضمّنة (JavaScript من 0.4.0، وPython وGo من 0.1.0).
  • تحديثات حية عبر اتصال WebSocket واحد، مع server-sent events والاستطلاع كبدائل.
  • انتظار الجاهزية لا يرمي خطأً أبدًا، وstatus يخبرك: ready أو stale أو not-ready.
  • مفاتيح المتصفح لا تستقبل إلا الأعلام المتاحة للعميل.
import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!,
  baseUrl: "https://edge.nanoflags.io",
  service: "checkout-api",
});
await flags.ready();

const result = flags.evaluate("checkout-v2", false, { key: user.id, region: "EU" });
// { value, reason: "rule_match", ruleIndex: 1, inRollout: true, bucket: 37.12, revision: 184 }

flags.on("update", (u) => console.log("r" + u.revision, u.transport, u.latencyMs));

OpenFeature

أبقِ مواضع الاستدعاء قياسية.

تغلّف مزوّدات OpenFeature عميل NanoFlags: لـ SDK الخادم وSDK الويب في JavaScript، ولـ Python، ولـ Go. يبقى التقييم محليًا داخل المزوّد، ويواصل NanoFlags التحميل والتحديثات الحية. وتستخدم استدعاءات الأعلام في شيفرتك واجهة OpenFeature القياسية.

التثبيت

npm i @nanoflags/openfeature-provider
import { OpenFeature } from "@openfeature/server-sdk";
import { createClient } from "@nanoflags/sdk";
import { NanoFlagsProvider } from "@nanoflags/openfeature-provider/server";

const nanoflags = createClient({ sdkKey: process.env.NANOFLAGS_SDK_KEY!, baseUrl: "https://edge.nanoflags.io" });
await OpenFeature.setProviderAndWait(new NanoFlagsProvider({ client: nanoflags }));

const on = await OpenFeature.getClient().getBooleanValue("checkout-v2", false, { targetingKey: user.id });

CLI

الأعلام من الطرفية ومن CI.

تعمل @nanoflags/cli بمفتاح CI (التصدير، والسيناريوهات، ومراجع الشيفرة) أو بمفتاح مسؤول (كل ما سبق، إضافة إلى إنشاء الأعلام والنشر). ومفاتيح الـ SDK مرفوضة.

  • nanoflags flags create <key> --type boolean

    أنشئ علمًا بنوع وقيمة افتراضية واسم ووصف.

  • nanoflags eval <flag> --context '{…}'

    قيّم سياقًا على المسودة أو على النسخة المنشورة، مع السبب ومسار التقييم.

  • nanoflags scenarios run --source draft

    شغّل فحوص السيناريوهات لـ commit، ويكون رمز الخروج 1 إذا فشل أحدها.

  • nanoflags refs scan . --repo owner/name

    اعثر على مراجع الأعلام في شيفرتك وارفعها.

  • nanoflags publish --expected-revision <n>

    انشر المسودة وفق سياسة البيئة.

  • nanoflags export --out project.json

    صدّر المشروع كاملًا بصيغة JSON.

مرّر المفتاح في NANOFLAGS_KEY لا كمعامل: المعاملات تظهر في قوائم العمليات وسجل الطرفية.

التثبيت

npm i -g @nanoflags/cli
terminal
export NANOFLAGS_KEY=nf_adm_…          # admin key: create flags, publish

nanoflags flags create new-checkout --description "New checkout flow"
nanoflags flags create search-limit --type number --default 25

nanoflags eval checkout-v2 --context '{"key":"user_42","region":"EU"}'
# checkout-v2 = true
# reason: rule_match · rule r2 (#2) · inside rollout (bucket 37.12)
# source: draft of production
مرجع الـ CLI

GitHub

فحوص الأعلام حيث تُراجع الشيفرة.

طريقتان لإدخال NanoFlags في طلبات الدمج: Action تضيفه إلى workflow، وتطبيق تثبّته مرة واحدة.

GitHub Action

يشغّل فحوص السيناريوهات لكل commit ويُفشل المهمة إذا فشل أحدها، ويرفع مراجع الشيفرة اختياريًا. استخدم مفتاح CI: يشغّل السيناريوهات ولا يستطيع النشر، والـ Action يرفض مفاتيح المسؤول.

.github/workflows/flags.yml
name: Flags
on:
  pull_request:          # NOT pull_request_target
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  scenarios:
    runs-on: ubuntu-latest
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - uses: motazalmaroai/nanoflags-sdk/integrations/github-action@main   # pin to a commit SHA
        with:
          key: ${{ secrets.NANOFLAGS_CI_KEY }}
          source: draft
دليل CI

تطبيق GitHub

  • تعليق على طلب الدمج يعرض حالة كل علم يشير إليه التغيير، ويُحدَّث في مكانه.
  • فحص باسم “NanoFlags scenarios” على المسودة أو النسخة المنشورة التي تختارها.
  • مراجع الشيفرة من الفرع الافتراضي، وتلميحات تنظيف للأعلام التي لا يقرؤها أحد.
دليل تطبيق GitHub

تحقّق بنفسك

حزم موقّعة، ومفاتيح عامة.

تُوقَّع كل نسخة منشورة بخوارزمية Ed25519 قبل توزيعها. والمفاتيح العامة متاحة دون مصادقة، فتستطيع التحقق من الحزمة بـ curl وشيفرتك فقط.

  1. اجلب المفاتيح العامة

    قائمة JSON من مفاتيح JWK، لكل منها kid وstatus. وأثناء تدوير المفاتيح يُدرج المفتاح القديم بالحالة retiring.

  2. اقرأ ترويسات التوقيع

    يرسل الـ edge التوقيع ومعرّف المفتاح ومعرّف البيئة مع كل حزمة موقّعة.

  3. تحقّق من السلسلة القياسية

    توقيع Ed25519 على السلسلة أدناه، وسطرها الأخير هو SHA-256 لنص الحزمة كما أُرسل حرفيًا. وهذا بالضبط ما يفعله الـ SDK.

صيغة التوقيع
terminal
# 1. Public signing keys (no authentication)
curl -s https://edge.nanoflags.io/v1/keys
# {"keys":[{"kty":"OKP","crv":"Ed25519","x":"…","kid":"k1","alg":"EdDSA","use":"sig","status":"active"}]}

# 2. A signed bundle and its signature headers
curl -s -D headers.txt -o bundle.json \
  -H "Authorization: Bearer $NANOFLAGS_SDK_KEY" https://edge.nanoflags.io/v1/bundle
grep -i '^x-nanoflags-' headers.txt
# X-NanoFlags-Signed: true
# X-NanoFlags-Key-Id: k1
# X-NanoFlags-Signature: …
# X-NanoFlags-Environment-Id: …

# 3. Ed25519 signature over this canonical string
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of bundle.json, byte for byte>

ابدأ بعلم واحد.

خطة Explore مجانية: مشروع واحد بثلاث بيئات، وكل حزم الـ SDK والـ CLI.