Ns register filter

Man page: http://aolserver.com/man/4.0/tcl/ns_filter.html

---

NAME

ns_register_filter - Register a filter or trace callback

SYNOPSIS

ns_register_filter ?-first? when method URLpatttern procname ?arg arg ...?

ns_register_filter_shortcut when method URLpatttern (new in AOLserver 4.5.2)

ns_register_filter_error ?-first? when method URLpatttern (ampools module for AOLserver 4.5.2)

DESCRIPTION

Registers a Tcl filter script for the specified method/URL combination on a virtual server. The script can be called at one of several times as indicated by the when argument:

• read - upcoming in AOLserver 4.6 - runs in the driver thread while in the read state in a different Tcl interpreter from the rest of the connection - procedure will not receive a conn id so should not have arguments(?) and normal ns_conn and similar commands will not work.
• prequeue - runs in the driver thread while in the ready state in a different Tcl interpreter from the rest of the connection - new in AOLserver 4.5 but there are known memory leak issues that are fixed in upcoming AOLserver 4.6. Procedure will not receive a conn id so should not have arguments(?) and normal ns_conn and similar commands will not work.
• preauth - pre-authorization
• postauth- post-authorization before page data has been returned to the user
• write - upcoming in AOLserver 4.6 - Invokes proc after each write to the client. Server normally buffers response output so this callback is called potentially just once when flushing the connection output buffers.
• trace - after the connection has been processed and closed.

The registered script will be called at the specified stage of a connection, if the method/URL combination for the filter matches the method/URL combination for the connection using glob style (i.e. as in string match) matching. For example, these are valid URLpatterns:

   /employees/*.tcl
   /accounts/*/out

Using pre-authorization, the procedure will be called (assuming that the method/URL combination matches) just before authorization. If the procedure returns with a code of:

• TCL_OK (using: return "filter_ok"): The server will continue to the next pre-authorization filter for this connection, or, if there are no more pre-authorization filters, it will continue on with authorization.
• TCL_BREAK (using: return "filter_break"): The server will not process any more pre-authorization filters for this connection, and it will continue on with authorization.
• TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more pre-authorization filters. It will not authorize the request, and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has sent a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.

Using post-authorization, the procedure will be called (assuming that the method/URL combination matches) just after successful authorization. If the procedure returns:

• TCL_OK (using: return "filter_ok"): The server will continue to the next post-authorization filter for this connection, or, if there are no more post-authorization filters, it will run the function registered to handle this request.
• TCL_BREAK (using: return "filter_break"): The server will not process any more post-authorization filters for this connection, and it will run the function registered to handle this request.
• TCL_RETURN (using: return "filter_return"): The server will close the connection and will not run any more post-authorization filters and it will not run the function registered for this METHOD/URL. It WILL run any trace functions registered for this METHOD/URL, usually including logging. It is assumed that the filter has returned a proper response (e.g., using ns_return) to the client before returning TCL_RETURN.

Using trace, the procedure will be called (assuming that the method/URL combination match) after the connection has been totally processed and closed. If the procedure returns:

• TCL_OK (using: return "filter_ok"): The server will continue to the next trace filter.
• TCL_BREAK (using: return "filter_break"): The rest of the trace filters are ignored.
• TCL_RETURN (using: return "filter_break"): The rest of the trace filters are ignored.

Syntax for the registered procedure:

The conn (connection id) argument is optional for procedures registered by ns_register_filter if the procedure has 1 or 2 arguments (including why but not including conn). The following examples show the variations that can be used in this case:

   ns_register_filter trace GET /noargs filter_noargs
   ns_register_filter trace GET /context filter_context fnord
   ns_register_filter trace GET /conncontext filter_conncontext

   proc filter_noargs { why } {
   ns_log Notice "filter noargs"
   return filter_ok
   } ;# filter_noargs

   proc filter_context { arg why } {
   ns_log Notice "filter context. Arg: $arg"
   return filter_ok
   } ;# filter_noargs

   proc filter_conncontext { conn arg why } {
   ns_log Notice "filter conn context"
   return filter_ok
   } ;# filter_noargs

Note that documentation in the past listed these syntax forms as supported but they will NOT work:

   
   # this will throw an error 
   ns_register_filter postauth GET /threeargs threeargs aaa
   ns_register_filter postauth GET /fourargs fourargs aaa bbb ccc
   

   #  these call signatures are NOT supported:  
   proc threeargs { conn context { greeble bork } why } {
   ...
   } ;
   proc fourargs { conn context { greeble bork } {hoover quark} why } {
   ...
   } ;

Note that the server detects the number of arguments in your procedure only the first time it is invoked as a filter/trace. Therefore if you change the number of arguments after this, this change will not be recognized until after a server restart.

ns_register_filter_shortcut

Registers a C filter at the specified when at the top of the filters list which simply returns NS_FILTER_RETURN, effectively preventing further filter processing for that when. This is most useful to prevent a Tcl interpreter from being allocated to run globally registered filters for Fastpath (static) resources that don't really need that filter. In combination with ns_pools, this allows you to keep threads dedicated to serving requests for URLs registered to a particular pool lightweight, without the memory overhead of a Tcl interpreter.

ns_register_filter_error

Similarly, registers a C filter at the specified when (but not at the top, unless -first is specified) which simply returns NS_ERROR. This is most useful with the trace when to prevent void traces (registered with ns_register_trace) and ServerTraces, i.e. access logging.

NOTES

Note ns_register_filter (and _trace) is similar to ns_register_proc except that the pattern-matching for the URL is performed differently. With ns_register_proc, the specified URL is used to match that URL and any URL below it in the hierarchy. Wildcards such as "*" are meaningful only for the final part of the URL, such as /scripts/*.tcl. With ns_register_filter, the URLpattern is used to match URLs as a string with standard string-matching characters. ns_register_proc always results in a single match to just one procedure, whereas multiple procedures registered with ns_register_filter can be matched and will be called in the order they were registered.

In AOLserver 4.5.2, you can use the optional -first switch to specify that the procedure should go to the top of registered filters for a particular pattern and therefore to be called first.

To be more precise the allowed matching characters in URLpattern are determined by Tcl_StrMatch which in turn is determined by TCL string match.

SEE ALSO

ns_register_trace - very similar to ns_register_filter trace - known internally as void_traces, procedures registered by this command fire after the procedures registered by ns_register_filter trace and differ in that they only execute if a response was successfully sent to the client (i.e. not a Server Error), plus their return value is ignored. See ns_register_trace for more details.

---