امنیت، هویت، استقرار و تاب‌آوری · فصل ۹ — Resource، Provider، Cost و Organizational Failure · 127
Provider API Drift/Quota
failure را بعد از وقوع و به‌صورت موردی تحلیل می‌کند و هنوز detection، containment و repair path از قبل طراحی نشده است. موضوع جاری: «Provider API Drift/Quota». می‌تواند failure family «Provider API Drift/Quota» را بازتولید/تشخیص دهد و detection، containment و recovery مناسب را تعیین کند.
خلاصهٔ درس
failure را بعد از وقوع و به‌صورت موردی تحلیل می‌کند و هنوز detection، containment و repair path از قبل طراحی نشده است. موضوع جاری: «Provider API Drift/Quota».
می‌تواند failure family «Provider API Drift/Quota» را بازتولید/تشخیص دهد و detection، containment و recovery مناسب را تعیین کند.
خروجی این درس
می‌تواند failure family «Provider API Drift/Quota» را بازتولید/تشخیص دهد و detection، containment و recovery مناسب را تعیین کند.
1. هر خطای provider را transient فرض نکنید
وقتی client code تغییر نکرده ولی integration می‌شکند، حداقل سه خانواده علت را جدا نگه دارید: contract/version drift، quota/rate throttling و transient service failure. اگر همه را با retry یکسان پاسخ دهید، drift واقعی می‌تواند پشت retry storm پنهان شود و throttling هم با schema failure اشتباه شود.
2. API version و contract expectation را ثبت کنید
برای هر request، نسخهٔ API یا model endpoint، endpoint/operation، request shape و contract مورد انتظار را در record نگه دارید. «همان endpoint قبلی» evidence کافی نیست؛ provider ممکن است version را retire کند، behavior را تغییر دهد یا replacement پیشنهاد کند.
3. Contract observation را از status code جدا کنید
یک پاسخ 200 می‌تواند از نظر transport موفق باشد ولی semantics فیلد required نسبت به contract pin شده drift کرده باشد. برعکس، 429 ممکن است contract را کاملاً حفظ کند و فقط quota window را نشان دهد. بنابراین parser/compatibility probe و status/quota probe باید مستقل اجرا شوند.
4. Breaking change را با evidence تشخیص دهید
در این درس drift وقتی معتبر است که observed contract با expectation pin شده ناسازگار باشد: فیلد required حذف/rename شود، type/meaning عوض شود، version دیگر پشتیبانی نشود یا behavior قابل‌اتکای client شکسته شود. صرف اضافه‌شدن فیلد اختیاری یا افزایش latency به‌تنهایی contract drift نیست.
5. 429 را throttling evidence بدانید، نه schema evidence
در fixture این درس، 429 همراه quota evidence و Retry-After یا retry-after-ms به‌عنوان throttling طبقه‌بندی می‌شود. action پیش‌فرض، کاهش فشار و رعایت guidance provider است؛ retry فوری و بدون bound می‌تواند quota را بدتر کند.
6. 503 را از quota exhaustion جدا نگه دارید
Provider می‌تواند برای overload یا failure موقت 503 بدهد و همان‌زمان contract و quota probe سالم باشند. اگر retry guidance وجود دارد، bounded retry/backoff می‌تواند مناسب باشد؛ اما این evidence نباید به‌عنوان quota exhaustion یا schema break ثبت شود.
7. Version pinning containment است، تضمین ابدی نیست
Pin کردن نسخه حرکت خاموش contract را کم می‌کند و diagnosis را قابل ممیزی‌تر می‌سازد، ولی provider هنوز می‌تواند نسخه را deprecate یا retire کند. record باید lifecycle/deprecation evidence و migration path را جدا نگه دارد و UNKNOWN را وقتی evidence ناقص است حفظ کند.
8. Retry policy باید failure-class aware باشد
CONTRACT_DRIFT و VERSION_RETIRED معمولاً با retry همان request اصلاح نمی‌شوند. QUOTA_THROTTLE باید Retry-After، backoff، admission control یا queueing را رعایت کند. TRANSIENT_SERVICE می‌تواند bounded retry داشته باشد. هر policy باید attempt limit و stop condition داشته باشد.
9. Fallback فقط وقتی bounded و qualified است
Fallback provider یا version جایگزین نباید صرفاً چون «کار می‌کند» فعال شود. باید capability/contract موردنیاز را برآورده کند و data/egress/policy boundary را نقض نکند. اگر qualification جایگزین معلوم نیست، state آن REQUIRES_REQUALIFICATION یا UNKNOWN باقی می‌ماند.
10. Containment با recovery فرق دارد
کاهش request rate یا switch موقت به fallback می‌تواند incident را مهار کند، اما closure نیست. Recovery وقتی معتبر است که compatibility probe، quota/service probe و request-level behavior روی rerun اعلام‌شده دوباره داخل bound باشند.
11. Provider Contract Drift & Quota Recovery Record v1
Artifact اصلی ۱۳ بُعد دارد: API version، contract expectation، contract observation، status code، quota usage، Retry-After، compatibility probe، failure class، retry policy، backoff state، fallback state، closure probe و residual provider risk. هر بُعد باید observation، authority، inference یا UNKNOWN برچسب داشته باشد.
12. Classification را از دو probe مستقل بسازید
Contract probe می‌پرسد «response هنوز با contract pin شده compatible است؟». Quota/status probe می‌پرسد «آیا quota/rate state یا transient service signal وجود دارد؟». CONTRACT_DRIFT، VERSION_RETIRED، QUOTA_THROTTLE، TRANSIENT_SERVICE، HEALTHY و UNKNOWN outcomeهای اصلی Lab هستند.
13. Closure باید علت طبقه‌بندی‌شده را دوباره آزمایش کند
برای drift، rerun باید نسخه/contract جدید یا migration اصلاح‌شده را verify کند. برای throttling، closure باید نشان دهد quota window بازیابی شده و retry/admission behavior فشار را تکثیر نمی‌کند. برای transient service، rerun باید recovery را بدون نسبت‌دادن غلط به quota نشان دهد.
14. Lab: هشت fixture و 64 assertion
Lab کاملاً local و synthetic است. هشت fixture شامل baseline سالم، 429 با contract سالم، 200 با contract drift، 503 با retry guidance، version بازنشسته، evidence متناقض/ناکافی، transfer با quota پایین‌تر و transfer با 503 مستقل از quota است. evaluator برای هر case هشت field می‌سازد و oracle در مجموع 64 assertion را می‌سنجد.
15. Exit checklist و انتقال
قبل از خروج باید بتوانید توضیح دهید کدام evidence contract/version است و کدام quota/status، چرا retry policy انتخاب‌شده با failure class سازگار است، fallback چه qualificationی دارد و closure با چه probe مستقلی ثابت می‌شود. در transfer، schema compatible می‌ماند ولی quota پایین‌تر می‌شود و بعد 503 با retry guidance ظاهر می‌شود؛ classification باید از evidence جدید بازسازی شود، نه از drift قبلی کپی شود.
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
Q1 retrieval
Why is HTTP 429 not proof of provider contract drift?
Q2 application
A pinned endpoint returns 200 but changes the required response semantics. Which failure family is primary?
Q3 diagnosis
A compatible response returns 503 with Retry-After while quota remains healthy. How should it be classified?
Q4 decision
Why is unlimited exponential retry unsafe for 429 or drift?
Q5 transfer
Schema stays compatible, quota is lowered, then a 503 appears. How should the prior drift diagnosis be used?
ملاک‌های ارزیابی (rubric)
A sufficient response separates contract/version evidence from quota/status evidence, preserves UNKNOWN when probes conflict or are missing, selects retry/backoff/fallback behavior that matches the classified failure, and distinguishes containment from closure. Closure requires an explicit rerun of the relevant contract or provider-state probe. Transfer must be rebuilt from the lower-quota and later-503 evidence instead of copying a prior drift classification.
منابع و تازگی
مطالعهٔ موارد (case studies)
تصاویر درس
فایل‌های آزمایشگاه
Implement the bounded evaluator in starter.py for the eight supplied synthetic cases. No network calls, provider credentials, or paid quota are required. Keep API-version/contract evidence separate from status/quota evidence. A 429 alone is not contract drift; a 200 alone is not contract compatibility; and a successful retry is not closure evidence. Preserve UNKNOWN when compatibility or quota evidence is missing. Match retry/backoff/fallback behavior to the classified failure, then require a relevant closure probe.
Run python run_checks.py to verify fixture shape before implementing the evaluator.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)