NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

ns_return(n) 5.0.0a naviserver "NaviServer Built-in Commands"

Name

ns_return - Return a complete HTTP response

Table Of Contents

Synopsis

Description

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).

COMMANDS

ns_return ?-binary? status mime-type body

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.

ns_returnfile status mime-type filepath

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.

ns_returnfp status mime-type channel length

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.

ns_respond ?-status status? ?-type mime-type? ?-length int? ?-headers setid? ?-string body? ?-binary body? ?-file filepath? ?-fileid channel?

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.

-status status

The HTTP status code. Default 200.

-type mime-type

The mime-type of the response body. Default */*.

-headers setid

A set of headers which will replace any pending headers for the response.

-string body

The Tcl string to send as the response body. The body may be encoded into an appropriate character set if required by the client and server settings.

-binary body

The byte-array representation of the given Tcl object will be used as the response body. No character set conversion will be done.

-file filepath

The file identified by the given filepath will be sent as the response body. The bytes of the file will not be transformed in any way.

-fileid channel

The file identified by the given Tcl channel will be sent as the response body. The bytes of the file will not be transformed in any way.

-length length

Specifies the number of bytes to send from the channel.

EXAMPLES

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!"
 }

CONFIGURATION

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:

  1. 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.

  2. 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.

  3. Delivering the file from the own NaviServer file cache. This option is activated, when the parameter cache is set to true.

Global fastpath configuration parameters

cache

Use the NaviServer file cache for file deliveries (boolean, defaults to false)

cachemaxentry

Maximum size of a single entry, when parameter cache is true (integer, defaults to 8kB)

cachemaxsize

Size of the cache, when parameter cache is true; (integer, defaults to 10MB)

mmap

Use mmap for file deliveries (and cache is false) (boolean, defaults to false)

gzip_static

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)

gzip_refresh

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)

gzip_cmd

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 "")

brotli_static

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)

brotli_refresh

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)

brotli_cmd

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 "")

minify_css_cmd

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 "")

minify_js_cmd

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 "")

Per-server fastpath configuration parameters

File Locations

The parameters serverdir and pagedir specify, from which locations in the filesystem pages should be served.

serverdir

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.

pagedir

Defines absolute or relative path for serving content files. Relative names are relative to the serverdir (string, defaults to pages)

Directory Handling

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.

directoryfile

Index files for directory (string, defaults to index.adp index.tcl index.html index.htm)

directoryadp

Name of an ADP page to use to display directory listings. (string, defaults to "")

directoryproc

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)

directorylisting

Style of directory listings. Can be fancy, simple, or none. This value is a parameter for the directoryproc _ns_dirlist. (string, defaults to simple)

hidedotfiles

Hide files starting with a dot in directory listings. This value is a parameter for the directoryproc _ns_dirlist. (boolean, defaults to false).

See Also

ns_adp_puts, ns_conn, ns_guesstype, ns_register, ns_write, ns_writer, returnstatus-cmds

Keywords

brotli, cache, charset, configuration, encoding, fastpath, gzip, minify, mmap, pagedir, response, return, server built-in, serverdir, status, writer