{
  "title": "تصمیم معماری درگاه API Gateway",
  "slug": "team/platform/gateway/ADR/ADR-Gateway-001",
  "url": "/docs/team/platform/gateway/ADR/ADR-Gateway-001",
  "frontmatter": {
    "layout": "doc",
    "title": "تصمیم معماری درگاه API Gateway",
    "description": "تصمیم معماری برای انتخاب فناوری درگاه ورودی واحد و نحوه اعتبارسنجی توکن‌ها",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Antigravity",
    "owner": "Platform Team",
    "created_at": "2026-06-14",
    "updated_at": "2026-06-14",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "تصمیم معماری درگاه API Gateway",
      "content": "**Architectural Decision Record — API Gateway Choice & Strategy**\n\n> **ADR-Gateway-001**"
    },
    {
      "level": 2,
      "heading": "وضعیت",
      "content": "APPROVED (تایید شده)"
    },
    {
      "level": 2,
      "heading": "تاریخ",
      "content": "2026-06-14\n\n---"
    },
    {
      "level": 2,
      "heading": "زمینه",
      "content": "**Context**\n\nدر معماری میکروسرویس پلتفرم NONS، بخش فرانت‌اند (کلاینت‌ها) نباید مستقیماً با سرویس‌های متعدد و متفرق بک‌اند ارتباط برقرار کند. تعامل مستقیم کلاینت‌ها با میکروسرویس‌ها مشکلاتی همچون امنیت ضعیف، مدیریت نامتراکم CORS، دشواری در پیاده‌سازی ردگیری درخواست‌ها (Tracing)، و افزایش سطح حمله (Attack Surface) را به همراه دارد. \n\nهمچنین طبق استانداردهای پلتفرم، لایه درگاه باید فاقد هرگونه منطق کسب‌وکار (Business Logic) یا دانش نسبت به دامنه‌ها باشد و صرفاً وظایف پلتفرمی و انتقالی را بر عهده بگیرد.\n\n---"
    },
    {
      "level": 2,
      "heading": "مسئله",
      "content": "**Problem Statement**\n\nبرای ایجاد یک نقطه ورود واحد (Single Entry Point)، نیازمند درگاهی هستیم که:\n- ترافیک‌های ورودی را به میکروسرویس‌های متناظر هدایت کند.\n- امکان ثبت پویای سرویس‌ها (Dynamic Service Discovery) بدون نیاز به توقف و ری‌استارت درگاه را داشته باشد.\n- فاقد منطق کسب‌وکار باشد.\n- عملکردهای متقاطع (Cross-Cutting Concerns) مانند اعتبارسنجی بدون حالت توکن‌های دسترسی (JWT Validation)، اعمال محدودیت نرخ درخواست (Rate Limiting)، مدیریت هدرهای امنیتی، CORS و تزریق Correlation ID را در بالاترین کارایی مدیریت کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "گزینه‌های بررسی‌شده",
      "content": "**Considered Options**"
    },
    {
      "level": 3,
      "heading": "گزینه ۱ — توسعه درگاه اختصاصی با Node.js / Express",
      "content": "پیاده‌سازی یک سرویس پروکسی اختصاصی با زبان TypeScript و فریم‌ورک Express یا Fastify.\n\n- **مزایا:** کنترل ۱۰۰٪ روی کد، امکان نوشتن مستقیم میان‌افزارها (Middlewares) در لایه Node.js.\n- **معایب:** کارایی پایین‌تر در مقایسه با وب‌سرورهای بومی کامپایل‌شده (C/Go)، نیاز به نگهداری مداوم کد، پیچیدگی در پیاده‌سازی پروکسی با پشتیبانی از WebSocket، عدم وجود ویژگی بومی Service Discovery و نیاز به توسعه دستی آن.\n- **نتیجه:** رد شد."
    },
    {
      "level": 3,
      "heading": "گزینه ۲ — استفاده از Nginx به عنوان درگاه ایستا",
      "content": "استفاده از وب‌سرور محبوب Nginx برای مسیریابی درخواست‌ها.\n\n- **مزایا:** سرعت فوق‌العاده بالا، مصرف منابع بسیار کم، پایداری بالا در تولید.\n- **معایب:** پیکربندی‌ها کاملاً ایستا (Static) هستند. در صورت اضافه شدن یا تغییر پورت هر میکروسرویس در داکر، فایل‌های تنظیمات Nginx باید به صورت دستی یا با اسکریپت‌های پیچیده تغییر کرده و پروسه Nginx ری‌لود (Reload) شود. پیاده‌سازی اعتبارسنجی JWT به لایه‌های پولی یا برنامه‌نویسی Lua (مانند OpenResty) نیاز دارد. (در معماری نهایی، کلیدهای JWKS توسط **Token Service (Ory Hydra)** منتشر می‌شوند.)\n- **نتیجه:** رد شد."
    },
    {
      "level": 3,
      "heading": "گزینه ۳ — استفاده از Kong API Gateway",
      "content": "یک درگاه مدیریت‌یافته مبتنی بر OpenResty (Nginx + Lua).\n\n- **مزایا:** پورتفولیوی بسیار قوی از پلاگین‌ها، کارایی بسیار بالا، امکانات گسترده امنیتی.\n- **معایب:** سنگین بودن ساختار (نیاز به دیتابیس جداگانه مانند Cassandra یا PostgreSQL در مدل سنتی)، پیچیدگی بالای کانفیگ در مدل Declarative (بدون دیتابیس)، و لایسنس پولی برای برخی از پلاگین‌های مهم.\n- **نتیجه:** رد شد."
    },
    {
      "level": 3,
      "heading": "گزینه ۴ — استفاده از Traefik (v3) ✅",
      "content": "یک پروکسی معکوس و درگاه API مدرن و سبک‌وزن که برای سیستم‌های کانتینری (Docker & Kubernetes) نوشته شده است.\n\n- **مزایا:**\n  - **کشف سرویس پویا (Dynamic Service Discovery):** به صورت کاملاً بومی با ارائه‌دهندگان کانتینری (مانند Kubernetes API و Docker Provider) ادغام می‌شود و مسیرها بلافاصله و بدون نیاز به ری‌استارت بارگذاری می‌شوند.\n  - **سرعت و کارایی بالا:** نوشته‌شده با زبان Go و کامپایل شده به کدهای بومی.\n  - **سیستم میان‌افزار (Middleware System) قدرتمند:** پشتیبانی داخلی از ابزارهای Rate Limiting، CORS، هدرهای امنیتی و Forward Auth.\n  - **پشتیبانی بومی از TLS/Let's Encrypt:** دریافت و تمدید خودکار گواهینامه‌های SSL.\n  - **داشبورد مانیتورینگ بومی:** ارائه یک وب‌اینترفیس ساده و کارآمد برای مشاهده وضعیت مسیرها و میان‌افزارها.\n- **نتیجه:** پذیرفته شد.\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیم",
      "content": "**Decision**\n\nاستفاده از **Traefik نسخه ۳.۳** به عنوان API Gateway رسمی پلتفرم NONS تصویب شد."
    },
    {
      "level": 3,
      "heading": "جزئیات فنی پیاده‌سازی تصمیمات کلیدی:",
      "content": "1. **مسیریابی پویا و استراتژی کشف سرویس (D17):**\n   - **مسیر رسمی توسعه و استقرار (Kubernetes-Native):** مسیریابی و کشف سرویس‌ها در کلیه محیط‌ها (شامل توسعه محلی در کلاستر K3d و استقرار پروداکشن در K3s) به صورت پویا بر پایه Traefik + Kubernetes CRD / Ingress انجام می‌شود (D13).\n   - **لایه قدیمی سازگاری (Legacy Docker Compose):** مسیریابی بر پایه Docker Provider (`providers.docker`) صرفاً به عنوان لایه قدیمی انطباق توسعه طبقه‌بندی شده و خارج از مسیرهای استقرار رسمی است.\n2. **اعتبارسنجی بدون حالت و کش کلیدها (Stateless JWT Validation):** بررسی اعتبار JWT به صورت Stateless (بررسی امضا، exp، issuer و audience) انجام می‌شود. کلیدهای عمومی JWKS مربوط به Ory Hydra به صورت محلی کش می‌شوند. زمان انقضای کش کلیدها (Cache Refresh Interval) از طریق متغیر محیطی (مانند `GATEWAY_JWKS_CACHE_TTL` با مقدار پیش‌فرض ۱ ساعت) مدیریت می‌شود.\n3. **سیاست طول عمر توکن‌ها (Token TTL Policy):** مقادیر TTL از متغیرهای محیطی (`AUTH_ACCESS_TOKEN_TTL` and `AUTH_REFRESH_TOKEN_TTL`) خوانده می‌شوند. سیاست پیش‌فرض اولیه پیشنهادی پلتفرم بدین صورت است: Access Token برابر `15m` و Refresh Token برابر `30d`.\n4. **سیاست ابطال و خروج (Logout & Revocation Policy):** عدم ابطال فوری توکن‌های دسترسی صادرشده یک تصمیم معماری آگاهانه و دائمی است (محدود به فاز MVP نیست). درگاه فاقد لیست سیاه توکن‌هاست و تا پایان زمان TTL توکن را معتبر می‌داند. در صورت نیاز عملیاتی آینده، یک Revocation Cache مبتنی بر Redis بدون تغییر در درگاه قابل الحاق است.\n5. **محدودیت نرخ بر پایه Redis (Redis-based Rate Limiting):** تمامی شمارنده‌ها برای تضمین مقیاس‌پذیری افقی از روز اول (Day 1) در **Redis** نگهداری می‌شوند. استفاده از In-memory Rate Limiting به طور کامل رد شد.\n6. **سیاست وابستگی و خرابی آبشاری (Fail-Closed Auth Strategy):** ارتباط درگاه با Auth Service تحت استراتژی **Fail-Closed** مدیریت می‌شود؛ یعنی در صورت عدم دسترسی به Auth Service، درگاه درخواست را بلاک کرده و خطای `503 Service Unavailable` بازمی‌گرداند. تنظیمات ارتباط با Auth Service شامل Timeout برابر `2s` و تعداد تلاش مجدد (Retry) برابر `0` است.\n7. **تزریق و مرز اعتماد هویت (Identity Injection & Trust Boundary):** پس از احراز هویت موفق، درگاه هدرهای هویتی شامل `X-User-Id` (شناسه کاربر Kratos)، `X-Subject` (موضوع توکن)، `X-Roles` (نقش‌ها)، `X-Permissions` (مجوزها) و `X-Trace-Id` را تزریق کرده و به مقصد می‌فرستد. **قانون امنیتی حیاتی:** این هدرها فقط و فقط زمانی معتبر هستند که از سمت درگاه فرستاده شده باشند؛ سرویس‌های بالادست باید تمامی هدرهای هویتی مستقیم ارسالی توسط کلاینت را پاک/نادیده بگیرند. سرویس‌ها نیاز به اعتبارسنجی مجدد JWT ندارند.\n8. **تزریق و انتشار Correlation ID:** وجود هدر `X-Correlation-ID` الزامی است و باید به تمامی سرویس‌های بالادستی منتشر (Propagate) شود.\n9. **مدیریت رازها و استقرار (D15, D18):** استقرار رسمی درگاه در محیط‌های کلاستر از طریق Helm انجام می‌شود. هیچ رازی در مخزن ذخیره نمی‌شود.\n   - **فاز ۱ (فعلی):** استفاده از Kubernetes Secrets.\n   - **فاز ۲ (آینده):** استفاده از HashiCorp Vault.\n10. **نقشه راه توسعه پیشرفته (Advanced Roadmap):**\n    - **ارتباطات امن داخلی:** فعال‌سازی mTLS به فاز **Post-Kubernetes Adoption** موکول گردید.\n    - **کنترل جریان خرابی:** پیاده‌سازی Circuit Breaker در فازهای آینده از طریق **Service Mesh** (الگوی Envoy / Istio / Linkerd) انجام خواهد شد.\n    - **سیستم همکاران فروش:** سیاست دامنه کوکی (Cookie Domain Strategy) به **فاز Affiliate** موکول گردید.\n11. **سیاست CORS:** مدیریت CORS صرفاً و به صورت متمرکز در Gateway انجام می‌شود. هیچ سرویس داخلی مجاز به داشتن CORS Policy مستقل نیست.\n12. **حفظ ساختار مسیرها (Path Rewriting):** درگاه عمل بازنویسی مسیر را انجام نمی‌دهد؛ هر میکروسرویس مسئول نسخه‌بندی APIهای داخلی خود است.\n\n---"
    },
    {
      "level": 2,
      "heading": "مدل معماری",
      "content": "**Architectural Model**\n\n```mermaid\ngraph TD\n    Client[Client / Browser] -->|1. Request with Bearer Token| Gateway[Traefik API Gateway]\n    Gateway -->|2. Forward Auth /v1/auth/validate| AuthService[Auth Service]\n    AuthService -->|3. Get JWKS Keys | Hydra[Ory Hydra]\n    AuthService -->>|4. Valid / Inject user headers| Gateway\n    Gateway -->|5. Forward with X-User-Id| Upstream[Upstream Microservices]\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "پیامدها",
      "content": "**Consequences**\n\n- **تسهیل توسعه:** مسیرها به صورت بومی در مانیفست‌های Kubernetes/Ingress تعریف می‌شوند. لایه قدیمی داکر کامپوز نیز صرفاً برای سازگاری موقت قدیمی از برچسب‌های Docker Labels استفاده می‌کند.\n- **امنیت متمرکز:** تمام سیاست‌های امنیتی CORS، هدرهای HTTP و محدودیت نرخ درگاه به صورت متمرکز در Traefik مدیریت می‌شوند.\n- **جداسازی کامل:** میکروسرویس‌های بک‌اند نیازی به تعامل مستقیم با Token Service (Ory Hydra) جهت بررسی امضای توکن ندارند و اطلاعات هویتی کاربر را مستقیماً از هدرهای معتبر ارسالی توسط Gateway دریافت می‌کنند.\n\n---"
    },
    {
      "level": 2,
      "heading": "مزایا و معایب",
      "content": "**Pros & Cons**"
    },
    {
      "level": 3,
      "heading": "مزایا (Pros)",
      "content": "- ✅ ثبت کاملاً داینامیک سرویس‌ها بدون نیاز به ری‌استارت درگاه.\n- ✅ سبک‌وزن بودن و مصرف بسیار پایین رم و پردازنده (بدون نیاز به دیتابیس جداگانه).\n- ✅ متمرکز شدن منطق اعتبارسنجی هویت در سطح درگاه و Bridge.\n- ✅ سازگاری ۱۰۰ درصدی با Kubernetes Ingress در هر دو فاز توسعه محلی و پروداکشن."
    },
    {
      "level": 3,
      "heading": "معایب (Cons)",
      "content": "- ❌ وابستگی به اجرای سرویس Forward Auth برای مسیرهای احراز هویت شده (افزایش ناچیز تاخیر شبکه که با کش کردن کلیدهای JWKS در سطح سرویس احراز هویت به کمتر از ۲ میلی‌ثانیه کاهش می‌یابد).\n\n---\n\n**آخرین بروزرسانی:** 2026-06-14  \n**وضعیت:** ✅ تایید شده (APPROVED)"
    }
  ]
}