Wapp

Check-in [f6b7dbaa54]
Login

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

Overview
Comment:More documentation updates
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: f6b7dbaa549d8923bd17ad18a8a1839cc90132a71941bd024898020e4c2a7e57
User & Date: drh 2018-02-07 18:33:20.646
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
Side-by-Side Diff Ignore Whitespace Patch
Changes to README.md. 
1
2
3
4
5
6
7
8
9
10

11
12
13
14


15
16
17
18
19
20
21

1
2
3
4
5
6
7
8
9

10
11
12


13
14
15
16
17
18
19
20
21










-
+


-
-
+
+








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 surface → Simple to learn and use
  *   Very small API → easy 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
  *   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
︙
45
46
47
48
49
50
51
52

53
54
55
56
57
58
59

45
46
47
48
49
50
51

52
53
54
55
56
57
58
59








-
+









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

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




+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+


+
-
+







-
-
+
+



-
+







-
+


+








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
         

1.0 Interfaces
2.0 Interfaces
--------------

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



63
64
65
66
67
68
69
70
71
72
73
74
75

76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96










+
+
+











-
-


>
    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

SCRIPT\_FILENAME := DOCUMENT\_ROOT + SCRIPT\_NAME
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

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 
      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 ever reach application code. There is no risk
      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 escape generated text so that it is safe for inclusion
      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
︙