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

حِزم SDK

SDK لغة Go

يقيّم SDK لغة Go الأعلام محليًا ودون إدخال/إخراج، على إعداد في الذاكرة يُبقيه محدّثًا في الخلفية عبر الاتصال الحي. لا يفشل التقييم ولا يتوقف أبدًا، والعميل آمن للاستخدام المتزامن.

التثبيت

sh
go get github.com/motazalmaroai/nanoflags-sdk/go@v0.2.0
  • الوحدة github.com/motazalmaroai/nanoflags-sdk/go بالإصدار v0.2.0. تتطلب Go 1.22 أو أحدث.
  • الاعتماديات: github.com/coder/websocket (التحديثات الحيّة) وgolang.org/x/text (تطبيع Unicode للطرح التدريجي). وكل ما عدا ذلك، بما فيه Ed25519، من المكتبة القياسية.
  • الحزمة engine نقلٌ لمحرك NanoFlags. وهي مختبَرة على الحالات المشتركة المولَّدة من المحرك المرجعي (21,998 حالة تقييم) إضافة إلى حالات خاصة بـ Go، وتعطي النتائج نفسها التي تعطيها حزمتا جافاسكريبت وPython.
  • برخصة Apache-2.0. والشيفرة المصدرية في مستودع nanoflags-sdk.

البدء السريع

انسخ مفتاح خادم (nf_srv_…) من الإعدادات ← مفاتيح SDK (Settings → SDK keys) في لوحة التحكم واحفظه في متغير بيئة.

main.go
package main

import (
	"context"
	"log"
	"os"
	"time"

	nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"
)

func main() {
	client, err := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"), nanoflags.WithService("checkout-api"))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	if err := client.WaitForReady(ctx); err != nil {
		log.Printf("flags not loaded yet (%v): evaluations return their fallbacks", err)
	}

	user := nanoflags.Context{"key": "user-42", "plan": "pro", "country": "SA"}
	if client.BoolVariation("new-checkout", user, false) {
		// ...
	}
}

أنشئ عميلًا واحدًا لكل مفتاح SDK عند البدء وشاركه بين الـ goroutines. والعنوان الأساسي افتراضيًا هو الحافة المستضافة https://edge.nanoflags.io. وأمثلة قابلة للتشغيل في go/examples.

السياقات

nanoflags.Context من النوع map[string]any. وقد تكون القيم نصوصًا أو قيمًا منطقية أو أرقامًا أو nil أو شرائح أو خرائط. و"key" هو الهوية الثابتة المستخدمة في الطرح بالنسب المئوية، وعادةً معرّف المستخدم أو الحساب. وتطابق قواعد الاستهداف كل خاصية أخرى.

go
ctx := nanoflags.Context{"key": account.ID, "plan": account.Plan, "beta": true, "seats": 12}
ranking := client.StringVariation("search-ranking", ctx, "relevance-v2")
  • لا يغادر السياق العملية لاتخاذ القرار. وانظر القياس لمعرفة ما ترسله بيانات التشخيص.
  • مرّر key نفسه للمستخدم نفسه في كل مكان: يقع المفتاح نفسه في شريحة الطرح نفسها في Go وPython وجافاسكريبت ولوحة التحكم.

القراءات المُنمَّطة

انتبه إلى ترتيب الوسائط: مفتاح العلم، ثم السياق، ثم قيمة الاحتياط.

go
enabled := client.BoolVariation("new-checkout", user, false)
accent  := client.StringVariation("accent", user, "blue")
limit   := client.Float64Variation("rate-limit", user, 100)
layout  := client.JSONVariation("layout", user, map[string]any{"cols": 3})

all := client.AllFlags(user) // map[string]any, records no telemetry
الدالةتعيد
BoolVariation(key, ctx, fallback bool) boolالقيمة المنطقية للعلم
StringVariation(key, ctx, fallback string) stringالقيمة النصية للعلم
Float64Variation(key, ctx, fallback float64) float64القيمة الرقمية للعلم
JSONVariation(key, ctx, fallback any) anyبيانات Go عادية: nil وbool وfloat64 وstring و[]any وmap[string]any
…VariationDetail(key, ctx, fallback)القيمة مع Detail، انظر التفاصيل والأسباب
Evaluate(key, ctx, fallback any) Detailنتيجة المحرك دون فحص للنوع
AllFlags(ctx) · AllFlagsDetail(ctx)كل أعلام الإعداد

تحصل على قيمة الاحتياط عندما لم يُحمَّل إعداد بعد، أو لعلم مجهول (أو غير مكشوف للعميل مع مفتاح متصفح)، أو عندما يقدّم العلم نوعًا غير المطلوب. والعلم المعطّل ليس حالة احتياط: فهو يعيد قيمة off المضبوطة له.

التفاصيل والأسباب

go
on, detail := client.BoolVariationDetail("new-checkout", user, false)
log.Printf("%v reason=%s rule=%s revision=%d", on, detail.Reason, detail.RuleID, detail.Revision)

for _, step := range detail.Trace { // the same steps the dashboard shows
	log.Printf("%-10s %s — %s", step.Kind, step.Title, step.Detail)
}
trace
config     Configuration loaded — r63
rule       Rule 01 matched — plan = pro
allocation Allocation evaluated — 25% rollout · key inside allocation (bucket 12.34)
result     Returned true — Inside the 25% allocation.
الحقلالمعنى
Valueالقيمة المقدَّمة.
Reasonrule_match، default (لم تطابق قاعدة)، off (العلم معطّل)، flag_not_found، error. والثوابت: nanoflags.ReasonRuleMatch وهكذا.
RuleIndex · RuleIDالقاعدة المطابقة (فهرس يبدأ من الصفر، و-1 عند عدم المطابقة).
InRollout · Bucketمؤشرات تُضبط للطرح بالنسب المئوية (الشريحة من 0 إلى 99.99).
Revisionنسخة الإعداد التي جاءت منها النتيجة.
Trace[]TraceStep بالحقول Kind وTitle وDetail.
Errorلماذا كان Reason هو error (خطأ تقييم أو عدم تطابق نوع).

التحديثات الحيّة وOnChange

يفتح العميل اتصال WebSocket واحدًا إلى GET /v1/live. وتدفع الحافة كل نسخة منشورة موقّعةً مسبقًا؛ فيتحقق منها العميل ويستبدلها ذرّيًا. ولا تحلّ إجابة HTTP أقدم محل نسخة مدفوعة أبدًا.

go
stop := client.OnChange(func(e nanoflags.ChangeEvent) {
	if e.HasLatency {
		log.Printf("now on r%d via %s, %v after commit", e.Revision, e.Transport, e.Latency)
	}
})
defer stop()

client.OnError(func(err error) {
	var nf *nanoflags.Error
	if errors.As(err, &nf) {
		log.Printf("nanoflags %s: %v", nf.Code, err)
	}
})
الحقلالمعنى
Revision · PreviousRevisionالنسخة الجديدة والنسخة التي حلّت محلها (-1 للأولى).
Checksumبصمة الإعداد الجديد.
Sourcenetwork أو store أو bootstrap
Transportlive (مدفوعة) أو stream (مجلوبة بعد إشعار أحداث من الخادم) أو poll
Latency · HasLatencyمن الالتزام في قاعدة البيانات حتى هذا الحدث، للنسخ المدفوعة التي تحمل وقت التزامها. يقارن ساعة قاعدة البيانات بساعة هذا الجهاز.
  • تعمل الدوال المرتدة بالترتيب على goroutine واحدة للعميل: اجعلها قصيرة. وكلٌّ من OnChange وOnError وOnStatus يعيد دالة لإلغاء الاشتراك.
  • الاحتياط: ما دام تعذّر فتح اتصال، أحداث الخادم (GET /v1/stream)، واستطلاع GET /v1/bundle مع ETag كل 30 ثانية (وكل 5 دقائق كشبكة أمان أثناء سلامة الاتصال). وتتراجع محاولات إعادة الاتصال من ثانية واحدة حتى 5 دقائق مع تذبذب. وانظر وسائل النقل للبروتوكول.

الجاهزية والحالة

go
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := client.WaitForReady(ctx); errors.Is(err, nanoflags.ErrNotReady) {
	// no configuration yet: evaluations return their fallbacks
}

client.Status()    // nanoflags.StatusNotReady | StatusReady | StatusStale
client.Revision()  // revision in use
client.Transport() // "live" | "stream" | "poll"
<-client.Ready()   // closed once the first load has finished
  • WaitForReady(ctx) يعود بعد انتهاء التحميل الأول: nil عندما يكون إعداد قيد الاستخدام، وإلا السبب (*nanoflags.Error أو ErrNotReady أو خطأ السياق).
  • StatusReady: الإعداد معروف أنه الحالي. StatusStale: إعداد قيد الاستخدام لكن لا يُعرف أنه الحالي (تعذّر الوصول إلى الحافة، أو استُعيد من المخزن، أو حُذفت البيئة). StatusNotReady: لا شيء محمَّل.
  • لا توقف الطلبات بانتظار الجاهزية: انتظر مرة واحدة عند البدء بمهلة قصيرة، ودع قيم الاحتياط تغطي الباقي.

آخر إعداد سليم والتهيئة المسبقة

الطلبات الفاشلة تُبقي الإعداد الحالي (StatusStale). والحزمة التي تفشل في التحقق، أو تحتاج محركًا أحدث، لا تحلّ محل المستخدمة أبدًا.

go
client, err := nanoflags.New(sdkKey,
	nanoflags.WithStore(nanoflags.FileStore("/var/cache/app/flags.json")), // survives restarts
)

// Or start from a configuration you ship:
data, _ := os.ReadFile("flags-bootstrap.json")
client, err = nanoflags.New(sdkKey, nanoflags.WithBootstrapJSON(data))
  • FileStore يكتب ذرّيًا بالصلاحيات 0600، فيستطيع التشغيل بعد إعادة البدء التقييم قبل الوصول إلى الحافة. ويُتحقق من النسخة المحفوظة مجددًا عند التحميل.
  • WithStore يقبل أي Store (Load(ctx) / Save(ctx, data)). وWithBootstrap(*engine.Bundle) يقبل حزمة محلَّلة.

التحقق من التوقيع

مع العنوان الأساسي الافتراضي، يُتحقق من توقيع Ed25519 لكل حزمة مقابل مفاتيح الإنتاج المضمّنة في الوحدة (OfficialSigningKeys) قبل استخدامها: عبر الاتصال الحي وعبر الاستطلاع ومن المخزن. وتُرفض الحزم غير الموقّعة. وتُحسب بصمة البايتات الموقّعة كما قدّمتها الحافة تمامًا.

go
require := true
client, err := nanoflags.New(sdkKey,
	nanoflags.WithBaseURL("https://flags.internal.example"),
	nanoflags.WithVerification(nanoflags.VerifyOptions{
		PublicKeys: []nanoflags.JWK{{Kty: "OKP", Crv: "Ed25519", X: "…", Kid: "k1"}},
		Require:    &require,
	}),
)
  • الحزمة الموقّعة بمعرّف مفتاح مجهول (تدوير مفاتيح) تجعل العميل يحمّل GET /v1/keys مرة واحدة، ومرة في الدقيقة على الأكثر.
  • تُثبَّت الحزم على أول بيئة وُقّعت لها.
  • على حافة أخرى يكون التحقق معطّلًا ما لم تضبطه. وFetchKeys: true يحمّل المفاتيح من تلك الحافة؛ والمفاتيح المثبّتة أقوى. وWithoutVerification() يعطّله.
  • النص القانوني والترويسات موصوفة في التواقيع.

جلسات الاختبار

تثبّت جلسة الاختبار المشتركة (بالإنجليزية)، التي تُنشأ في لوحة التحكم (السيناريوهات ← جلسة اختبار مشتركة، Scenarios → Shared test session)، لقطةً من الإعداد وسياقًا اصطناعيًا على رمز (nf_ts_…). والخدمة التي تتلقى الرمز في ترويسة x-nanoflags-session تقيّم على تلك اللقطة، بسياق الجلسة وقد غطّاه سياق الاستدعاء (والغلبة للاستدعاء)، لذلك الطلب وحده. وتحمل الأحداث المأخوذة كعيّنة من جلسة معرّفَها. وجلسات الاختبار المشتركة جزء من خطة Scale.

go
// net/http middleware: reads x-nanoflags-session and resolves the session once per request.
mux := http.NewServeMux()
mux.HandleFunc("/cart", func(w http.ResponseWriter, r *http.Request) {
	flags := client.FlagsFor(r.Context()) // session-scoped while the session is active
	v2 := flags.BoolVariation("checkout-v2", nanoflags.Context{"key": userID}, false)

	// The next service joins the same session (or add nanoflags.SessionHeaders(r.Context())).
	downstream := &http.Client{Transport: &nanoflags.SessionTransport{}}
	req, _ := http.NewRequestWithContext(r.Context(), http.MethodGet, pricingURL, nil)
	res, err := downstream.Do(req)
	// …
})
http.ListenAndServe(":8080", nanoflags.SessionMiddleware(client)(mux))

// Anywhere else (queues, jobs, tests): carry the token in a context.Context.
ctx := nanoflags.WithSession(context.Background(), job.SessionToken)
client.FlagsFor(ctx).BoolVariation("checkout-v2", nanoflags.Context{"key": job.UserID}, false)

// Or resolve one explicitly.
s := client.Session(ctx, r.Header.Get(nanoflags.SessionHeader), nanoflags.SessionService("checkout-api"))
s.Active(); s.ID(); s.ExpiresAt(); s.Revision()
الواجهةالوصف
client.Session(ctx, token, opts...) *SessionEvaluatorتحلّ الجلسة (GET /v1/session) وتعيد مقيّمًا محصورًا فيها؛ ولا يحدّ ctx إلا مدة الانتظار.
SessionEvaluatorدوال القراءة الخاصة بالعميل، ومعها Active() وID() وExpiresAt() وRevision().
SessionMiddleware(client, opts...)func(http.Handler) http.Handler: يعمل المعالج داخل جلسة الطلب.
client.FlagsFor(ctx, opts...)مقيّم الطلب الذي ينتمي إليه ctx، يُحلّ مرة واحدة لكل طلب وعميل؛ وخارج الجلسة يتصرّف كالعميل.
WithSession(ctx, token)ctx وفيه token جلسةً حالية؛ والرمز الغائب أو المشوّه يُخرج من أي جلسة.
CurrentSession(ctx) · SessionHeaders(ctx)الرمز الحالي (أو "")؛ وhttp.Header فيه x-nanoflags-session داخل الجلسة، وإلا فارغ.
SessionTransport{Base}http.RoundTripper يضيف الترويسة إلى الطلبات الصادرة بسياق جلسة.
SessionService(name)يُرسل كـ X-NanoFlags-Service (افتراضيًا: WithService)؛ وقد تُقصر الجلسة على خدمات معيّنة.
SessionHeader · IsSessionToken(s)"x-nanoflags-session"؛ والرمز من 1 إلى 512 محرفًا ASCII قابلًا للطباعة.
  • تُسأل الحافة مرة واحدة لكل رمز وخدمة، ويتشارك المستدعون المتزامنون الطلب نفسه، ويُخزَّن الجواب مؤقتًا حتى تنتهي الجلسة. وتُتذكَّر الرموز المجهولة 15 ثانية، وعمليات البحث الفاشلة (المبلَّغ عنها عبر OnError بالرمز session) 3 ثوانٍ.
  • لا تفشل أبدًا: الرمز الغائب أو المشوّه أو المجهول أو المنتهي أو الملغى أو غير المسموح به يعود إلى الإعداد العادي، ويتصرّف المقيّم تمامًا كالعميل. وإن انتهت الجلسة أثناء الطلب تعيد Active() القيمة false وتستمر التقييمات على الإعداد المنشور. ولا تغيّر نسخةٌ منشورة حديثًا ما تقيّمه جلسة نشطة.
  • تُمرَّر الجلسة المجهولة إلى الخدمات التالية مع ذلك: الخدمة التالية تقرّر بنفسها.
  • تغيّر الجلسة اللقطة والسياق اللذين يستخدمهما التقييم فقط؛ فهي لا تمنح أي وصول إلى البيانات ولا يجوز استخدامها للتفويض. وحزم الجلسات غير موقّعة، فلا ينطبق عليها التحقق. والجلسة الملغاة تظل تعمل في عملية خزّنتها مؤقتًا حتى وقت انتهائها.

مزوّد OpenFeature

sh
go get github.com/motazalmaroai/nanoflags-sdk/go/ofprovider@v0.1.0
go
import (
	"github.com/open-feature/go-sdk/openfeature"
	nanoflags "github.com/motazalmaroai/nanoflags-sdk/go"
	"github.com/motazalmaroai/nanoflags-sdk/go/ofprovider"
)

client, err := nanoflags.New(os.Getenv("NANOFLAGS_SDK_KEY"))
if err != nil {
	log.Fatal(err)
}
_ = openfeature.SetProviderAndWait(ofprovider.New(client, ofprovider.WithCloseClient()))

of := openfeature.NewDefaultClient()
on, _ := of.BooleanValue(ctx, "new-checkout", false,
	openfeature.NewEvaluationContext("user-42", map[string]any{"plan": "pro"}))
  • وحدة منفصلة (github.com/motazalmaroai/nanoflags-sdk/go/ofprovider بالإصدار v0.1.0، وGo 1.24، وOpenFeature Go SDK v1.17)، فلا يعتمد الـ SDK نفسه على OpenFeature.
  • يبقى التقييم محليًا في العميل المغلَّف. ويصبح مفتاح الاستهداف هو key.
  • الأسباب: DISABLED وDEFAULT وTARGETING_MATCH وSPLIT (الطرح التدريجي)، وERROR مع FLAG_NOT_FOUND أو PROVIDER_NOT_READY أو TYPE_MISMATCH أو GENERAL. والمتغيّر هو معرّف القاعدة؛ وتحمل البيانات الوصفية للعلم revision.
  • الأحداث: PROVIDER_READY وPROVIDER_STALE وPROVIDER_ERROR، وPROVIDER_CONFIGURATION_CHANGED مع مفاتيح الأعلام التي تغيّرت.
  • الخيارات: WithCloseClient() يغلق عميل NanoFlags عند الإيقاف؛ وWithInitTimeout(d) يحدّ مدة التهيئة.

الخيارات

الخيارالافتراضي
WithBaseURL(url)https://edge.nanoflags.io
WithService(name)"unknown"، الاسم الذي تُبلغ به هذه العملية
WithHTTPClient(*http.Client)النقل الافتراضي (يحترم HTTPS_PROXY)
WithPollInterval(d) · WithLivePollInterval(d)30 ث / 5 د (0 يعطّل الاستطلاع)
WithLive(bool) · WithStreaming(bool)true / true
WithVerification(VerifyOptions) · WithoutVerification()الحافة المستضافة: مفاتيح مضمّنة والتواقيع إلزامية؛ والحافات الأخرى: معطّل
WithStore · WithBootstrap · WithBootstrapJSONلا شيء
WithEvents(EventsOptions)10 % من التقييمات، تُرسل كل 10 ث؛ وبلاغ خدمة كل 60 ث. وDisabled: true يعطّله.
WithLogger(*slog.Logger)يُهمَل

رموز الأخطاء

تصل أعطال الخلفية إلى OnError كـ *nanoflags.Error له Code: network وunauthorized وhttp وinvalid_bundle وstore وconfig وsignature وsession وengine وenvironment_deleted. والتحديث الفاشل لا يغيّر الإعداد المستخدم أبدًا. والمعاني مطابقة لـ SDK جافاسكريبت.

القياس

يحمل الحدث المأخوذ كعيّنة أسماء الخصائص التي تستخدمها قواعد العلم مقرونة بنوعها ({"plan": "string"})، ولا يحمل قيمها افتراضيًا أبدًا. وEventsOptions.Redact يحلّ محل ذلك.

الإغلاق والإيقاف

go
client, err := nanoflags.New(sdkKey)
if err != nil {
	log.Fatal(err)
}
defer client.Close() // idempotent; waits for every goroutine

// Before exiting a short job, send queued telemetry:
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
_ = client.Flush(ctx)
  • Close() يوقف الاتصال الحي والاستطلاع والقياس، وينتظر كل goroutine. واستدعاؤه أكثر من مرة آمن.
  • بعد Close() يواصل التقييم العمل على آخر إعداد.
  • Refresh(ctx) يعيد التحقق الآن؛ وFlush(ctx) يرسل القياس المنتظر الآن.

حل المشكلات

  1. كل تقييم يعيد قيمة الاحتياط. افحص الخطأ من WaitForReady وسجّل OnError. الرمز unauthorized يعني أن المفتاح رُفض؛ ومع مفتاح متصفح (nf_pub_…) لا تُسلَّم إلا الأعلام المكشوفة للعميل.
  2. ترتيب وسائط خاطئ. دوال القراءة في Go تأخذ (key, ctx, fallback). أمّا حزمتا Python وجافاسكريبت فتأخذان قيمة الاحتياط قبل السياق.
  3. خلف وسيط. النقل الافتراضي يحترم HTTPS_PROXY؛ ومرّر WithHTTPClient لإعدادات TLS أو وسطاء مخصّصين. وإن حُجبت الترقية يستخدم العميل أحداث الخادم والاستطلاع، ويعرض Transport() القيمة stream أو poll.
  4. 403 ‏«error code: 1010» من طلبات HTTP الخاصة بك. ترفض الحافة بعض قيم User-Agent الافتراضية للمكتبات. ويرسل الـ SDK ‏nanoflags-go/<version>، فلا يتأثر بذلك إلا الشيفرة التي تستدعي الحافة مباشرة (مثل طلبات OFREP أو السكربتات): اضبط هناك ترويسة User-Agent وصفية.
  5. الرمز signature. لم تجتز حزمة التحقق فلم تُستخدم. ومع WithBaseURL مخصّص ثبّت مفاتيح تلك الحافة.
  6. الرمز engine. يحتاج الإعداد محرك تقييم أحدث من SupportedEngineVersion: حدّث الوحدة.
  7. الرمز environment_deleted. أغلقت الحافة الاتصال بالرمز 4004. يتوقف العميل عن إعادة الاتصال ويُبقي آخر إعداد بحالة StatusStale؛ استبدل المفتاح.
لغات أخرى
لـ Python حزمة SDK أصلية أيضًا: انظر SDK بايثون. ولتطبيقات الجوال حزم أصلية لـ React Native وFlutter وiOS وAndroid. وتتوفر حزم SDK أصلية للخوادم أيضًا لـ Java و.NET وPHP وRuby. ويمكن للغات الأخرى قراءة أعلام NanoFlags عبر مزوّد OpenFeature OFREP.