BlackHole

BlackHole یک adapter نهایی برای دور ریختن داده است. در انتهای chain قرار می‌گیرد، ترافیک upstream را از نود قبلی می‌گیرد و بدون ساخت socket، اتصال به peer راه دور یا ارسال به نودی دیگر، آن را دور می‌ریزد.

دو رفتار پشتیبانی می‌شود:

• حالت passive line را می‌پذیرد، Est را در جهت downstream به سمت قبلی گزارش می‌دهد و payloadِ upstream را بی‌سروصدا دور می‌ریزد.
• حالت active به‌محض دریافت Init در جهت upstream، یک Finish در جهت downstream به سمت قبلی می‌فرستد.

از آنجا که BlackHole یک adapter است، callbackهای downstream در رابط runtime آن معتبر نیستند. پس از آن نود دیگری قرار ندهید.

این نود چه می‌کند؟

• می‌تواند آخرین نود در chain باشد.
• پیکربندی دارای next را نمی‌پذیرد.
• هر payloadِ upstream را که دریافت کند دور می‌ریزد.
• بافر payload دورریخته‌شده را با lineReuseBuffer() برای استفاده مجدد برمی‌گرداند.
• payload را prepend، فریم‌بندی، رمزنگاری، decode یا بازنویسی نمی‌کند.
• برای هر line، state جداگانه‌ای به تونل اختصاص نمی‌دهد.
• به left padding اضافه نیاز ندارد.
• packet line نمی‌سازد و آزاد نمی‌کند.

جایگاه رایج

نقطه نهایی دور ریختن داده در حالت passive:

TcpListener -> BlackHole

تست chain UDP:

UdpListener -> BlackHole

در chainهای policy یا تست می‌توان از BlackHole استفاده کرد؛ زمانی که ترافیک پذیرفته‌شده باید در انتهای chain مصرف یا دور ریخته شود.

BlackHole تونل میانی نیست. برای ساختاری مانند TcpListener -> BlackHole -> TcpConnector باید از تونل دیگری برای policy یا مسیریابی استفاده کنید.

نمونه تنظیم

حالت passive:

{
  "name": "dropper",
  "type": "BlackHole",
  "settings": {
    "mode": "passive"
  }
}

حالت active:

{
  "name": "rejector",
  "type": "BlackHole",
  "settings": {
    "mode": "active"
  }
}

فیلدهای لازم

فیلدهای سطح اصلی:

فیلد	نوع	توضیح
name	string	نام دلخواه نود که باید در فایل پیکربندی یکتا باشد.
type	string	باید دقیقاً "BlackHole" باشد.
settings	object	باید mode داشته باشد.

فیلدهای اجباری settings:

فیلد	نوع	توضیح
mode	string	انتخاب میان دور ریختن بی‌سروصدای payload و بستن فوری اتصال.

mode اجباری است. پیاده‌سازی فعلی مقدار پیش‌فرض ندارد.

فیلدهای اختیاری

فیلد اختیاری در settings وجود ندارد.

فیلد next را در سطح نود تنظیم نکنید. BlackHole adapter انتهای chain است.

مرجع حالت‌ها

حالت Passive

مقادیر قابل قبول:

مقدار	معنی
passive	نام اصلی حالت passive.
drop	نام مستعار حالت passive.
packet-drop	نام مستعار حالت passive؛ نود را به packet tunnel تبدیل نمی‌کند.
silent	نام مستعار حالت passive.
calm	نام مستعار حالت passive.

در حالت passive:

• با دریافت Init در upstream، یک Est در downstream به سمت قبلی فرستاده می‌شود.
• payloadِ upstream دور ریخته می‌شود و بافر آن برای استفاده مجدد برمی‌گردد.
• Est، Finish، Pause و Resume در upstream کاری انجام نمی‌دهند.
• callbackهای downstream در لبه adapter غیرفعال‌اند.

حالت passive خودش line را نمی‌بندد؛ فقط payload را مصرف می‌کند و منتظر می‌ماند تا سمت قبلی line را ببندد.

حالت Active

مقادیر قابل قبول:

مقدار	معنی
active	نام اصلی حالت active.
close	نام مستعار حالت active.
aggressive	نام مستعار حالت active.
kill	نام مستعار حالت active.
kill-connection	نام مستعار حالت active.

در حالت active:

• با دریافت Init در upstream، یک Finish در downstream به سمت قبلی فرستاده می‌شود و callback بلافاصله برمی‌گردد.
• اگر payloadِ upstream به نود برسد، همچنان دور ریخته می‌شود و بافر آن برای استفاده مجدد برمی‌گردد.
• callbackهای downstream در لبه adapter غیرفعال‌اند.

این حالت اتصال را در انتهای chain بی‌درنگ رد می‌کند.

پردازش Payload

برای هر payloadِ upstream، تابع lineReuseBuffer() روی بافر ورودی فراخوانی می‌شود و سپس callback برمی‌گردد.

هیچ بایتی از payload از نود عبور نمی‌کند. چون headerای prepend و فریمی ساخته نمی‌شود، مقدار required_padding_left در BlackHole برابر 0 است.

رفتار Lifecycle

BlackHole از قواعد جهت‌دهی adapter انتهای downstream پیروی می‌کند:

جهت callback	رفتار
upstream Init در حالت passive	tunnelPrevDownStreamEst() می‌فرستد.
upstream Init در حالت active	tunnelPrevDownStreamFinish() می‌فرستد.
upstream payload	بافر را با lineReuseBuffer() برای استفاده مجدد برمی‌گرداند.
upstream Est / Finish / Pause / Resume	بدون عمل.
callbackهای downstream	در این لبه adapter نامعتبرند و adapterCreate() آن‌ها را مسدود می‌کند.

چون نود بعدی وجود ندارد، هیچ‌گاه tunnelNextUpStream*() را فراخوانی نمی‌کند.

نکته‌ها

• در metadata، نود BlackHole به لایه خاصی محدود نیست؛ با این حال stream و packet را به یکدیگر تبدیل نمی‌کند.
• برای chainهایی که به پاسخ برنامه نیاز دارند مناسب نیست، زیرا هیچ payloadی از آن عبور نمی‌کند.
• حالت passive می‌تواند سمت قبلی را برای مدت نامعینی باز بگذارد اگر آن سمت line را باز نگه دارد.
• حالت active برای endpointای مناسب است که باید اتصال را عمداً رد یا قطع کند.
• این نود تنظیمی برای پروتکل، مشخصات ورود، آدرس راه دور، port یا فریم‌بندی ندارد.