Connecting to production: the architecture of remote bindings 🔌 — بازنویسی شده برای خوانندگان حوزه DevOps / SRE. تاریخ: 2025-11-12. نویسندگان اصلی: Samuel Macleod و Dario Piotrowicz.

Remote bindings چیست و چرا مهم است؟ 😊 Remote bindings اتصالاتی هستند که به منابعی که روی حساب Cloudflare شما مستقر شده‌اند وصل می‌شوند، به جای اینکه شبیه‌سازی محلی استفاده شوند. با عمومی شدن این قابلیت، حالا می‌توانید هنگام اجرای کد Worker روی ماشین لوکال، مستقیماً به منابعی مثل R2 buckets و D1 databases متصل شوید. این یعنی می‌توانید تغییرات محلی را روی داده‌های واقعی و سرویس‌های زنده تست کنید، بدون اینکه هر بار نیاز به deploy داشته باشید — سرعت تکرار و بازتولید مسائل در محیط واقعی به شدت بهتر می‌شود.

تغییر رویکرد توسعه روی پلتفرم Workers

یکی از ویژگی‌های کلیدی پلتفرم Cloudflare Workers این بوده که توسعه‌دهنده بتواند بدون هر بار دیپلوی، کدش را محلی تست کند. مسیر پشتیبانی از این تجربه در طول سال‌ها تغییر کرده است. در ابتدا wrangler dev در حالت remote اجرا می‌شد که هر تغییر را روی یک نسخه preview از Worker در شبکه Cloudflare deploy می‌کرد. این روش امکان تست زنده را می‌داد اما پیچیدگی، سرعت پایین تکرار، اتصال‌های دیباگ ناپایدار و پشتیبانی ضعیف از سناریوهای multi-worker، تجربه کاربری مناسبی ایجاد نمی‌کرد.

به همین دلیل سرمایه‌گذاری زیادی روی یک محیط توسعه کاملاً لوکال صورت گرفت و از میانه 2023 تجربه لوکال تبدیل به مسیر پیش‌فرض برای wrangler dev شد. از آن زمان تلاش زیادی برای بهبود Wrangler، پلاگین Cloudflare Vite (و @cloudflare/vitest-pool-workers) و Miniflare انجام شده است. اما حالت قدیمی remote هنوز با flag ای مثل wrangler dev –remote در دسترس بود، چون یک ویژگی حیاتی را فراهم می‌کرد: اتصال به منابع از راه دور در حین توسعه محلی.

در حالت لوکال معمولی، همه bindingها شبیه‌سازی محلی می‌شوند و داده‌ها معمولاً خالی یا تستی هستند؛ برای بسیاری از موارد این کافی است، ولی وقتی لازم باشد منابع بین تیم به اشتراک گذاشته شوند، باگی که فقط روی داده واقعی رخ می‌دهد بازتولید شود یا اطمینان از تطابق با محیط production لازم باشد، دسترسی به منابع واقعی حیاتی است. بنابراین ایده ساده بود: بهترین ویژگی‌های remote mode (دسترسی به منابع از راه دور) را به تجربه wrangler dev بیاوریم، بدون از دست دادن پیشرفت‌های محیط توسعه لوکال.

نتیجه: از Wrangler v4.37.0 به بعد می‌توانید برای هر binding به‌صورت جداگانه مشخص کنید که از منبع remote استفاده کند یا شبیه‌سازی محلی، کافیست گزینه remote: true را اضافه کنید — ساده و بدون نیاز به مدیریت پیچیده API key یا credentials، چون Wrangler از اتصال Oauth موجود به Cloudflare API استفاده می‌کند. ⚙️

مثال config که نشان می‌دهد چگونه می‌توانید این گزینه را اضافه کنید:

[p] 

  
{  
  "name": "my-worker",  
  "compatibility_date": "2025-01-01",  
  "kv_namespaces": [{  
    "binding": "KV",  
    "id": "my-kv-id",  
  },{  
    "binding": "KV_2",  
    "id": "other-kv-id",  
    "remote": true  
  }],  
  "r2_buckets": [{  
    "bucket_name": "my-r2-name",  
    "binding": "R2"  
  }]  
}

نکته: برخی bindingها قبلاً همین رفتار را داشتند؛ مثلاً AI binding همیشه به یک منبع remote وصل می‌شد، چون شبیه‌سازی محلی برای تمام مدل‌های AI عملی نبود. با رشد نیازهای مختلف در محصولات (مثل Images و Hyperdrive)، راه‌حل‌های تکه‌تکه‌ای شکل گرفت که الان همه تحت یک راهکار یکپارچه به نام remote bindings متحد شده‌اند.

معماری فنی — چرا این کار شدنی است؟

هدف ما این بود که بدون تغییر کد production، دسترسی به منابع remote ساده باشد؛ به همین خاطر تصمیم گرفتیم داده را در نقطه استفاده در Worker از راه دور واکشی کنیم. مثال رایج:

  
const value = await env.KV.get("some-key")

این کد نشان می‌دهد که env.KV.get(“some-key”) باید مقداری را که در namespace KV روی اکانت شما است از شبکه بگیرد. سوال این است که چطور کاری کنیم که فراخوانی‌هایی مثل env.KV.put(“key”, “value”) واقعاً در یک KV واقعی ذخیره شوند؟

یک گزینه اولیه این بود که از Cloudflare API استفاده کنیم و تمام env را با stubهایی جایگزین کنیم که هر عملیات را به یک HTTP call تبدیل کنند. این روش برای KV، R2 و D1 که API HTTP بالغ دارند قابل انجام بود، اما مشکلاتی داشت: باید سطح کامل API bindings را بازتولید می‌کردیم، هر عملیات را مپ می‌کردیم و برای عملیات‌هایی که معادل HTTP نداشتند دردسر ایجاد می‌شد. نگهداری و پیاده‌سازی این راه‌حل پیچیده بود.

خوشبختانه یک API آماده داشتیم — همان API‌ای که در production استفاده می‌شود. در واقع bindingها روی پلتفرم به سادگی به یک service binding خلاصه می‌شوند: ارتباط بین دو Worker که از طریق HTTP یا JSRPC صحبت می‌کنند. برای مثال، KV binding به‌عنوان یک service binding بین Worker شما و یک platform Worker که KV را پیاده‌سازی می‌کند عمل می‌کند؛ runtime فراخوانی‌های JS مثل env.KV.get() را تبدیل به HTTP می‌کند.

ما متوجه شدیم که یک مرز شبکه‌ای طبیعی بین runtime محلی و Worker سرویس وجود دارد که می‌توانیم از آن استفاده کنیم. به‌جای اینکه runtime production تبدیل را انجام دهد، می‌توانیم runtime محلی (workerd) را طوری بسازیم که env.KV.get() را مستقیم به یک سرویس راه دور HTTP بفرستد و از runtime production عبور نکند. به عبارت دیگر: یک remote proxy client در سمت لوکال و یک remote proxy server در سمت Cloudflare قرار می‌گیرند تا ترافیک binding را به منبع واقعی برسانند — کاملاً شفاف برای Worker محلیتان.

تصور کنید یک Worker محلی با یک KV binding که به‌جای شبیه‌سازی محلی، توسط remote proxy client مدیریت می‌شود؛ آن client از طریق یک remote proxy server به KV واقعی متصل می‌شود و محتوای واقعی را برمی‌گرداند. هر binding می‌تواند به طور مستقل یا محلی شبیه‌سازی شود یا از proxy remote استفاده کند، پس ترکیب‌های متنوعی مثل دو binding محلی و یک binding remote را راحت پشتیبانی می‌کنیم.

چی درباره JSRPC؟

بخش قبلی درباره bindingهایی صحبت می‌کرد که روی HTTP عمل می‌کنند، اما بسیاری از bindingهای جدید از JSRPC استفاده می‌کنند. برای اینکه workerd محلی بتواند با یک runtime production از طریق JSRPC صحبت کند، ما به یک کانال ارتباطی امن و کارا نیاز داشتیم. همزمان یک پروژه موازی (Cap’n Web) این امکان را فراهم می‌کرد؛ ما آن را با استفاده از websockets و Cap’n Web یکپارچه کردیم تا bindingهای مبتنی بر JSRPC (مثل Images و JSRPC service bindings به own Workers) هم به‌صورت remote کار کنند.

پشتیبانی برای Vite، Vitest و اکوسیستم JavaScript 🧪

نخواستیم این قابلیت فقط در wrangler dev محدود بماند. هدف این بود که Cloudflare Vite Plugin و بسته vitest-pool-workers و هر ابزار دیگر از اکوسیستم جاوااسکریپت هم بتوانند از remote bindings بهره ببرند. برای این منظور بسته wrangler حالا utilityهایی مثل startRemoteProxySession را صادر می‌کند تا ابزارهای دیگر هم بتوانند نشست‌های remote proxy را راه‌اندازی کنند. برای جزئیات بیشتر مستندات remote bindings را ببینید.

چطور امتحانش کنیم؟

کافیه wrangler dev را اجرا کنید — از Wrangler v4.37.0 به بعد (و @cloudflare/vite-plugin v1.13.0، @cloudflare/vitest-pool-workers v0.9.0) remote bindings در همه پروژه‌ها در دسترس است و می‌توانید با افزودن remote: true برای هر binding آن را فعال کنید. 🚀

خلاصه برای SRE/DevOps: این مدل به شما اجازه می‌دهد workflowهای تستی نزدیک به production داشته باشید، بازتولید باگ‌های وابسته به داده واقعی را راحت‌تر کنید و بدون قربانی کردن تجربه توسعه لوکال از منابع زنده بهره ببرید. اگر نیاز به جزئیات پیاده‌سازی یا کمک در کانفیگ دارید، بگید تا با مثال‌های عملی و نکات عیب‌یابی بیشتر همراه کنم.

Runtime Production در معماری Remote Bindings

هدف این مقاله توضیح چگونگی استفاده از remote bindings و تجربهٔ runtime production را در توسعه و تست با منابع زنده است.

برای اطلاعات بیشتر، لطفاً به مقاله مرتبط مراجعه کنید: درک و بهینه‌سازی مصرف منابع در Prometheus.