NaviServer - programmable web server
4.99  5.0

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

ns_conn(n) 4.99.30 naviserver "NaviServer Built-in Commands"

Name

ns_conn - Find information about the current HTTP connection

Table Of Contents

Synopsis

Description

This command is used to retrieve various pieces of information about a connection.

COMMANDS

ns_conn option ?arg arg ...?

The subcommands of ns_conn are (in alphabetical order):

ns_conn acceptedcompression

Returns the compression formats accepted by the client.

ns_conn addr

Returns the local IP address (IPv4 or IPv6) of the current connection.

ns_conn auth

Returns the authorization header content as an ns_set. For Basic authentication there are reserved keys: Username and Password, these are the keys returned by ns_conn authuser and ns_conn authpassword.

In case of Digest authentication, all the fields provided are returned in the ns_set. For Bearer authentication the base65 encoded Token is returned in the ns_set.

This ns_set can be updated.

For other authorization schemes, the Authorization header field can be handled like all other request header fields:

 set auth_header [ns_set iget [ns_conn headers] Authorization ""]
ns_conn authpassword

Returns the decoded user password from the authorization data.

ns_conn authuser

Returns the decoded username from the authorization data.

ns_conn channel

Returns the Tcl channel name for the current connection.

ns_conn clientdata ?value?

Query or set the client date of the current connection. The client data is provided by the application and is potentially passed to different threads and can be used to establish the context with the connection thread. For example, the writer thread outputs the client data when listing running connections (one can determine e.g. which user has initiated the delivery, etc.).

ns_conn close

Closes the connection so the script (or ADP) can do any time-consuming processing without making the client wait. If you use ns_conn close in an ADP, streaming should be turned on before closing the connection (i.e. <SCRIPT RUNAT=SERVER STREAM=ON>) or nothing will get sent out at all.

ns_conn compress ?level?

Either set or query the compression level for the current connection. Use ns_conn compress 0 to indicate that compression should be deactivated

ns_conn content ?-binary? ?offset? ?length?

Returns the content of the HTTP request body, optionally a substring of that content starting at offset and extending length characters. If the option -binary is used, the content is returned raw. Otherwise, a conversion to the encoding of the connection is performed. Note that the client response might be returned as string content (as retrieved by this command) or as file (see ns_conn contentfile ).

ns_conn contentfile

Returns name of the temporary file which holds contents of the request. Whether of not a content files is returned depends on the configuration settings.

ns_conn contentlength

Returns the number of bytes in the content passed in.

ns_conn contentsentlength ?bytes?

Returns or sets the number of bytes in the content to be sent.

ns_conn copy off len chan

Copies number of bytes from the current connection starting at the given offset to a Tcl channel.

ns_conn driver

Returns the name of the module (nssock or nsssl) that is acting as the communications driver for this connection.

ns_conn encoding ?encoding?

Query or set the encoding for the current connection.

ns_conn fileheaders file

Return the ns_set with header information for the uploaded file with the specified name (returned via [ns_conn files]). If the file was uploaded with the HTML5 multiple attribute a list of ns_sets is returned.

ns_conn filelength file

Return the length of the uploaded file with the specified name (returned via [ns_conn files]). If the file was uploaded with the HTML5 multiple attribute a list of file lengths is returned.

ns_conn fileoffset file

Return the offset of the uploaded file with the specified name (returned via [ns_conn files]). If the file was uploaded with the HTML5 multiple attribute a list of offsets is returned.

ns_conn files

Return files uploaded with the current form.

ns_conn flags

Return the internal flags of the current connection. Use with care, the flags might change over versions.

ns_conn form ?-fallbackcharset fallbackcharset?

Returns any submitted form data as an ns_set. This form data may have been submitted with a POST or appended to the URL in a GET request.

The option -fallbackcharset can be used to specify an alternative character set in cases, the decoding the form-data leads to invalid UTF-8. Instead of raising an exception, a second attempt of decoding the data is made with the fallback charset. Note that the fallback charset can be provided as well via the configuration parameter formfallbackcharset. For more details, see ns_getform.

Note: ns_conn form is not suitable for multipart formdata file upload. Use ns_getform instead.

ns_conn headerlength

Returns the length of the header. Together with ns_conn contentlength this can be used to determine the uncompressed request size, (not counting chunked overhead).

ns_conn headers

Returns all the HTTP request header fields as an ns_set. The keys of the ns_set represent the field names. The case of the returned field names depends on the "HeaderCase" configuration parameter. By default, HeaderCase is "Preserve", which means case is preserved.

ns_conn host

Returns the host part of the URL in the HTTP request line. This is only set, when the NaviServer is used as a proxy server.

ns_conn id

Returns the unique identifier of the current connection.

ns_conn isconnected

Returns 1 if you're in a connection thread, and you are therefore allowed to make calls to ns_conn. It returns 0 if you're not in a connection thread (such as when you're in a schedule procedure) and you are not allowed to make calls to ns_conn.

ns_conn keepalive ?value?

Query or set the keepalive for the current connection.

ns_conn location

Returns the location string for this virtual server in the form: protocol://hostname[:port]. The location is determined via the following means:

  1. if ns_locationproc is configured, its result is returned.

  2. if virtual hosting is enabled, and the "Host:" header field is provided and valid, it returns its content.

  3. If everything above fails, it is determined by virtual hosts mapping table (as defined in the "ns/module/nssock/servers" or "ns/module/nsssl/servers" section in the configuration file).

  4. If everything above fails, and a connection is open, it is determined by the current socket address.

  5. If everything above fails, it is determined by configuration values of the driver.

ns_conn method

Returns the HTTP method, e.g. GET.

ns_conn outputheaders

Returns an ns_set containing the HTTP response header fields, i.e. the fields that will be sent out when a result is returned to the client. This ns_set can be manipulated like any other ns_set. You can also use this command to extend/update/clear to the set of HTTP response header fields.

For example:

 ns_set put [ns_conn outputheaders] "Content-Disposition" "attachment;filename=export.xotcl"
ns_conn peeraddr ?-source configured|direct|forwarded?

Returns the IP address of the client, i.e. the "other side" of the HTTP connection. An IPv4 address is returned in the form of a string separated with periods (e.g., 155.164.59.75), an IPv6 address is returned in the form of a string separated with colons (e.g., 2001:628:404:74::31). In reverse proxy mode the IP address is determined by the value forwarded by the reverse proxy server (via the x-fowarded-for header field).

The result can be influenced by the -source to return the result as configured by the reverse proxy mode (default), or to return always the direct or forwarded IP address.

ns_conn peerport

Returns the port of the client, i.e. the "other side" of the HTTP connection.

ns_conn pool

Returns the current connection pool from the currently connected server.

ns_conn port

When NaviServer is used as a proxy server, it returns the port specified explicitly in the URL of the HTTP request. In all other cases (no explicit ":port" part in the URL, no proxy server request), the returned port number is 0.

ns_conn protocol

Returns the protocol of the current connection. When NaviServer is used as a proxy server, it contains the URL in the HTTP request line.

ns_conn query

Returns the query parameters of the HTTP request (transmitted after question mark via URL).

ns_conn partialtimes

Returns detailed timing information about the current requests. The result is a dict containing the keys "accepttime" (the time between the accept of a socket and its adding to the queue; not always easy to interpret), "queuetime" (time in the queue), "filtertime" (time spent during running of filters) and "runtime" (time spent so far during the main request).

ns_conn ratelimit ?limit?

Query or set rate limit for the current connection. The value is provided in KB/s (kilobytes per second). A value of 0 means unlimited. Default values can be provided per connection pool (parameter ratelimit) or on the driver level (parameter writerratelimit). The limit is only enforced on connections using writer threads.

ns_conn request

Returns the HTTP request line as presented by the client, e.g. GET / HTTP/1.1.

ns_conn server

Returns the name of the server handling the request.

ns_conn sock

Returns the socket id (integer fd) of current connection.

ns_conn start

Returns the time the connection request started in "sec:usec" (aka ns_time) format.

ns_conn status ?value?

Query or set the HTTP status code for the current connection.

ns_conn timeout

Returns absolute time value beyond which conn should not wait on resources, such as condition variables.

ns_conn url

Returns the URL of the HTTP request. This is the portion of the request after the hostname, for example [ns_conn url] on returns /index.adp.

ns_conn urlc

Returns the number of elements (delimited by `/') in the URL of the HTTP request.

ns_conn urlencoding ?encoding?

Query or set the url encoding for the current connection.

ns_conn urlv ?idx?

Returns a list containing the pieces of the URL delimited by `/'. When idx is provided, return the nth element of the URL vector.

ns_conn version

Returns the version of the HTTP request. This is usually 1.0 or 1.1.

ns_conn zipaccepted

Returns 0 or 1 depending on whether or not the client accepts a zip encoded response.

EXAMPLES

 if { [string match /page/* [ns_conn url]] } {
  ns_returnnotfound
 }

See Also

ns_adp, ns_getform, ns_locationproc, ns_queryget, ns_set, ns_subnetmatch, ns_time

Keywords

IPv4, IPv6, connection, gzip, reverseproxy, server built-in