BlackHole

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

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

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

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

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

• می‌تواند آخرین node در chain باشد.
• config دارای next را نمی‌پذیرد.
• هر payloadِ upstream را که دریافت کند دور می‌ریزد.
• buffer 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	نام دلخواه node که باید در فایل config یکتا باشد.
type	string	باید دقیقاً "BlackHole" باشد.
settings	object	باید mode داشته باشد.

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

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

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

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

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

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

مرجع حالت‌ها

حالت Passive

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

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

در حالت passive:

• با دریافت Init در upstream، یک Est در downstream به سمت قبلی فرستاده می‌شود.
• payloadِ upstream دور ریخته می‌شود و buffer آن برای استفاده مجدد برمی‌گردد.
• 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 به node برسد، همچنان دور ریخته می‌شود و buffer آن برای استفاده مجدد برمی‌گردد.
• callback‌های downstream در لبه adapter غیرفعال‌اند.

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

پردازش Payload

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

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

رفتار Lifecycle

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

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

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

نکته‌ها

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

متادیتای نود

metadata برگرفته از کد منبع:

ویژگی	مقدار
node flags	kNodeFlagChainEnd | kNodeFlagNoChain | kNodeFlagSupportsSplice
can_have_prev	true
can_have_next	false
layer_group	kNodeLayerAnything
layer_group_prev_node	kNodeLayerAnything
layer_group_next_node	kNodeLayerNone
required_padding_left	0 bytes

پشتیبانی splice

مصرف‌کنندهٔ upstream buffer ورودی را بازیافت و باقی‌ماندهٔ بدنهٔ pipe خصوصی را تخلیه می‌کند. pipe سالم و خالی ممکن است برای استفادهٔ مجدد در cache بماند. حالت passive داده را مصرف می‌کند؛ حالت active در Init، line را می‌بندد و پس از بسته‌شدن line عادی، payload دیگری نمی‌پذیرد. handler برای payload در downstream وجود ندارد.

buffer‌های عادیِ fallback همچنان پذیرفته می‌شوند. splice به build پشتیبانی‌شدهٔ Linux، فعال‌بودن misc.splice، نبود node packet و پشتیبانی همهٔ node‌های chainِ نهایی پس از گسترش و ادغام نیاز دارد. flag قابلیت این بررسی‌ها را دور نمی‌زند. بدون اندازه‌گیری، بهبود کارایی تضمین نمی‌شود.

config packet این node دولایه همچنان splice را فعال نمی‌کند.