Feature Flags, Canary و Bounded Rollout

1. مسئله: Deployment با Activation یکی نیست

ممکن است Artifact جدید روی سرویس Deploy شده باشد، اما رفتار جدید هنوز خاموش باشد. کنترل دیگری می‌تواند همان رفتار را فقط برای یک Cohort محدود فعال کند. اگر Deployment، Activation و Exposure را یک «کلید انتشار» فرض کنیم، شواهد لازم برای تصمیم ایمن از بین می‌رود.

سؤال عملیاتی فقط این نیست که «نسخه 2 Deploy شده؟». باید بدانیم چه Artifactی حاضر است، Feature Flag چه مقداری resolve کرده، برای کدام Subject یا Cohort، با چه Rule، در چه Observation Window و بر پایه کدام Health Evidence.

Artifact این درس Bounded Rollout Control Record v1 است. این Record وضعیت‌ها را جدا نگه می‌دارد تا خروجی نهایی بتواند PROMOTE، HOLD، ROLLBACK یا UNKNOWN صریح باشد؛ نه یک عبارت مبهم مثل «به‌نظر خوب است».

2. Feature Flag Evaluation یک تصمیم Runtime است

Feature Flag Evaluation در زمان اجرا مقدار یک Flag را تعیین می‌کند. OpenFeature یک API مستقل از Vendor برای ارزیابی Flag تعریف می‌کند؛ Application مقدار را درخواست می‌کند و Provider آن را به سیستم مدیریت Flag متصل می‌کند.

از این موضوع نتیجه اضافه نگیریم. Evaluation API خودش به معنی یک Control Plane عمومی برای ساخت و ذخیره Flagها نیست. در Record باید Deployment State و Flag Resolution را در فیلدهای جدا ثبت کنیم.

حداقل داده مفید برای هر ردیف شامل Artifact Version، Deployment Evidence، Flag Key، Default Value، مقدار یا Variant Resolve شده، Evaluation Reason در صورت وجود و Evaluation Context است.

3. Targeting Context باید قابل بازتولید باشد

Targeting زمانی مفید است که بتوان عضویت Cohort را دوباره تولید کرد. Evaluation Context در OpenFeature می‌تواند Targeting Key و Context Fieldهای لازم برای Rule، Override یا Fractional Evaluation را حمل کند.

در Bounded Rollout مهم‌ترین ویژگی Determinism است: یک Subject مصنوعی با Context یکسان باید در ارزیابی‌های تکراری داخل همان Cohort بماند. اگر فرمت Targeting Key بین Requestها تغییر کند، درصد Rollout دیگر معنای قابل اتکایی ندارد.

Normalized Targeting Key، Attributeهای غیرحساس موردنیاز، Rule Identifier، Bucket/Cohort Result و Evidence لازم برای تکرار Classification را ثبت کن. این درس به داده شخصی واقعی نیاز ندارد؛ Synthetic ID کافی است.

4. Percentage سقف Exposure است، نه اثبات Safety

Canary Percentage فقط Blast Radius را محدود می‌کند. این عدد ثابت نمی‌کند Release سالم است. ممکن است Cohort پنج‌درصدی Feature Error جدی داشته باشد؛ یا Cohort بیست‌وپنج‌درصدی سالم باشد اما Bake Window لازم هنوز کامل نشده باشد.

Progressive Exposure یعنی گسترش مرحله‌ای به گروه‌های بزرگ‌تر. بنابراین Record باید Exposure Ceiling فعلی و Evidence لازم برای افزایش آن را مشخص کند.

به‌جای «10% پاس شد، پس امن است» بنویس: «10% Exposure در Window لازم مشاهده شد، Feature-Specific Health Gate پاس شد، Recovery Trigger فعال نشد و Policy اجازه مرحله بعد را می‌دهد.»

5. Canary Deployment را از Feature Activation جدا کن

Canary Deployment و Feature Flag دو کنترل مرتبط اما متفاوت‌اند. Platform می‌تواند Traffic را میان نسخه قدیم و جدید تقسیم کند. Feature Flag جداگانه تصمیم می‌گیرد رفتار داخل Artifact برای کدام Subject فعال باشد.

چند حالت ممکن است:

• Artifact جدید در Canary Deploy شده ولی Feature برای همه خاموش است؛
• Artifact جدید گسترده Deploy شده اما Feature فقط برای Cohort داخلی فعال است؛
• دو Artifact همزمان Traffic می‌گیرند و Feature فقط در بخشی از Traffic نسخه جدید فعال است؛
• Artifact کامل Deploy شده اما Activation به دلیل نبود Health Evidence متوقف است.

در Bounded Rollout Control Record v1 اگر هر دو وجود دارند، Deployment Share و Feature Exposure را جدا ثبت کن. آن‌ها را در یک «Rollout Percentage» ادغام نکن.

6. قبل از Health، Cohort را تعریف کن

Health Data فقط وقتی قابل تفسیر است که بدانیم چه جمعیتی Exposure گرفته است. قبل از تصمیم Health، Cohort Rule، Targeting Key Policy، Membership Proof، Exposure Start و Exposure Ceiling را ثبت کن.

Cohort باید Rule صریح و قابل بررسی داشته باشد: Synthetic Internal Users، Stable Hash Bucket، Region، Service Identity یا Attribute دیگری که بتوان از Evidence بازسازی کرد.

اگر Cohort Identity ناپایدار است، حتی با Aggregate Health سبز هم Progression را متوقف کن. در غیر این صورت Population مورد اندازه‌گیری در طول تصمیم تغییر می‌کند.

7. Feature-Specific Health Gate بساز

Deployment Health و Feature Health می‌توانند با هم فرق داشته باشند. Process ممکن است Up باشد و Global Latency طبیعی باشد، اما Path جدید فقط برای Cohort فعال‌شده Fail کند.

در حد امکان Health Gate باید Signal مخصوص همان Feature داشته باشد: Error Rate مسیر فعال، Latency Requestهای متاثر، Correctness Probe، Domain Outcome، Saturation یا Indicator مناسب دیگر. Gate باید Rule قابل دفاع داشته باشد، نه صرفاً رنگ سبز Dashboard.

Observed Signal و Decision مشتق‌شده از آن را جدا ثبت کن. Summary سبز Deployment جای Row-Level Evidence مربوط به Feature را نمی‌گیرد.

8. Bake Time یعنی جمع‌آوری Evidence

Bake Window فرصت می‌دهد Failureهای کند یا کم‌تکرار آشکار شوند. مدت آن یک Risk/Observability Choice است، نه عدد جهانی.

ممکن است Window کوتاه سبز باشد اما Window موردنیاز بلندتر Fail شود. در این وضعیت Promotion انجام نمی‌شود. Start Time، Completion Criterion، Observationها و کامل یا ناقص بودن Window را ثبت کن.

اگر Window لازم کامل نشده، طبق Policy وضعیت HOLD یا UNKNOWN بده. Observation ناقص را PASS اعلام نکن.

9. Flag-Off همیشه Rollback کامل نیست

خاموش کردن Feature می‌تواند ورود Requestهای بعدی به Path جدید را متوقف کند، اما الزاماً Side Effectهای پایدار قبلی را برنمی‌گرداند. ممکن است Data Write جدید، Schema State، External Message یا Business Action ماندگار شده باشد.

در Recovery دو سؤال جدا داریم: «Activation خاموش شده؟» و «Side Effectها Reconcile شده‌اند؟». Kill Switch می‌تواند درست کار کند ولی Recovery هنوز ناقص باشد.

Side-Effect Boundary، Compatibility Assumption، Compensating Action و Completion Condition را ثبت کن. اگر اثر پایدار باقی مانده، عبارت «Flag خاموش شد پس Rollback کامل است» باید رد شود.

10. Failure Probe: Targeting Key ناپایدار

فرض کن یک Subject مصنوعی دوبار Evaluate می‌شود. بار اول Key برابر acct-0042 است و بار دوم Middleware مقدار 42 می‌فرستد. هر دو به یک Subject منطقی اشاره دارند، اما Provider رشته‌های متفاوت را Hash می‌کند و Subject به Bucket دیگری می‌رود.

این یک Rollout-Control Failure است حتی اگر هر دو Evaluation یک Flag Value معتبر برگردانند. Cohort Assignment دیگر Sticky نیست و Exposure قابل بازتولید نیست. Decision درست HOLD_TARGETING_UNSTABLE است تا Normalization تعمیر و Membership Proof تکرارپذیر شود.

ترتیب تصمیم مهم است: Cohort Determinism قبل از Percentage Arithmetic.

11. Failure Probe: Deployment سبز، Feature Health قرمز

ممکن است Deployment Probeها PASS باشند اما Feature Path در Cohort فعال Fail کند. این دقیقاً همان چیزی است که Feature-Specific Health Gate باید آشکار کند.

اگر Rollback Trigger تعریف‌شده فعال شده باشد، ROLLBACK_REQUIRED انتخاب می‌شود و Recovery Path محدود اجرا می‌شود. اگر Trigger فعال نیست ولی Health Fail است، HOLD_HEALTH_FAILED انتخاب کن. موفقیت Deployment به‌تنهایی مجوز Promotion نیست.

Artifact Delivery فقط ثابت می‌کند Build جدید به Runtime مقصد رسیده؛ Safety رفتار فعال‌شده را ثابت نمی‌کند.

12. Bounded Rollout Control Record v1 را ردیفی بساز

برای هر Rollout Stage این فیلدها را مستقل ثبت کن:

Observation مستقیم، Policy Choice و Unknown را از هم جدا نگه دار. اگر چیزی مشاهده نشده، آن را UNKNOWN ثبت کن نه این‌که حدس محتمل بنویسی.

13. Promotion، Rollback و Retirement سه تصمیم متفاوت‌اند

Promotion یعنی Exposure بیشتر. Rollback یعنی کاهش یا بازگردانی Exposure طبق Recovery Path تعریف‌شده. Retirement یعنی حذف Control موقت وقتی Rollout پایدار شده و Flag دیگر لازم نیست.

ممکن است Feature در Full Exposure باشد اما Flag هنوز آماده Retirement نباشد؛ مثلاً Client قدیمی هنوز Default Path می‌خواهد، Prerequisite Flag باقی است، Cleanup Commit Merge نشده یا Retirement Verification کامل نشده است.

Retirement Condition باید Owner، Cleanup Action، Compatibility Condition و Verification Evidence را مشخص کند. Flag بدون Owner به Stale-Flag Debt تبدیل می‌شود و رفتار آینده را مبهم می‌کند.

14. Lab: هشت Rollout Case محلی را تحلیل کن

Lab فقط از Synthetic Local Fixture استفاده می‌کند. Structural Check را اجرا کن، تابع analyze_rollout(case) را پیاده‌سازی کن و هشت Evidence Dimension را بدون دیدن Answer مورد انتظار Classification کن.

Caseها شامل Healthy Bounded Cohort، Artifact Deploy شده با Flag خاموش، Unstable Targeting، Feature-Specific Health Failure، Side Effect ماندگار پس از Flag Disablement، Short Window سبز و Bake Window بلند Fail، Premature Retirement و Changed-Context Transfer هستند.

تابع باید این کلیدها را برگرداند: deployment_state، targeting_state، cohort_state، activation_state، health_gate، bake_gate، recovery_state و lifecycle_decision. هدف تفکیک Evidence است، نه حفظ کردن Labelها.

15. Transfer: با Cohort Model متفاوت دوباره بساز

Transfer Case، Subject Identity، Rollout Stageها و Signal شکست را عوض می‌کند. Percentage و Bake Duration Case اول را کپی نکن. Control Record را از Evidence جدید بساز.

روش ثابت می‌ماند: Deployment State را اثبات کن، Deterministic Targeting را اثبات کن، Cohort واقعی Exposure را نام ببر، Feature-Specific Health را Evaluate کن، Observation Window لازم را رعایت کن، Disablement را از Recovery کامل جدا نگه دار و Retirement را فقط پس از Stable Full Exposure و Cleanup Evidence تعریف کن.

خروجی باید برای Engineer دیگری قابل Review باشد؛ به‌طوری که هر Decision به Observation، Policy Choice صریح یا Bounded Unknown قابل ردیابی باشد.