Project

General

Profile

ModjyWSGI » History » Version 1

Alan Kennedy, 2009-03-15 09:05 PM

1 1 Alan Kennedy
h1. WSGI standards compliance and portability
2
3
h2(#intro). Introduction
4
5
6
Modjy is a WSGI server, so as such it must attempt to comply with the WSGI specification as much as possible. Ideally, this means that it should be possible to take any python WSGI middleware component and run it on modjy without modification. The purpose of this page is list the details of modjy's WSGI compliance, and any considerations which might affect application portability.
7
8
9
10
11
h2(#wsgi_environ). The WSGI environment.
12
13
14
15
h3. WSGI variables
16
17
18
19
Modjy's WSGI environment contains all of the required WSGI environment variables. They are listed here, along with modjy-specific notes where appropriate.
20
21
22
23
|
24
Variable|
25
Description|
26
Modjy Default|
27
Modjy notes|
28
29
|
30
wsgi.version|
31
The version of the WSGI standard with which modjy complies.|
32
=.(1,0)|
33
Modjy is designed against version 1.0 of the WSGI standard.|
34
35
|
36
wsgi.url_scheme|
37
A string representing the *scheme* portion of the URL.|
38
=.e.g. *http* or *https* |
39
 |
40
41
|
42
wsgi.input|
43
The input stream for this request.|
44
The supplied input stream is WSGI-compliant|
45
See below for notes about the "WSGI input stream.":#input_stream|
46
47
|
48
wsgi.errors|
49
The error stream for this request.|
50
An output stream to which applications can write diagnostic output.|
51
See below for notes about the "destination of diagnostic output":#error_stream.|
52
53
|
54
wsgi.multithread|
55
A boolean value indicating whether or not an application object may be called simultaneously from multiple threads.|
56
=.1|
57
The default behaviour of modjy is to call application objects from multiple threads. The *multithread* configuration parameter can be used to force modjy to only call application objects from one thread at a time. Also, if caching of applications is disabled through use of the *cache_callables* parameter, new application objects are created for each new HTTP request and called once only for that request. Therefore, *wsgi.multithread* will also be *false* when *cache_callables* is *false*.|
58
59
|
60
wsgi.multiprocess|
61
A boolean value indicating whether or not similar application objects will be called from multiple operating system processes.|
62
=.0|
63
This value will always be *false* on modjy.|
64
65
|
66
wsgi.run_once|
67
A boolean value indicating if the server expects to call the application object only once. |
68
=.0|
69
Under modjy, this value depends solely on the value of the *cache_callables* parameter. If caching of application objects is disabled, *wsgi.run_once* will be *true*, otherwise it will be *false*.|
70
71
|
72
wsgi.file_wrapper|
73
TBD|
74
=.TBD|
75
TBD|
76
77
78
79
h3. Required CGI environment variables
80
81
82
All of the following variables appear in the WSGI dictionary as *string* values.
83
84
85
|
86
Variable|
87
Description|
88
Example values|
89
Modjy notes|
90
91
|
92
REQUEST_METHOD|
93
The HTTP request method for this request.|
94
=.*GET*, *PUT*, *POST*, etc.|
95
 |
96
97
|
98
SCRIPT_NAME|
99
The initial portion of the request URL's path that corresponds to the application object.|
100
=. |
101
 |
102
103
|
104
PATH_INFO|
105
The remainder of the request URL's path, after the *SCRIPT_NAME* has been subtracted.|
106
=. |
107
 |
108
109
|
110
QUERY_STRING|
111
A string containing the query portion of the URL request.|
112
=."name1=value&name2=value2", etc.|
113
 |
114
115
|
116
CONTENT_TYPE|
117
The mime type of the body content being uploaded for this request.|
118
=."application/octet-stream", etc.|
119
May be the empty string, e.g. if there is no body being uploaded.|
120
121
|
122
CONTENT_LENGTH|
123
The length of the body content being uploaded for this request.|
124
=. |
125
May be the empty string, e.g. if there is no body being uploaded.|
126
127
|
128
SERVER_NAME|
129
The name of the network host on which this request was received.|
130
=."www.myserver.com", etc.|
131
This value is that returned by the HttpServletRequest method getLocalName(), which was introduced in the servlet 2.4 specification. For a discussion of the difference between the getLocalName() and getServerName() methods, see the Sun document "J2EE 1.4 Compatibility Issues":http://docs.sun.com/source/819-0077/J2EE.html and the "CGI specification":http://www.ietf.org/rfc/rfc3875, section 4.1.14.|
132
133
|
134
SERVER_PORT|
135
The number of the network port on which this request was received.|
136
=."8080", "80", etc.|
137
This value is that returned by the HttpServletRequest method getLocalPort(). See the notes above under SERVER_NAME for a discussion.|
138
139
140
141
h3. Optional CGI environment variables.
142
143
144
145
In addition to the CGI variables required by WSGI, modjy also supplies values for the following CGI environment variables, both standard and non-standard.
146
147
148
All of the following variables appear in the WSGI dictionary as *string* values.
149
150
151
|
152
Variable|
153
Description|
154
Example values|
155
Modjy notes|
156
157
|
158
PATH_TRANSLATED|
159
 |
160
=. |
161
 |
162
163
|
164
SERVER_PROTOCOL|
165
The HTTP version in use for this request.|
166
=.*HTTP/1.1*, *HTTP/1.0*, etc.|
167
 |
168
169
|
170
REMOTE_HOST|
171
The host name for the remote machine making this request.|
172
=.machine.domain.com|
173
This value will only be set to a dns name if your J2EE container is configured to do reverse-DNS lookups on request IP addresses. If your container is not so configured, then this will contain the numeric IP address of the remote machine, i.e. this variable will contain the same value as *REMOTE_ADDR*, described below. With Tomcat 6, reverse-dns lookups are configured through the *enableLookups* attribute of *<Connector>* elements, e.g. "HTTP Connectors":http://tomcat.apache.org/tomcat-6.0-doc/config/http.html for standalone Tomcats or "AJP Connectors":http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html if you're hosting your Tomcat inside an Apache server.|
174
175
|
176
REMOTE_ADDR|
177
The IP address of the remote machine making this request.|
178
=."192.168.0.1", "127.0.0.1", etc.|
179
This will contain a string representation of the numeric IP address of the remote machine.|
180
181
|
182
REMOTE_PORT|
183
The TCP port number through which this request was made from the client machine.|
184
=."1234", "2345", etc.|
185
This will contain a string representation of the port number of the socket from the remote machine which provided the request.|
186
187
|
188
HTTPS|
189
A string indicating if the request was received through a secure HTTPS connection.|
190
=.either "on", "off", etc.|
191
 |
192
193
|
194
AUTH_TYPE|
195
A string indicating the type of authentication credentials included in this request.|
196
=."BASIC", "DIGEST", etc.|
197
If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.|
198
199
|
200
REMOTE_USER|
201
A string indicating the login name of the user making this request.|
202
=. |
203
If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.|
204
205
206
207
208
h2(#container_vars). Container specific environment variables.
209
210
211
212
The following is a table of the modjy-specific environment variables that appear in the WSGI environment.
213
214
215
216
|
217
Variable|
218
Description|
219
Value|
220
Notes|
221
222
|
223
modjy.version|
224
The version of modjy currently running.|
225
(0, 22, 3)|
226
The value will always be a 3-tuple, containing the (major, minor, micro) release numbers.|
227
228
|
229
modjy.params.*|
230
The parameters with which this modjy servlet instance was configured. This allows the WSGI application to inspect the configuration of the container.|
231
|
232
For example, the modjy configuration variable *cache_callables* will appear in the WSGI namespace under the name *modjy.params.cache_callables*. The values of each variable/parameter will be the original string from the servlet configuration file.|
233
234
235
236
237
h2(#j2ee_vars). J2EE specific environment variables.
238
239
240
241
As well as setting WSGI environment variables for its own container specific things, modjy also creates environment variables to provide access to the original J2EE objects for a HTTP request and for the modjy servlet. Those variables are listed in the table below.
242
243
244
245
*NB:* The usage of these variables is a breach of the WSGI specification! Reliance on being able to bypass WSGI middleware and access the original request directly will make your application *non-portable*, *possibly broken* and may even cause "middleware meltdown":http://mail.python.org/pipermail/web-sig/2004-October/000935.html!
246
247
248
249
*NB:* These objects and their contents are only guaranteed to be valid for the duration of the current request/response cycle. Should it be desired to retain any information from any of these objects, a copy of the object or its values should be taken, or of corresponding values from the WSGI environment.
250
251
252
253
|
254
Variable|
255
Value|
256
257
|
258
j2ee.request|
259
The "javax.servlet.http.HttpRequest":http://java.sun.com/products/servlet/2.4/javadoc/javax/servlet/http/HttpServletRequest.html object corresponding to this WSGI request.|
260
261
|
262
j2ee.response|
263
The "javax.servlet.http.HttpResponse":http://java.sun.com/products/servlet/2.4/javadoc/javax/servlet/http/HttpServletResponse.html object corresponding to this WSGI request.|
264
265
|
266
j2ee.servlet|
267
The "javax.servlet.http.HttpServlet":http://java.sun.com/products/servlet/2.4/javadoc/javax/servlet/http/HttpServlet.html under which this WSGI request is running, i.e. the modjy servlet.|
268
269
|
270
j2ee.servlet_context|
271
The "javax.servlet.ServletContext":http://java.sun.com/products/servlet/2.4/javadoc/javax/servlet/ServletContext.html object for the j2ee.servlet defined above.|
272
273
|
274
j2ee.servlet_config|
275
The "javax.servlet.ServletConfig":http://java.sun.com/products/servlet/2.4/javadoc/javax/servlet/ServletConfig.html object for the j2ee.servlet defined above.|
276
277
278
279
280
h2(#input_stream). The WSGI input stream.
281
282
283
284
h3. Reading beyond content-length on wsgi.input
285
286
287
According to the WSGI 1.0 specification: ??The server is not required to read past the client's specified Content-Length, and is allowed to simulate an end-of-file condition if the application attempts to read past that point. The application should not attempt to read more data than is specified by the CONTENT_LENGTH variable??.
288
289
Currently, modjy's behaviour in this situation is defined by the J2EE container. This is because the standard J2EE "javax.servlet.ServletInputStream":http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletInputStream.html (on which the modjy wsgi.input is layered) is container-defined, and will thus have container-specific behaviour.
290
291
This means that applications can potentially expect any of the following behaviours, depending on the J2EE container
292
293
294
 # That an exception be raised by the container when more bytes are read than should be.
295
 # That the container insert an EOF file marker when the input-stream reaches the content-length.
296
 # That the reads silently fail?
297
298
In the future, I may implement a wrapper for wsgi.input that provides uniform, and perhaps configurable, behaviour across J2EE containers in this scenario.
299
300
301
h3. 100 Continue
302
303
304
305
TBD.
306
307
308
309
310
h2(#error_stream). Destination of output to wsgi.errors
311
312
313
What happens to diagnostic output is dependent on the configuration of the J2EE servlet container in which modjy is running. Under Tomcat 6, for example, this is configured through the *swallowOutput* attribute of "org.apache.catalina.core.StandardContext":http://tomcat.apache.org/tomcat-6.0-doc/config/context.html objects. A *true* setting for this attribute will cause java *System.err* and *System.out* output, and thus wsgi.errors, to appear in the servlet context log.
314
315
316
317
h2(#bulk_transfers). Bulk transfers of file contents.
318
319
320
321
The WSGI spec describes optional support for bulk file transfers. Modjy currently does not support this feature, but may in the future.