PacketReceiver

PacketReceiver یک شمارنده endpoint برای packetهای IPv4 است. این نود packetهای خام IPv4 را دریافت و مصرف می‌کند، آن‌ها را بر اساس source IP گروه‌بندی می‌کند، تعداد دریافتی از هر source را با مقدار مورد انتظار مقایسه می‌کند و نتیجه را در یک فایل گزارش می‌نویسد.

در کنار PacketSender می‌توان از آن برای پیدا کردن source IPهای قابل دسترس یا مجاز در محیط‌های محدودشده بر اساس IP استفاده کرد. PacketSender از بازه‌های source پیشنهادی ترافیک تولید می‌کند و PacketReceiver نشان می‌دهد packetهای کدام source IP واقعاً به مقصد رسیده‌اند.

جایگاه رایج

دریافت packetهای raw IPv4 از capture/output node:

RawSocket -> PacketReceiver

دریافت packet از tunnel path:

UdpStatelessSocket -> WireGuardDevice -> PacketReceiver

PacketReceiver می‌تواند packetها را از callbackهای upstream یا downstream دریافت کند. در نتیجه هم می‌توان آن را در انتهای یک packet chain قرار داد و هم در ابتدای chainی که packetها از peer سمت next وارد آن می‌شوند.

چه کاری انجام می‌دهد

• یک CIDR از نوع IPv4 یا آرایه‌ای از بازه‌های CIDR را زیر نظر می‌گیرد.
• برای هر source IP در این بازه‌ها یک شمارنده جدا در نظر می‌گیرد.
• packetهایی را می‌شمارد که source address آن‌ها در یکی از بازه‌های تعیین‌شده باشد.
• packetهای خارج از بازه‌های تنظیم‌شده را در شمارنده unexpected قرار می‌دهد.
• buffer هر packet مصرف‌شده را به pool برمی‌گرداند.
• پس از گذشت report-after-ms گزارش را می‌نویسد.
• اگر گزارش هنوز نوشته نشده باشد، هنگام destroy یک گزارش نهایی تولید می‌کند.
• پایان کار آن به Finish روی packet-line وابسته نیست.

برای matching فقط source address مربوط به IPv4 بررسی می‌شود. Protocol، port، destination address و payload در شمارنده‌های هر IP نقشی ندارند.

تست Source-IP Allowlist

برای محیط‌های IP-restricted یا allowlisted:

1. PacketSender.source-ipv4-range را با source IP rangeهای candidate تنظیم کنید.
2. PacketReceiver.source-ipv4-range را با همان rangeها تنظیم کنید.
3. expected-packets-per-ip را برابر count مورد انتظار از sender بگذارید.
4. تست را اجرا کنید و منتظر report گیرنده بمانید.
5. دنبال source IPهایی بگردید که loss کم یا delivery کامل دارند.

بهترین گزینه‌ها source IPهایی هستند که مقدار received آن‌ها به expected نزدیک است و loss-percent کمی دارند.

نمونه تنظیم

{
  "name": "packet-receiver",
  "type": "PacketReceiver",
  "settings": {
    "source-ipv4-range": [
      "198.51.100.0/24",
      "203.0.113.0/24"
    ],
    "expected-packets-per-ip": 100,
    "report-after-ms": 7000,
    "output-file": "packet-receiver-report.txt"
  }
}

برای PacketSender متناظر با protocol-number: "ALL" و packets-per-ip: 100 از این مقدار استفاده کنید:

{
  "expected-packets-per-ip": 25500
}

زیرا حالت ALL برای هر source IP تعداد 100 * 255 packet می‌فرستد.

فیلدهای ضروری

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

فیلد	نوع	توضیح
name	string	نام دلخواه نود. باید داخل فایل config یکتا باشد.
type	string	باید دقیقاً "PacketReceiver" باشد.
settings	object	لازم است و نباید خالی باشد.

فیلدهای ضروری داخل settings:

فیلد	نوع	توضیح
source-ipv4-range	string یا آرایه string	یک بازه CIDR از نوع IPv4 یا آرایه‌ای از این بازه‌ها که باید زیر نظر گرفته شوند.

این نود باید یا tunnel قبلی داشته باشد یا tunnel بعدی، تا packetها بتوانند به آن برسند.

تنظیمات اختیاری

گزینه	نوع	پیش‌فرض	توضیح
expected-packets-per-ip	integer	1	تعداد packet مثبت مورد انتظار برای هر source IP تحت track.
report-after-ms	integer	1000	مدت انتظار مثبت پیش از نوشتن گزارش و پایان دادن به برنامه. آن را بیشتر از مدت ارسال به‌علاوه تأخیر احتمالی tunnel قرار دهید.
output-file	string	packet-receiver-report.txt	مسیر غیرخالی فایل گزارش.

جفت شدن با PacketSender

از این countهای مورد انتظار استفاده کنید:

Sender mode	Receiver expected-packets-per-ip
TCP	sender packets-per-ip
UDP	sender packets-per-ip
ICMP	sender packets-per-ip
ALL	sender packets-per-ip * 255

report-after-ms معمولاً باید بیشتر از این مقدار باشد:

PacketSender duration-ms + network delay + reordering/jitter window

اگر گزارش زودتر از موعد نوشته شود، packetهای دیررس گم‌شده حساب می‌شوند؛ زیرا PacketReceiver پس از ثبت گزارش دیگر شمارنده‌ها را به‌روزرسانی نمی‌کند.

فرمت Report

گزارش فقط در output-file نوشته می‌شود و با فیلدهای خلاصه زیر آغاز می‌شود:

PacketReceiver report
output-file: packet-receiver-report.txt
source-ip-count: ...
expected-packets-per-ip: ...
expected-total-packets: ...
received-total-packets: ...
lost-total-packets: ...
unexpected-packets: ...

سپس برای هر source IP زیر نظر یک ردیف می‌نویسد:

source-ip | expected | received | lost | loss-percent | histogram
198.51.100.1 | 100 | 100 | 0 | 0.00% | [################################]
198.51.100.2 | 100 | 50 | 50 | 50.00% | [################----------------]

عرض histogram برابر ۳۲ نویسه است. # سهم packetهای دریافت‌شده و - سهم packetهای نرسیده را نسبت به تعداد مورد انتظار نشان می‌دهد.

unexpected-packets هم packetهای IPv4 با source IP خارج از بازه‌های تنظیم‌شده را دربر می‌گیرد و هم packetهای غیر IPv4 یا بیش از حد کوتاهی را که این نود مصرف کرده است.

رفتار Direction

callback ورودی	رفتار
upstream Payload	packet را می‌شمارد و buffer آن را به pool برمی‌گرداند.
downstream Payload	packet را می‌شمارد و buffer آن را به pool برمی‌گرداند.
Init, Est, Pause, Resume, Finish	کاری انجام نمی‌دهند. پایان کار بر اساس timer و گزارش تعیین می‌شود، نه lifecycle مربوط به line.

PacketReceiver با packet-tunnel API خود WaterWall ساخته می‌شود و line state مخصوص tunnel ندارد.

نکته‌های Buffer و Padding

در metadata نود، مقدارهای زیر اعلام شده‌اند:

required_padding_left = 0
layer_group = kNodeLayerAnything
layer_group_next_node = kNodeLayer3
layer_group_prev_node = kNodeLayer3

این نود چیزی به ابتدای payload اضافه نمی‌کند، آن را frame یا بازنویسی نمی‌کند و به نود دیگری هم نمی‌فرستد. پس از شمارش، buffer مربوط به packet را مصرف می‌کند و به pool برمی‌گرداند.

نکته‌های عملی

• روی PacketSender و PacketReceiver از source rangeهای یکسان استفاده کنید.
• rangeها را آن‌قدر کوچک نگه دارید که یک counter برای هر source IP منطقی باشد.
• برای مسیرهای high-latency، high-jitter یا multi-hop tunnel مقدار report-after-ms طولانی‌تری استفاده کنید.
• در محیط‌های محدودشده بر اساس source IP، آدرس‌هایی که loss کمی دارند به احتمال زیاد قابل استفاده یا مجاز هستند.
• این نود برای آزمایش packet و تهیه گزارش است، نه برای عبور دادن ترافیک application.