ns_urlspace - Assign Application Data to URLs
The command ns_urlspace allows you to assign, query, list, or delete data in the trie data structure representing the URL space. It supports filters and inheritance, enabling you to assign data to specific URL patterns (e.g., all ".adp" pages) or to assign data to a higher-level node, which can be inherited by all nodes below it.
The values assigned to the URL space are shared among all threads of a server. This using this command is somewhat similar to the use of nsv but differs in its inheritance and filtering capabilities.
This command allows you, for example, to implement access control (similar to the nsperm module) at the Tcl level. Other applications include blacklisting certain parts of the URL tree from statistics, or assigning different master templates to different parts of the URL tree.
The ns_urlspace command provides scripting access to functionality that has been part of NaviServer for a long time. For example, the mapping of requests to connection thread pools is performed using the same mechanism. In this case, the mapping of URLs to pools can be performed via the command ns_server, or it can be provided via configuration variables in the pool section (see, e.g., Tuning NaviServer).
Assigns a value to a node in the URL space specified by URL. By default, the value is inherited by all sub-nodes, unless the option -noinherit is specified.
The URL can include glob-style patterns (e.g., "/*.adp") to match multiple URLs.
The option -contextfilter allows you to specify additional context constraints for the assignment (see Context Constraints).
# Assign values to URL patterns ns_urlspace set /*.adp A ns_urlspace set /*.html H ns_urlspace set /internal/space/* I # Assign a value with a context filter set contextFilter [ns_set create "user-agent" "*bot*"] ns_urlspace set -contextfilter $contextFilter /*.adp C
Retrieves a value from the URL space for a specified URL. By default, the returned value might be inherited from a parent node in the trie structure.
When the option -exact is used, inheritance is deactivated, and only values directly assigned to the URL are returned. When the option -noinherit is specified, only values set with the -noinherit flag are considered.
The option -context setId allows you to specify context constraints for the retrieval (see Context Constraints).
# Retrieve mappings without context ns_urlspace get /test.adp # Returns: A ns_urlspace get /internal/space/documents/info.html # Returns: I # Retrieve mapping with context set context [ns_set create "user-agent" "googlebot"] ns_urlspace get -context $context /test.adp # Returns: C
Lists the values assigned to the URL space, which is either the default URL space or the one specified by -id. The command returns a list of lists, where each item contains the following elements:
key — The key associated with the assignment.
path — The URL pattern (e.g., "/internal/space").
filter pattern — Any context filters applied (e.g., "*.adp").
inherit or noinherit — Whether inheritance is enabled.
?contextfilter? — The optional contextfilter
data — The assigned value.
ns_urlspace list
Returns: {. / *.html inherit H} {. / *.adp inherit A} {. / *.adp inherit {user-agent *bot*} C} {. /internal/space * inherit I}
Unset a value for a URL for the given or default key. This command undoes the effects of ns_urlspace set.
The option -allfilters implies that all context filters are deleted. When the option -noinherit is used, only the values set with -noinherit are deleted, and vice versa.
The option -recurse performs the operation recursively on all sub-nodes under the specified URL. Unless -recurse is specified, the command returns 1 on success or 0 on failure.
Allocates a new URL space ID. When the number of compile-time configured URL spaces runs out, a Tcl exception is raised.
# Allocate a new URL space set newId [ns_urlspace new] # Use the new URL space ID ns_urlspace set -id $newId /*.php P
# Define mappings in the default URL space # Map all .adp files to "A" ns_urlspace set /*.adp A # Map all .html files to "H" ns_urlspace set /*.html H # Map a specific internal area to "I" ns_urlspace set /internal/space/* I # Query mappings ns_urlspace get /test.adp # Returns: A ns_urlspace get /foo/bar/test.adp # Returns: A ns_urlspace get /foo/baz/info.html # Returns: H ns_urlspace get /foo/baz/info.text # Returns: (no value assigned) ns_urlspace get /internal/space/documents/info.html # Returns: I
In addition to the glob based URL space matching, NaviServer supports so-called context constraints or context filters. These constraints allow one to include additional information such as IP-addresses or header fields in the matching process. These constraints are applied after the classical URLspace processing and add more information to the matching process. The general rule the a more specific URL space rule dominates a less specific ones continues to hold.
By using context filers one can specify that when one is applying a matching from a URL to some data, not only the URL matters, but as well an additional context. One can use this for defining different access rules, when e.g. bots access your web server, or when internal requests are issued.
API-wise the context can be specified by an ns_set with keys being header fields of a request or some IP ranges. When the context filters are used in the connection pool definition, the connection information is taken directly from the incoming socket connections.
In the following example, we provide an explicit ns_set for the context and use a single URL pattern /*.adp which is set once with a context constraint.
#
# Create a plain URL space mapping with the value of "A" and a rule
# with a context filter with the value "C"
#
% ns_urlspace set /*.adp A
% ns_urlspace set -contextfilter {user-agent *bot*} /*.adp C
# Get the mapping for a concrete URL without context
% ns_urlspace get /test.adp
A
# Create a context filter for user-agents containing "bot"
% set botContext [ns_set create filter1 "user-agent" "googlebot"]
# Get the mapping for a concrete URL based on the context
% ns_urlspace get -context $botContext /test.adp
C
See for a configuration example of context constraints for setting up a connection pool for bots in ns_server.
The URL patterns used in ns_urlspace commands support glob-style patterns, allowing for flexible matching. Be cautious when defining patterns to ensure they match the intended URLs.
The URL space is stored in a trie data structure for efficient matching.
When using context filters, ensure that the context filter of the ns_urlspace set command and the ns_set (or request headers) accurately represent the request conditions you want to match. For security reasons, you should not rely solely on untrusted request header fields.