Wapp

Wapp - A Web-Application Framework for TCL
==========================================

1.0 Introduction
----------------

Wapp is a framework for writing web applications in TCL,
with the following advantages:

  *   Very small API → easy to learn and use
  *   A complete application is contained in a single file
  *   Resistant to attacks and exploits
  *   Cross-platform → CGI, SCGI, or a built-in web server
  *   The MVC design pattern is supported but not required
  *   The Wapp framework itself is a  single-file TCL script
      that is "source"-ed, "package require"-ed, 
      or even copy/pasted into the application TCL script
  *   The framework can easily be embedded within a larger application
      to provide a web-based monitoring capability to an existing
      code base

  *   2-clause BSD license


2.0 Hello World
---------------

Here is a minimal web application written using Wapp:

>
    #!/usr/bin/tclsh
    package require wapp
    proc wapp-default {} {
      wapp-subst {<h1>Hello, World!</h1>\n}
    }
    wapp-start $argv

To run this application using the built-in web-server, store the code above
in a file (here we use the name "hello.tcl") and do:

>
    tclsh hello.tcl

To run the app using the built-in web-server bound to all TCP addresses
and listening on port 8080, use:

>
    tclsh hello.tcl --server 8080

To run the app as an SCGI server listening on port 9001:

>
    tclsh hello.tcl --scgi 9001

To run the application as CGI, make the hello.tcl file executable and
move it into the appropriate directory of the web server.

3.0 Further information
-----------------------

  *  [Introduction To Writing Wapp Applications](/doc/trunk/docs/intro.md)
  *  [Quick Reference](/doc/trunk/docs/quickref.md)
  *  [Wapp Parameters](/doc/trunk/docs/params.md)
  *  [Wapp Commands](/doc/trunk/docs/commands.md)
  *  [URL Mapping](/doc/trunk/docs/urlmapping.md)
  *  [Security Features](/doc/trunk/docs/security.md)
  *  [How To Compile wapptclsh - Or Not](/doc/trunk/docs/compiling.md)

     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

  +  **BASE\_URL** → "http://example.com/cgi-bin/script"
  +  **SELF\_URL** → "http://example.com/cgi-bin/script/method"
  +  **PATH\_HEAD** → "method"
  +  **PATH\_TAIL** → "extra/path"

The first five elements of the example above, HTTP\_HOST through
QUERY\_STRING, are standard CGI.  The final four elements are Wapp
extensions.




















### 3.2 Undefined Parameters When Using SCGI on Nginx

Some of the CGI parameters are undefined by default when using CGI mode
with Nginx.  If these CGI parameters are needed by the application, then
values must be assigned in the Nginx configuration file.  For example:

|**wapp-cache-control** _CONTROL_|→|Set caching behavior of current page|
|**wapp-content-security-policy** _POLICY_|→|Set the CSP for the current page|
|**wapp-debug-env**|→|Return a text description of the Wapp environment|
|**wapp** {_TEXT_}|→|Append _TEXT_ without substitution|
|**wapp-unsafe** _TEXT_|→|Append _TEXT_ that contains nothing that needs to be escaped|



3.0 Parameters
--------------

>
|BASE\_URL|→|URL for the Wapp script without a method|
|CONTENT|→|Raw (unparsed) POST content|
|CONTENT\_LENGTH|→|Number of bytes of raw, unparsed POST content|
|CONTENT\_TYPE|→|Mimetype of the POST content|
|DOCUMENT\_ROOT|→|Directory that is the root of the webserver content tree|
|HTTP\_COOKIE|→|Raw, unparsed cookies|
|HTTP\_HOST|→|Hostname to which this request was sent|
|HTTP\_USER\_AGENT|→|Name of client program that sent current request|
|HTTPS|→|Exists and has value "on" if the request is encrypted|
|PATH\_HEAD|→|First element of PATH\_INFO. Determines request handler|
|PATH\_INFO|→|URL path beyond the application script name|
|PATH\_TAIL|→|Part of PATH\_INFO beyond PATH\_HEAD|
|REMOTE\_ADDR|→|IP address of the client|
|REMOTE\_PORT|→|TCP port of the client|
|REQUEST\_METHOD|→|"GET" or "POST" or "HEAD"|
|SAME\_ORIGIN|→|True if this request is from the same origin|
|SCRIPT\_FILENAME|→|Full pathname of the Wapp application script|
|SCRIPT\_NAME|→|Prefix of PATH\_INFO that identifies the application script|
|SELF\_URL|→|URL of this request without PATH\_TAIL|
|WAPP\_MODE|→|One of "cgi", "scgi", "server", or "local"|

4.0 URL Parsing
---------------

Assuming "env.tcl" is the name of the Wapp application script:

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
            \_________/ \__________/\__________/
                 |           |          |
             HTTP_HOST  SCRIPT_NAME  PATH_INFO

>
    SCRIPT_FILENAME := DOCUMENT_ROOT + SCRIPT_NAME

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    \______________________________/ \_/ \_____/
                   |                  |     |
                BASE_URL         PATH_HEAD  '-- PATH_TAIL     

>

    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    \__________________________________/         \__________/
                   |                                  |
                SELF_URL                         QUERY_STRING

URL Mapping In Wapp
===================

1.0 Anatomy Of A URL
--------------------

A Uniform Resource Locator (URL) is divided into parts as follows:

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
    \___/   \_________/ \______________________/ \__________/ \_____/
      |          |              |                     |          |
    scheme   authority        path                  query      fragment


Assuming that /demo/env.tcl is the script that implements the application,
traditional CGI and SCGI provide the following breakdown:

>
    https://wapp.tcl.tk/demo/env.tcl/abc/def/ghi?a=5&b=22.425#point42
            \_________/ \__________/\__________/ \__________/
                 |           |          |             |
             HTTP_HOST  SCRIPT_NAME  PATH_INFO   QUERY_STRING

Wapp provides additional variables not found in traditional CGI:

>
                SELF_URL