NaviServer Programmable Web Server

ns_urlspace(n)

NaviServer Built-in Commands – 5.0.0a


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

Name

ns_urlspace - Assign Application Data to URLs

Table Of Contents

Synopsis

Description

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

COMMANDS

ns_urlspace set ?-constraints constraints? ?-id integer? ?-key value? ?-noinherit? URL data

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
ns_urlspace get ?-context setId? ?-exact? ?-id integer? ?-key value? ?-noinherit? URL

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
ns_urlspace list ?-id integer?

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}
ns_urlspace unset ?-allconstraints? ?-id integer? ?-key value? ?-noinherit? ?-recurse? URL

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.

ns_urlspace new

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

COMMON OPTIONS

-id integer

Specifies the ID of the URL space. Multiple different URL spaces can be used, which can be allocated with the command ns_urlspace new. The maximum number of available URL spaces is a compile-time constant of NaviServer. When no ID is specified, NaviServer automatically allocates a default ID on first usage.

-key value

Every URL assignment can have a key, which is logically part of the URL space. Using this key, you could, for example, assign different values to a URL for different HTTP methods like GET or POST. The key can be used for other purposes as well. If no key is specified, it defaults to the constant "." (dot character).

EXAMPLES

 # 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

Context Constraints

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.

NOTES

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.

See Also

ns_server, ns_set, nsv

Keywords

context constraints, data structure, server built-in, shared, trie, urlspace, variables