PacketReceiver

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

در کنار 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 و protocol انتخاب‌شده یک شمارنده جدا در نظر می‌گیرد.
packet‌هایی را می‌شمارد که source address و protocol آن‌ها با تنظیمات مطابقت داشته باشد.
packet‌های خارج از بازه‌ها یا protocol‌های انتخاب‌شده را در شمارنده unexpected قرار می‌دهد.
buffer هر packet مصرف‌شده را به pool برمی‌گرداند.
پس از گذشت report-after-ms گزارش را می‌نویسد.
اگر گزارش هنوز نوشته نشده باشد، هنگام destroy یک گزارش نهایی تولید می‌کند.
پایان کار آن به Finish روی packet-line وابسته نیست.

برای تطبیق، آدرس مبدأ و شماره protocol در IPv4 بررسی می‌شوند. پورت، آدرس مقصد و payload در شمارنده‌ها نقشی ندارند.

تست source-IP Allowlist

برای محیط‌هایی که دسترسی را بر اساس IP یا allowlist محدود می‌کنند:

PacketSender.source-ipv4-range را با بازه‌های IP مبدأ مورد نظر تنظیم کنید.
PacketReceiver.source-ipv4-range را با همان بازه‌ها تنظیم کنید.
protocol‌های مورد انتظار را با protocol-number انتخاب کنید و expected-packets-per-ip را برابر packets-per-ip فرستنده بگذارید.
تست را اجرا کنید و منتظر گزارش گیرنده بمانید.
IP‌های مبدأ با packet loss کم یا دریافت کامل را پیدا کنید.

بهترین گزینه‌ها 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"
    ],
    "protocol-number": ["TCP", "UDP", 253],
    "expected-packets-per-ip": 100,
    "report-after-ms": 7000,
    "output-file": "packet-receiver-report.txt"
  }
}

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

{
  "protocol-number": "ALL",
  "expected-packets-per-ip": 100
}

گیرنده برای مجموع مورد انتظار هر IP و کل گزارش، خودش مقدار را در ۲۵۵ ضرب می‌کند.

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

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

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

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

فیلد	نوع	توضیح
`source-ipv4-range`	string یا آرایه string	یک بازه CIDR از نوع IPv4 یا آرایه‌ای از این بازه‌ها که باید زیر نظر گرفته شوند.
`protocol-number`	string، integer یا آرایه	`TCP`، `UDP`، `ICMP`، `ALL`، عدد ۰ تا ۲۵۵، یا آرایه غیرخالی از نام‌ها و عددها. `ALL` فقط به‌تنهایی مجاز است و شماره‌های ۰ تا ۲۵۴ را انتخاب می‌کند. شماره‌های تکراری، حتی با نام معادل، نامعتبرند.

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

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

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

جفت شدن با PacketSender

در همه حالت‌ها، از جمله ALL، مقدار expected-packets-per-ip گیرنده را برابر packets-per-ip فرستنده بگذارید. protocol‌های یکسان را در دو سمت انتخاب کنید. آرایه‌هایی مانند [6, 17] یا ["TCP", "UDP"] چند protocol را انتخاب می‌کنند.

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: ...
selected-protocol-count: ...
expected-total-packets: ...
received-total-packets: ...
lost-total-packets: ...
unexpected-packets: ...

سپس برای هر source IP یک ردیف مجموع و برای هر protocol انتخاب‌شده یک ردیف می‌نویسد. ترتیب آرایه حفظ می‌شود و ALL به ترتیب عددی گزارش می‌شود:

source-ip | protocol-number | expected | received | lost | loss-percent | histogram
51.100.1 | total | 200 | 150 | 70 | 35.00% | [########################--------]
51.100.1 | 6 | 100 | 120 | 0 | 0.00% | [################################]
51.100.1 | 17 | 100 | 30 | 70 | 70.00% | [#########-----------------------]

عرض histogram برابر ۳۲ کاراکتر است. # سهم packet‌های دریافت‌شده و - سهم packet‌های نرسیده را نسبت به تعداد مورد انتظار نشان می‌دهد. packet‌های اضافه در received باقی می‌مانند ولی histogram پس از پر شدن ثابت می‌ماند. Loss هر IP برابر مجموع کمبودهای protocol‌های انتخاب‌شده است؛ دریافت اضافه یک protocol کمبود دیگری را پنهان نمی‌کند.

unexpected-packets شامل packet‌های با protocol انتخاب‌نشده یا 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

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

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

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

متادیتای node

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

ویژگی	مقدار
node flags	`kNodeFlagChainHead` \| `kNodeFlagChainEnd`
`can_have_prev`	`true`
`can_have_next`	`true`
`layer_group`	`kNodeLayer3`
`layer_group_prev_node`	`kNodeLayer3`
`layer_group_next_node`	`kNodeLayer3`
`required_padding_left`	`0` بایت

جایگاه رایج​

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

تست source-IP Allowlist​

نمونه تنظیم​

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

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

جفت شدن با PacketSender​

فرمت Report​

رفتار direction​

نکته‌های buffer و padding​

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

متادیتای node​