ns_return - Return a complete HTTP response
These are the lower elevel commands are used to construct a complete HTTP response and return it to the requesting client. The response may be transcoded into a different encoding, compressed and/or sent in chunks as automatically negotiated by the client and server settings.
Unless otherwise noted, these commands return true if the command failed and false otherwise. All of them can raise an error if their arguments are incorrect.
The behavior of the file delivery commands ns_returnfile and ns_repond is influenced by the fastpath settings, that define, how static files are served. The fastpath settings are described in the CONFIGURATION section at the end of this page.
Note that there are additional higher level commands are designed to ease consistent behavior in common success, redirect or error situations (see returnstatus-cmds).
Return a complete response to the client consisting of the given body and a set of HTTP headers. status is an integer HTTP status code such as 200 (OK) or 404 (Not Found). When the optional flag -binary is used, the content of the Tcl byte-array is transmitted.
mime-type is the mime-type of the body. If a charset attribute is included in the mime-type it will be used to set the encoding of the connection. Otherwise, the connection encoding will be used to construct a charset attribute for the mime-type.
If body is Tcl byte-array object then no transcoding will take place. Otherwise, the encoding in effect for the current connection will be used to encode the body.
After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.
Return the given file as the complete response body. Headers are constructed using status, mime-type and any pending headers set using ns_conn outputheaders. The bytes of the file are not transformed in any way.
After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.
Return length bytes from channel as the response body. The current offset of the channel is the beginning of the body -- the offset will be left at length bytes. The bytes of the file are not transformed in any way.
After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.
Return a complete response to the client using exactly one of -string, -binary, -file or -fileid as the body.
After the command completes the connection is returned to the driver thread to be closed or monitored for keep-alive and the calling connection thread continues to execute code.
A traditional geek greeting:
ns_register_proc GET /hello {
ns_return 200 text/plain "Hello World!"
}
A traditional Albanian greeting, using an explicit charset:
ns_register_proc GET /hello {
ns_return 200 "text/plain; charset=iso-8859-2" "Përshëndetje të gjithëve!"
}
The behavior of the file delivery commands ns_returnfile and ns_respond -file ..., as well as the automatic delivery of static files is influenced by the fastpath settings, which define, how files are served. The fastpath section of the configuration file for a server server1 has a global part (general settings for all servers) and a per (virtual) server part:
ns_section ns/fastpath {
# global configuration
ns_param ...
...
}
ns_section ns/server/server1/fastpath {
# per-server configuration
ns_param ...
...
}
Most prominently, the global fastpath parameters define the delivery mode. In general, fastpath supports three delivery modes for static content:
Delivering file via chunk reads from the file, where the chunk size is typical the writersize of a writer thread. This is the same behavior as in ns_respond -fileid ... or in ns_returnfp. This delivery mode is activated, when both the global fastpath parameter cache and mmap are false.
Delivering from mapped memory, when mmap is defined and the operating supports it. In this case the file to be delivered is mapped into memory and served from there. The buffer size etc. is determined from the operating system. This option is activated, when the global fastpath parameter mmap is true and cache is false.
Delivering the file from the own NaviServer file cache. This option is activated, when the parameter cache is set to true.
Use the NaviServer file cache for file deliveries (boolean, defaults to false)
Maximum size of a single entry, when parameter cache is true (integer, defaults to 8kB)
Size of the cache, when parameter cache is true; (integer, defaults to 10MB)
Use mmap for file deliveries (and cache is false) (boolean, defaults to false)
Send the gzip-ed version of the file if available and the client accepts gzip-ed content. When a file path/foo.ext is requested, and there exists a file path/foo.ext.gz, and the timestamp of the gzip-ed file is equal or newer than the source file, use the gzip-ed file for delivery. (boolean, defaults to false)
Refresh gzip file (i.e. re-gzip source) when the modification time of the compressed file is older than the modification time of the source. Note that the command is just used for re-gzip-ing outdated .gz-files; it does not actively compress files, which were previously not compressed (this would be wasteful for e.g. large temporary files, there is not cleanup, etc.). For refreshing gzip files, the Tcl command "::ns_gzipfile source target" is used. This command can be potentially redefined by an application. When this parameter is not defined (or the refresh command fails), outdated gzip-ed files are ignored, and a warning is written to the error.log. (boolean, defaults to false)
Command for gzip-ing files, used by ::ns_gzipfile. The value of gzip_cmd is used in ::ns_gzipfile to locate the gzip command in the OS. If gzip_cmd is not defined, and ::ns_gzipfile is called, an error is written to the error.log. Example setting: "/usr/bin/gzip -9". (string, defaults to "")
Send the brotli compressed version of the file if available and the client accepts brotli compressed content. When a file path/foo.ext is requested, and there exists a file path/foo.ext.br, and the timestamp of the brotli compressed file is equal or newer than the source file, use the brotli compressed file for delivery. (boolean, defaults to false)
Refresh the brotli compressed file (i.e. re compress source) when the modification time of the compressed file is older than the modification time of the source. Note that the command is just used for recompressing outdated .br-files; it does not actively compress files, which were previously not compressed (this would be wasteful for e.g. large temporary files, there is not cleanup, etc.). For refreshing gzip files, the Tcl command "::ns_brotlifile source target" is used. This command can be potentially redefined by an application. When this parameter is not defined (or the refresh command fails), outdated brotli compressed files are ignored, and a warning is written to the error.log. (boolean, defaults to false)
Command for producing brotli compressed files, used by ::ns_brotlifile. The value of brotli_cmd is used in ::ns_brotlifile to locate the brotlicommand in the OS. If brotli_cmd is not defined, and ::ns_brotlifile is called, an error is written to the error.log. Example setting: "/usr/bin/brotli -f -q 11". (string, defaults to "")
Command for minifying .css files. When recompressing outdated gzip files (see parameters gzip_refresh and gzip_cmd), NaviServer will optionally minify css files on the fly, when minify_css_cmd is specified. In these cases, the returned file will be minified and compressed. The configured command must read css files from stdin and to write the minified content to stdout. Example setting: "/usr/bin/yui-compressor --type css". (string, defaults to "")
Command for minifying .jsfiles. When recompressing outdated gzip files (see parameters gzip_refresh and gzip_cmd), NaviServer will optionally minify JavaScript files on the fly, when minify_js_cmd is specified. In these cases, the returned file will be minified and compressed. The configured command must read JavaScript files from stdin and to write the minified content to stdout. Example setting: "/usr/bin/yui-compressor --type js". (string, defaults to "")
The parameters serverdir and pagedir specify, from which locations in the filesystem pages should be served.
Defines absolute or relative path to server's home directory. Relative names are relative to the home in ns/parameters. (string, defaults to "")
Note: This parameter can be overloaded by defining a callback with ns_serverrootproc, e.g., for mass virtual hosting.
Defines absolute or relative path for serving content files. Relative names are relative to the serverdir (string, defaults to pages)
The parameters for directory handling specify what should happen, when the requested URL points to a directory. In a first step, NaviServer looks for a directoryfile in this directory. If there is no such file, the server will try to serve a directory listing ADP, or - if no directoryadp is configured - it will execute the Tcl proc specified by directoryproc.
Index files for directory (string, defaults to index.adp index.tcl index.html index.htm)
Name of an ADP page to use to display directory listings. (string, defaults to "")
Name of Tcl proc to use to display directory listings. One can either specify directoryproc, or directoryadp, but not both. (string, defaults to _ns_dirlist)
Style of directory listings. Can be fancy, simple, or none. This value is a parameter for the directoryproc _ns_dirlist. (string, defaults to simple)
Hide files starting with a dot in directory listings. This value is a parameter for the directoryproc _ns_dirlist. (boolean, defaults to false).