Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
| Comment: | Further documentation refinements. |
|---|---|
| Downloads: | Tarball | ZIP archive | SQL archive |
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
271766c541a09c526ae7a4b4c7066a69 |
| User & Date: | drh 2019-03-07 14:37:48 |
Context
|
2019-03-07
| ||
| 14:49 | More documentation improvements. check-in: 984d973c34 user: drh tags: trunk | |
| 14:37 | Further documentation refinements. check-in: 271766c541 user: drh tags: trunk | |
| 13:34 | Documentation updates: improvements to the description of URL mapping and CGI variables. check-in: 2eac47dda7 user: drh tags: trunk | |
Changes
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 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 58 59 60 61 62 63 64 65 66 67 68 69 70 |
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) * [Limitations of Wapp](/doc/trunk/docs/limitations.md) * [Example Applications](/file/examples) * [Real-World Uses Of Wapp](/doc/trunk/docs/usageexamples.md) * [Debugging Hints](/doc/trunk/docs/debughints.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 |
Wapp - A Web-Application Framework for TCL ========================================== Wapp is a framework for writing web applications in TCL, with the following advantages: * Small and simple API → easy to learn and use * A complete application is contained in a single file of TCL * Resistant to attacks and exploits * Cross-platform → CGI, SCGI, or a built-in web server * The Wapp framework itself is a single-file TCL script * Easy to embedded in a larger application to provide a web-based monitoring capability * The MVC design pattern is supported but not required * 2-clause BSD license Documentation ------------- * ["Hello World!" App (6 lines of code)](/doc/trunk/docs/helloworld.md) * [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) * [Limitations of Wapp](/doc/trunk/docs/limitations.md) * [Example Applications](/file/examples) * [Real-World Uses Of Wapp](/doc/trunk/docs/usageexamples.md) * [Debugging Hints](/doc/trunk/docs/debughints.md) |
Changes to docs/params.md.
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
...
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
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:
|
|
|
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
...
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
|
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 the 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. The following is the same information show in a diagram:
>
http://example.com/cgi-bin/script/method/extra/path?q1=5
\_________/\_____________/\________________/ \__/
| | | |
HTTP_HOST SCRIPT_NAME PATH_INFO `-- QUERY_STRING
>
http://example.com/cgi-bin/script/method/extra/path?q1=5
\_______________________________/ \____/ \________/
| | |
BASE_URL PATH_HEAD PATH_TAIL
>
http://example.com/cgi-bin/script/method/extra/path?q1=5
\______________________________________/
|
SELF_URL
### 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:
|
Changes to docs/quickref.md.
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
..
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
|
|**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|
................................................................................
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
|
>
|
|
|
|
<
<
<
|
|
|
>
>
>
|
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
..
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
|**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|
<a name="cgiparams"></a>
3.0 CGI 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 TLS 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|
................................................................................
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
>
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/urlmapping.md.
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 |
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
|
| | |
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 |
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
|