LoggerTunnel

LoggerTunnel نودی شفاف برای مشاهده و ثبت payload است. داده را تغییر نمی‌دهد، line تازه‌ای نمی‌سازد و آزاد نمی‌کند و جهت lifecycle در chain را نیز عوض نمی‌کند.

وقتی می‌خواهید رفتار یک chain را بدون دست بردن در مسیر اصلی ترافیک بررسی کنید، از این نود استفاده کنید.

جایگاه رایج

از آنجا که LoggerTunnel فقط نقش ناظر دارد، می‌تواند در ابتدا، میانه یا انتهای بخشی از chain قرار بگیرد:

TcpListener -> LoggerTunnel -> TcpConnector
TunDevice -> LoggerTunnel -> IpManipulator
UdpListener -> LoggerTunnel -> UdpConnector

این نود می‌تواند هم prev و هم next داشته باشد، اما نبودن یکی از طرف‌ها نیز مشکلی ایجاد نمی‌کند. اگر callback قرار باشد به سمتی برود که وجود ندارد، نود فقط برمی‌گردد و lifecycle ساختگی ایجاد نمی‌کند.

نمونه تنظیمات

ثبت payload در network logger:

{
  "name": "trace-http",
  "type": "LoggerTunnel",
  "settings": {
    "mode": "log",
    "level": "info"
  },
  "next": "next-node"
}

ذخیره payload خام در فایلی جداگانه برای هر جهت:

{
  "name": "payload-dump",
  "type": "LoggerTunnel",
  "settings": {
    "mode": "file",
    "output-mode": "split-direction"
  },
  "next": "next-node"
}

استخراج فقط payload مربوط به TCP از packetهای IPv4:

{
  "name": "tcp-body-dump",
  "type": "LoggerTunnel",
  "settings": {
    "mode": "tcp-payload-file",
    "output-mode": "per-payload"
  },
  "next": "next-node"
}

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

فیلد	نوع	توضیح
`type`	string	باید `LoggerTunnel` باشد.
`settings`	object	باید object غیرخالی باشد و `mode` داشته باشد.

نوشتن فیلد name به‌شدت توصیه می‌شود، زیرا خروجی فایل از نام نود به‌عنوان پیشوند استفاده می‌کند. اگر name خالی یا ناموجود باشد، پیشوند LoggerTunnel به کار می‌رود.

تنظیمات

گزینه	اجباری	پیش‌فرض	توضیح
`mode`	بله	ندارد	نوع خروجی. یکی از `log`، `file` یا `tcp-payload-file`.
`level`	خیر، فقط برای حالت log	`debug`	سطح network logger برای `mode: "log"`. یکی از `debug`، `info`، `warning`، `error` یا `fatal`.
`output-mode`	خیر، فقط برای حالت‌های فایل	`split-direction`	ساختار فایل برای `mode: "file"` و `mode: "tcp-payload-file"`. یکی از `per-payload`، `split-direction` یا `single-file`.

وقتی mode برابر log است، output-mode استفاده نمی‌شود. وقتی mode برابر file یا tcp-payload-file است، level استفاده نمی‌شود.

modeها

mode	چیزی که ثبت می‌شود	مقصد
`log`	طول payload و نمایش hex از کل بافر آن.	WaterWall network logger.
`file`	دقیقاً همان بایت‌های موجود در `sbuf_t` هنگام callback.	فایل‌ها در working directory فعلی.
`tcp-payload-file`	فقط TCP transport payload استخراج‌شده از packet IPv4.	فایل‌ها در working directory فعلی.

output-mode

output-mode برای file و tcp-payload-file استفاده می‌شود.

مقدار	رفتار
`per-payload`	هر callbackِ payload را در فایل جداگانه‌ای می‌نویسد: `<name>-up-1.txt`، `<name>-up-2.txt`، `<name>-down-1.txt` و ... . شمارنده‌های upstream و downstream جدا هستند. فایل‌ها در حالت write باز می‌شوند؛ بنابراین فایل هم‌نام از اجرای قبلی ممکن است بازنویسی شود.
`split-direction`	همه بایت‌های upstream را به `<name>-up.txt` و بایت‌های downstream را به `<name>-down.txt` اضافه می‌کند.
`single-file`	داده هر دو جهت را به `<name>-all.txt` اضافه می‌کند.

پسوند فایل‌ها .txt است، اما محتوای آن‌ها بایت خام است. هیچ separator، timestamp، طول packet یا marker فریم اضافه نمی‌شود.

جریان اجرا

LoggerTunnel پیش از عبور دادن payload، آن را در لاگ یا فایل ثبت می‌کند.

مسیر upstream:

previous node -> LoggerTunnel logs payload -> next node

در upstream، اگر next وجود داشته باشد، payload با tunnelNextUpStreamPayload() فرستاده می‌شود.

مسیر downstream:

next node -> LoggerTunnel logs payload -> previous node

در downstream، اگر prev وجود داشته باشد، payload با tunnelPrevDownStreamPayload() فرستاده می‌شود.

Callbackهای غیر payload بدون تغییر عبور می‌کنند:

جهت callback	رفتار
Upstream `Init`, `Est`, `Finish`, `Pause`, `Resume`	در صورت وجود `next`، به نود بعدی فرستاده می‌شود.
Downstream `Init`, `Est`, `Finish`, `Pause`, `Resume`	در صورت وجود `prev`، به نود قبلی فرستاده می‌شود.

این نود state مخصوص line ندارد. State آن در سطح تونل است و حالت، سطح لاگ، مسیر و شمارنده فایل‌ها و mutex لازم برای سریالی کردن نوشتن فایل را نگه می‌دارد.

استخراج TCP Payload

در tcp-payload-file، هر بافر payload به‌عنوان یک packet کامل IPv4 بررسی می‌شود و فقط بایت‌های پس از headerهای IPv4 و TCP نوشته می‌شوند.

packet در این حالت‌ها نادیده گرفته می‌شود:

کوتاه‌تر از header IPv4 باشد
IPv4 نباشد
protocol آن TCP نباشد
طول header یا total length معتبر نباشد
fragment شده باشد
طول header TCP معتبر نباشد
TCP segment هیچ transport payload نداشته باشد

این حالت فقط IPv4 را پشتیبانی می‌کند. Packetهای IPv6 و غیر TCP نادیده گرفته می‌شوند.

اگر یک packet معتبر بعد از IPv4 total length داده اضافه داشته باشد، آن bytes اضافه بخشی از TCP payload استخراج‌شده نیستند.

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

LoggerTunnel محتوای واقعی ترافیک را ثبت می‌کند. هنگام کار با password، token، private key، cookie، اطلاعات کاربران و ترافیک production با احتیاط از آن استفاده کنید.
در log mode، کل payload به hex تبدیل می‌شود. در traffic زیاد یا payload بزرگ، log می‌تواند بسیار حجیم شود.
مسیر خروجی فایل نسبت به working directory فعلی processِ WaterWall محاسبه می‌شود.
split-direction و single-file به فایل‌های موجود append می‌کنند. در صورت نیاز فایل‌های قدیمی را rotate یا حذف کنید.
file writeها داخل state نود serialize می‌شوند، بنابراین چند worker هم‌زمان از مسیر خروجی فایل عبور نمی‌کنند.
در chainهای packet، file mode کل packet buffer رسیده به نود را ذخیره می‌کند. فقط وقتی از tcp-payload-file استفاده کنید که bufferها packetهای IPv4 باشند و هدف شما application bytes مربوط به TCP باشد.
خطا در log یا file write عمداً مسیر forwarding را تغییر نمی‌دهد. payload بدون تغییر از chain عبور می‌کند.

مشخصات نود

ویژگی	مقدار
جایگاه	Chain head، middle، chain end یا no-chain
Layer group	Anything to anything
Per-line state	ندارد
ایجاد line	خیر
آزاد کردن line	خیر
تغییر payload	خیر
Required left padding	`0`
File prefix	مقدار `name` نود، یا `LoggerTunnel` در صورت خالی بودن

جایگاه رایج​

نمونه تنظیمات​

فیلدهای اجباری​

تنظیمات​

modeها​

output-mode​

جریان اجرا​

استخراج TCP Payload​

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

مشخصات نود​