DevOps والتشغيل الأدلة التقنية

Flagsmith للإعدادات عن بعد Remote Config دون نشر

نغير حد الشحن المجاني ووسائل الدفع في متجر صغير من لوحة Flagsmith دون نشر، ونرى كيف أوقفت قيمة خاطئة واحدة كل طلبات الدفع، وكيف يحمي الكود نفسه منها.

Flagsmith للإعدادات عن بعد Remote Config دون نشر

بعد أسبوعين من تجربة Unleash في المقال السابق من هذه السلسلة جاء طلب من نوع آخر إلى فريق المتجر الإلكتروني نفسه. فقد قرر قسم المبيعات أن يخفض حد الشحن المجاني من 200 ريال إلى 150 في عطلة نهاية الأسبوع، وأن يجرب وسيلة دفع جديدة هي STC Pay عند موظفي الشركة أولاً، وأن يعطي عملاء الخطة المدفوعة شحناً مجانياً دائماً. وكل هذا لا يحتاج إلى «نعم أو لا» كما في ال Feature Flag، وإنما إلى أرقام وقوائم تتغير، وكان الفريق يكتبها في ملف إعداد داخل الكود، فكل تغيير يعني طلب دمج ومراجعة ونشراً، وفي يوم الخميس مساءً لا يريد أحد أن ينشر لأجل رقم.

وهذا ما يسمى الإعداد عن بعد Remote Config: قيم يقرؤها التطبيق وقت التشغيل من خدمة خارجية، وتغيرها من لوحة دون نشر. وأغلب أدوات ال Flags تقدم شيئاً منه، ولكن Flagsmith بنى عليه من البداية، فكل ميزة فيه لها مفتاح تشغيل وقيمة معاً. وفي مقال المفهوم استخدمنا Flagsmith لإطلاق صفحة الدفع الجديدة بالنسب، وجربنا ال Kill Switch وتوقف الخدمة، فلن نعيد ذلك هنا. وإنما نأخذ الجزء الذي لم نجربه: الإعدادات نفسها، وأنواعها، وما يحدث عندما يكتب أحدهم قيمة خاطئة في الإنتاج. وسوف نناقش في هذا المقال ما يلي:

  • الفرق بين ال Feature Flag والإعداد عن بعد، ومتى تحتاج إلى الثاني.
  • كيف يختار Flagsmith القيمة لكل عميل: قيمة البيئة، ثم تجاوز المجموعة، ثم تجاوز العميل.
  • تجربة عملية على Flagsmith 2.288.2: إعداد صفحة الدفع ب JSON، وقيمة مختلفة لكل بيئة، وتجاوزات، وقيم متعددة Multivariate.
  • أنواع القيم كما يخزنها Flagsmith ويقرؤها الكود، وكيف غير خطأ حرف واحد النوع دون أي رسالة.
  • قيمة JSON ناقصة أوقفت كل طلبات الدفع، وكيف يحمي التطبيق نفسه منها.
  • التجاوز الذي ينسخ الإعداد كله ثم يتأخر عنه، والتقييم المحلي أم البعيد وما يخزنه كل منهما عن العملاء.
  • ما الذي تجده محدوداً في النسخة المفتوحة، وقد وجدنا فيها حدوداً لم نتوقعها.

الإعداد عن بعد Remote Config: ما الفرق عن ال Flag؟

ال Feature Flag يجيب عن سؤال واحد: هل يعمل هذا المسار؟ أما الإعداد عن بعد فيجيب عن سؤال «بأي قيمة يعمل؟»، مثل حد الشحن المجاني، وعدد المنتجات المسموح في السلة، ونص الإعلان أعلى الصفحة، وقائمة وسائل الدفع. ويقول توثيق Flagsmith إن الإعداد عن بعد يعيد قيمة من نوع نص أو رقم أو قيمة منطقية أو JSON مع حالة الميزة، وإنك تستطيع أن ترسل عدة قيم معاً بتخزينها ككائن JSON.

وقبل أن تنقل كل ملف الإعداد إلى Flagsmith، فرق بين ثلاثة أنواع من القيم، لأن لكل منها مكاناً مختلفاً:

  • قيم تتغير بقرار من العمل: حد الشحن، ونص الإعلان، ووسائل الدفع المتاحة، وهذه مكانها الإعداد عن بعد، لأن من يقرر تغييرها ليس المطور، ولأنها تتغير أسرع من دورة النشر.
  • قيم تقنية تتبع الكود: عنوان قاعدة البيانات، وحجم مجمع الاتصالات Connection Pool، ومهلة الطلبات، وهذه مكانها ملف الإعداد مع الكود ومراجعة الكود، لأن تغييرها خطأ قد يوقف الخدمة كلها، ولأنها مرتبطة بإصدار معين.
  • الأسرار: مفاتيح بوابة الدفع وكلمات المرور، ومكانها مدير الأسرار كما شرحنا في إدارة الأسرار، وليس أداة Flags يراها كل من في الفريق.

وقد يتساءل البعض: إذا كان الإعداد عن بعد يغير سلوك الإنتاج دون مراجعة ودون نشر، أليس هذا خطراً؟ والإجابة نعم، وهو الخطر نفسه الذي يجعل Kill Switch مفيداً: تغيير سريع لا يمر بخط CI. لذلك سوف ترى في التجربة أن أهم جزء في الإعداد عن بعد ليس الأداة، وإنما الكود الذي يقرأ القيمة ويتحقق منها قبل أن يثق بها.

من أين تأتي القيمة لكل عميل؟ Overrides

في Flagsmith تعرف الميزة Feature مرة واحدة في المشروع، ثم يكون لها في كل بيئة حالة وقيمة، ثم يمكنك أن تضيف تجاوزات Overrides بمستويين: تجاوز لمجموعة Segment تحددها صفات العميل Traits، وتجاوز لعميل واحد Identity. والقاعدة أن الأخص يفوز، كما تبين الصورة التالية بالقيم التي استخدمناها في التجربة:

الميزة checkout_config مفتاح تشغيل مع قيمة JSON لكل بيئة، وفيها ثلاثة مستويات: أولاً تجاوز العميل Identity Override ل user-42 بوسيلة دفع mada فقط لحالة دعم فني، ثم تجاوز المجموعة Segment Override ل pro_customers بحد شحن 0 بحسب الصفة plan = pro، ثم قيمة البيئة Environment حيث production بحد 200 وstaging يضيف stc_pay، وعلى اليسار ما رآه كل عميل: user-42 بحد 200 ووسيلة mada، وuser-8 بخطة pro بحد 0 و100 منتج، وuser-7 بحد 200 و50 منتجاً وثلاث وسائل دفع
تجاوز العميل يفوز على تجاوز المجموعة، وتجاوز المجموعة يفوز على قيمة البيئة

وفي الصورة أعلاه لاحظ أن كل مستوى يحمل القيمة كاملة، وليس الفرق فقط، فتجاوز مجموعة الخطة المدفوعة فيه JSON كامل بكل الحقول، وهذا تفصيل صغير سوف يسبب لنا مشكلة حقيقية في التجربة. ولاحظ أيضاً أن الصفات التي تختار بها المجموعة، مثل plan، يرسلها تطبيقك مع كل تقييم، ويشرح توثيق الهويات كيف يتعامل معها Flagsmith، وأين يخزنها، وهذا ما سوف نختبره أيضاً.

كيف يعمل Flagsmith من الداخل؟ Architecture

Flagsmith تطبيق Django مكتوب ب Python، ويتكون في التشغيل الذاتي من ثلاث خدمات من صورة واحدة: خدمة ال API التي تقدم اللوحة وواجهة الإدارة وواجهة ال SDKs، ومعالج المهام الذي ينفذ الأعمال الخلفية، وقاعدة بيانات PostgreSQL تحفظ كل شيء. وعندما يغير أحدهم قيمة في اللوحة، يحفظها ال API في قاعدة البيانات، وتصبح جزءاً من وثيقة البيئة Environment Document، وهي ملف JSON واحد فيه كل ميزات البيئة وقيمها والمجموعات بشروطها وتجاوزات العملاء، وهذه الوثيقة هي ما يجلبه ال SDK في التقييم المحلي.

وال SDK على السيرفر يجلب الوثيقة كل فترة، والافتراضي في flagsmith-nodejs 8.1.2 ستون ثانية كما قرأنا في كود المكتبة، وجعلناها في التجربة عشر ثوان حتى لا ننتظر. وهذا يعني أن تغيير حد الشحن في الإنتاج قد يحتاج إلى دقيقة حتى يصل إلى كل السيرفرات، وكل سيرفر في دورته الخاصة، فإذا كان عندك سيرفران فقد يرى عميل حد 150 على أحدهما وحد 200 على الآخر لبضع ثوان. وهذا مقبول لحد الشحن، وغير مقبول لقيمة يحسب بها مبلغ يدفعه العميل ثم يتحقق منها سيرفر آخر، لذلك احسب المبلغ مرة واحدة في الطلب واحفظه معه، ولا تعد قراءة الإعداد في كل خطوة من خطوات الدفع.

أما تطبيقات المتصفح والجوال فلا تجلب الوثيقة، وإنما تسأل الخادم عن قيم عميل واحد بمفتاح البيئة العادي، فيقيم الخادم ويعيد النتائج فقط، وهذا هو التقييم البعيد الذي سوف نقيسه في التجربة. والفرق بين الطريقتين ليس السرعة فقط، وإنما ما يعرفه الخادم عن عملائك، كما سوف ترى.

تجربة عملية Lab: Flagsmith مع PostgreSQL

الآن سوف نشغل Flagsmith 2.288.2 مع PostgreSQL 18 ومعالج المهام الخلفية Task Processor، وننشئ مشروع المتجر ببيئتين، ثم نضع إعداد صفحة الدفع ك JSON مع تجاوزات، ونكتب تطبيق Node.js يقرؤه بمكتبة flagsmith-nodejs 8.1.2 بالتقييم المحلي، ثم نجرب الأخطاء التي تحدث فعلاً مع الإعداد عن بعد. وتحتاج التجربة إلى Docker فقط، والخدمة على 127.0.0.1.

تشغيل الخادم Docker Compose

الملف التالي مبني على ملف Compose في المستودع الرسمي، بعد تثبيت الإصدار، والاستغناء عن خدمات التجارب Kafka وClickHouse التي أضافها المشروع مؤخراً، والإبقاء على معالج المهام الذي يوصي به:

name: wr-ff-flagsmith

x-flagsmith-env: &flagsmith-env
  DATABASE_URL: postgresql://flagsmith:lab-db-pass@db:5432/flagsmith
  USE_POSTGRES_FOR_ANALYTICS: "true"
  ENVIRONMENT: production
  DJANGO_ALLOWED_HOSTS: "*"
  FLAGSMITH_DOMAIN: 127.0.0.1:48000
  DJANGO_SECRET_KEY: lab-secret-change-me
  ALLOW_REGISTRATION_WITHOUT_INVITE: "true"
  TASK_RUN_METHOD: TASK_PROCESSOR

services:
  db:
    image: postgres:18-alpine
    container_name: wr-ff-flagsmith-db
    environment:
      POSTGRES_USER: flagsmith
      POSTGRES_PASSWORD: lab-db-pass
      POSTGRES_DB: flagsmith
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d flagsmith -U flagsmith"]
      interval: 2s
      retries: 30

  migrate:
    image: flagsmith/flagsmith:2.288.2
    container_name: wr-ff-flagsmith-migrate
    command: ["migrate"]
    environment: *flagsmith-env
    depends_on:
      db:
        condition: service_healthy

  api:
    image: flagsmith/flagsmith:2.288.2
    container_name: wr-ff-flagsmith-api
    command: ["serve"]
    environment: *flagsmith-env
    ports:
      - "127.0.0.1:48000:8000"
    depends_on:
      migrate:
        condition: service_completed_successfully

  tasks:
    image: flagsmith/flagsmith:2.288.2
    container_name: wr-ff-flagsmith-tasks
    command: ["run-task-processor"]
    environment: *flagsmith-env
    depends_on:
      migrate:
        condition: service_completed_successfully

volumes:
  pgdata:
    name: wr-ff-flagsmith-pgdata

networks:
  default:
    name: wr-ff-flagsmith-net

في الإعداد أعلاه لاحظ التالي:

  • الصورة نفسها تعمل بثلاثة أدوار بحسب الأمر: migrate ينشئ الجداول ثم ينتهي، وserve يقدم ال API واللوحة، وrun-task-processor ينفذ المهام الخلفية مثل كتابة سجل التدقيق وتحديث وثيقة البيئة، والشرح في توثيق التشغيل ب Docker.
  • TASK_RUN_METHOD: TASK_PROCESSOR يرسل المهام إلى الخدمة tasks بدل أن ينفذها في خيط جانبي داخل ال API، وهذا ما يوصي به الملف الرسمي للإنتاج.
  • ALLOW_REGISTRATION_WITHOUT_INVITE يسمح بإنشاء أول حساب، وفي الإنتاج أغلق التسجيل بعد إنشاء حسابات الفريق.

وأول تشغيل أخذ وقتاً لم نتوقعه، فقد بقيت خدمة migrate في حالة unhealthy قرابة أربع دقائق، والخدمتان الأخريان في حالة Created تنتظرانها، وظننا أن شيئاً تعطل:

wr-ff-flagsmith-api Created
wr-ff-flagsmith-tasks Created
wr-ff-flagsmith-migrate Up 3 minutes (unhealthy)
wr-ff-flagsmith-db Up 3 minutes (healthy)
migrate started 2026-11-05T09:04:59Z finished 2026-11-05T09:08:53Z exit 0
616

والسبب أن الترحيل الأول ينفذ 616 خطوة Migration على قاعدة فارغة، وأخذ 3 دقائق و54 ثانية، وكلمة unhealthy مضللة هنا، لأن الصورة فيها فحص صحة Healthcheck مصمم لخدمة ال API، ولا معنى له لخدمة الترحيل، ولذلك يعطله الملف الرسمي لهذه الخدمة. فلا توقف الترحيل ظناً أنه معلق، وإنما اقرأ سجله، وستجد سطور Applying … OK تتقدم. وبعد التشغيل استهلكت خدمة ال API نحو 544 ميجابايت من الذاكرة، وخدمة المهام 340، وقاعدة البيانات 115، وحجم الصورة 532 ميجابايت، وهذا أكثر بكثير مما رأيناه مع Unleash، لأن Flagsmith تطبيق Django كامل بعدة عمليات.

المشروع والبيئتان عبر API

ننشئ الحساب والمؤسسة Organisation والمشروع والبيئتين ومفتاح السيرفر بسكربت، كما في مقال المفهوم، ونحفظ القيم في ملف للخطوات التالية:

TOKEN=$(curl -s -X POST $F/auth/users/ -H "$J" -d '{"email":"[email protected]","password":"Lab-Pass-2026-x9","re_password":"Lab-Pass-2026-x9","first_name":"Lab","last_name":"Admin"}' | j "['key']")
H="Authorization: Token $TOKEN"
ORG=$(curl -s -X POST $F/organisations/ -H "$H" -H "$J" -d '{"name":"Shop"}' | j "['id']")
PRJ=$(curl -s -X POST $F/projects/ -H "$H" -H "$J" -d "{\"name\":\"shop\",\"organisation\":$ORG}" | j "['id']")
PROD=$(curl -s -X POST $F/environments/ -H "$H" -H "$J" -d "{\"name\":\"production\",\"project\":$PRJ}" | j "['api_key']")
STG=$(curl -s -X POST $F/environments/ -H "$H" -H "$J" -d "{\"name\":\"staging\",\"project\":$PRJ}" | j "['api_key']")
SER=$(curl -s -X POST $F/environments/$PROD/api-keys/ -H "$H" -H "$J" -d '{"name":"shop backend"}' | j "['key']")
org 1, project 1, production BhRbpXGK8J2pHbdw5yrVrj, staging mrew6FGyH7BApNxANxrVpS, server key ser.NhyS…

وبعد ذلك احتجنا إلى نداءات كثيرة على ال Admin API، وأولها فشل. فتغيير قيمة الميزة في بيئة بالطريقة التي تبدو طبيعية، أي PATCH على حالة الميزة مع القيمة كنص، رد بهذا الخطأ:

{"feature_state_value":{"non_field_errors":["Invalid data. Expected a dictionary, but got str."]}} HTTP 400

والسبب أن نقاط ال API في Flagsmith لا تتفق على شكل القيمة: بعضها يقبل النص مباشرة، مثل PUT على /environments/{key}/featurestates/{id}/، وبعضها يريد كائناً فيه النوع والقيمة، مثل {"type":"unicode","string_value":"…"} عند إنشاء تجاوز مجموعة. لذلك كتبنا ملفاً صغيراً ب Python يغلف هذه النداءات، حتى يكون كل تغيير في التجربة سطراً واحداً يمكن إعادته، وهذا أفضل من أن تتذكر شكل كل نقطة:

def set_value(env_key, name, value, enabled=True):
    """Environment default for a feature: on/off and its value."""
    fs = call('GET', f'/environments/{env_key}/featurestates/?feature_name={name}')['results'][0]
    return call('PUT', f"/environments/{env_key}/featurestates/{fs['id']}/",
                {'enabled': enabled, 'feature_state_value': value, 'feature': fs['feature'], 'environment': fs['environment']})

def typed(value):
    """Override values need an explicit type: a Python int must stay an int, not the string '0'."""
    if isinstance(value, bool): return {'type': 'bool', 'boolean_value': value}
    if isinstance(value, int): return {'type': 'int', 'integer_value': value}
    return {'type': 'unicode', 'string_value': value}

def segment_override(env_key, name, segment_id, value, enabled=True):
    fseg = call('POST', '/features/feature-segments/', {'feature': feature_id(name), 'segment': segment_id, 'environment': env_id(env_key)})
    return call('POST', '/features/featurestates/', {'feature': feature_id(name), 'environment': env_id(env_key), 'feature_segment': fseg['id'],
                                                   'enabled': enabled, 'feature_state_value': typed(value)})

def identity_override(env_key, identifier, name, value, enabled=True):
    ident = call('POST', f'/environments/{env_key}/identities/', {'identifier': identifier})
    return call('POST', f"/environments/{env_key}/identities/{ident['id']}/featurestates/",
                {'feature': feature_id(name), 'enabled': enabled, 'feature_state_value': value})

والدالة typed لم تكن في النسخة الأولى من الملف، وأضفناها بعد مشكلة سوف تراها في قسم إطلاق القيمة لعشرة بالمئة. وهذا الملف هو ما يكتبه فريق التشغيل عادة حول أي أداة Flags، ويضعه في المستودع، حتى يكون إعداد بيئة جديدة أو استعادة الإعدادات بعد حادثة أمراً يمكن تكراره، ولا يعتمد على من يتذكر أين ضغط في اللوحة.

إعداد صفحة الدفع JSON لكل بيئة

ننشئ الميزة checkout_config بقيمة JSON فيها حد الشحن المجاني ووسائل الدفع وأقصى عدد للمنتجات، ونكتب في وصفها أنها إعداد دائم وليست Release Flag، حتى لا يحذفها أحد في مراجعة ال Flags المنسية:

$ create feature checkout_config
{'id': 1, 'name': 'checkout_config', 'type': 'STANDARD', 'initial_value': '{"free_shipping_threshold":200,"payment_methods":["mada","apple_pay","cod"],"max_items":50}', 'default_enabled': True}
$ feature state in staging
2 True {"free_shipping_threshold":200,"payment_methods":["mada","apple_pay","cod"],"max_items":50}

لاحظ أن initial_value ينسخ إلى كل البيئات عند الإنشاء، ثم تصبح قيمة كل بيئة مستقلة. ثم أضفنا STC Pay إلى بيئة staging فقط حتى يختبرها فريق الجودة:

staging True {"free_shipping_threshold":200,"payment_methods":["mada","apple_pay","cod","stc_pay"],"max_items":50}

ثم أنشأنا مجموعة pro_customers لمن صفته plan تساوي pro، وأضفنا لها في الإنتاج تجاوزاً بحد شحن صفر و100 منتج، ثم تجاوزاً لعميل واحد هو user-42، وهي حالة دعم فني حقيقية تحدث في كل متجر: عميل فشلت معه Apple Pay مرات، فطلب الدعم الفني أن يرى مدى فقط حتى يحل البنك مشكلته:

$ segment pro_customers (plan = pro)
segment id 1
$ production override for pro_customers: free shipping from 0
featurestate 4 segment link 2 {'type': 'unicode', 'string_value': '{"free_shipping_threshold":0,"payment_methods":["mada","apple_pay","cod"],"max_items":100}', …}
$ identity override for one customer (support case)
featurestate 3 1 {"free_shipping_threshold":200,"payment_methods":["mada"],"max_items":50}

وأضفنا أيضاً الميزة checkout_layout من نوع القيم المتعددة Multivariate، قيمتها الأساسية one_page ونسخة two_steps بنسبة 50%، وهي التجربة نفسها التي عملناها بالنسخ Variants في Unleash، والميزة new_checkout بمجموعة نسبتها 50%، حتى يبقى المتجر واحداً في كل السلسلة.

التطبيق مع التقييم المحلي Local Evaluation

ملف إنشاء العميل كما في مقال المفهوم، ولكن بالإصدار 8.1.2 من المكتبة:

// One place that creates the Flagsmith client for the shop backend.
import { Flagsmith } from 'flagsmith-nodejs';

export const flagsmith = new Flagsmith({
  environmentKey: process.env.FLAGSMITH_SERVER_KEY,   // ser.… key: local evaluation
  apiUrl: process.env.FLAGSMITH_API_URL,              // http://api:8000/api/v1/
  enableLocalEvaluation: true,
  environmentRefreshIntervalSeconds: Number(process.env.REFRESH_S || 10),
});

والسكربت config.mjs يقرأ الإعداد لثلاثة عملاء:

// What checkout settings does each customer get? Remote config read as JSON.
import { flagsmith } from './flagsmith.mjs';

const customers = [
  ['user-7', { plan: 'free' }],
  ['user-8', { plan: 'pro' }],
  ['user-42', { plan: 'free' }],
];
for (const [id, traits] of customers) {
  const flags = await flagsmith.getIdentityFlags(id, traits);
  const cfg = JSON.parse(flags.getFeatureValue('checkout_config'));
  console.log(id, traits.plan, '->', JSON.stringify(cfg), '| layout:', flags.getFeatureValue('checkout_layout'));
}
flagsmith.close();
user-7 free -> {"free_shipping_threshold":200,"payment_methods":["mada","apple_pay","cod"],"max_items":50} | layout: two_steps
user-8 pro -> {"free_shipping_threshold":0,"payment_methods":["mada","apple_pay","cod"],"max_items":100} | layout: two_steps
user-42 free -> {"free_shipping_threshold":200,"payment_methods":["mada"],"max_items":50} | layout: one_page

في المخرج أعلاه لاحظ التالي:

  • العميل العادي أخذ قيمة البيئة، وعميل الخطة المدفوعة أخذ تجاوز المجموعة، والعميل user-42 أخذ تجاوزه الخاص، تماماً كترتيب الصورة الأولى.
  • تجاوز العميل الواحد وصل رغم أن التقييم محلي، والسبب إعداد البيئة use_identity_overrides_in_local_eval الذي كان مفعلاً بشكل افتراضي في بيئتنا، وسوف نرى بعد قليل ماذا يعني ذلك لمفتاح السيرفر.
  • القيمة تصل نصاً، والكود يحولها ب JSON.parse، وهذا السطر هو الذي سوف يوقف المتجر بعد قليل.

ثم قيمنا الميزتين لألف عميل:

{ new_checkout_on: 484, one_page: 511, two_steps: 489 }

484 عميلاً في مجموعة ال 50%، والقيم المتعددة 511 و489، وهي توزيعات قريبة من النصف كما في Unleash، فالأداتان تستخدمان الفكرة نفسها: هاش ثابت لمعرف العميل.

والصورة التالية من لوحة Flagsmith بعد إنشاء الميزات، ولاحظ العلامتين بجانب checkout_config: تجاوز مجموعة واحد وتجاوز عميل واحد:

قائمة الميزات في بيئة production في Flagsmith 2.288.2: checkout_banner بقيمة Free shipping over 2…، وcheckout_config بقيمة JSON وعليه علامة تجاوز مجموعة واحد وتجاوز عميل واحد ووصف إعداد دائم، وcheckout_layout بقيمة one_page ووصف تجربة تحذف بعد انتهائها، وcod_enabled بقيمة true، وmax_cart_items بقيمة 100، وnew_checkout مطفأ مع تجاوز مجموعة، وفي القائمة الجانبية Scheduling وFeature Change Requests وIdentities وSDK Keys
كل ميزة فيها مفتاح تشغيل وقيمة، والعلامات تبين التجاوزات

بأي نوع تصل القيمة؟ Value Types

لا يطلب منك Flagsmith أن تحدد نوع القيمة عندما تكتبها في اللوحة، وإنما يخمنه من النص. أنشأنا ثلاث ميزات بقيم مختلفة، وقرأنا كيف خزنها الخادم، ثم كيف وصلت إلى JavaScript:

max_cart_items   initial_value='50'                             stored as int: 50
checkout_banner  initial_value='Free shipping over 200 SAR'     stored as str: 'Free shipping over 200 SAR'
cod_enabled      initial_value='true'                           stored as bool: True
max_cart_items   number 50
checkout_banner  string "Free shipping over 200 SAR"
cod_enabled      boolean true
checkout_config  string "{\"free_shipping_threshold\":200,\"payment_methods\":[\"mad
max_cart_items + 1 = 51

النص 50 صار رقماً، والنص true صار قيمة منطقية، أما JSON فبقي نصاً يحلله الكود. وهذا مريح حتى يخطئ أحدهم، فسألنا: ماذا لو كتب موظف المبيعات حد السلة 1O0، بحرف O بدل الصفر، وهو خطأ يحدث على لوحة المفاتيح أكثر مما تتخيل؟ والكود الذي يفحص السلة بسيط:

// The cart check that uses max_cart_items. What happens when someone types 1O0 (letter O) instead of 100?
import { flagsmith } from './flagsmith.mjs';
const flags = await flagsmith.getEnvironmentFlags();
const max = flags.getFeatureValue('max_cart_items');
for (const items of [3, 60, 150]) console.log(`cart with ${items} items, max=${JSON.stringify(max)} -> ${items > max ? 'rejected' : 'accepted'}`);
console.log('typeof max:', typeof max, '| max + 1 =', max + 1);
flagsmith.close();
stored: '1O0'
cart with 3 items, max="1O0" -> accepted
cart with 60 items, max="1O0" -> accepted
cart with 150 items, max="1O0" -> accepted
typeof max: string | max + 1 = 1O01

قبل Flagsmith القيمة دون أي اعتراض، وخزنها نصاً، وفي JavaScript المقارنة بين رقم ونص لا يمكن تحويله إلى رقم تعطي false دائماً، فقبلت السلة 150 منتجاً، أي أن الحد اختفى تماماً دون أي خطأ في السجلات. وهذا أسوأ من أن يتوقف التطبيق، لأن أحداً لن يلاحظ حتى يأتي طلب بألف قطعة من منتج عليه خصم.

مشكلة حقيقية Real Problem: إصلاحنا غير النوع

ثم أعدنا الحد إلى 100 بالسكربت، فظهرت المشكلة الحقيقية الأولى في هذه التجربة. أرسلنا القيمة "100" عبر ال API، وهي في JSON نص لأنها بين علامتي تنصيص، فخزنها Flagsmith نصاً كما هي، ولم يخمن النوع كما يفعل في اللوحة. وفي اللوحة ظهرت القيمة بين علامتي تنصيص كما ترى في الصورة السابقة قبل أن نصلحها، والكود أعطى هذا:

cart with 3 items, max="100" -> accepted
cart with 60 items, max="100" -> accepted
cart with 150 items, max="100" -> rejected
typeof max: string | max + 1 = 1001

المقارنة عملت هذه المرة، لأن JavaScript يحول النص "100" إلى رقم عند المقارنة، ولكن الجمع لصق النصين فأعطى 1001، فلو كان في الكود حساب مثل «الحد زائد عشرة للعملاء المدفوعين» لصار الحد ألفاً وعشرة. وعندما أرسلنا الرقم 100 دون علامتي تنصيص عاد كل شيء صحيحاً:

stored: 100
cart with 150 items, max=100 -> rejected
typeof max: number | max + 1 = 101

والدرس أن النوع في الإعداد عن بعد ليس مضموناً، فهو يعتمد على من كتب القيمة وكيف كتبها، من اللوحة أو من ال API أو من سكربت استعادة. لذلك لا تقم باستخدام قيمة من Flagsmith مباشرة في حساب، وإنما حولها إلى النوع الذي تتوقعه وتحقق منه في مكان واحد، وهذا ما سوف نكتبه في القسم التالي.

قيمة JSON ناقصة قوساً: Bad Config

هذا السيناريو هو ما يخافه كل من يستخدم الإعداد عن بعد. كتبنا معالجاً يشبه نقطة الدفع في المتجر، يقرأ الإعداد لكل طلب ويحلله، وشغلناه يستقبل طلباً كل ثانية، ثم حفظنا في الإنتاج قيمة جديدة بحد 150 ريالاً، ونسينا القوس الأخير، كما يحدث عندما يعدل أحدهم JSON طويلاً في مربع نص:

// A checkout handler that trusts the remote JSON. One request per second for user-7.
import { flagsmith } from './flagsmith.mjs';
const t0 = Date.now();
const timer = setInterval(async () => {
  const s = Math.round((Date.now() - t0) / 1000);
  try {
    const flags = await flagsmith.getIdentityFlags('user-7', { plan: 'free' });
    const cfg = JSON.parse(flags.getFeatureValue('checkout_config'));
    console.log(`t=${String(s).padStart(2)}s 200 threshold=${cfg.free_shipping_threshold} methods=${cfg.payment_methods.join(',')}`);
  } catch (err) {
    console.log(`t=${String(s).padStart(2)}s 500 ${err.name}: ${err.message.slice(0, 70)}`);
  }
  if (s >= 24) { clearInterval(timer); flagsmith.close(); }
}, 1000);
09:12:47 someone saves checkout_config without the closing brace
t= 1s 200 threshold=200 methods=mada,apple_pay,cod
…
t=10s 200 threshold=200 methods=mada,apple_pay,cod
t=11s 500 SyntaxError: Expected ',' or '}' after property value in JSON at position 90 (line
t=12s 500 SyntaxError: Expected ',' or '}' after property value in JSON at position 90 (line
…
t=24s 500 SyntaxError: Expected ',' or '}' after property value in JSON at position 90 (line 

حفظ Flagsmith القيمة دون أي تحقق، لأنها بالنسبة له نص، وبعد دورة التحديث التالية فشل كل طلب دفع بخطأ 500، أي أن المتجر توقف عن البيع بسبب قوس، ودون نشر ودون أي تغيير في الكود. وهذا هو الوجه الآخر لل Kill Switch: الأداة التي تغير الإنتاج في ثوان تستطيع أن توقفه في ثوان. والصورة التالية تقارن المعالجين:

في الأعلى قيمة JSON ينقصها القوس الأخير حفظت بنجاح في 09:12:47، وعلى اليمين المعالج الذي يثق بالقيمة: من الثانية 1 إلى 10 يرد 200 ثم من 11 إلى 24 يرد 500 بخطأ SyntaxError عند الموضع 90 وكل طلب دفع يفشل، وعلى اليسار المعالج مع checkoutConfig بخمس خطوات: حلل النص، افحص كل حقل، احفظه كآخر قيمة سليمة lastGood، إذا فشل اكتب سطراً واحداً واستخدم lastGood، وإذا لم توجد قيمة سليمة فالقيمة الافتراضية في الكود، وتحته مخرج يرفض وسيلة الدفع applepay ويستمر بالرد 200، وفي الأسفل عملية جديدة مع قيمة سيئة تبدأ بالقيمة الافتراضية
Flagsmith يقبل النص كما هو، والتحقق مسؤولية تطبيقك

والإصلاح أن تعامل الإعداد عن بعد كأي مدخل من خارج الكود، تماماً كما تعامل طلباً من المتصفح: تحلله، وتتحقق من كل حقل، وتحتفظ بآخر قيمة سليمة، وتعود إلى قيمة افتراضية في الكود إذا لم تر قيمة سليمة أبداً. والملف checkout-config.mjs يفعل ذلك:

// Remote config is input from outside the code: parse it, check it, keep the last good value.
const DEFAULT = Object.freeze({ free_shipping_threshold: 200, payment_methods: ['mada', 'cod'], max_items: 50 });
const KNOWN_METHODS = new Set(['mada', 'apple_pay', 'cod', 'stc_pay']);
let lastGood = DEFAULT;
let lastBadRaw = null;

function check(cfg) {
  if (!Number.isInteger(cfg.free_shipping_threshold) || cfg.free_shipping_threshold < 0) throw new Error('free_shipping_threshold must be an integer >= 0');
  if (!Array.isArray(cfg.payment_methods) || cfg.payment_methods.length === 0) throw new Error('payment_methods must be a non-empty list');
  for (const m of cfg.payment_methods) if (!KNOWN_METHODS.has(m)) throw new Error(`unknown payment method ${m}`);
  if (!Number.isInteger(cfg.max_items) || cfg.max_items < 1 || cfg.max_items > 500) throw new Error('max_items must be 1..500');
  return cfg;
}

export function checkoutConfig(flags) {
  const raw = flags.getFeatureValue('checkout_config');
  try {
    lastGood = Object.freeze(check(JSON.parse(raw)));
    lastBadRaw = null;
  } catch (err) {
    if (raw !== lastBadRaw) console.error(`[config] checkout_config rejected (${err.message}); using the last good value`);
    lastBadRaw = raw;   // log once per bad value, not once per request
  }
  return lastGood;
}

في الكود أعلاه لاحظ التالي:

  • قائمة وسائل الدفع المعروفة في الكود، لأن الكود هو الذي يعرف كيف يتعامل مع كل وسيلة، فوسيلة لا يعرفها الكود ليست إعداداً وإنما خطأ.
  • الحدود الدنيا والعليا، مثل 1 إلى 500 منتج، تمنع القيمة التي تبدو صحيحة وهي خطأ، مثل صفر منتج أو مئة ألف.
  • الخطأ يكتب مرة واحدة لكل قيمة سيئة، وليس مع كل طلب، حتى لا يغرق السجل بآلاف الأسطر، وهذا السطر هو ما ترسل عليه تنبيهاً.
  • القيمة الافتراضية في الكود محافظة: وسيلتان مجربتان وحد 200، وليست آخر عرض تسويقي.

وجربنا ثلاث حالات. عملية جديدة بدأت والقيمة الناقصة ما زالت في الإنتاج، ثم عملية تعمل تغيرت قيمتها إلى قيمة فيها وسيلة دفع مكتوبة خطأ applepay بدل apple_pay، ثم أصلحناها:

--- new process, bad JSON already in Flagsmith
[config] checkout_config rejected (Expected ',' or '}' after property value in JSON at position 90 (line 1 column 91)); using the last good value
t= 1s 200 threshold=200 methods=mada,cod
t= 2s 200 threshold=200 methods=mada,cod
--- running process: good value, then a bad one (unknown method), then fixed
t= 1s 200 threshold=150 methods=mada,apple_pay,cod
…
t=11s 200 threshold=150 methods=mada,apple_pay,cod
[config] checkout_config rejected (unknown payment method applepay); using the last good value
t=12s 200 threshold=150 methods=mada,apple_pay,cod
…
t=26s 200 threshold=150 methods=mada,apple_pay,cod

العملية الجديدة لم تر قيمة سليمة قط، فبدأت بالقيمة الافتراضية، والعملية التي تعمل رفضت القيمة الخاطئة واستمرت بآخر قيمة سليمة، ولم يفشل أي طلب دفع في الحالتين. ولاحظ الثمن: عندما ترفض القيمة يعمل المتجر بقيمة غير التي كتبها فريق المبيعات، لذلك يجب أن يصل سطر الرفض إلى من كتبها خلال دقائق، وهذا عمل التنبيهات، وإلا ظن الفريق أن تخفيض الشحن يعمل وهو لا يعمل.

وتستطيع أن تضيف خطوة قبل ذلك كله: Flagsmith يدعم التحقق من القيمة عند حفظها في اللوحة، فإذا اخترت .json كما ترى في صورة التجاوز أدناه، يعرض المحرر علامة صحة بجانبه، ولكنه تنبيه للكاتب وليس حماية، لأن ال API قبل القيمة الناقصة منا دون اعتراض. فالحماية الحقيقية هي التي في الكود.

تجاوز ينسخ الإعداد كله: Override Drift

بعد أن نجحت STC Pay في staging، أضافها الفريق إلى قيمة الإنتاج، وقرأنا الإعداد للعملاء الثلاثة مرة أخرى:

$ production default now adds stc_pay
user-7 free -> {"free_shipping_threshold":150,"payment_methods":["mada","apple_pay","cod","stc_pay"],"max_items":50} | layout: two_steps
user-8 pro -> {"free_shipping_threshold":0,"payment_methods":["mada","apple_pay","cod"],"max_items":100} | layout: two_steps
user-42 free -> {"free_shipping_threshold":200,"payment_methods":["mada"],"max_items":50} | layout: one_page

العميل العادي رأى الوسيلة الجديدة، أما عملاء الخطة المدفوعة، وهم أفضل عملاء المتجر، فلم يروها، والعميل user-42 بقي بحد 200 بينما الجميع على 150. والسبب ما لاحظناه في الصورة الأولى: كل تجاوز يحمل JSON كاملاً نسخ في يوم إنشائه، فلا يعرف بأي تغيير على قيمة البيئة بعد ذلك. والصورة التالية من اللوحة تبين نسخة المجموعة القديمة كما هي:

نافذة Edit Feature checkout_config في Flagsmith على تبويب Segment Overrides، وفيها تجاوز pro_customers مفعل بقيمة JSON كاملة: free_shipping_threshold 0 وpayment_methods mada وapple_pay وcod وmax_items 100، ومحرر القيمة يعرض خيارات txt وjson مع علامة صحة وxml وtoml وyaml، وملاحظة أن تجاوزات الهوية تفوز دائماً على تجاوزات المجموعة
تجاوز المجموعة نسخة كاملة من الإعداد، وليس فرقاً عنه

وهذه المشكلة لا تخص Flagsmith، وإنما تخص كل إعداد يجمع قرارات كثيرة في قيمة واحدة. والحل أن تقسم الإعداد بحسب القرار، كما تبين الصورة التالية:

على اليمين قيمة الإنتاج بعد إضافة stc_pay بحد 150 وأربع وسائل، ونسخة pro_customers القديمة بحد 0 وثلاث وسائل دون stc_pay، ونسخة user-42 القديمة بحد 200 بدل 150 ووسيلة mada، وتحتها أن أفضل العملاء لا يرون وسيلة الدفع الجديدة، وعلى اليسار الحل: مفتاح لكل قرار، free_shipping_threshold بقيمة 150 وتجاوز pro_customers يغيره إلى 0 فقط، وpayment_methods قائمة واحدة للجميع دون تجاوزات، وmax_cart_items رقم int وليس نصاً، وتجاوز العميل الواحد مؤقت يكتب سببه وتاريخ حذفه في التذكرة
كل مفتاح يحمل قراراً واحداً، والتجاوز يغير ما يختلف فقط

فحد الشحن ميزة مستقلة، والتجاوز للخطة المدفوعة يغيره وحده، ووسائل الدفع قائمة واحدة لا تتجاوزها أي مجموعة، فإذا أضفت وسيلة وصلت إلى الجميع. وتجاوز العميل الواحد حالة مؤقتة بطبيعتها، فاكتب سببه وتاريخ حذفه في تذكرة الدعم، وراجع قائمة الهويات التي لها تجاوزات كل شهر، لأن هذه التجاوزات لا تظهر في أي مكان آخر، وتبقى سنوات إذا نسيها أحد.

قيمة جديدة لعشرة بالمئة أولاً Config Canary

بعد التقسيم أنشأنا الميزة free_shipping_threshold وحدها بقيمة 150، وأراد قسم المبيعات أن يجرب حداً أقل، 120 ريالاً، على عشرة بالمئة من العملاء قبل أن يعممه، وهذا هو الإطلاق التدريجي نفسه، ولكن لقيمة وليس لمسار في الكود. فأضفنا تجاوزين: مجموعة الخطة المدفوعة بقيمة صفر، ومجموعة نسبتها 10% اسمها config_canary_10 بقيمة 120، وكانت النتيجة الأولى كما يلي:

free_shipping_threshold created, stored as int 150
overrides: pro_customers -> {'type': 'unicode', 'string_value': '0', 'integer_value': 150, 'boolean_value': None} | config_canary_10 -> {'type': 'unicode', 'string_value': '120', 'integer_value': 150, 'boolean_value': None}

وهنا ظهرت مشكلة النوع مرة ثانية، وفي مكان لم نتوقعه. فقيمة البيئة رقم صحيح لأننا أنشأناها من النص 150 فخمن Flagsmith نوعها، أما التجاوزان فخزنا نصين، '0' و'120'، لأن دالة التجاوز في ملفنا كانت ترسل كل قيمة بالنوع unicode. أي أن العميل العادي سوف يحصل على رقم، وعميل الخطة المدفوعة على نص، في المفتاح نفسه. فأضفنا الدالة typed التي رأيتها في ملف المساعدة، وهي ترسل الرقم بالنوع int، وأعدنا إنشاء التجاوزين، ثم قيمنا المفتاح لألف عميل، كل عاشر منهم بالخطة المدفوعة:

fixed overrides: pro_customers -> {'type': 'int', 'string_value': None, 'integer_value': 0, 'boolean_value': None} | config_canary_10 -> {'type': 'int', 'string_value': None, 'integer_value': 120, 'boolean_value': None}
{
  'free -> 150 (number)': 814,
  'pro -> 0 (number)': 100,
  'free -> 120 (number)': 86
}

في المخرج أعلاه لاحظ التالي:

  • كل القيم أرقام الآن، في البيئة وفي التجاوزين، وهذا ما يجب أن تتحقق منه بعد أي سكربت يكتب في Flagsmith.
  • كل عملاء الخطة المدفوعة المئة أخذوا الصفر، ولم يدخل أحد منهم مجموعة التجربة، لأن تجاوز المجموعة الأول في الترتيب يفوز، وأنشأنا تجاوز الخطة المدفوعة أولاً. فإذا عكست الترتيب فسوف يدفع بعض أفضل عملائك ثمن الشحن في التجربة.
  • 86 من 900 عميل عادي رأوا الحد الجديد، أي قرابة 9.6%، وسوف يبقون في المجموعة نفسها عندما ترفع النسبة، لأن الهاش ثابت كما رأينا في Unleash.

وبهذا تستطيع أن تقارن المبيعات ومتوسط السلة بين المجموعتين قبل أن تعمم الحد، ولكن المقارنة الصادقة تحتاج إلى أكثر من عد العملاء، وهو موضوع المقال القادم.

ماذا لو استخدمنا التقييم البعيد؟ What If

في التقييم المحلي يجلب ال SDK وثيقة البيئة Environment Document كاملة ويقيم في الذاكرة. والبديل هو التقييم البعيد Remote Evaluation، حيث يرسل ال SDK لكل عميل طلباً إلى Flagsmith مع صفاته، وهو الوضع الافتراضي إذا لم تفعل enableLocalEvaluation. فقسنا الفرق لعشرين عميلاً، وأرسلنا مع كل عميل صفتين: الخطة والبريد، كما يفعل كثير من المطورين عندما يمررون كائن المستخدم كاملاً:

identities stored in production: 1 ['user-42']
$ node local-eval-time.mjs
20 local evaluations took 10.2 ms
identities stored in production: 1 ['user-42']
$ node remote-eval.mjs
20 remote evaluations took 1507 ms
identities stored in production: 21 ['user-42', 'user-1', 'user-2', 'user-3', 'user-4', 'user-5']
traits stored for user-3: [('plan', 'free'), ('email', '[email protected]')]

في المخرج أعلاه لاحظ أمرين. الأول السرعة: عشرون تقييماً محلياً في 10 ملي ثانية، والعشرون أنفسهم عن بعد في ثانية ونصف، أي نحو 75 ملي ثانية تضاف إلى كل طلب دفع، والخادم على الجهاز نفسه، فكيف إذا كان في شبكة أخرى. والثاني الأهم: التقييم البعيد أنشأ هوية Identity محفوظة لكل عميل في قاعدة بيانات Flagsmith، وحفظ معها صفاته، ومنها البريد الإلكتروني. أي أن أداة ال Flags صارت تحمل نسخة من بيانات عملائك الشخصية، يراها كل من يفتح صفحة Identities في اللوحة، وتحتاج إلى أن تعاملها كقاعدة بيانات فيها بيانات شخصية، في النسخ الاحتياطي والصلاحيات ومدة الحفظ. أما التقييم المحلي فلم ينشئ هوية واحدة، لأن الصفات بقيت داخل تطبيقك. والصورة التالية تلخص الفرق:

عمودان: التقييم المحلي Local Evaluation بمفتاح ser 10.2 ms لعشرين عميلاً بعد تحميل القواعد، والهويات المخزنة من 1 إلى 1 والصفات تبقى داخل تطبيقك، ولكن مفتاح السيرفر يجلب البيئة كلها: segments pro_customers وcheckout_rollout وidentity_overrides ل user-42، ومفتاح العميل يرد HTTP 403، لذلك مكانه السيرفر فقط، والتقييم البعيد Remote Evaluation بطلب POST لكل نداء 1507 ms للعشرين أنفسهم أي نحو 75 ms لكل طلب، والهويات من 1 إلى 21 وكل عميل يصبح هوية محفوظة مع صفاته plan وemail، ولا ترسل صفة لا تحتاج إليها القواعد
التقييم المحلي أسرع، ويبقي صفات العملاء عندك

ولكن للتقييم المحلي ثمناً أيضاً، فقد طلبنا وثيقة البيئة بمفتاح السيرفر ثم بمفتاح البيئة العادي:

keys: ['allow_client_traits', 'api_key', 'feature_states', 'hide_disabled_flags', 'hide_sensitive_data', 'id', 'identity_overrides', 'name', 'project', 'updated_at', 'use_identity_composite_key_for_hashing', 'use_identity_overrides_in_local_eval']
segments: ['pro_customers', 'checkout_rollout']
identity_overrides: [('user-42', [('checkout_config', '{"free_shipping_threshold":200,"payment_methods":["mada"],"max_items":50}')])]
size bytes: 4240
same document with the client key: HTTP 403

الوثيقة فيها كل المجموعات بشروطها، وكل تجاوزات العملاء بأسمائهم، وهذا ما يجعل مفتاح السيرفر سراً كما ذكرنا في مقال المفهوم. وإذا كان عندك آلاف التجاوزات لعملاء، فهي كلها في الذاكرة في كل سيرفر، وتجلب مع كل تحديث، فاجعل تجاوز العميل الواحد استثناء وليس طريقة عمل. ويرفض الخادم الوثيقة بمفتاح البيئة العادي، وهو المفتاح الذي يوضع في المتصفح والجوال، وهذا هو التصميم الصحيح. وإذا كان عندك تطبيقات كثيرة تحتاج إلى الوثيقة نفسها، فهناك Edge Proxy تقف بينها وبين الخادم، كما رأينا مع Unleash Edge.

حدود النسخة المفتوحة Open Source Limits

يقول المستودع إن أغلب الكود بترخيص BSD-3-Clause، ويقول سؤال النسخة المفتوحة في التوثيق إن الأدوار RBAC والدخول الموحد SAML في النسخة التجارية، وإن ميزاتها مغلقة المصدر وتحتاج إلى رخصة. ولكننا وجدنا على خادمنا حدوداً أخرى لم نقرأها في أي صفحة، فبدأنا بطلب بيانات الاشتراك من الخادم نفسه:

organisation subscription: OK {"max_seats": 1, "max_api_calls": 50000, "max_projects": 1, "payment_source": null, "chargebee_email": null, "feature_history_visibility_days": 7, "audit_log_visibility_days": 0}
audit log entries: 0
change request: HTTP 405
second project: HTTP 403 {"detail":"You do not have permission to perform this action."}

الخادم المستضاف ذاتياً يعامل المؤسسة كأنها على الخطة المجانية، وهذا له ثلاث نتائج رأيناها فعلاً:

  • مشروع واحد لكل مؤسسة: إنشاء مشروع ثان رد ب 403 «ليست لديك صلاحية» رغم أننا مدير المؤسسة، وهي رسالة مضللة. وقرأنا السبب في كود الخادم نفسه داخل الصورة، في projects/permissions.py: الصلاحية ترفض إذا بلغ عدد المشاريع حد الاشتراك، والحد في الخطة المجانية MAX_PROJECTS_IN_FREE_PLAN = 1. والحل الذي نجح معنا أن تنشئ مؤسسة ثانية، فأنشأنا مؤسسة Shop payments ومشروعاً فيها دون مشكلة، ولكن هذا يعني أن الفريق والمفاتيح والمجموعات منفصلة بين المؤسستين.
  • سجل التدقيق مسجل ومخفي: طلب سجل التدقيق Audit Log أعاد صفر مدخلات، بينما في قاعدة البيانات 35 سطراً في جدول audit_auditlog. والسبب في audit/views.py: الخادم يعرض السجل للأيام التي يسمح بها الاشتراك فقط، وهي صفر. أي أن سؤال «من غير حد الشحن أمس؟» لا تجيب عنه اللوحة، وإنما استعلام SQL مباشر على قاعدة البيانات. وتاريخ الميزة نفسه يظهر سبعة أيام فقط.
  • طلبات التغيير والجدولة: نقطة إنشاء طلب التغيير ردت ب 405، ويقول توثيق النسخة التجارية إن طلبات التغيير Change Requests والجدولة Flag Scheduling في صورها الخاصة، رغم أن اللوحة في النسخة المفتوحة تعرض قائمتي Scheduling وFeature Change Requests كما رأيت في الصورة.
audit_auditlog rows in the database: 35
second organisation 2 -> project 2 payments

أما المقاعد فلم تمنعنا رغم أن الاشتراك يقول مقعداً واحداً، فقد أنشأنا رابط دعوة، وسجل مطور ثان وانضم به، وأصبح في المؤسسة عضوان. ولكن الدعوة بالبريد ردت ب 500، وسجل الخادم يقول ConnectionRefusedError عند الاتصال ب SMTP، لأننا لم نعد البريد، فإذا أردت الدعوات بالبريد فأضف إعداد SMTP في متغيرات البيئة، أو استخدم روابط الدعوة. والصورة التالية تلخص ما وجدناه:

عمودان: يعمل في النسخة المفتوحة: ال Flags والإعدادات عن بعد Remote Config، والبيئات والمجموعات Segments والتجاوزات، والقيم المتعددة Multivariate بنسب، والتقييم المحلي مع تجاوزات العملاء، وأعضاء فريق برابط دعوة دون حد للمقاعد، والكود بترخيص BSD-3-Clause في أغلبه، ومحدود أو غير موجود: مشروع واحد لكل مؤسسة Organisation مع POST projects يرد 403، وسجل التدقيق مسجل ومخفي صفر يوم مع audit 0 shown و35 rows in DB، وتاريخ الميزة يظهر 7 أيام فقط، وطلبات التغيير والجدولة في صور Enterprise مع create-change-request يرد 405، وSAML وLDAP وأدوار RBAC، والدعوة بالبريد تحتاج إلى SMTP
الإعداد عن بعد كامل في النسخة المفتوحة، والحوكمة ليست فيها

ويذكر توثيق التحديث الفوري أن التحديث الفوري Real-time Flags يحتاج إلى اشتراك Enterprise، ويذكر توثيق الجدولة أنها في خطط Scale-up وEnterprise. فإذا أراد فريق المبيعات أن يبدأ تخفيض الشحن مساء الخميس تلقائياً، فإما أن يغيره أحدهم بيده في الموعد، أو أن تكتب مهمة مجدولة Cron Job تستدعي ال API بسكربت مثل الذي كتبناه، وتسجل ما فعلته في سجلاتك أنت، لأن سجل التدقيق في اللوحة لن يعرضه.

التنظيف Cleanup

docker rm -f wr-ff-flagsmith-app
docker compose -p wr-ff-flagsmith down -v

قصة من الواقع: إعداد وصل إلى الجميع دفعة واحدة CrowdStrike

في 19 يوليو 2024 الساعة 04:09 بتوقيت UTC نشرت CrowdStrike تحديثاً لبرنامج الحماية على أجهزة Windows، ولم يكن التحديث كوداً جديداً، وإنما ما تسميه الشركة محتوى استجابة سريعة Rapid Response Content، أي بيانات إعداد يقرؤها البرنامج الموجود ليعرف أي سلوك يراقب. وبحسب التقرير الأولي للحادثة كان في المحتوى قالبان، وبسبب خطأ في أداة التحقق Content Validator مر أحدهما رغم أن بياناته فيها مشكلة، فوصل إلى الأجهزة، وتعطلت أجهزة Windows التي استقبلته وهي تعمل، حتى سحبت الشركة التحديث الساعة 05:27، أي بعد 78 دقيقة.

وما يهمنا هنا هو ما التزمت به الشركة بعد الحادثة، لأنه قائمة تصلح لأي إعداد عن بعد: أن تنشر هذا المحتوى تدريجياً بدءاً بنشر كناري Canary ثم لأجزاء أكبر، وأن تضيف فحوصاً إلى أداة التحقق، وأن تحسن معالجة الأخطاء في البرنامج الذي يقرأ المحتوى، وأن تعطي العملاء تحكماً في موعد وصول هذه التحديثات. وهي ثلاث طبقات رأيناها كلها في تجربتنا الصغيرة: تحقق قبل الحفظ، وكود يرفض القيمة السيئة ولا يتعطل، وإطلاق القيمة الجديدة لعشرة بالمئة أولاً. والدرس أن البيانات التي تغير سلوك برنامج يعمل هي جزء من الإصدار، حتى لو لم تمر بخط CI، فعاملها بالحذر نفسه.

الإعداد في Git أم في Flagsmith؟ Config as Code

بعد كل ما رأيناه قد يتساءل البعض: لماذا لا نبقي الإعداد في ملف داخل المستودع، كما كان، ونجعل نشره سريعاً؟ والإجابة أن الخيارين صحيحان، ولكل منهما ثمن، والفرق يظهر في ثلاثة أسئلة يطرحها الفريق عند كل مفتاح:

  • من يغير القيمة؟ إذا كان المطور، فالملف في Git أفضل، لأن التغيير يمر بمراجعة الكود والاختبارات، ويبقى في تاريخ المستودع للأبد. وإذا كان قسم المبيعات أو الدعم الفني، فلا تطلب منهم أن يكتبوا طلب دمج لتغيير رقم، فهذا يجعل المطور وسيطاً لكل قرار تسويقي.
  • كم مرة تتغير؟ القيمة التي تتغير مرة في الشهر لا تستحق خدمة إضافية في طريق كل طلب، والقيمة التي تتغير كل عطلة نهاية أسبوع، أو تحتاج إلى قيمة مختلفة لمجموعة من العملاء، هي ما صنع له الإعداد عن بعد.
  • هل تحتاج إلى سجل يعتمد عليه؟ Git يعطيك من غير ماذا ومتى ولماذا في كل سطر، أما Flagsmith المفتوح فرأينا أنه لا يعرض سجل التدقيق، فإذا كان المفتاح يؤثر في المال أو في الالتزام بنظام، فإما أن يبقى في Git، أو أن تكتب تغييراته عبر سكربت يحفظ سجله في مكان تعتمد عليه.

والحل الذي اختاره فريق المتجر في النهاية جمع بين الاثنين: القيم التقنية في Git مع الكود، وقيم العمل في Flagsmith، ودالة التحقق لكل مفتاح في الكود نفسه، ومعها القيمة الافتراضية، فتمر حدود كل قيمة بمراجعة الكود، ويبقى تغيير القيمة داخل هذه الحدود سريعاً بيد من يملك القرار. وهذا التقسيم يعني أن أسوأ ما يستطيع أن يفعله شخص في اللوحة محدود بما سمح به الكود، وهو ما رأيناه عندما رفض المتجر وسيلة دفع لا يعرفها.

قواعد الإعداد عن بعد في الفريق Team Rules

بعد التجربة كتب فريق المتجر قواعد الإعداد عن بعد، وهي تختلف عن قواعد ال Release Flags التي كتبوها مع Unleash، لأن الإعداد يعيش طويلاً ويغيره أشخاص ليسوا مطورين:

  • كل مفتاح له مالك وشكل مكتوب: الوصف يقول من يغير القيمة، وما نوعها، وما حدودها، مثل «حد الشحن، رقم صحيح من 0 إلى 1000، يملكه قسم المبيعات».
  • التحقق في الكود قبل أي استخدام: دالة واحدة لكل مفتاح تحول القيمة إلى نوعها وتتحقق منها وتعيد آخر قيمة سليمة، ولا يقرأ أحد القيمة مباشرة من ال SDK.
  • الرفض يصل إلى من كتب: سطر الرفض في السجلات عليه تنبيه يصل إلى قناة القسم الذي يملك المفتاح، وليس إلى مناوب التشغيل فقط.
  • التغيير الكبير يمر ب staging أولاً ثم بنسبة صغيرة: وسيلة دفع جديدة أو تغيير في شكل JSON يجرب في staging، ثم في الإنتاج لمجموعة 10% قبل الجميع، كما فعلنا مع STC Pay وحد الشحن.
  • لا أسرار ولا قيم تقنية: مفاتيح بوابة الدفع وعناوين الخدمات ليست إعداداً عن بعد.
  • الصفات بأقل قدر: لا ترسل إلى Flagsmith إلا الصفات التي تحتاج إليها قواعد المجموعات، مثل الخطة، ولا ترسل البريد أو رقم الجوال.

ولاحظ أن القاعدة الثانية هي الأهم بين كل ما في هذا المقال. فكل المشاكل التي رأيناها، الحرف O بدل الصفر، والنص بدل الرقم، والقوس الناقص، ووسيلة الدفع المكتوبة خطأ، اختفت من المتجر بدالة واحدة من عشرين سطراً، ولم يحتج أي منها إلى ميزة في الأداة.

أخطاء شائعة Common Mistakes

  • JSON.parse مباشرة على القيمة: قوس ناقص يوقف كل طلب يقرؤها.
  • الثقة بنوع القيمة: Flagsmith يخمن النوع في اللوحة، ويأخذه كما هو من ال API، فحول القيمة وتحقق منها في الكود.
  • إعداد كبير واحد مع تجاوزات: كل تجاوز نسخة كاملة تتأخر عن الأصل، فقسم الإعداد بحسب القرار.
  • تجاوزات عملاء دون تاريخ حذف: تبقى سنوات، وتكبر وثيقة البيئة في كل سيرفر.
  • التقييم البعيد مع صفات شخصية: كل عميل يصبح هوية محفوظة مع بريده في أداة ال Flags.
  • ظن أن سجل التدقيق يعمل: في النسخة المفتوحة يظهر صفر يوم، والسجل الحقيقي في قاعدة البيانات.
  • إيقاف الترحيل الأول لأنه unhealthy: 616 خطوة تحتاج إلى بضع دقائق، والفحص لا يخص هذه الخدمة.
  • أسرار في الإعداد عن بعد: كل من يفتح اللوحة يراها، وكل سيرفر يحملها في ذاكرته.

قائمة تحقق قبل الإنتاج Checklist

البندكيف تتحقق
كل مفتاح إعداد له دالة تحققابحث في الكود عن getFeatureValue، ويجب أن يكون داخل دالة التحقق فقط
القيمة السيئة لا توقف الطلباتاحفظ JSON ناقصاً في staging، ويجب أن تبقى الطلبات 200 ويظهر سطر رفض واحد
سطر الرفض عليه تنبيهالقيمة السيئة في staging تصل إلى قناة مالك المفتاح
القيمة الافتراضية في الكود محافظةعملية جديدة مع قيمة سيئة تعمل بالقيم المجربة
التقييم محلي، والمفتاح في الأسرارenableLocalEvaluation: true، ومفتاح ser. ليس في كود المتصفح
لا صفات شخصيةصفحة Identities فارغة أو لا تحتوي على بريد أو جوال
تجاوزات العملاء مراجعةقائمة شهرية بالهويات التي لها تجاوزات وتذكرة لكل منها
من غير ماذااستعلام على audit_auditlog أو سجل التغييرات في سكربتك، لأن اللوحة لا تعرضه
نسخة احتياطية لقاعدة البياناتاستعادة مجربة كما في قاعدة 3-2-1
التسجيل مغلقمحاولة إنشاء حساب جديد ترفض بعد إنشاء حسابات الفريق

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • الإعداد عن بعد يغير قيم الإنتاج دون نشر، وهو مناسب لقرارات العمل مثل حد الشحن ووسائل الدفع، وليس للقيم التقنية أو الأسرار.
  • في Flagsmith لكل ميزة مفتاح وقيمة لكل بيئة، وتجاوز العميل يفوز على تجاوز المجموعة، وهذا يفوز على قيمة البيئة، والتقييم المحلي يحمل الثلاثة.
  • Flagsmith يخمن النوع من نص اللوحة، ويأخذه كما هو من ال API، فحرف O بدل الصفر ألغى حد السلة، وإرسال "100" بدل 100 جعل الجمع يعطي 1001.
  • قيمة JSON ينقصها قوس أوقفت كل طلبات الدفع، كما عطل إعداد واحد أجهزة عملاء CrowdStrike في 2024، ودالة تحقق تحتفظ بآخر قيمة سليمة أبقت المتجر يعمل في كل الحالات.
  • التجاوز ينسخ الإعداد كاملاً، فلم يصل STC Pay إلى عملاء الخطة المدفوعة، والحل مفتاح لكل قرار.
  • التقييم البعيد أبطأ بنحو 75 ملي ثانية لكل طلب، وحفظ هوية كل عميل مع بريده في Flagsmith.
  • النسخة المفتوحة تعطي مشروعاً واحداً لكل مؤسسة، وتخفي سجل التدقيق، ولا تعطي طلبات التغيير ولا الجدولة.

وفي المقال القادم من هذه السلسلة بإذن الله نسأل السؤال الذي بقي معلقاً منذ النسختين one_page وtwo_steps: أيهما يبيع أكثر؟ ونجيب عنه بالأرقام مع GrowthBook. والمقالات المرتبطة بهذا المقال:

دليلFeature Flags: انشر الكود وفعل الميزة لاحقاًكيف يفصل ال Feature Flag بين نشر الكود وإطلاق الميزة، وكيف تطلقها لجزء من المستخدمين أولاً وتوقفها فوراً إذا تعطلت.دليلإدارة الأسرار Secrets Manager: OpenBao أم Infisical؟نشغل OpenBao ثم Infisical على المسار نفسه، من هوية التطبيق إلى كلمات مرور تنتهي وحدها وسجل يقول من قرأ السر، ونرى ما تعطيه كل أداة دون رخصة.دليلالتنبيهات Alerting: ماذا تنبه عليه ومتى توقظ أحداً؟نبني مع Alertmanager تنبيهات تصل فيها المشكلة الواحدة في رسالة واحدة، والعاجل فوراً والروتيني في ملخص صباحي، ونجرب كل قرار بالثواني.دليلالسجلات Logging للمطورين: ماذا تسجل وماذا لا تسجلكيف تكتب سجلات Logs تساعدك على فهم ما حدث في الإنتاج، وما الذي لا يدخل السجل أبداً، وكيف تجمعها في مكان واحد.

تدريب عملي Practice

  1. شغل Flagsmith بملف Compose أعلاه، وأنشئ ميزة رقمية من اللوحة وأخرى بالقيمة نفسها من ال API بين علامتي تنصيص، وقارن ما يصل إلى الكود من كل منهما.
  2. اكتب دالة تحقق لمفتاح إعداد من مشروعك، ثم احفظ فيه خمس قيم خاطئة مختلفة، وتأكد أن كل واحدة تكتب سطر رفض واحداً وأن الطلبات لا تفشل.
  3. قسم إعداداً كبيراً فيه تجاوزات إلى مفاتيح صغيرة، ثم غير قيمة البيئة لكل مفتاح، وتأكد أن المجموعات ترى التغيير إلا في المفتاح الذي تتجاوزه.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال وتنفيذ التجربة على Flagsmith 2.288.2 مع PostgreSQL 18 ومعالج المهام، وflagsmith-nodejs 8.1.2 على Node.js 22.23.4، على Docker Engine 29.8.0، ومراجعة حدود النسخة المفتوحة في كود الخادم والتوثيق في 5 نوفمبر 2026.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.