NaviServer Built-in Commands – 5.0.0b1
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 -constraints 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 constraints
ns_urlspace set -constraints {"user-agent" "*bot*"} /*.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 constraints 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 -allconstraints 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. These constraints allow you to include additional (context) information such as the current IP addresses or current header fields in the URL space lookup. They’re applied after the constraint-less URL match and participate in the usual "most specific wins" resolution (i.e., if there are multiple definitions for the same method and URL pattern pair, having different context constraints, the most definition is taken).
With context constraints, you can say "I want /foo.adp to map to X only when this request comes from a Googlebot, and to Y otherwise." Or "serve internal pages only to clients in our corporate subnet."
When you attach a context constraints in a connection-pool mapping, or via ns_register_proc, ns_register_filter etc., the live socket’s headers and peer address are used automatically when deciding, which proc/filter/etc. is to be used. When you specify the context constraints in a ns_urlspace set command, you can pass directly a context to a ns_urlspace set command, by providing an "ns_set" whose keys are header names (e.g. "user-agent") or the special key "x-ns-ip" (pseudo header field) for IP/mask filters.
Context constraints may be conjunctive: if you supply multiple key/value pairs, all must match. Conjunctions are specified as a flat list.
Example:
# Base mapping when no context matches:
% ns_urlspace set /*.adp DefaultHandler
# When *either* user-agent contains "bot":
% ns_urlspace set -constraints {user-agent *bot*} /*.adp BotHandler
# When *both* UA="bot" *and* IP in 10.0.0.0/8:
% ns_urlspace set -constraints {user-agent *bot* x-ns-ip 10.0.0.0/8} \
/*.adp BotInternalHandler
# Try without context:
% ns_urlspace get /test.adp
DefaultHandler
# Try with only user-agent googlebot:
% set ctx1 [ns_set create user-agent googlebot]
% ns_urlspace get -context $ctx1 /test.adp
BotHandler
# Try with UA=googlebot *and* internal IP:
% set ctx2 [ns_set create user-agent googlebot x-ns-ip 10.0.12.5]
% ns_urlspace get -context $ctx2 /test.adp
BotInternalHandler
See also the ns_server configuration examples for defining connection pools that use context constraints to route "*bot*" traffic into a dedicated pool.
Context constraints can be as well set for the following commands ns_register_adp, ns_register_cgi, ns_register_fastpath, ns_register_filter, and ns_register_proc.
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 constraints, ensure that the context constraints 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.