From 1ed2d1bc0121b80c0e25f1a3331e805843ab124f Mon Sep 17 00:00:00 2001 From: bol-van Date: Mon, 13 Apr 2026 10:04:42 +0300 Subject: [PATCH] update docs --- docs/manual.en.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/docs/manual.en.md b/docs/manual.en.md index 4274009..546ff3b 100644 --- a/docs/manual.en.md +++ b/docs/manual.en.md @@ -41,6 +41,8 @@ - [The track table structure](#the-track-table-structure) - [ICMP processing](#icmp-processing) - [raw IP processing](#raw-ip-processing) + - [Timers](#timers) + - [Timer function prototype](#timer-function-prototype) - [nfqws2 C interface](#nfqws2-c-interface) - [Base constants](#base-constants) - [Standard blobs](#standard-blobs) @@ -99,6 +101,9 @@ - [lua_cutoff](#lua_cutoff) - [execution_plan](#execution_plan) - [execution_plan_cancel](#execution_plan_cancel) + - [Timer control](#timer-control) + - [timer_set](#timer_set) + - [timer_del](#timer_del) - [zapret-lib.lua base function library](#zapret-liblua-base-function-library) - [Base desync functions](#base-desync-functions) - [luaexec](#luaexec) @@ -646,6 +651,7 @@ General parameters for all versions - nfqws2, dvtws2, winws2. --ipcache-lifetime= ; IP cache entry lifetime in seconds. 0 - unlimited. --ipcache-hostname=[0|1] ; 1 or no argument enables hostname caching for use in zero-phase strategies --reasm-disable=[type[,type]] ; disable fragment reassembly for a list of payloads: tls_client_hello quic_initial. without arguments - disable reasm for everything. + --timer-res=msec ; timer resolution in msec. default - 50 DESYNC ENGINE INIT: --writeable[=] ; create a directory for Lua with write permissions and store its path in the "WRITEABLE" env variable (only one directory) @@ -1588,6 +1594,50 @@ If the ip protocol is not recognized as tcp, udp, icmp, icmpv6, it is considered Dissect has ip/ip6 field and payload. Payload contains all data after L3 headers. desync.track is always missing. +## Timers + +Lua code can be called independently of received network data. +The event source is time. +A timer is an nfqws2 object, identified by a unique name, that allows you to call a specified Lua function at a specified frequency or once after a certain period of time. +The timer is set by the [timer_set](#timer_set) function, and deleted by the [timer_del](#timer_del) function. + +nfqws2 is a single-threaded program, like the Lua engine. Timers are called in the same thread that processes network data. +In Linux and Windows, packets are received in blocks, not one at a time. A block is processed until all remaining packets are exhausted. +Timers are called between block processing. If processing takes a significant amount of time, the timer call may not be perfectly timed. + +It's important to remember the timer resolution specified with the `--timer-res` parameter. The default is 50 ms. +This means that the timer call check can be performed no more frequently than the specified interval. +If you set the period to 70 ms, the timer will be called staggered. +70 will be called at 100, +140 at 150, and +210 at 250. +Therefore, it's advisable to set the period to a multiple of the timer resolution. +Increasing the resolution (decreasing `--timer-res`) may slightly increase CPU load, +since the processor will wake up every specified period to check all timers. +The more timers, the higher CPU load for checking. +The maximum resolution is 100 checks per second, which corresponds to `--timer-res=10`. + +Timers can be useful for handling unreplied packets. +For example, you need to send something somewhere and read the response. But the other party might not respond or the response might not arrive. +To prevent your system from hanging in an undefined state and leaving garbage in memory, a timer can help. +Using timers, desync functions, and send functions, you can build a full-fledged state machine - even your own implementation of TCP or another guaranteed delivery system. +The system should be designed asynchronously, using a state machine. Direct sleep delays is not the option, as they break the queue-based traffic processing scheme. +While you're waiting, everything else will hang. + +### Timer function prototype + +``` +function timer(name, data) +``` + +The timer function can be passed any Lua variable of any type. +A table can be used to store state associated with the timer. +Simple type variables can be used to pass read-only values ​​one-way. +data is set when the timer is started via [timer_set](#timer_set). +When the timer is deleted, the variable is automatically deallocated if there are no other references to it. + +If a timer function fails with an error, the timer is forcibly deleted. +Therefore, when developing timer functions, it is especially important to avoid error conditions. + +A one-shot timer is automatically deleted after the timer function is called. Manual deletion is not required, although it is permitted. + # nfqws2 C interface @@ -2360,6 +2410,37 @@ function execution_plan_cancel(ctx) A one-time cancellation of all subsequent instances within a profile. The instance performing the cancellation takes over the coordination of further actions and is called the orchestrator. +### Timer control + +Timer creation and deletion functions can be called from any Lua code. +This could be lua-init, lua-desync, or a timer function. A timer function can also act on itself, such as changing the period or terminating its own calls. + +Timers are identified by a name. Multiple timers with different names can call the same timer function. +It will be passed the timer name and arbitrary data as parameters (#timer-function-prototype) + +#### timer_set + +Create or replace the timer. + +``` +function timer_set(name, func, period, oneshot, data) +``` + +* name - a unique timer name. If a timer with this name already exists, it is deleted and replaced with a new one. When replaced, the countdown restarts. +* func - the timer function name (string) +* period - the timer call frequency in milliseconds (see [timer resolution](#timers)) +* oneshot - a bool indicating whether the timer is single-shot (true) or periodic (false) +* data - an arbitrary variable passed to the [timer-function](#timer-function-prototype) + +#### timer_del + +Delete the timer. + +``` +function timer_del(name) +``` + + # zapret-lib.lua base function library Nearly every function includes detailed comments regarding its purpose and parameters.