داربست — خودآموز MLOps و مهندسی سامانه‌های هوش مصنوعی (پیشرفته)

فصل ۳ از ۹

پیشرفت ترم
۰٪

در این فصل چه یاد می‌گیری#

فصلِ قبل یک سرویس ساخت که هر کسی می‌تواند صدایش بزند، هر چند بار که بخواهد. این فصل همان سرویس را پشتِ یک مرز می‌گذارد.

یک اسکریپتِ رهاشده در یک ثانیه ۴۰ درخواست می‌فرستد. بدونِ مرز، هر ۶۰ درخواستِ آن ثانیه‌ها سرو می‌شوند و مدل ۶۰ بار اجرا می‌شود. با یک محدودکنندهٔ نرخِ هر صدازننده جدا، ۳۰ تا رد می‌شوند و اپلیکیشنِ بی‌گناه صفر بار رد می‌شود. و بعد نشان می‌دهیم که «نه» گفتن دو جور است، با دو Retry-After کاملاً متفاوت: ۱ ثانیه و ۳۶۰۰ ثانیه.

یک گردانه با شمارندهٔ کنارش

آخر این فصل می‌توانی:

  • بگویی کلیدِ سرویس کجا زندگی می‌کند و چرا هرگز داخلِ artifact نمی‌رود
  • یک محدودکنندهٔ نرخ با پنجرهٔ لغزان بنویسی که قابلِ تست باشد
  • سهمیهٔ هر صدازننده را جدا نگه داری تا یکی بقیه را از پا نیندازد
  • کدِ ۴۲۹ را بخشی از قرارداد بنویسی، نه یک خطای اتفاقی

قبل از شروع#

از فصلِ ۱: artifact و MANIFEST — و در این فصل می‌بینی که همان هش، یک نشتیِ کلید را هم لو می‌دهد. از فصلِ ۲: همان سرورِ 127.0.0.1، کدِ وضعیت، سربرگ، و تستِ قرارداد. این فصل به آن قرارداد دو بندِ تازه اضافه می‌کند — بندِ پنجمش («بیشترین نرخِ درخواست») در فصلِ ۲ فقط نوشته شد و هیچ‌وقت پیاده نشد.

💡 نکته: محدودسازیِ نرخ به زمان نیاز دارد و زمانِ سیستم روی هر ماشین جواب دیگری می‌دهد. پس اینجا زمان را به‌عنوان ورودیِ تابع می‌دهیم، نه اینکه از سیستم بخوانیمش — فعلاً همین‌قدر بدان که این کار نتیجه را روی هر ماشینی یکسان می‌کند. فصلِ ۴ همین ترفند را با نامِ خودش — «ساعتِ مجازی» — کامل می‌سازد و از آنجا ابزارِ ثابتِ دوره می‌شود.

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

اجرا زمانِ تقریبی
کلِ نوت‌بوک روی CPU کمتر از یک دقیقه
GPU لازم نیست

۱. سه سؤالی که سرویسِ بی‌مرز جوابشان را ندارد#

سرویسِ فصلِ ۲ کار می‌کند، نسخه دارد، قرارداد دارد و تستِ قرارداد هم دارد. و هر کسی که آدرسش را بداند می‌تواند تا ابد صدایش بزند. سه سؤال هست که هیچ‌جای آن سرویس جوابشان نیست:

  • کی صدایم می‌زند؟ بدونِ جواب، نمی‌توانی بگویی کدام تیم کدام بار را ساخته، و نمی‌توانی جلوی یکی را بدونِ بستنِ کلِ سرویس بگیری.
  • چقدر حق دارد؟ بدونِ جواب، یک حلقهٔ for که کسی یادش رفت متوقفش کند، همان اثری را دارد که یک حملهٔ عمدی.
  • وقتی نه می‌گویی، چه می‌گویی؟ «نه»ای که فقط قطع کند، صدازننده را وادار می‌کند دوباره و سریع‌تر تلاش کند — دقیقاً همان حلقهٔ فصلِ ۲.

این سه، سه سازوکارِ متفاوت‌اند: کلید، محدودکنندهٔ نرخ، و کدِ وضعیت. هر سه را در همین فصل می‌سازیم.

۲. کلید کجا زندگی می‌کند — و کجا هرگز نه#

قاعده یک خط است: کلید هرگز داخلِ artifact نمی‌رود. نه در config.json، نه در کد، نه در نوت‌بوک، نه در تاریخچهٔ git. دلیلش هم ساده است: artifact ساخته می‌شود تا کپی شود — به رجیستری، به ماشینِ دیگر، به لپ‌تاپِ یک همکار. هر کپی یک کپیِ آن کلید هم هست.

بیایید همین را روی بستهٔ فصلِ ۱ اندازه بگیریم: یک بازرسِ کوچک که سه شکلِ رایجِ راز را در فایل‌های بسته می‌گردد.

import hashlib
import json
import re

model = fit_model(TRAIN[:800])
MODEL_VERSION = "1.0.0"

BUNDLE = WORK / "artifact-boundary"
BUNDLE.mkdir(exist_ok=True)
SETTINGS = {"version": MODEL_VERSION, "normalise": True,
            "rate_per_second": 10, "daily_quota": 25}
(BUNDLE / "config.json").write_text(json.dumps(SETTINGS, ensure_ascii=False),
                                    encoding="utf-8")
(BUNDLE / "serve.py").write_text(
    'API_KEY = os.environ["SERVICE_API_KEY"]   # کلید از محیط، نه از فایل\n',
    encoding="utf-8")

SECRET_SHAPES = [
    ("کلیدِ سرویس", re.compile(r"\bsk-[A-Za-z0-9-]{8,}\b")),
    ("توکنِ حامل", re.compile(r"\bBearer\s+[A-Za-z0-9._-]{8,}\b")),
    ("رشتهٔ اتصال", re.compile(r"\w+://[^\s:@/]+:[^\s:@/]+@")),
]


def leaks(path):
    text = path.read_text(encoding="utf-8", errors="replace")
    return [name for name, shape in SECRET_SHAPES if shape.search(text)]


def audit(title):
    print(title)
    for f in sorted(BUNDLE.iterdir()):
        found = leaks(f)
        print(f"  {f.name:<12} {'نشتی: ' + '، '.join(found) if found else 'پاک':<22}"
              f" هش {hashlib.sha256(f.read_bytes()).hexdigest()[:12]}")


audit("بستهٔ سالم:")
SETTINGS["api_key"] = "sk-live-9f3a7c21bb04"          # اشتباهِ کلاسیک
(BUNDLE / "config.json").write_text(json.dumps(SETTINGS, ensure_ascii=False),
                                    encoding="utf-8")
audit("همان بسته، بعد از یک خطِ اضافه:")
del SETTINGS["api_key"]
(BUNDLE / "config.json").write_text(json.dumps(SETTINGS, ensure_ascii=False),
                                    encoding="utf-8")
بستهٔ سالم:
  config.json  پاک                    هش 2fdc4619e996
  serve.py     پاک                    هش 7f9a6a020c0c
همان بسته، بعد از یک خطِ اضافه:
  config.json  نشتی: کلیدِ سرویس      هش 6b2094432d60
  serve.py     پاک                    هش 7f9a6a020c0c

یک خط اضافه شد و هشِ فایل کاملاً عوض شد. این خبرِ خوب است: بازرس هم قابلِ خودکار شدن است و هم ارزان — ترمِ ۶ همین را به یک دروازهٔ بیلد تبدیل می‌کند.

ولی خبرِ بد را هم صریح بگوییم: پاک کردنِ کلید از فایل، کلید را امن نمی‌کند. اگر آن بسته یک بار جایی رفته باشد، آن کلید سوخته است و تنها کارِ درست عوض کردنش است. serve.py راهِ درست را نشان می‌دهد: نامِ متغیرِ محیطی داخلِ کد است، مقدارش بیرون.

و در Colab، «بیرون» یعنی Colab Secrets:

def secret(name, sample):
    """کلید را از Colab Secrets می‌گیرد. هر شکستی — چه بیرونِ Colab باشی و چه
    راز را نساخته باشی — به مقدارِ نمونهٔ همین فصل برمی‌گردد، چون این فصل
    نباید کسی را مجبور به ساختنِ راز کند."""
    try:
        from google.colab import userdata
        return userdata.get(name), "Colab Secrets"
    except Exception:
        return sample, "مقدارِ نمونهٔ همین فصل"


SERVICE_KEY, source = secret("SERVICE_API_KEY", "k-mobile-4a19")
print("کلید از کجا آمد:", source)
print("چند حرفِ اولش  :", SERVICE_KEY[:4] + "…")     # خودِ کلید هرگز چاپ نمی‌شود
کلید از کجا آمد: مقدارِ نمونهٔ همین فصل
چند حرفِ اولش  : k-mo…

اگر در Colab رازی به نامِ SERVICE_API_KEY ساخته باشی، خطِ اول عوض می‌شود — و برای همین این تنها خروجیِ تقریبیِ فصل است. کلیدِ خودِ این فصل ساختگی است و ارزشِ راز شدن ندارد؛ الگو مهم است، نه این کلید.

و به خطِ دوم دقت کن: کلید هرگز کامل چاپ نمی‌شود. هر چیزی که چاپ شود در خروجیِ نوت‌بوک می‌ماند، و خروجیِ نوت‌بوک را آدم‌ها برای هم می‌فرستند.

۳. مرز، در سرویس#

حالا همان سرورِ فصلِ ۲ را با یک تفاوت بالا می‌آوریم: قبل از هر کاری، سربرگِ X-API-Key را می‌خواند و صدازننده را اسم می‌دهد. فعلاً هیچ محدودیتی نمی‌گذاریم — یک OpenGate که همه‌چیز را می‌پذیرد — تا نقطهٔ شروعِ اندازه‌گیری داشته باشیم.

import threading
import urllib.error
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

KEYS = {"k-analytics-7d2f": "تحلیل", "k-mobile-4a19": "اپلیکیشن"}
COUNTERS = {"served": 0, "no_key": 0, "unknown_key": 0, "throttled": 0}
LABEL = {"served": "سرو شد", "no_key": "بدونِ کلید",
         "unknown_key": "کلیدِ ناشناس", "throttled": "از سهم گذشت"}
CLOCK = {"now": 0.0}


class OpenGate:
    """مرزِ باز: هر چه بیاید می‌پذیرد. نقطهٔ شروعِ اندازه‌گیری."""

    def allow(self, caller, now):
        return True, 0, ""


GATE = OpenGate()


def caller_of(headers):
    key = headers.get("X-API-Key")
    if key is None:
        return None, "no_key", "کلید لازم است"
    if key not in KEYS:
        return None, "unknown_key", "کلید معتبر نیست"
    return KEYS[key], "served", None


class Handler(BaseHTTPRequestHandler):
    def log_message(self, *args):
        pass

    def _send(self, code, payload, extra=()):
        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        for name, value in extra:
            self.send_header(name, value)
        self.end_headers()
        self.wfile.write(body)

    def do_POST(self):
        # بدنه را همیشه می‌خوانیم، حتی برای درخواستی که رد می‌شود: اگر پیش از خواندنش
        # پاسخ بدهیم و اتصال را ببندیم، کلاینت روی بعضی سیستم‌ها به‌جای پاسخ خطای اتصال می‌گیرد.
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        caller, bucket, message = caller_of(self.headers)
        if caller is None:
            COUNTERS[bucket] += 1
            return self._send(401, {"error": message})
        allowed, retry_after, why = GATE.allow(caller, CLOCK["now"])
        if not allowed:
            COUNTERS["throttled"] += 1
            return self._send(429, {"error": why},
                              [("Retry-After", str(retry_after))])
        COUNTERS["served"] += 1
        label = model.predict([normalise(json.loads(raw)["text"])])[0]
        self._send(200, {"label": label, "model_version": MODEL_VERSION,
                         "caller": caller})


class Server(ThreadingHTTPServer):
    def handle_error(self, request, client_address):
        pass


server = Server(("127.0.0.1", 0), Handler)
threading.Thread(target=server.serve_forever, daemon=True).start()
BASE = f"http://127.0.0.1:{server.server_address[1]}"
SAMPLE = [r["text"] for r in TEST[:80]]


def call(text, key=None, now=0.0):
    CLOCK["now"] = now                    # زمان را خودمان جلو می‌بریم
    headers = {"Content-Type": "application/json"}
    if key is not None:
        headers["X-API-Key"] = key
    request = urllib.request.Request(
        BASE + "/v1/predict",
        data=json.dumps({"text": text}, ensure_ascii=False).encode("utf-8"),
        headers=headers)
    try:
        with urllib.request.urlopen(request, timeout=5) as response:
            return response.status, json.loads(response.read()), dict(response.headers)
    except urllib.error.HTTPError as error:
        return error.code, json.loads(error.read()), dict(error.headers)


print("بدونِ کلید  :", call(SAMPLE[0])[:2])
print("کلیدِ ناشناس:", call(SAMPLE[0], "k-someone-else")[:2])
print("کلیدِ درست  :", call(SAMPLE[0], SERVICE_KEY)[1])
print("شمارنده‌ها  :", " · ".join(f"{LABEL[k]} {v}" for k, v in COUNTERS.items()))
بدونِ کلید  : (401, {'error': 'کلید لازم است'})
کلیدِ ناشناس: (401, {'error': 'کلید معتبر نیست'})
کلیدِ درست  : {'label': 'حساب کاربری', 'model_version': '1.0.0', 'caller': 'اپلیکیشن'}
شمارنده‌ها  : سرو شد 1 · بدونِ کلید 1 · کلیدِ ناشناس 1 · از سهم گذشت 0

سه تصمیمِ ریز که هر سه عمدی‌اند:

  • بررسیِ کلید قبل از هر پردازشی است. بدنهٔ درخواستی که اجازه ندارد فقط از اتصال خوانده و دور ریخته می‌شود و به مدل نمی‌رسد. خودِ خواندن لازم است، چون اگر سرور بدنهٔ نخوانده را رها کند و اتصال را ببندد، کلاینت ممکن است به‌جای پاسخِ ۴۰۱ یک خطای اتصال بگیرد (روی ویندوز: ConnectionAbortedError: [WinError 10053]).
  • کلید در پاسخ تکرار نمی‌شود. پیامِ خطا می‌گوید «کلید معتبر نیست»، نه «کلیدِ فلان معتبر نیست» — وگرنه کلید در سیاههٔ طرفِ مقابل می‌نشیند.
  • صدازننده در پاسخ هست. فیلدِ caller به خودِ صدازننده می‌گوید سرویس او را چه کسی می‌شناسد؛ همان چیزی که فردا مچِ کلیدی را می‌گیرد که جای اشتباه رفته.

۴. پنجرهٔ لغزان: هر صدازننده، سهمِ خودش#

یک اسکریپتِ تحلیلی رها شده و در یک ثانیه چهل بار سرویس را صدا می‌زند. همان لحظه، اپلیکیشن هم دارد کارِ عادی‌اش را می‌کند. سؤال این نیست که «چند تا رد شود»؛ سؤال این است که رد شدن‌ها سرِ چه کسی بیاید.

from collections import deque


class SlidingWindow:
    """پنجرهٔ لغزان، جدا برای هر صدازننده. زمان ورودیِ تابع است، نه خواندنی از سیستم."""

    def __init__(self, limit, window):
        self.limit, self.window = limit, window
        self.hits = {}

    def allow(self, caller, now):
        seen = self.hits.setdefault(caller, deque())
        while seen and seen[0] <= now - self.window:
            seen.popleft()
        if len(seen) >= self.limit:
            return False, max(1, round(seen[0] + self.window - now)), "نرخت از حد گذشت"
        seen.append(now)
        return True, 0, ""


TRAFFIC = []
for second in range(4):
    for i in range(5):
        TRAFFIC.append((second + i * 0.1, "اپلیکیشن"))       # ترافیکِ آرامِ همیشگی
for i in range(40):
    TRAFFIC.append((1.0 + i * 0.005, "تحلیل"))               # اسکریپتی که رها شده
TRAFFIC.sort()


def replay(gate):
    tally = {}
    for now, caller in TRAFFIC:
        ok = gate.allow(caller, now)[0]
        box = tally.setdefault((int(now), caller), [0, 0])
        box[0 if ok else 1] += 1
    return tally


loose = replay(OpenGate())
tight = replay(SlidingWindow(limit=10, window=1.0))
print(f"{'ثانیه':<7}{'صدازننده':<12}{'رسیده':>8}{'بی‌مرز':>10}{'با مرز':>10}{'ردشده':>9}")
for key in sorted(loose):
    print(f"{key[0]:<7}{key[1]:<12}{sum(loose[key]):>8}{loose[key][0]:>10}"
          f"{tight[key][0]:>10}{tight[key][1]:>9}")
print(f"{'جمع':<19}{len(TRAFFIC):>8}"
      f"{sum(v[0] for v in loose.values()):>10}"
      f"{sum(v[0] for v in tight.values()):>10}"
      f"{sum(v[1] for v in tight.values()):>9}")
print("رد شدنِ اپلیکیشن:",
      sum(tight[k][1] for k in tight if k[1] == "اپلیکیشن"))
ثانیه  صدازننده       رسیده    بی‌مرز    با مرز    ردشده
0      اپلیکیشن           5         5         5        0
1      اپلیکیشن           5         5         5        0
1      تحلیل             40        40        10       30
2      اپلیکیشن           5         5         5        0
3      اپلیکیشن           5         5         5        0
جمع                      60        60        30       30
رد شدنِ اپلیکیشن: 0

۳۰ رد از ۶۰، و همه‌شان سرِ همان یکی که تندروی کرد. خطِ آخر عددِ اصلیِ فصل است: اپلیکیشن صفر بار رد شد.

اگر حساب مشترک بود، این عدد صفر نمی‌ماند. یک محدودکنندهٔ نرخِ سراسری فقط می‌شمارد «چند درخواست در ثانیه» و وقتی از حد رد شد، هر کسی که بعدش برسد رد می‌شود — یعنی اسکریپتِ خرابِ یک تیم، سرویسِ تیمِ دیگر را می‌خواباند. کلیدِ بخشِ ۳ دقیقاً برای همین لازم بود: بدونِ اسمِ صدازننده، سهمِ جداگانه ممکن نیست.

و «لغزان» یعنی چه؟ پنجره یک بازهٔ ثابتِ ساعتی نیست؛ همیشه یک ثانیهٔ گذشته از همین لحظه است. حلقهٔ while دقیقاً همین کار را می‌کند: هر بار، ضربه‌های قدیمی‌تر از پنجره را از جلوی صف بیرون می‌اندازد. پنجرهٔ ثابت یک ضعفِ معروف دارد — کسی که ۱۰ درخواست در پایانِ یک پنجره و ۱۰ تای دیگر در آغازِ پنجرهٔ بعد بفرستد، در عمل ۲۰ درخواست در کسری از ثانیه فرستاده و هیچ حدی نشکسته.

✅ چک کن: window را از ۱ ثانیه به ۱۰ ثانیه ببر، یک بار با limit=10 و یک بار با limit=100، و دوباره اجرا کن. قبل از اجرا حدس بزن ستونِ «ردشده» چه می‌شود، بعد ببین. جوابت باید توضیح بدهد که «۱۰ در ثانیه» و «۱۰۰ در ده ثانیه» دو سیاستِ متفاوت‌اند، نه دو نوشتنِ یک سیاست — و کدامشان اجازهٔ انفجارِ لحظه‌ای می‌دهد.

۵. دو جورِ «نه»، با دو Retry-After#

نرخِ لحظه‌ای تنها حدِ ممکن نیست. حدِ دوم سهمیه است: یک سقفِ کلی که با گذشتِ زمان برنمی‌گردد. حالا سرویس را با هر دو بالا می‌آوریم و دو بار بارش می‌کنیم — یک بار تند و کوتاه، یک بار آرام و طولانی.

class Boundary:
    """دو حد روی هم: نرخِ لحظه‌ای، و سهمیه‌ای که با گذشتِ زمان برنمی‌گردد."""

    def __init__(self, limit, window, quota):
        self.rate = SlidingWindow(limit, window)
        self.quota, self.used = quota, {}

    def allow(self, caller, now):
        if self.used.get(caller, 0) >= self.quota:
            return False, 3600, "سهمیهٔ دوره‌ات تمام شد"
        ok, retry_after, why = self.rate.allow(caller, now)
        if ok:
            self.used[caller] = self.used.get(caller, 0) + 1
        return ok, retry_after, why


GATE = Boundary(limit=10, window=1.0, quota=25)
for key in COUNTERS:
    COUNTERS[key] = 0


def burst(count, first, step, key="k-analytics-7d2f"):
    seen = []
    for i in range(count):
        status, body, headers = call(SAMPLE[i % len(SAMPLE)], key,
                                     now=first + i * step)
        seen.append((status, body.get("error"), headers.get("Retry-After")))
    return seen


fast = burst(40, first=1.0, step=0.005)        # ۴۰ درخواست در یک پنجره
slow = burst(40, first=10.0, step=0.25)        # ۴ در ثانیه، زیرِ حدِ نرخ
for name, seen in (("تندِ یک‌پنجره‌ای", fast), ("آرام، ولی طولانی", slow)):
    codes = [s for s, _, _ in seen]
    first_no = next(row for row in seen if row[0] == 429)
    print(f"{name}: ۲۰۰ → {codes.count(200)} · ۴۲۹ → {codes.count(429)}"
          f" · اولین ۴۲۹ در درخواستِ {codes.index(429) + 1}")
    print(f"    پیام: {first_no[1]} · Retry-After: {first_no[2]} ثانیه")
print("سهمیهٔ مصرف‌شده:", GATE.used)
print("شمارنده‌ها    :", " · ".join(f"{LABEL[k]} {v}" for k, v in COUNTERS.items()))
تندِ یک‌پنجره‌ای: ۲۰۰ → 10 · ۴۲۹ → 30 · اولین ۴۲۹ در درخواستِ 11
    پیام: نرخت از حد گذشت · Retry-After: 1 ثانیه
آرام، ولی طولانی: ۲۰۰ → 15 · ۴۲۹ → 25 · اولین ۴۲۹ در درخواستِ 16
    پیام: سهمیهٔ دوره‌ات تمام شد · Retry-After: 3600 ثانیه
سهمیهٔ مصرف‌شده: {'تحلیل': 25}
شمارنده‌ها    : سرو شد 25 · بدونِ کلید 0 · کلیدِ ناشناس 0 · از سهم گذشت 55

همان کدِ ۴۲۹، دو معنای کاملاً متفاوت — و تفاوت در Retry-After است، نه در کد.

بارِ تند به دیوارِ نرخ خورد و جوابش «یک ثانیه صبر کن» بود: مشکل موقتی است و با کمی صبر حل می‌شود. بارِ آرام از حدِ نرخ رد نشد و در عوض سهمیه را تمام کرد؛ جوابش «یک ساعت» است، یعنی امروز دیگر خبری نیست.

صدازننده‌ای که فقط کد را ببیند، این دو را یکی می‌بیند و در هر دو حالت پشتِ سرِ هم دوباره تلاش می‌کند. به همین دلیل Retry-After بخشی از قرارداد است، نه یک تزئین: عددِ داخلش همان چیزی است که به رفتارِ کلاینت شکل می‌دهد.

📏 اندازه بگیر: با چه چیزی مقایسه شد؟ با همان سرویس و همان کلید؛ تنها متغیر شکلِ ترافیک بود — ۴۰ درخواست در یک پنجره در برابرِ همان ۴۰ درخواست پخش‌شده در ده ثانیه. روی کدام داده؟ همان ۴۰ تیکتِ اولِ مجموعهٔ آزمون در هر دو بار. با چند seed؟ seed اینجا معنا ندارد و این خودش نکته است: محدودکنندهٔ نرخ یک تابعِ قطعی از زمان‌های ورودی است. چون زمان را ورودی دادیم نه از سیستم خواندیم، هر سه عددِ این جدول روی هر ماشینی عیناً تکرار می‌شود — و همین چیزی است که یک محدودکننده را قابلِ تست می‌کند.

🔧 اگر کار نکرد: اگر کلاینتت به‌جای گرفتنِ کدِ ۴۲۹ اصلاً بشکند، این را می‌بینی: urllib.error.HTTPError: HTTP Error 429: Too Many Requests. این باگ نیست، رفتارِ عادیِ urlopen است: هر کدِ ۴xx و ۵xx را به‌شکلِ exception بالا می‌آورد. تابعِ call ما همین را می‌گیرد و به یک سه‌تایی تبدیل می‌کند. و درسِ واقعی‌اش این است: کلاینتی که ۴۲۹ را exception ببیند، معمولاً بلافاصله دوباره تلاش می‌کند — یعنی بدترین کارِ ممکن. Retry-After را بخوان و همان‌قدر صبر کن.

۶. ۴۲۹ بخشی از قرارداد است#

فصلِ ۲ تستِ قرارداد را ساخت تا شکلِ پاسخِ موفق را قفل کند. مرز هم دقیقاً همان‌قدر قرارداد است: اگر ننویسی‌اش، اولین باری که یک کلاینت به ۴۲۹ می‌خورد، فکر می‌کند سرویس خراب شده.

GATE = Boundary(limit=10, window=1.0, quota=25)
for key in COUNTERS:
    COUNTERS[key] = 0


def boundary_contract():
    no_key = call(SAMPLE[0], None, now=100.0)
    bad_key = call(SAMPLE[0], "k-someone-else", now=100.0)
    ok = call(SAMPLE[0], "k-mobile-4a19", now=100.0)
    over = [call(SAMPLE[0], "k-mobile-4a19", now=100.0 + i * 0.01)
            for i in range(1, 15)][-1]
    return [
        ("بی‌کلید کدِ ۴۰۱ می‌گیرد", no_key[0] == 401),
        ("کلیدِ ناشناس هم ۴۰۱، با پیامِ متفاوت",
         bad_key[0] == 401 and bad_key[1]["error"] != no_key[1]["error"]),
        ("هیچ پاسخِ ۴۰۱ای خودِ کلید را برنمی‌گرداند",
         "k-someone-else" not in json.dumps(bad_key[1], ensure_ascii=False)),
        ("کلیدِ درست کدِ ۲۰۰ و نامِ صدازننده", ok[0] == 200 and "caller" in ok[1]),
        ("عبور از نرخ کدِ ۴۲۹ می‌دهد، نه ۵۰۰", over[0] == 429),
        ("هر ۴۲۹ سربرگِ Retry-After دارد", over[2].get("Retry-After") is not None),
        ("Retry-After عددِ ثانیه است", str(over[2].get("Retry-After")).isdigit()),
    ]


checks = boundary_contract()
for name, passed in checks:
    print(f"  {'سبز' if passed else 'قرمز'}  {name}")
print(f"{sum(p for _, p in checks)} از {len(checks)} سبز")
  سبز  بی‌کلید کدِ ۴۰۱ می‌گیرد
  سبز  کلیدِ ناشناس هم ۴۰۱، با پیامِ متفاوت
  سبز  هیچ پاسخِ ۴۰۱ای خودِ کلید را برنمی‌گرداند
  سبز  کلیدِ درست کدِ ۲۰۰ و نامِ صدازننده
  سبز  عبور از نرخ کدِ ۴۲۹ می‌دهد، نه ۵۰۰
  سبز  هر ۴۲۹ سربرگِ Retry-After دارد
  سبز  Retry-After عددِ ثانیه است
7 از 7 سبز

۷ از ۷ — و بندِ پنجم مهم‌ترینشان است: «کدِ ۴۲۹ می‌دهد، نه ۵۰۰».

تفاوتشان یک کلمه است و همان یک کلمه رفتارِ کلاینت را عوض می‌کند. ۵۰۰ یعنی «من خرابم، دوباره بزن». ۴۲۹ یعنی «من سالمم، تو زیاده‌روی کردی، به‌اندازهٔ Retry-After صبر کن». سرویسی که موقعِ فشار ۵۰۰ برمی‌گرداند، صدازننده‌ها را دعوت می‌کند که بلافاصله دوباره بزنند — و همان حلقه‌ای می‌شود که فصلِ ۷ اسمش را می‌گذارد.

۷. مرز چه چیزی را حل نمی‌کند#

اگر نگرانی این است… مرزِ این فصل جواب می‌دهد؟ کارِ درست
یک تیم کلِ ظرفیت را می‌خورد بله سهمِ جدا برای هر کلید (بخشِ ۴)
اسکریپتی رها شده و بی‌نهایت می‌زند بله نرخ + سهمیه (بخشِ ۵)
کلید در یک artifact بیرون رفته نه — فقط پیدایش می‌کند کلید را عوض کن، بعد بازرس را خودکار کن
کسی محتوای درخواستِ دیگری را می‌بیند نه این مسئلهٔ رمزنگاریِ مسیر است، نه مرزِ نرخ
یک کلید بینِ ده نفر دست‌به‌دست شده نه کلیدِ جدا برای هر مصرف‌کننده
سرویس ذاتاً کند است نه cache و مدلِ کوچک‌تر (فصلِ ۵)
مدل جوابِ بد می‌دهد نه هیچ محدودیتی کیفیت نمی‌سازد

سطرِ آخر عمدی است. مرز فقط می‌گوید کی و چقدر؛ دربارهٔ چه چیزی حرفی ندارد. سرویسی که مرزِ عالی و مدلِ بد دارد، فقط با نظم و ترتیب جوابِ غلط می‌دهد.

🤖 از دستیارت بپرس: «تفاوتِ 429 Too Many Requests و 403 Forbidden و 401 Unauthorized چیست و کدام‌یک یعنی «دوباره تلاش کن»؟» بعد این را بپرس: «اگر پنجاه کلاینت هم‌زمان ۴۲۹ بگیرند و همه‌شان دقیقاً Retry-After ثانیه صبر کنند، ثانیهٔ بعد چه اتفاقی می‌افتد؟» — جوابش یک موجِ هم‌زمانِ تازه است، و دواش همان jitterی است که فصلِ ۴ می‌سازد.

واژه‌های تازهٔ این فصل#

کلمه تلفظ به حروف فارسی یعنی چه
API key ای‌پی‌آی کی رشته‌ای که هویتِ صدازنندهٔ یک سرویس را ثابت می‌کند
secret manager سکرت منیجر جایی بیرونِ کد که رازها را نگه می‌دارد و به کد می‌دهد
rate limit ریت لیمیت سقفِ تعدادِ درخواست در یک بازهٔ زمانی
sliding window اسلایدینگ ویندو پنجره‌ای که همیشه «فلان‌قدر گذشته از همین لحظه» است
quota کوتا سقفِ کلیِ یک دوره، که با گذشتِ زمان پر نمی‌شود
throttling تراتلینگ کند کردن یا رد کردنِ درخواستِ اضافی به‌جای شکستن
noisy neighbour نویزی نیبر مصرف‌کننده‌ای که با پرخوری، بقیه را از سرویس محروم می‌کند

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

مرز گفت چه کسی حق دارد و چقدر. فصلِ بعد سراغِ کاری می‌رود که اصلاً در قالبِ «درخواست و پاسخ» جا نمی‌شود و آن را به یک صف می‌سپارد: با نرخِ شکستِ سی درصد چند کار بدونِ تلاشِ دوباره جان سالم به در می‌برند و چند تا با آن، و چرا یک کارِ غیریکسان‌توان موقعِ تلاشِ دوباره عوارضِ تکراری می‌سازد. و همان‌جا ساعتِ مجازی را با نامِ خودش می‌سازیم — همان ترفندی که این فصل قرضش گرفت.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.