Wapp

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

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

Wapp is a new 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
  *   2-clause BSD license


2.0 Hello World

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](docs/intro.md)

  *  [Quick Reference](docs/quickref.md)

Wapp Quick Reference
====================

1.0 Application Template
------------------------

>
    package require wapp
    proc wapp-page-XXXXX {} {
      wapp-trim {
        # Content to deliver for page XXXXX
      }
    }
    proc wapp-default {} {
      wapp-trim {
        # Content for all other pages
      }
    }
    wapp-start $argv
         

2.0 Interfaces
--------------

>
|**wapp-start** $argv|→|Starts up the Wapp application|
|**wapp-subst** {_TEXT_}|→|Append _TEXT_ to the output with substitution|
|**wapp-trim** {_TEXT_}|→|Like **wapp-subst** but also removes left-margin whitespace|
|**wapp-param** _NAME_ _DEFAULT_|→|Return value of parameter _NAME_|
|**wapp-set-param** _NAME_ _VALUE_|→|Set parameter _NAME_ to _VALUE_|
|**wapp-param-exists** _NAME_|→|True if parameter _NAME_ exists|
|**wapp-param_list** _GLOB_|→|Return parameter names matching _GLOB_|
|**wapp-allow-xorigin-params**|→|Allow GET and POST parameters for cross-origin requests|
|**wapp-mimetype** _MIMETYPE_|→|Set the reply mimetype|
|**wapp-reply-code** _CODE_|→|Set the HTTP reply code|
|**wapp-redirect** _TARGET_|→|Redirect to _TARGET_|
|**wapp-reset**|→|Reset the output back to an empty string|
|**wapp-set-cookie** _NAME_ _VALUE_|→|Set cookie _NAME_ to have _VALUE_|
|**wapp-clear-cookie** _NAME_|→|Delete cookie _NAME_|
|**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|

>
    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

  1.  The default
      [Content Security Policy](https://en.wikipedia.org/wiki/Content_Security_Policy)
      of "CSP"
      for all Wapp applications is _default\_src 'self'_.  In that mode,
      resources must all be loaded from the same origin, the use of
      eval() and similar commands in javascript is prohibited, and
      no in-line javascript or CSS is allowed.  These limitations help
      keep applications safe from 
      [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting)
      attacks, even in the face of application coding errors. If these
      restrictions are too severe for an application, the CSP can be
      relaxed using the "wapp-content-security-policy" command.

  2.  Access to GET query parameters and POST parameters is prohibited
      unless the origin of the request is the application itself, as
      determined by the Referrer field in the HTTP header. This feature
      helps to prevent
      [Cross-site Request Forgery](https://en.wikipedia.org/wiki/Cross-site_request_forgery)
      attacks. The "wapp-allow-xorigin-params" command can be used to
      disable this protection on a case-by-case basis.

  3.  Cookies, query parameters, and POST parameters are automatically
      decoded before they reach application code. There is no risk
      that the application program will forget a decoding step or
      accidently miscode a decoding operation.

  4.  Reply text generated using the "wapp-subst" and "wapp-trim" commands
      automatically escapes generated text so that it is safe for inclusion
      within HTML, within a javascript or JSON string literal, as a URL,
      or as the value of a query parameter. As long as the application
      programmer is careful to always use "wapp-subst" and/or "wapp-trim"
      to generate replies, there is little risk of injection attacks.

  5.  If the application is launched on a command-line with the --trim
      option, then instead of running the application, Wapp scans the