الـ ADRs والـ Feature Flags: القرارات المكتوبة والـ rollout من غير deploy

أهلًا بيك. النهارده حاجتين بيبانوا مش مرتبطين، بس الاتنين عن نفس السؤال: إزاي تغيّر system شغال بأمان، وتفتكر ليه غيّرته. الـ feature flags والـ ADRs. بص على checkout dot naive dot js. checkout جديد عايزين نجرّبه على خمسة في المِيّة، و beta للـ team، و flag قديم، وقرار مهم. الـ flag جاي من env variable، فعشان تقفله لازم deploy. والـ feature لو بتكسر الـ checkout، كل دقيقة بفلوس. الخمسة في المِيّة بـ Math dot random في كل request. نفس الـ user يشوف الجديد، يعمل refresh، يشوف القديم. والـ cart بيتلخبط، والـ metrics بتاعة التجربة ملهاش معنى. الـ beta list مكتوبة في الـ code، فأي حد جديد محتاج deploy. الـ flag القديم: الـ rollout خلص من سنتين، والـ code لسه فيه الفرعين، ومحدش عارف يشيله ولا لأ. والقرار: اتكتب في Slack thread، والـ thread اتمسح، والـ engineer اللي أخده مشي.

أول فكرة: الـ deploy غير الـ release. الـ deploy إنك تنزّل code جديد على الـ servers. الـ release إن الـ users يشوفوا الـ feature. من غير flags، الاتنين حاجة واحدة: الـ code نزل، يبقى الكل شايفه. ومع الـ flags، الـ code بينزل مقفول، وبعدين تفتحه لنفسك، وبعدين للـ team، وبعدين لواحد في المِيّة، وتراقب الـ metrics، وتكبّر. ولو حاجة بازت، تقفل على طول من غير deploy ولا rollback. وده كمان اللي بيخلّي trunk-based development ممكن: الكل بيعمل merge على main كل يوم، والحاجات اللي لسه مش خلصانة مستخبية ورا flag.

الـ flags مش نوع واحد، وكل نوع ليه عمر مختلف. release flag: بيخبّي feature لحد ما تخلص وتنزل. عمره أيام أو أسابيع، ولازم يتشال بعدها. experiment flag: A و B، عشان تقيس أنهي أحسن. عمره قد التجربة. ops flag أو kill switch: يقفل حاجة تقيلة وقت الضغط، زي الـ recommendations أو الـ search المتقدّم. ده ممكن يعيش على طول، بس لازم يتجرّب. permission flag: feature للـ plan الـ premium أو لعميل معيّن. ده business logic، وأحيانًا مكانه الحقيقي الـ database مش الـ flag system. اكتب نوع كل flag وصاحبه وتاريخ انتهائه وقت ما تعمله. إزاي الـ flag بيقرر؟ الـ app بيبعت context: الـ user key، والـ email، والبلد، ونسخة الـ app، والـ plan. والـ flag فيه ترتيب: لو مقفول، الـ off variation، خلاص. لو الـ user ده بالاسم في الـ targets، ياخد اللي متحدّد له. ده للـ team ولعميل اشتكى وعايز تقفل عليه بس. بعدين الـ rules بالترتيب. زي: الـ email بيخلص بـ baassma dot tech، أو البلد مصر و نسخة الـ app خمسة أو أكتر. أول rule كل شروطها صح هي اللي بتكسب. ولو مفيش، الـ fallthrough، وده غالبًا الـ percentage rollout. والمهم: كل ده بيرجّع reason. FLAG_NOT_FOUND و OFF و TARGET و RULE و FALLTHROUGH. وقت الـ debugging، الـ reason ده بيوفّر عليك ساعات.

الـ percentage rollout، وده قلب الموضوع. Math dot random غلط، لأن نفس الـ user ياخد حاجة مختلفة كل مرة. الصح: hash. خد اسم الـ flag، و salt، و الـ user key، واعملهم sha256، وحوّل أول أربع bytes لرقم من صفر لمِيّة. ده الـ bucket بتاع الـ user ده للـ flag ده. الـ bucket ما بيتغيّرش، فنفس الـ user ياخد نفس الحاجة على كل server، ومن غير ما تخزّن حاجة. ولما تكبّر من خمسة لعشرين، اللي الـ bucket بتاعه أقل من خمسة لسه أقل من عشرين، فمحدش بيخرج. والـ salt بيخلّي كل flag يختار مجموعة مختلفة. من غيره، نفس الواحد في المِيّة هيبقوا فئران التجارب لكل feature. والـ key لازم ما يتغيّرش: الـ user id، مش الـ session. وللـ users اللي مش عاملين login، device id في cookie. والتجارب، A و B. نفس الـ rollout، بس بأكتر من variation، زي control نص، و A ربع، و B ربع. وعشان تحلّل النتيجة، لازم تعرف مين شاف إيه بالضبط. ده اسمه exposure event: لما الـ user يتقيّم في التجربة، ابعت event فيه الـ flag والـ variation والـ user. مرة واحدة، مش في كل request. ابعته لما الـ user فعلًا يشوف الحاجة، مش لكل الـ users في الـ startup، وإلا التحليل يتلخبط. وما تغيّرش الأوزان في نص التجربة، ولا تبص على النتيجة كل يوم وتوقف أول ما تعجبك. ده اسمه peeking، وبيطلّع نتايج غلط. حدّد حجم الـ sample قبل ما تبدأ.

الـ prerequisites. feature الـ wallet مبنية على الـ payments الجديدة. لو قفلت الـ payments، الـ wallet لازم تتقفل لوحدها. فالـ wallet flag بيقول: الـ prerequisite بتاعي payments لازم تكون on. ولو حد عمل cycle بالغلط، A محتاج B و B محتاج A، الـ engine ما يدخلش في loop للأبد، يرجّع error والـ default. وده كمان example لحاجة مهمة: الـ engine لازم ما يرميش exception أبدًا في الـ request. أي حاجة غريبة، الـ default اللي في الـ code، و reason بـ ERROR، و log.

دلوقتي الـ client جُوّه الـ app. ما تعملش network call لكل flag في كل request. الـ client بيجيب الـ flags كلها، يخزّنها في الـ memory، ويقيّم locally. وبيعمل refresh كل كام second، أو بـ streaming زي server-sent events. لو الـ flag service وقع، الـ client يفضل بآخر نسخة نجحت. ده اسمه last-known-good. والـ app ما يقعش أبدًا بسبب الـ flags. لو أول ما الـ app اشتغل ملقاش أي نسخة، يستخدم الـ defaults اللي في الـ code. فالـ default لازم يبقى الحاجة الآمنة، غالبًا الـ feature مقفولة. والـ version: لو نسخة أقدم وصلت متأخرة، اتجاهلها. ولو الـ flag رجّع type غلط، زي number والـ code مستني boolean، الـ default. والـ tools. فيه LaunchDarkly و Unleash و Flagsmith و GrowthBook و ConfigCat، ولكل واحد SDK. و OpenFeature هو standard من الـ CNCF: الـ code بتاعك بيكلّم API واحد، و provider تحته تقدر تغيّره. فما تبقاش مربوط بـ vendor. والأسامي اللي استخدمناها، زي reason و variation و targeting key، هي نفسها اللي في OpenFeature. والكلام اللي هنكتبه النهارده هو نفس فكرة الـ engine اللي جُوّه الـ SDKs دي. في الـ production، استخدم واحد منهم، بس هتبقى فاهم بيعمل إيه.

الـ flag debt. كل flag هو if جوّه الـ code. عشر flags يعني ألف وأربعة وعشرين احتمال للـ code، ومحدش بيعمل test لكلهم. وفيه قصة مشهورة: Knight Capital خسرت حوالي أربعمية وستين مليون دولار في خمسة وأربعين دقيقة سنة ألفين واتناشر، لأن flag قديم اتعاد استخدامه بمعنى جديد، و server واحد كان عليه الـ code القديم. فالقواعد: كل release flag ليه تاريخ انتهاء. tool بتلف على الـ flags: اللي عدّى تاريخه، واللي واخد مِيّة في المِيّة بقاله شهر من غير rules، واللي مقفول بقاله شهور، وتفتح tickets. لما تشيل flag، تشيل الـ code القديم كمان. وما تعيدش استخدام اسم flag قديم أبدًا.

ننتقل للـ ADRs. ADR يعني Architecture Decision Record. ملف markdown صغير، لكل قرار مهم واحد: ليه Postgres؟ ليه signed cookies مش Redis للـ sessions؟ ليه Kafka؟ الشكل المشهور من Michael Nygard: عنوان ورقم. status: Proposed، أو Accepted، أو Deprecated، أو Superseded. تاريخ. Context: الوضع كان إيه، وإيه الـ constraints، وإيه الاختيارات اللي كانت قدامنا. Decision: اخترنا إيه، بجملة واضحة. Consequences: هنكسب إيه، وهندفع تمن إيه. والجزء ده أهم جزء، لأنه بيقول للي جاي بعدك إنت كنت عارف الـ tradeoffs. إمتى تكتب ADR؟ لما القرار صعب ترجع فيه، أو بيفرق مع أكتر من team، أو حد هيسأل بعد سنة ليه عملنا كده. database، و protocol، و طريقة الـ auth، و monolith ولا services. مش لاسم variable. الـ ADRs بتعيش في الـ repo، في folder اسمه docs slash adr، وبتتعمل بـ pull request، فالـ review هو المناقشة نفسها. الـ ADR ما بيتعدّلش بعد ما يتقبل. لو القرار اتغيّر، تكتب ADR جديد، والقديم يبقى Superseded، ومعاه link للجديد. فتقدر تقرا تاريخ تفكير الـ team. والـ CI يعمل lint: كل ADR فيه الـ sections، والـ status صح، والـ links مش مكسورة، ومفيش رقمين زي بعض.

التحدي. عندك lab dot js بيحكي قصة الـ checkout الجديد من أول واحد في المِيّة لحد الـ kill switch، وبعدين الـ ADRs، و test dot js. والمطلوب flags dot js. كل التفاصيل في الكومنت: bucket، و evaluate بالترتيب كامل والـ reasons، والـ rollout، والـ prerequisites والـ cycle، و createFlagClient بالـ last-known-good والـ versions والـ types والـ exposures، و staleFlags، و parseAdr و lintAdrs. اقرا الكومنت كويس، ونشغّل test dot js لحد ما تبقى أربعتاشر من أربعتاشر.

الحل. bucket: أول أربع bytes من الـ sha256، مقسومين على أكبر رقم، في مِيّة. evaluate: نفس الترتيب بالضبط، وكل خطوة بترجّع reason. والـ prerequisites بتنادي evaluate تاني، ومعاها Set بالـ keys اللي اتقيّموا، فالـ cycle بيبان. الـ client: الـ flags في متغيّر واحد بيتبدّل كله مرة واحدة، فمفيش request يشوف نص نسخة. والـ catch بيسجّل الـ error ويسيب القديم. والـ ADRs: parser بسيط بالسطور، والـ lint بيلف مرتين: مرة لكل ADR لوحده، ومرة للـ links بين بعض. نشغّل lab dot js.

// flags.js: feature flags بالـ targets والـ rules والـ rollout الثابت والـ prerequisites، و client بـ last-known-good والـ exposures، و flag debt، و lint للـ ADRs
// lab.js و test.js بيعملوا import من هنا: bucket و evaluate و createFlagClient و staleFlags و parseAdr و lintAdrs
import { createHash } from "node:crypto";

export function bucket(flagKey, salt, contextKey) {
  const h = createHash("sha256").update(`${flagKey}.${salt}.${contextKey}`).digest();
  return (h.readUInt32BE(0) / 2 ** 32) * 100;
}

const OPS = {
  in: (v, values) => values.includes(v),
  notIn: (v, values) => !values.includes(v),
  endsWith: (v, values) => typeof v === "string" && values.some((s) => v.endsWith(s)),
  gte: (v, values) => typeof v === "number" && v >= values[0],
  lt: (v, values) => typeof v === "number" && v < values[0],
};

const matches = (clause, ctx) => {
  const op = OPS[clause.op];
  if (!op) return false;
  const v = ctx[clause.attribute];
  return v !== undefined && op(v, clause.values);
};

function pick(flag, serve, ctx) {
  if (serve.variation !== undefined) return { variation: serve.variation, inRollout: false };
  if (ctx.key === undefined || ctx.key === null) return null;
  const b = bucket(flag.key, flag.salt ?? flag.key, ctx.key);
  let sum = 0;
  for (const w of serve.rollout) {
    sum += w.weight;
    if (b < sum) return { variation: w.variation, inRollout: true };
  }
  return { variation: serve.rollout.at(-1).variation, inRollout: true };
}

export function evaluate(flags, key, ctx = {}, defaultValue, seen = new Set()) {
  const flag = flags[key];
  if (!flag) return { value: defaultValue, variation: null, reason: "FLAG_NOT_FOUND" };
  if (seen.has(key)) return { value: defaultValue, variation: null, reason: "ERROR", error: "PREREQUISITE_CYCLE" };
  const out = (variation, reason, extra = {}) => ({ value: flag.variations[variation], variation, reason, ...extra });
  if (!flag.on) return out(flag.offVariation, "OFF");
  for (const pre of flag.prerequisites ?? []) {
    const r = evaluate(flags, pre.key, ctx, undefined, new Set([...seen, key]));
    if (r.reason === "ERROR") return { ...r, value: defaultValue };
    if (r.variation !== pre.variation) return out(flag.offVariation, "PREREQUISITE_FAILED", { prerequisite: pre.key });
  }
  for (const [variation, keys] of Object.entries(flag.targets ?? {})) {
    if (keys.includes(ctx.key)) return out(variation, "TARGET");
  }
  for (const [i, rule] of (flag.rules ?? []).entries()) {
    if (rule.clauses.every((c) => matches(c, ctx))) {
      const p = pick(flag, rule, ctx);
      if (!p) return { value: defaultValue, variation: null, reason: "ERROR", error: "MISSING_KEY" };
      return out(p.variation, "RULE", { ruleIndex: i, inRollout: p.inRollout });
    }
  }
  const p = pick(flag, flag.fallthrough, ctx);
  if (!p) return { value: defaultValue, variation: null, reason: "ERROR", error: "MISSING_KEY" };
  return out(p.variation, "FALLTHROUGH", { inRollout: p.inRollout });
}

export function c
…

$ node lab.js
① Math.random ضد bucket، نفس الـ user عشر مرات:
   random: new old old old new new old new old new
   bucket: new new new new new new new new new new

② الـ rollout خطوة خطوة:
     1% ←   11 user، واللي كانوا قبل كده فضلوا؟ true
     5% ←   44 user، واللي كانوا قبل كده فضلوا؟ true
    25% ←  240 user، واللي كانوا قبل كده فضلوا؟ true
    50% ←  499 user، واللي كانوا قبل كده فضلوا؟ true
   100% ← 1000 user، واللي كانوا قبل كده فضلوا؟ true

③ مين بياخد إيه وليه:
   ahmed    ← true (TARGET)
   sara     ← true (RULE rule 0)
   user-3   ← false (FALLTHROUGH)
   user-12  ← true (FALLTHROUGH)

④ الـ error rate زاد، الـ kill switch:
   قبل: true
   بعد ما قفلناه: {"value":false,"variation":"off","reason":"OFF"} من غير deploy
   الـ flag service وقع: {"version":2,"lastError":"ECONNREFUSED","flags":1} ← القيمة لسه: false
   exposures اتبعتت: 1

⑤ الـ flag debt:
   [{"key":"redis-sessions","why":"FULLY_ROLLED_OUT"}]

⑥ الـ ADRs في الـ CI:
   ADR-0001 Accepted   Postgres as the primary database
   ADR-0002 Superseded Redis for sessions ← ADR-0003
   ADR-0003 Accepted   Signed cookies for sessions
   ADR-0004 Approved   Kafka
   errors: ["ADR-0004 BAD_STATUS","ADR-0004 MISSING_SECT
…

الأول: Math dot random لنفس الـ user طلّع new و old متلخبطين، و bucket طلّع نفس الحاجة العشر مرات. التاني: من واحد لمِيّة في المِيّة، وكل مرة اللي كانوا جوّه فضلوا جوّه. التالت: أحمد بالـ target، و سارَة بالـ rule بتاعة الـ email، والباقي بالـ bucket. الرابع: قفلنا الـ flag، والـ client شاف النسخة الجديدة من غير deploy. والـ service وقع، والـ app فضل شغال بآخر نسخة. الخامس: flag الـ Redis sessions بقاله سنتين مِيّة في المِيّة، يتشال. والسادس: الـ lint مسك ADR بـ status غلط ومن غير Consequences. ونشغّل test dot js.

$ node test.js
✅ 1 bucket: نفس الـ user نفس الرقم، والـ salt والـ flag بيغيّروه، وكله بين صفر ومِيّة ["54.592","54.592","73.485","0.523"]
✅ 2 flag مقفول ← offVariation، و flag مش موجود ← الـ default [{"value":false,"variation":"off","reason":"OFF"},{"value":"fallback","variation":null,"reason":"FLAG_NOT_FOUND"}]
✅ 3 الترتيب: targets، وبعدين الـ rules بالترتيب (كل الـ clauses)، وبعدين الـ fallthrough [[true,"TARGET"],[false,"TARGET"],[true,"RULE"],[true,"RULE"],[false,"FALLTHROUGH"],[false,"FALLTHROUGH"],[false,"FALLTHROUGH"]]
✅ 4 rollout بالنسبة: صفر وخمسة وعشرين ومِيّة في المِيّة تقريبًا [0,512,1968,10000]
✅ 5 الـ rollout ثابت: اللي كانوا في الخمسة فضلوا في العشرين، وتغيير الـ salt بيخلطهم {"five":512,"twenty":1968,"overlapAfterSalt":27}
✅ 6 A/B بتلات variations بالأوزان، والـ value من variations {"control":5069,"a":2465,"b":2466}
✅ 7 prerequisites: wallet محتاج payments، والـ cycle بيرجّع الـ default ["FALLTHROUGH","PREREQUISITE_FAILED",{"value":false,"variation":null,"reason":"ERROR","error":"PREREQUISITE_CYCLE"}]
✅ 8 rollout من غير key ← ERROR بالـ default، و op مش معروف ما بيعملش match [{"value":false,"variation":null,"reason":"ERROR","error":"MISSING_KEY"},{"value":false,"var
…

كله نجح. آخر درس في الـ section ده، وأصعبهم: multi-region active-active. نفس الـ data بتتكتب في القاهرة وفي فرانكفورت في نفس الوقت، والـ network بينهم ممكن يقع. هنعمل conflict resolution بجد: last-writer-wins و vector clocks و CRDTs.

// checkout.naive.js: feature flags زي ما بتتعمل أول مرة
import express from "express";
const app = express();

const NEW_CHECKOUT = process.env.NEW_CHECKOUT === "true"; // عشان تقفله لازم deploy جديد

app.get("/checkout", (req, res) => {
  // 5% من الـ users؟ Math.random في كل request: نفس الـ user يشوف القديم مرة والجديد مرة
  if (NEW_CHECKOUT && Math.random() < 0.05) return res.send("new checkout");
  // beta للـ team: list مكتوبة في الـ code
  if (["[email protected]", "[email protected]"].includes(req.query.email)) return res.send("new checkout");
  res.send("old checkout");
});

// flag من سنتين، الـ rollout خلص من زمان، ومحدش فاكر ليه لسه موجود
if (process.env.USE_REDIS_SESSIONS !== "false") {
  // ...
}

// وقرار زي "ليه Redis للـ sessions مش signed cookies؟" مكتوب في Slack thread اتمسح
app.listen(3000);