NaviServer Built-in Commands – 5.1.0
ns_writer - Manage files with writer thread
This command allows one to submit data or file to be returned to the client connection using writer thread instead of current connection thread. Writer thread processes multiple sockets using async socket operations which consumes less resources than returning multiple files to the slow clients in separate thread.
Returns list of all currently submitted files. Every list entry contains the following elements:
start time of the initiating request,
name of the thread,
driver,
pool,
IP address of the client,
file descriptor,
remaining size,
bytes already sent,
current transfer rate
rate limit, and
the client data as provided via [ns_conn clientdata].
If -server is specified, only the submitted file entries from the specified server are returned. When NaviServer is running in reverse proxy mode, the client IP address is taken form the value as provided by the reverse proxy server.
Submit arbitrary data to be returned via writer thread, data can be binary. On success the function returns 1, otherwise 0.
Submits file to be returned via writer thread. For partial requests, ns_writer does NOT change status code or sets content-range. On success the function returns 1, otherwise 0. Optionally the following arguments can be used:
-headers Tells the writer to provide required HTTP headers, like content size, type and status. When this option is not used, make sure that the headers are provided (e.g. via ns_headers) from your application.
-offset If specified, file will be returned starting with this offset. The value can be specified in memory units (kB, MB, GB, KiB, MiB, GiB).
-size If not specified, the whole file will be returned, otherwise only given part. Can be combined with -offset. The value can be specified in memory units (kB, MB, GB, KiB, MiB, GiB).
Submits multiple files to be submitted in a single chunk. This call is quite similar to ns_writer submitfile, but it accepts a list of dicts as argument. Every dict element has to contain a filename element and optionally an -offset element and/or a -size element.
This function is, e.g., useful for video streaming applications, where multiple video file chunks should be transferred (sometimes) concatenated in a single chunk. Therefore, this function avoids the necessity to concatenate these files in advance (causing increased latency and disk usage).
ns_writer submitfiles {{filename /tmp/f1} {filename /tmp/f2 -offset 10}}
Query or set configuration parameter writersize of the writer(s) of the current or specified driver. When -driver is not specified the driver of the current connection thread is used. When the size is not provided, the actual setting is returned. When the size is provided, it can be specified in memory units (kB, MB, GB, KiB, MiB, GiB).
Query or set configuration parameter writerstreaming of the writer(s) of the current or specified driver. When -driver is not specified the driver of the current connection thread is used. When the value is specified, it has to be of the form of a valid Boolean value.
Writer threads are configured on network driver instances, such as ns/module/http, ns/module/https, or a per-server driver section. They allow selected responses to be sent by dedicated writer threads instead of by the connection thread.
Writer threads are an important mitigation against slow-reading clients. When a response is handed to a writer thread, the connection thread can return to processing other requests instead of blocking on network output. In practice, a small number of lightweight writer threads can serve many concurrent slow clients, and additional writer threads can be configured per network driver when more capacity is needed. Writer threads can mitigate slow-read attacks.
ns_section ns/module/http {
ns_param writerthreads 2
ns_param writersize 4kB
ns_param writerstreaming true
}
The writerthreads parameter specifies the number of writer threads for this network driver. When more than one writer thread is configured, responses are distributed across the available writer threads.
The writersize parameter specifies the minimum response size for using writer threads. When a file or response exceeds this size, NaviServer can hand the response to a writer thread and release the connection thread to handle other requests.
The writerstreaming parameter controls whether streaming output, such as output sent with ns_write, should also be sent through writer threads. This extends the same slow-client mitigation to streaming responses.
For the complete reference of network driver parameters, see NaviServer configuration parameter reference. read
For the complete reference of network driver parameters, see NaviServer configuration parameter reference.
ns_writer submitfile /tmp/biglist.txt
admin-config-params, ns_conn, ns_headers, ns_returnfile, ns_write