Wapp

Check-in [f6b7dbaa54]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More documentation updates
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:f6b7dbaa549d8923bd17ad18a8a1839cc90132a71941bd024898020e4c2a7e57
User & Date: drh 2018-02-07 18:33:20
Context
2018-02-07
20:00
Improvements to the same-origin detection logic. check-in: 8b769e4771 user: drh tags: trunk
18:33
More documentation updates check-in: f6b7dbaa54 user: drh tags: trunk
14:27
Documentation enhancements. check-in: 651c5f305b user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to README.md.

3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
..
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

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

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

  *   Very small API surface → Simple to learn and use
  *   A complete application is contained in a single file
  *   Resistant to attacks and exploits
  *   Cross-platform → Works via CGI, SCGI, or using a built-in web server
  *   Does not require MVC, but can do MVC if desired
  *   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 into the appropriate directory of your web server.

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

  *  [Introduction To Writing Wapp Applications](docs/intro.md)

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







|


|
|







 







|







3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
..
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

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)

Changes to docs/quickref.md.

1
2
3


















4
5
6

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

31
32
33
34
35
36
37
..
56
57
58
59
60
61
62



63
64
65
66
67
68
69
70
71
72
73
74
75
Wapp Quick Reference
====================



















1.0 Interfaces
--------------


|**wapp-start** $argv|→|Starts up the Wapp application.  Should be last.|
|**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_|→|Make _MIMETYPE_ the reply mimetype|
|**wapp-reply-code** _CODE_|→|Set the HTTP reply code to _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|


2.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




>
    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

SCRIPT\_FILENAME := DOCUMENT\_ROOT + SCRIPT\_NAME



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|


>
|







|
|



|







|


>







 







>
>
>











<
<
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
..
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96


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|&rarr;|Starts up the Wapp application|
|**wapp-subst** {_TEXT_}|&rarr;|Append _TEXT_ to the output with substitution|
|**wapp-trim** {_TEXT_}|&rarr;|Like **wapp-subst** but also removes left-margin whitespace|
|**wapp-param** _NAME_ _DEFAULT_|&rarr;|Return value of parameter _NAME_|
|**wapp-set-param** _NAME_ _VALUE_|&rarr;|Set parameter _NAME_ to _VALUE_|
|**wapp-param-exists** _NAME_|&rarr;|True if parameter _NAME_ exists|
|**wapp-param_list** _GLOB_|&rarr;|Return parameter names matching _GLOB_|
|**wapp-allow-xorigin-params**|&rarr;|Allow GET and POST parameters for cross-origin requests|
|**wapp-mimetype** _MIMETYPE_|&rarr;|Set the reply mimetype|
|**wapp-reply-code** _CODE_|&rarr;|Set the HTTP reply code|
|**wapp-redirect** _TARGET_|&rarr;|Redirect to _TARGET_|
|**wapp-reset**|&rarr;|Reset the output back to an empty string|
|**wapp-set-cookie** _NAME_ _VALUE_|&rarr;|Set cookie _NAME_ to have _VALUE_|
|**wapp-clear-cookie** _NAME_|&rarr;|Delete cookie _NAME_|
|**wapp-cache-control** _CONTROL_|&rarr;|Set caching behavior of current page|
|**wapp-content-security-policy** _POLICY_|&rarr;|Set the CSP for the current page|
|**wapp-debug-env**|&rarr;|Return a text description of the Wapp environment|
|**wapp** {_TEXT_}|&rarr;|Append _TEXT_ without substitution|
|**wapp-unsafe** _TEXT_|&rarr;|Append _TEXT_ that contains nothing that needs to be escaped|


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

>
|BASE\_URL|&rarr;|URL for the Wapp script without a method|
|CONTENT|&rarr;|Raw (unparsed) POST content|
|CONTENT\_LENGTH|&rarr;|Number of bytes of raw, unparsed POST content|
|CONTENT\_TYPE|&rarr;|Mimetype of the POST content|
|DOCUMENT\_ROOT|&rarr;|Directory that is the root of the webserver content tree|
|HTTP\_COOKIE|&rarr;|Raw, unparsed cookies|
|HTTP\_HOST|&rarr;|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


Changes to docs/security.md.

10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
..
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
  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 application 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 ever 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 escape 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







|







 







|




|







10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
..
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
  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