Wapp

      wapp-trim {
        <h1>Hello, World!</h1>
        <p>See the <a href='%html($B)/env'>Wapp
        Environment</a></p>
      }
    }
    proc wapp-page-env {} {
      wapp-allow-xorigin-params
      wapp-subst {<h1>Wapp Environment</h1>\n<pre>\n}
      foreach var [lsort [wapp-param-list]] {
        if {[string index $var 0]=="."} continue
        wapp-subst {%html($var) = %html([list [wapp-param $var]])\n}
      }
      wapp-subst {</pre>\n}
    }

The /env page is implemented by the "wapp-page-env" proc.  This proc
generates HTML that describes all of the query parameters. Parameter names
that begin with "." are for internal use by Wapp and are skipped
for this display.  Notice the use of "wapp-subst" to safely escape text
for inclusion in an HTML document.

4.0 Parameters
--------------

To better understand Wapp parameters, try running the previous
sample program, but extend the /env URL with extra path elements and query
parameters.  For example:
<http://localhost:8080/env/longer/path?q1=5&title=hello+world%21>

Notice how the query parameters in the input URL are decoded and become
parameters.  The same thing occurs with POST parameters
and cookies - they are all converted into parameters accessible
using the "wapp-param" interface.

4.1 Security By Default
-----------------------

For security reasons, this automatic decoding of GET and POST parameters
only occurs if inbound request is from the "same origin" or if the
special "wapp-allow-xorigin-params" interface is called.  An inbound
request is from the same origin if it is in response to clicking on a
hyperlink or form on a page that was generated by the same website.
Manually typing in a URL does not constitute the "same origin".  Hence,
in the example above the "wapp-allow-xorigin-params" interface is used
so that you can manually extend the URL to add new query parameters.

If query parameters can have side effects, then you should omit the
wapp-allow-xorigin-params call.  Only invoke wapp-allow-xorigin-params
for web pages that only query information.  Do not invoke 
wapp-allow-xorigin-params on pages where the parameters can be used
to change server-side state.

4.2 Environment Parameters
--------------------------

Wapp also provides parameters that describe the execution environment.
These parameter look like CGI environment variables.  To prevent environment
information from overlapping and overwriting query parameters, all the
environment information uses upper-case names and all query parameters
are required to be lower case.  If an input URL contains an upper-case
query parameter (or POST parameter or cookie), that parameter is silently
omitted.

The following environment parameters are always available:

  +  **CONTENT\_LENGTH**  
     The number of bytes of POST data.

  +  **CONTENT\_TYPE**  
     The mimetype of the POST data.  Usually this is
     application/x-www-form-urlencoded.

  +  **HTTP\_COOKIE**  
     The values of all cookies in the HTTP header

  +  **HTTP\_HOST**  
     The hostname (or IP address) and port that the client used to create
     the current HTTP request.  This is the first part of the request URL,
     right after the "http://" or "https://".  The format for this value
     is "HOST:PORT".  Examples:  "sqlite.org:80" or "127.0.0.1:32172".

  +  **HTTP\_USER\_AGENT**  
     The name of the web-browser or other client program that generated
     the current HTTP request.




  +  **HTTPS**  
     If the HTTP request arrived of SSL (via "https://"), then this variable
     has the value "on".  For an unencrypted request ("http://"), this
     variable does not exist.

  +  **PATH\_INFO**  
     The part of the URL path that follows the SCRIPT\_NAME.  For all modes
     other than CGI, this is exactly the URL pathname, though with the
     query parameters removed.  PATH_INFO begins with a "/".

  +  **REMOTE\_ADDR**  
     The IP address from which the HTTP request originated.

  +  **REMOTE\_PORT**  
     The TCP port from which teh HTTP request originated.

  +  **REQUEST\_METHOD**  



     "GET" or "HEAD" or "POST"





  +  **REQUEST\_URI**  
     The URL for the inbound request, without the initial "http://" or
     "https://" and without the HTTP\_HOST.  This variable is the same as
     the concatenation of $SCRIPT\_NAME and $PATH\_INFO.

  +  **SCRIPT_NAME**  
     In CGI mode, this is the name of the CGI script in the URL.  In other
     words, this is the initial part of the URL path that identifies the


     CGI script.  For other modes, this variable is an empty string.





All of the above are standard CGI environment values.
The following are supplemental environment parameters are added by Wapp:





  +  **BASE\_URL**  
     The text of the request URL through the SCRIPT\_NAME.  This value can
     be prepended to hyperlinks to ensure that the correct page is reached by
     those hyperlinks.

  +  **CONTENT**  
     The raw POST data text.

  +  **PATH\_HEAD**  
     The first element in the PATH\_INFO.  The value of PATH\_HEAD is used to
     select one of the "wapp-page-XXXXX" commands to run in order to generate
     the output web page.

  +  **PATH\_TAIL**  
     All of PATH\_INFO that follows PATH\_HEAD.

  +  **SAME\_ORIGIN**  
     This value is either "1" or "0" depending on whether the current HTTP
     request is a follow-on to another request from this same website or not.
     Query parameters and POST parameters are usually only decoded and added
     to Wapp's parameter list if SAME\_ORIGIN is 1.  If a webpage implemented
     by Wapp needs access to query parameters for a cross-origin request, then
     it should invoke the "wapp-allow-xorigin-params" interface to explicitly
     signal that cross-origin parameters are safe for that page.

  +  **SELF\_URL**  
     The URL for the current page, stripped of query parameter. This is
     useful for filling in the action= attribute of forms.


### 4.1 URL Parsing Example

     currentn 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".

The POST data parser for Wapp currently only understands
application/x-www-form-urlencoded content.  Wapp does not (currently)
have a decoder for multipart/form-data content.  A multipart/form-data
decoder might be added in the future.  Or, individual applications can
implement their own multipart/form-data decoder using the raw POST data
held in the CONTENT parameter.








8.0 Design Rules
----------------

All global procs and variables used by Wapp begin with the four character
prefix "wapp".  Procs and variable intended for internal use begin with
the seven character prefix "wappInt".