LoggerTunnel

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

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

جایگاه رایج

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

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

این node می‌تواند هم prev و هم next داشته باشد، اما نبودن یکی از طرف‌ها نیز مشکلی ایجاد نمی‌کند. اگر callback قرار باشد به سمتی برود که وجود ندارد، node فقط برمی‌گردد و 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 به‌شدت توصیه می‌شود، زیرا خروجی فایل از نام node به‌عنوان پیشوند استفاده می‌کند. اگر 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 از کل buffer آن.	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`، به node بعدی فرستاده می‌شود.
Downstream `Init`, `Est`, `Finish`, `Pause`, `Resume`	در صورت وجود `prev`، به node قبلی فرستاده می‌شود.

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

استخراج TCP Payload

در tcp-payload-file، هر buffer 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 داده اضافه داشته باشد، آن بایت‌های اضافه بخشی از TCP payload استخراج‌شده نیستند.

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

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

متادیتای نود

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

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

ویژگی	مقدار
node flags	`kNodeFlagNone`
`can_have_prev`	`true`
`can_have_next`	`true`
`layer_group`	`kNodeLayerAnything`
`layer_group_prev_node`	`kNodeLayerSameAsNext`
`layer_group_next_node`	`kNodeLayerSameAsPrev`
`required_padding_left`	`0` bytes

جایگاه رایج​

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

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

تنظیمات​

modeها​

output-mode​

جریان اجرا​

استخراج TCP Payload​

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

متادیتای نود​