Wapp

Check-in [ca3221ef4e]
Login

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

Overview
Comment:Minor updates to the documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: ca3221ef4e1aa4600c31dc9a72da9f6db7c9f16c7240f730e785ff110ce6d5e5
User & Date: drh 2019-02-16 12:07:45.838
Context
2019-03-04
19:18
Fix the multipart/form-data parser so that it can accept none-file uploads. Add the "fileupload.tcl" example. (check-in: cfa2467c17 user: drh tags: trunk)
2019-02-16
12:07
Minor updates to the documentation. (check-in: ca3221ef4e user: drh tags: trunk)
00:26
Add the -nowait option to the wapp-start proc. (check-in: 102ae00863 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to README.md.
11
12
13
14
15
16
17



18
19
20
21
22
23
24
  *   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
---------------

Here is a minimal web application written using Wapp:







>
>
>







11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
  *   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:
Changes to docs/commands.md.
18
19
20
21
22
23
24
25
26
27


28
29
30
31
32
33
34
of Wapp.  The other interfaces are merely details.

The following is a complete list of the public interface procs in Wapp:

  +  **wapp-start** _ARGLIST_  
     Start up the application.  _ARGLIST_ is typically the value of $::argv,
     though it might be some subset of $::argv if the containing application
     has already processed some command-line parameters for itself.  This
     proc never returns, and so it should be very last command in the application
     script.



  +  **wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  Command and variable substitutions only occur within
     "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and







|
|
|
>
>







18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
of Wapp.  The other interfaces are merely details.

The following is a complete list of the public interface procs in Wapp:

  +  **wapp-start** _ARGLIST_  
     Start up the application.  _ARGLIST_ is typically the value of $::argv,
     though it might be some subset of $::argv if the containing application
     has already processed some command-line parameters for itself.  By default,
     this proc never returns, and so it should be very last command in the
     application script.  To embed Wapp in a larger application, include
     the -nowait option in _ARGLIST_ and this proc will return immediately
     after setting up all necessary file events.

  +  **wapp-subst** _TEXT_  
     This command appends text to the end of reply to an HTTP request.
     The _TEXT_ argument should be enclosed in {...} to prevent substitutions.
     The "wapp-subst" command itself will do all necessary backslash
     substitutions.  Command and variable substitutions only occur within
     "%html(...)", "%url(...)", "%qp(...)", "%string(...)", and
Changes to docs/params.md.
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151

152
153
154
155
156
157
158
159
Parameter values in the original HTTP request may be encoded in various
ways.  Wapp decodes parameter values before returning them to the
application.  Application developers never see the encoded values.
There is never an opportunity to miss a decoding step.

For security reasons, Query and POST parameters are only added to the
Wapp parameter set if the inbound request is from the "same origin" or
if the special "wapp-allow-xorigin-params" interface is called.  
An inbound request is from the same origin if it is in response to 
clicking on a hyperlink or form on a page that was generated by the
same website.
Manually typing in a URL does not constitute the "same origin".  Hence,
in the "env.tcl" example above the "wapp-allow-xorigin-params" interface 
is used so that you can manually extend the URL to add new query parameters.

If query parameters can have side effects, then you should omit the
wapp-allow-xorigin-params call.  Only invoke wapp-allow-xorigin-params
for web pages that only query information.  Do not invoke 
wapp-allow-xorigin-params on pages where the parameters can be used
to change server-side state.

3.0 CGI Parameter Details
-------------------------

The CGI parameters in Wapp describe the HTTP request that is to be answered
and the execution environment.
These parameter look like CGI environment variables.  To prevent environment
information from overlapping and overwriting query parameters, all the
environment information uses upper-case names and all query parameters
are required to be lower case.  If an input URL contains an upper-case
query parameter (or POST parameter or cookie), that parameter is silently
omitted.

The following CGI parameters are available:

  +  **CONTENT\_LENGTH**  
     The number of bytes of POST data.

     This parameter is omitted for non-POST requests.

  +  **CONTENT\_TYPE**  
     The mimetype of the POST data.  Usually this is
     application/x-www-form-urlencoded.
     This parameter is omitted for non-POST requests.

  +  **DOCUMENT\_ROOT**  







|
|



|




|



















>
|







115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
Parameter values in the original HTTP request may be encoded in various
ways.  Wapp decodes parameter values before returning them to the
application.  Application developers never see the encoded values.
There is never an opportunity to miss a decoding step.

For security reasons, Query and POST parameters are only added to the
Wapp parameter set if the inbound request is from the "same origin" or
if the special "wapp-allow-xorigin-params" interface is called.
An inbound request is from the same origin if it is in response to
clicking on a hyperlink or form on a page that was generated by the
same website.
Manually typing in a URL does not constitute the "same origin".  Hence,
in the "env.tcl" example above the "wapp-allow-xorigin-params" interface
is used so that you can manually extend the URL to add new query parameters.

If query parameters can have side effects, then you should omit the
wapp-allow-xorigin-params call.  Only invoke wapp-allow-xorigin-params
for web pages that only query information.  Do not invoke
wapp-allow-xorigin-params on pages where the parameters can be used
to change server-side state.

3.0 CGI Parameter Details
-------------------------

The CGI parameters in Wapp describe the HTTP request that is to be answered
and the execution environment.
These parameter look like CGI environment variables.  To prevent environment
information from overlapping and overwriting query parameters, all the
environment information uses upper-case names and all query parameters
are required to be lower case.  If an input URL contains an upper-case
query parameter (or POST parameter or cookie), that parameter is silently
omitted.

The following CGI parameters are available:

  +  **CONTENT\_LENGTH**  
     The number of bytes of POST data.
     This parameter is either omitted or has a value of "0"
     for non-POST requests.

  +  **CONTENT\_TYPE**  
     The mimetype of the POST data.  Usually this is
     application/x-www-form-urlencoded.
     This parameter is omitted for non-POST requests.

  +  **DOCUMENT\_ROOT**