Wapp

Wapp is really just a collection of TCL procs. All procs are in a single file named "wapp.tcl".

The procs that form the public interface for Wapp begin with "wapp-". The implementation uses various private procedures that have names beginning with "wappInt-". Applications should use the public interface only.

The most important Wapp interfaces are:

• wapp-start
• wapp-subst and wapp-trim
• wapp-param

Understand the four interfaces above, and you will have a good understanding of Wapp. The other interfaces are merely details.

The following is a complete list of the public interface procs in Wapp:

• wapp-start ARGLIST
  Start up the application. ARGLIST is typically the value of $::argv, though it might be some subset of $::argv if the containing application has already processed some command-line parameters for itself. By default, this proc never returns, and so it should be very last command in the application script. To embed Wapp in a larger application, include the -nowait option in ARGLIST and this proc will return immediately after setting up all necessary file events.

• wapp-subst TEXT
  This command appends text to the end of reply to an HTTP request. The TEXT argument should be enclosed in {...} to prevent accidental substitutions. The "wapp-subst" command itself will do all necessary backslash substitutions. Command and variable substitutions occur within "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and "%unsafe(...)". The substitutions are escaped (except in the case of "%unsafe(...)") so that the result is safe for inclusion within the body of an HTML document, a URL, a query parameter, or a javascript or JSON string literal, respectively.

Caution #1: When using Tcl 8.6 or earlier, command substitution, but not variable substitution, occurs outside of the quoted regions. This problem is fixed using the new "-command" option to the regsub command in Tcl 8.7. Nevertheless, it is suggested that you avoid using the "[" character outside of the %-quotes. Use "[" instead.

Caution #2: The %html() and similar %-substitutions are parsed using a regexp, which means that they cannot do matching parentheses. The %-substitution is terminated by the first close parenthesis, not the first matching close-parenthesis.

• wapp-trim TEXT
  Just like wapp-subst, this routine appends TEXT to the web page under construction. The same substitution functions are supported. The difference is that this routine also removes surplus whitespace from the left margin, so that if the TEXT argument is indented in the source script, it will appear at the left margin in the generated output.

• wapp-param NAME DEFAULT
  Return the value of the Wapp parameter NAME, or return DEFAULT if there is no such query parameter or environment variable. If DEFAULT is omitted, then it is an empty string.

• wapp-set-param NAME VALUE
  Change the value of parameter NAME to VALUE. If NAME does not currently exist, it is created.

• wapp-param-exists NAME
  Return true if and only if a parameter called NAME exists for the current request.

• wapp-param-list NAME
  Return a TCL list containing the names of all parameters for the current request. Note that there are several parameters that Wapp uses internally. Those internal-use parameters all have names that begin with ".".

• wapp-allow-xorigin-params
  Query parameters and POST parameters are usually only parsed and added to the set of parameters available to "wapp-param" for same-origin requests. This restriction helps prevent cross-site request forgery (CSRF) attacks. Query-only web pages for which it is safe to accept cross-site query parameters can invoke this routine to cause query parameters to be decoded.

• wapp-mimetype MIMETYPE
  Set the MIME-type for the generated web page. The default is "text/html".

• wapp-reply-code CODE
  Set the reply-code for the HTTP request. The default is "200 Ok".

• wapp-redirect TARGET-URL
  Cause an HTTP redirect to TARGET-URL.

• wapp-reset
  Reset the web page under construction back to an empty string.

• wapp-set-cookie NAME VALUE
  Cause the cookie NAME to be set to VALUE.

• wapp-clear-cookie NAME
  Erase the cookie NAME.

• wapp-safety-check
  Examine all TCL procedures in the application and return a text string containing warnings about unsafe usage of Wapp commands. This command is run automatically if the "wapp-start" command is invoked with a --lint option.

• wapp-cache-control CONTROL
  The CONTROL argument should be one of "no-cache", "max-age=N", or "private,max-age=N", where N is an integer number of seconds.

• wapp-content-security-policy POLICY
  Set the Content Security Policy (hereafter "CSP") to POLICY. The default CSP is default_src 'self', which is very restrictive. The default CSP disallows (a) loading any resources from other origins, (b) the use of eval(), and (c) in-line javascript or CSS of any kind. Set POLICY to "off" to completely disable the CSP mechanism. Or specify some other policy suitable for the needs of the application.

  The following allows inline images using <img src='data:...'> and inline "style='...'" attributes, but restricts all other attack vectors and thus seems to be a good choice for many applications:

   wapp-content-security-policy {
      default-src 'self' data:;
      style-src 'self' 'unsafe-inline';
   }

• wapp-debug-env
  This routine returns text that describes all of the Wapp parameters. Use it to get a parameter dump for troubleshooting purposes.

• wapp TEXT
  Add TEXT to the web page output currently under construction. TEXT must not contain any TCL variable or command substitutions. This command is rarely used.

• wapp-unsafe TEXT
  Add TEXT to the web page under construction even though TEXT does contain TCL variable and command substitutions. The application developer must ensure that the variable and command substitutions does not allow XSS attacks. Avoid using this command. The use of "wapp-subst" is preferred in most situations.