# فصل ۰۳ — مرزِ سرویس: کی، چقدر، و با چه کلیدی

<div dir="rtl">

# فصل ۰۳ — مرزِ سرویس: کی، چقدر، و با چه کلیدی

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

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

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

![یک گردانه با شمارندهٔ کنارش](/lesson-assets/t4-s03-boundary-and-limits/prompt/01-image-turnstile-and-meter.png)

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

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

## قبل از شروع

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

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

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-4-deployment/session-03-boundary-and-limits.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

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

<div dir="rtl">

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

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

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

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

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

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

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

</div>

```python
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")
```

```text
بستهٔ سالم:
  config.json  پاک                    هش 2fdc4619e996
  serve.py     پاک                    هش 7f9a6a020c0c
همان بسته، بعد از یک خطِ اضافه:
  config.json  نشتی: کلیدِ سرویس      هش 6b2094432d60
  serve.py     پاک                    هش 7f9a6a020c0c
```

<div dir="rtl">

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

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

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

</div>

```python
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] + "…")     # خودِ کلید هرگز چاپ نمی‌شود
```

```text-approx
کلید از کجا آمد: مقدارِ نمونهٔ همین فصل
چند حرفِ اولش  : k-mo…
```

<div dir="rtl">

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

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

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

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

</div>

```python
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()))
```

```text
بدونِ کلید  : (401, {'error': 'کلید لازم است'})
کلیدِ ناشناس: (401, {'error': 'کلید معتبر نیست'})
کلیدِ درست  : {'label': 'حساب کاربری', 'model_version': '1.0.0', 'caller': 'اپلیکیشن'}
شمارنده‌ها  : سرو شد 1 · بدونِ کلید 1 · کلیدِ ناشناس 1 · از سهم گذشت 0
```

<div dir="rtl">

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

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

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

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

</div>

```python
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] == "اپلیکیشن"))
```

```text
ثانیه  صدازننده       رسیده    بی‌مرز    با مرز    ردشده
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
```

<div dir="rtl">

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

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

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

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

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

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

</div>

```python
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()))
```

```text
تندِ یک‌پنجره‌ای: ۲۰۰ → 10 · ۴۲۹ → 30 · اولین ۴۲۹ در درخواستِ 11
    پیام: نرخت از حد گذشت · Retry-After: 1 ثانیه
آرام، ولی طولانی: ۲۰۰ → 15 · ۴۲۹ → 25 · اولین ۴۲۹ در درخواستِ 16
    پیام: سهمیهٔ دوره‌ات تمام شد · Retry-After: 3600 ثانیه
سهمیهٔ مصرف‌شده: {'تحلیل': 25}
شمارنده‌ها    : سرو شد 25 · بدونِ کلید 0 · کلیدِ ناشناس 0 · از سهم گذشت 55
```

<div dir="rtl">

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

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

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

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

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

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

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

</div>

```python
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)} سبز")
```

```text
  سبز  بی‌کلید کدِ ۴۰۱ می‌گیرد
  سبز  کلیدِ ناشناس هم ۴۰۱، با پیامِ متفاوت
  سبز  هیچ پاسخِ ۴۰۱ای خودِ کلید را برنمی‌گرداند
  سبز  کلیدِ درست کدِ ۲۰۰ و نامِ صدازننده
  سبز  عبور از نرخ کدِ ۴۲۹ می‌دهد، نه ۵۰۰
  سبز  هر ۴۲۹ سربرگِ Retry-After دارد
  سبز  Retry-After عددِ ثانیه است
7 از 7 سبز
```

<div dir="rtl">

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

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

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

</div>

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

<div dir="rtl">

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

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

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

</div>

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

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا سهمِ نرخ باید **برای هر کلید جدا** باشد و نه یکی برای کلِ سرویس؟

**تمرینِ اجباری:** یک ردهٔ سوم به `KEYS` اضافه کن با سهمِ متفاوت — مثلاً «مهمان» با `limit=2` و `quota=5`. حالا همان ترافیکِ بخشِ ۴ را با هر سه رده اجرا کن و **سه عدد** بده: ردشدهٔ هر رده، ردشدهٔ کل، و **تعدادِ دفعاتی که یک ردهٔ سالم به‌خاطرِ ردهٔ پرخور رد می‌شود** (که باید صفر بماند — ثابتش کن). **بعد عمداً خرابش کن:** سهم را به‌جای کلید، روی کلِ سرویس بگذار و همان سه عدد را دوباره بده. **تفاوتِ عددِ سوم، کلِ درسِ این فصل است.**

**تمرینِ ستاره‌دار ⭐:** `SlidingWindow` را با یک **سطلِ توکن** (`token bucket`) عوض کن: سطلی با ظرفیتِ `B` که با نرخِ `r` توکن در ثانیه پر می‌شود و هر درخواست یک توکن برمی‌دارد. **سه چیز را اندازه بگیر:** با چه `B` و `r`ی همان ۳۰ ردِ بخشِ ۴ را می‌گیری، بیشترین انفجارِ لحظه‌ایِ مجاز در هر تنظیم، و اینکه اپلیکیشن هنوز صفر بار رد می‌شود یا نه. **و سؤالِ سخت را جواب بده: کدام‌یک از این دو الگو حافظهٔ کمتری می‌خورد وقتی صد هزار کلیدِ فعال داری، و چرا؟** — جوابت باید به این برسد که پنجرهٔ لغزان **هر ضربه** را نگه می‌دارد و سطل فقط **دو عدد**.

## در فصل بعد

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

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t4/s03-boundary-and-limits (یادستان, Yaadestan)
