Custom Connector Architecture

وقتی connector از «چند endpoint» به یک توده‌ی غیرقابل‌تشخیص تبدیل می‌شود

فرض کن provider پاسخ 200 داده، اما connection قبل از دریافت body قطع شده است. چند ثانیه بعد webhook همان عملیات می‌رسد، و هم‌زمان provider یک فیلد پاسخ را deprecated کرده است. اگر transport، auth، schema، retry، webhook و business mapping در یک تابع مخلوط شده باشند، دیگر نمی‌توانی جواب بدهی: آیا write واقعاً انجام شد؟ retry امن است؟ webhook تکراری است؟ تغییر schema فقط adapter را می‌شکند یا domain داخلی را هم؟

خروجی این درس Custom Connector Boundary and Contract Matrix v1 است. هر تصمیم باید از قرارداد provider تا promotion به canonical domain قابل بازسازی باشد؛ بدون secret واقعی، tenant واقعی یا hidden reasoning.

مرز مالکیت COM-029

COM-029 مالک معماری connector، لایه‌های contract و failure boundary است. COM-028 integration مشخص WooCommerce را مالک است و COM-030 canonical Order State Machine را. این درس نه vendor status را state داخلی اعلام می‌کند و نه success HTTP را permission برای تغییر business state می‌داند.

سه خط قرمز:

1. API description != runtime guarantee
2. provider payload != canonical domain
3. timeout != safe retry

مدل ذهنی: Provider contract → Transport/Auth → Schemas → Events → Retry/Rate limit → Adapter mapping → Canonical promotion → Reconciliation

مسیر قابل‌ممیزی:

provider contract/version → base URL + scoped auth → request/response schema → webhook/callback semantics → event identity → idempotency/retry/backoff/rate limit → mapping adapter/version → canonical command/event → reconciliation → evidence

هر لایه باید failure خودش را داشته باشد. اگر auth scope مشکل دارد، mapping را متهم نکن. اگر schema drift کرده، domain model را بی‌صدا عوض نکن. اگر write timeout شده، نتیجه را قبل از reconciliation «failed» یا «success» فرض نکن.

FACT، INFERENCE و DESIGN را جدا نگه دار

FACT: OpenAPI Specification 3.2.1 در 10 سپتامبر 2026 منتشر شده و نسخه‌ی جاری منتشرشده‌ی OAS است. OAS یک interface description مستقل از زبان برای HTTP APIها تعریف می‌کند.

FACT: در OAS 3.2.1، webhooks برای inbound requestهایی است که مستقل از یک API call دیگر رخ می‌دهند؛ callbacks به parent operation وابسته‌اند. توصیف این دو، delivery guarantee یا exactly-once semantics ایجاد نمی‌کند.

INFERENCE: وقتی contract، transport/auth، schema، delivery، retry/idempotency و mapping مستقل observable باشند، failure isolation و migration کم‌ریسک‌تر می‌شود.

DESIGN: MAKNOW provider quirk را در adapter نگه می‌دارد، mapping را version می‌کند، write نامطمئن را reconcile می‌کند و تا evidence decisive کامل نشود canonical success صادر نمی‌کند. این‌ها design محلی‌اند، نه requirement خود OpenAPI.

قرارداد ۲۳بعدی Connector

Gate 1 — Connector و Provider را هویت‌دار کن

connector_id و provider_id اجازه می‌دهند failure و migration را به نمونه‌ی مشخص وصل کنی. «API خارجی» یک identity کافی نیست.

Gate 2 — Contract version را مستقل از implementation version ثبت کن

contract_version مرز سازگاری provider را نشان می‌دهد. تغییر contract بدون ثبت version یعنی نمی‌توانی بفهمی کدام mapping و test معتبر بوده‌اند.

Gate 3 — OpenAPI ref evidence است، نه تضمین رفتار

openapi_ref نشان می‌دهد چه interfaceای توصیف شده؛ اما runtime behavior، semantic compatibility، latency و delivery guarantee را ثابت نمی‌کند.

Gate 4 — Base URL و credential باید reference باشند، نه secret داخل package

base_url_ref و credential_scope باید قابل‌ردیابی باشند ولی credential واقعی نباید در artifact آموزشی/connector contract embed شود.

Gate 5 — Auth scheme بدون scope کافی نیست

دانستن OAuth/API key نوع credential را می‌گوید، نه اینکه این credential مجاز به همان operation باشد. scope کم یا مبهم → HOLD_AUTH_SCOPE.

Gate 6 — Request و Response schema را جدا version کن

provider ممکن است response field را deprecate کند بدون اینکه request تغییر کند. اگر response_schema_version عوض شد ولی mapping_version ثابت ماند، promotion باید متوقف شود.

Gate 7 — Webhook و Callback را یکی نکن

Callback به parent operation وابسته است؛ webhook می‌تواند مستقل وارد شود. مهاجرت callback→webhook معمولاً endpoint rename ساده نیست: identity، verification، replay/retry و lifecycle ممکن است عوض شوند.

Gate 8 — Inbound event باید identity قابل‌dedupe داشته باشد

بدون event_identity نمی‌توان retry provider، replay یا duplicate delivery را از event جدید جدا کرد. «provider گفت webhook است» exactly-once نیست.

Gate 9 — Retryable write به idempotency یا reconciliation نیاز دارد

برای writeای که timeout شده، blind retry می‌تواند اثر را دو بار بسازد. اگر idempotency key پشتیبانی نمی‌شود، باید reconciliation بتواند effect قبلی را پیدا کند.

Gate 10 — Backoff باید rate-limit signal را بفهمد

429، Retry-After یا signal معادل باید policy را کنترل کند. retry loop سریع و ثابت هم provider را تشدید می‌کند و هم outage را طولانی‌تر.

Gate 11 — Provider quirk داخل mapping adapter می‌ماند

status یا field نام provider نباید مستقیم وارد canonical domain شود. adapter آن را به canonical_command_or_event نگاشت می‌کند و version خودش را دارد.

Gate 12 — Reconciliation قبل از promotion نامطمئن

اگر response قطع شد، webhook دیر رسید یا event order مبهم شد، reconciliation_strategy تعیین می‌کند با چه evidenceای external effect به canonical truth تبدیل می‌شود.

Gate 13 — Deprecation یک state عملیاتی است

deprecation_state باید ACTIVE/DEPRECATED/REMOVAL_DATE یا state صریح مشابه داشته باشد. فیلد deprecated نباید تا روز حذف «نامرئی» بماند.

Gate 14 — Missing decisive evidence باید fail-closed باشد

اگر version، auth scope، event identity، mapping version یا reconciliation ناقص است، HOLD_* مناسب صادر کن؛ dashboard تمیز مهم‌تر از boundary درست نیست.

مثال‌های حل‌شده

1. Baseline versioned connector → ACCEPT_CONTRACT

Contract، schemaها، scoped auth، event identity، idempotency، backoff، mapping version و reconciliation همگی evidence دارند. canonical interface می‌تواند با confidence محدود پذیرفته شود.

2. Response res-v7 → res-v8 ولی map-v9 ثابت → HOLD_MAPPING_VERSION

حتی اگر parser crash نکند، semantic mapping دیگر اثبات نشده است. ابتدا impact را بررسی و mapping contract را version کن.

3. POST timeout + blind retry + no idempotency/reconcile → HOLD_IDEMPOTENCY_GAP

Timeout نمی‌گوید اثر خارجی انجام نشده. بدون write identity یا reconciliation، retry می‌تواند duplicate effect بسازد.

4. Provider status مستقیم وارد Order domain → HOLD_PROVIDER_LEAKAGE

Provider-specific vocabulary باید داخل adapter بماند. Canonical domain فقط command/event خودش را می‌بیند.

5. Webhook بدون event identity با فرض exactly-once → HOLD_EVENT_IDENTITY

Delivery type به‌تنهایی uniqueness نمی‌سازد. replay و duplicate باید طراحی‌شده باشند.

6. Transfer: callback حذف، webhook v4 اضافه، response field deprecated

contract_version و mapping_version bump می‌شوند، webhook verification و event identity صریح می‌شوند، callback به deprecated می‌رود؛ اما canonical_command_or_event اگر semantic meaning ثابت است بدون تغییر باقی می‌ماند.

Failure modeهای رایج

• یک client class که auth، retry، mapping و business mutation را با هم انجام می‌دهد؛
• OpenAPI-valid را معادل semantically-compatible دانستن؛
• embedding secret داخل config/package؛
• auth scheme بدون credential scope؛
• schema change بدون mapping-version bump؛
• webhook را exactly-once فرض کردن؛
• blind retry روی write timeout؛
• ignore کردن Retry-After یا rate-limit signal؛
• provider status leakage به canonical model؛
• success code را canonical completion دانستن؛
• deprecation بدون owner/removal plan؛
• transfer با copy کردن تصمیم baseline بدون recompute.

Alternatives و trade-offها

Endpoint glue: شروع سریع، اما failure boundaries و migration سخت.

Generated client from OpenAPI: برای transport/types بسیار مفید است، اما semantic mapping، retry safety، event identity و reconciliation را به‌تنهایی حل نمی‌کند.

Unified provider model: کد consumer را ساده می‌کند، اما اگر lowest-common-denominator شود featureهای provider را پنهان می‌کند. adapter باید loss را صریح کند.

Event-driven only: latency خوب برای inbound changes، ولی بدون pull/reconcile ممکن است missed/replayed events کشف نشوند.

Layered connector + canonical boundary: کمی قرارداد و instrumentation بیشتر می‌خواهد، اما failure isolation، migration و auditability بهتر می‌دهد. این pattern محدود این درس است.

Experienced bridge: شانزده سؤال review

1. connector/provider identity چیست؟
2. contract version کجاست؟
3. OpenAPI ref به چه نسخه‌ای اشاره دارد؟
4. base URL و secret چگونه reference شده‌اند؟
5. auth scope دقیقاً همان operation را پوشش می‌دهد؟
6. request/response schema مستقل version شده‌اند؟
7. inbound flow webhook است یا callback و چرا؟
8. event identity چیست؟
9. duplicate/replay چگونه تشخیص داده می‌شود؟
10. write timeout با چه idempotency/reconciliation policy بسته می‌شود؟
11. retry policy چه failureهایی را retry می‌کند؟
12. rate-limit signal چگونه backoff را تغییر می‌دهد؟
13. mapping version چه زمانی bump می‌شود؟
14. provider-specific vocabulary کجا متوقف می‌شود؟
15. deprecation چه owner و removal plan دارد؟
16. آیا canonical promotion فقط از evidence قابل‌بازسازی است؟

تمرین هدایت‌شده و مستقل

Lab آفلاین ۸ fixture دارد: baseline، schema drift، unsafe timeout retry، provider leakage، webhook بدون identity، auth scope ناقص، rate-limit بدون backoff و transfer callback→webhook.

تمرین مستقل: provider فیلد legacy_status را deprecated و status_code را جایگزین می‌کند؛ callback قدیمی را هم حذف و webhook جدید اضافه می‌کند. Contract را طوری update کن که adapter mapping تغییر کند، event identity و verification صریح شوند و canonical event interface بدون نیاز واقعی تغییر نکند.

Verification evidence

Artifact پذیرفتنی همه‌ی ۲۳ بُعد را پر می‌کند یا یک non-success state صریح می‌دهد. هیچ secret واقعی داخل package نیست؛ schema/mapping version coherence قابل‌بررسی است؛ unsafe retry fail-closed می‌شود؛ provider vocabulary قبل از canonical boundary متوقف می‌شود؛ deprecation و reconciliation قابل‌ردیابی‌اند؛ و transfer فقط affected layers را تغییر می‌دهد.

Lab کاملاً synthetic و offline است؛ API key، network، store واقعی یا customer data لازم ندارد.

Assessment و transfer

برای پایان درس باید بتوانی:

1. مرز COM-029 را در برابر COM-028 و COM-030 توضیح بدهی؛
2. Custom Connector Boundary and Contract Matrix v1 را بسازی؛
3. OpenAPI description را از runtime guarantee جدا کنی؛
4. webhook و callback را درست تفکیک کنی؛
5. unsafe timeout retry را رد کنی؛
6. schema drift بدون mapping bump را fail-closed کنی؛
7. provider field/status را پشت adapter نگه داری؛
8. transfer callback→webhook + deprecation را بدون شکستن canonical interface بازطراحی کنی.

منابع و freshness

• OpenAPI Specification 3.2.1 — منتشرشده 10 سپتامبر 2026؛ rechecked در 15 سپتامبر 2026. مرجع FACT برای interface description، webhooks و callbacks.
• Bible فریز‌شده‌ی COM-029 در 3 سپتامبر 2026 نسخه 3.2.0 را current ثبت کرده بود؛ bytes Bible تغییر نکرده و freshness overlay فقط FACT خارجی را به 3.2.1 به‌روز کرده است.
• Layer boundaries، typed HOLD states، retry/reconciliation policy و canonical promotion در این درس MAKNOW DESIGN هستند و به OpenAPI نسبت داده نمی‌شوند.