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 1 Alan Kennedy
3 1 Alan Kennedy
h2(#intro). Introduction
4 1 Alan Kennedy
5 1 Alan Kennedy
6 1 Alan Kennedy
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 1 Alan Kennedy
8 1 Alan Kennedy
9 1 Alan Kennedy
10 1 Alan Kennedy
11 1 Alan Kennedy
h2(#wsgi_environ). The WSGI environment.
12 1 Alan Kennedy
13 1 Alan Kennedy
14 1 Alan Kennedy
15 1 Alan Kennedy
h3. WSGI variables
16 1 Alan Kennedy
17 1 Alan Kennedy
18 1 Alan Kennedy
19 1 Alan Kennedy
Modjy's WSGI environment contains all of the required WSGI environment variables. They are listed here, along with modjy-specific notes where appropriate.
20 1 Alan Kennedy
21 1 Alan Kennedy
22 1 Alan Kennedy
23 1 Alan Kennedy
|
24 1 Alan Kennedy
Variable|
25 1 Alan Kennedy
Description|
26 1 Alan Kennedy
Modjy Default|
27 1 Alan Kennedy
Modjy notes|
28 1 Alan Kennedy
29 1 Alan Kennedy
|
30 1 Alan Kennedy
wsgi.version|
31 1 Alan Kennedy
The version of the WSGI standard with which modjy complies.|
32 1 Alan Kennedy
=.(1,0)|
33 1 Alan Kennedy
Modjy is designed against version 1.0 of the WSGI standard.|
34 1 Alan Kennedy
35 1 Alan Kennedy
|
36 1 Alan Kennedy
wsgi.url_scheme|
37 1 Alan Kennedy
A string representing the *scheme* portion of the URL.|
38 1 Alan Kennedy
=.e.g. *http* or *https* |
39 1 Alan Kennedy
 |
40 1 Alan Kennedy
41 1 Alan Kennedy
|
42 1 Alan Kennedy
wsgi.input|
43 1 Alan Kennedy
The input stream for this request.|
44 1 Alan Kennedy
The supplied input stream is WSGI-compliant|
45 1 Alan Kennedy
See below for notes about the "WSGI input stream.":#input_stream|
46 1 Alan Kennedy
47 1 Alan Kennedy
|
48 1 Alan Kennedy
wsgi.errors|
49 1 Alan Kennedy
The error stream for this request.|
50 1 Alan Kennedy
An output stream to which applications can write diagnostic output.|
51 1 Alan Kennedy
See below for notes about the "destination of diagnostic output":#error_stream.|
52 1 Alan Kennedy
53 1 Alan Kennedy
|
54 1 Alan Kennedy
wsgi.multithread|
55 1 Alan Kennedy
A boolean value indicating whether or not an application object may be called simultaneously from multiple threads.|
56 1 Alan Kennedy
=.1|
57 1 Alan Kennedy
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 1 Alan Kennedy
59 1 Alan Kennedy
|
60 1 Alan Kennedy
wsgi.multiprocess|
61 1 Alan Kennedy
A boolean value indicating whether or not similar application objects will be called from multiple operating system processes.|
62 1 Alan Kennedy
=.0|
63 1 Alan Kennedy
This value will always be *false* on modjy.|
64 1 Alan Kennedy
65 1 Alan Kennedy
|
66 1 Alan Kennedy
wsgi.run_once|
67 1 Alan Kennedy
A boolean value indicating if the server expects to call the application object only once. |
68 1 Alan Kennedy
=.0|
69 1 Alan Kennedy
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 1 Alan Kennedy
71 1 Alan Kennedy
|
72 1 Alan Kennedy
wsgi.file_wrapper|
73 1 Alan Kennedy
TBD|
74 1 Alan Kennedy
=.TBD|
75 1 Alan Kennedy
TBD|
76 1 Alan Kennedy
77 1 Alan Kennedy
78 1 Alan Kennedy
79 1 Alan Kennedy
h3. Required CGI environment variables
80 1 Alan Kennedy
81 1 Alan Kennedy
82 1 Alan Kennedy
All of the following variables appear in the WSGI dictionary as *string* values.
83 1 Alan Kennedy
84 1 Alan Kennedy
85 1 Alan Kennedy
|
86 1 Alan Kennedy
Variable|
87 1 Alan Kennedy
Description|
88 1 Alan Kennedy
Example values|
89 1 Alan Kennedy
Modjy notes|
90 1 Alan Kennedy
91 1 Alan Kennedy
|
92 1 Alan Kennedy
REQUEST_METHOD|
93 1 Alan Kennedy
The HTTP request method for this request.|
94 1 Alan Kennedy
=.*GET*, *PUT*, *POST*, etc.|
95 1 Alan Kennedy
 |
96 1 Alan Kennedy
97 1 Alan Kennedy
|
98 1 Alan Kennedy
SCRIPT_NAME|
99 1 Alan Kennedy
The initial portion of the request URL's path that corresponds to the application object.|
100 1 Alan Kennedy
=. |
101 1 Alan Kennedy
 |
102 1 Alan Kennedy
103 1 Alan Kennedy
|
104 1 Alan Kennedy
PATH_INFO|
105 1 Alan Kennedy
The remainder of the request URL's path, after the *SCRIPT_NAME* has been subtracted.|
106 1 Alan Kennedy
=. |
107 1 Alan Kennedy
 |
108 1 Alan Kennedy
109 1 Alan Kennedy
|
110 1 Alan Kennedy
QUERY_STRING|
111 1 Alan Kennedy
A string containing the query portion of the URL request.|
112 1 Alan Kennedy
=."name1=value&name2=value2", etc.|
113 1 Alan Kennedy
 |
114 1 Alan Kennedy
115 1 Alan Kennedy
|
116 1 Alan Kennedy
CONTENT_TYPE|
117 1 Alan Kennedy
The mime type of the body content being uploaded for this request.|
118 1 Alan Kennedy
=."application/octet-stream", etc.|
119 1 Alan Kennedy
May be the empty string, e.g. if there is no body being uploaded.|
120 1 Alan Kennedy
121 1 Alan Kennedy
|
122 1 Alan Kennedy
CONTENT_LENGTH|
123 1 Alan Kennedy
The length of the body content being uploaded for this request.|
124 1 Alan Kennedy
=. |
125 1 Alan Kennedy
May be the empty string, e.g. if there is no body being uploaded.|
126 1 Alan Kennedy
127 1 Alan Kennedy
|
128 1 Alan Kennedy
SERVER_NAME|
129 1 Alan Kennedy
The name of the network host on which this request was received.|
130 1 Alan Kennedy
=."www.myserver.com", etc.|
131 1 Alan Kennedy
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 1 Alan Kennedy
133 1 Alan Kennedy
|
134 1 Alan Kennedy
SERVER_PORT|
135 1 Alan Kennedy
The number of the network port on which this request was received.|
136 1 Alan Kennedy
=."8080", "80", etc.|
137 1 Alan Kennedy
This value is that returned by the HttpServletRequest method getLocalPort(). See the notes above under SERVER_NAME for a discussion.|
138 1 Alan Kennedy
139 1 Alan Kennedy
140 1 Alan Kennedy
141 1 Alan Kennedy
h3. Optional CGI environment variables.
142 1 Alan Kennedy
143 1 Alan Kennedy
144 1 Alan Kennedy
145 1 Alan Kennedy
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 1 Alan Kennedy
147 1 Alan Kennedy
148 1 Alan Kennedy
All of the following variables appear in the WSGI dictionary as *string* values.
149 1 Alan Kennedy
150 1 Alan Kennedy
151 1 Alan Kennedy
|
152 1 Alan Kennedy
Variable|
153 1 Alan Kennedy
Description|
154 1 Alan Kennedy
Example values|
155 1 Alan Kennedy
Modjy notes|
156 1 Alan Kennedy
157 1 Alan Kennedy
|
158 1 Alan Kennedy
PATH_TRANSLATED|
159 1 Alan Kennedy
 |
160 1 Alan Kennedy
=. |
161 1 Alan Kennedy
 |
162 1 Alan Kennedy
163 1 Alan Kennedy
|
164 1 Alan Kennedy
SERVER_PROTOCOL|
165 1 Alan Kennedy
The HTTP version in use for this request.|
166 1 Alan Kennedy
=.*HTTP/1.1*, *HTTP/1.0*, etc.|
167 1 Alan Kennedy
 |
168 1 Alan Kennedy
169 1 Alan Kennedy
|
170 1 Alan Kennedy
REMOTE_HOST|
171 1 Alan Kennedy
The host name for the remote machine making this request.|
172 1 Alan Kennedy
=.machine.domain.com|
173 1 Alan Kennedy
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 1 Alan Kennedy
175 1 Alan Kennedy
|
176 1 Alan Kennedy
REMOTE_ADDR|
177 1 Alan Kennedy
The IP address of the remote machine making this request.|
178 1 Alan Kennedy
=."192.168.0.1", "127.0.0.1", etc.|
179 1 Alan Kennedy
This will contain a string representation of the numeric IP address of the remote machine.|
180 1 Alan Kennedy
181 1 Alan Kennedy
|
182 1 Alan Kennedy
REMOTE_PORT|
183 1 Alan Kennedy
The TCP port number through which this request was made from the client machine.|
184 1 Alan Kennedy
=."1234", "2345", etc.|
185 1 Alan Kennedy
This will contain a string representation of the port number of the socket from the remote machine which provided the request.|
186 1 Alan Kennedy
187 1 Alan Kennedy
|
188 1 Alan Kennedy
HTTPS|
189 1 Alan Kennedy
A string indicating if the request was received through a secure HTTPS connection.|
190 1 Alan Kennedy
=.either "on", "off", etc.|
191 1 Alan Kennedy
 |
192 1 Alan Kennedy
193 1 Alan Kennedy
|
194 1 Alan Kennedy
AUTH_TYPE|
195 1 Alan Kennedy
A string indicating the type of authentication credentials included in this request.|
196 1 Alan Kennedy
=."BASIC", "DIGEST", etc.|
197 1 Alan Kennedy
If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.|
198 1 Alan Kennedy
199 1 Alan Kennedy
|
200 1 Alan Kennedy
REMOTE_USER|
201 1 Alan Kennedy
A string indicating the login name of the user making this request.|
202 1 Alan Kennedy
=. |
203 1 Alan Kennedy
If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.|
204 1 Alan Kennedy
205 1 Alan Kennedy
206 1 Alan Kennedy
207 1 Alan Kennedy
208 1 Alan Kennedy
h2(#container_vars). Container specific environment variables.
209 1 Alan Kennedy
210 1 Alan Kennedy
211 1 Alan Kennedy
212 1 Alan Kennedy
The following is a table of the modjy-specific environment variables that appear in the WSGI environment.
213 1 Alan Kennedy
214 1 Alan Kennedy
215 1 Alan Kennedy
216 1 Alan Kennedy
|
217 1 Alan Kennedy
Variable|
218 1 Alan Kennedy
Description|
219 1 Alan Kennedy
Value|
220 1 Alan Kennedy
Notes|
221 1 Alan Kennedy
222 1 Alan Kennedy
|
223 1 Alan Kennedy
modjy.version|
224 1 Alan Kennedy
The version of modjy currently running.|
225 1 Alan Kennedy
(0, 22, 3)|
226 1 Alan Kennedy
The value will always be a 3-tuple, containing the (major, minor, micro) release numbers.|
227 1 Alan Kennedy
228 1 Alan Kennedy
|
229 1 Alan Kennedy
modjy.params.*|
230 1 Alan Kennedy
The parameters with which this modjy servlet instance was configured. This allows the WSGI application to inspect the configuration of the container.|
231 1 Alan Kennedy
|
232 1 Alan Kennedy
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 1 Alan Kennedy
234 1 Alan Kennedy
235 1 Alan Kennedy
236 1 Alan Kennedy
237 1 Alan Kennedy
h2(#j2ee_vars). J2EE specific environment variables.
238 1 Alan Kennedy
239 1 Alan Kennedy
240 1 Alan Kennedy
241 1 Alan Kennedy
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 1 Alan Kennedy
243 1 Alan Kennedy
244 1 Alan Kennedy
245 1 Alan Kennedy
*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 1 Alan Kennedy
247 1 Alan Kennedy
248 1 Alan Kennedy
249 1 Alan Kennedy
*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 1 Alan Kennedy
251 1 Alan Kennedy
252 1 Alan Kennedy
253 1 Alan Kennedy
|
254 1 Alan Kennedy
Variable|
255 1 Alan Kennedy
Value|
256 1 Alan Kennedy
257 1 Alan Kennedy
|
258 1 Alan Kennedy
j2ee.request|
259 1 Alan Kennedy
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 1 Alan Kennedy
261 1 Alan Kennedy
|
262 1 Alan Kennedy
j2ee.response|
263 1 Alan Kennedy
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 1 Alan Kennedy
265 1 Alan Kennedy
|
266 1 Alan Kennedy
j2ee.servlet|
267 1 Alan Kennedy
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 1 Alan Kennedy
269 1 Alan Kennedy
|
270 1 Alan Kennedy
j2ee.servlet_context|
271 1 Alan Kennedy
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 1 Alan Kennedy
273 1 Alan Kennedy
|
274 1 Alan Kennedy
j2ee.servlet_config|
275 1 Alan Kennedy
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 1 Alan Kennedy
277 1 Alan Kennedy
278 1 Alan Kennedy
279 1 Alan Kennedy
280 1 Alan Kennedy
h2(#input_stream). The WSGI input stream.
281 1 Alan Kennedy
282 1 Alan Kennedy
283 1 Alan Kennedy
284 1 Alan Kennedy
h3. Reading beyond content-length on wsgi.input
285 1 Alan Kennedy
286 1 Alan Kennedy
287 1 Alan Kennedy
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 1 Alan Kennedy
289 1 Alan Kennedy
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 1 Alan Kennedy
291 1 Alan Kennedy
This means that applications can potentially expect any of the following behaviours, depending on the J2EE container
292 1 Alan Kennedy
293 1 Alan Kennedy
294 1 Alan Kennedy
 # That an exception be raised by the container when more bytes are read than should be.
295 1 Alan Kennedy
 # That the container insert an EOF file marker when the input-stream reaches the content-length.
296 1 Alan Kennedy
 # That the reads silently fail?
297 1 Alan Kennedy
298 1 Alan Kennedy
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 1 Alan Kennedy
300 1 Alan Kennedy
301 1 Alan Kennedy
h3. 100 Continue
302 1 Alan Kennedy
303 1 Alan Kennedy
304 1 Alan Kennedy
305 1 Alan Kennedy
TBD.
306 1 Alan Kennedy
307 1 Alan Kennedy
308 1 Alan Kennedy
309 1 Alan Kennedy
310 1 Alan Kennedy
h2(#error_stream). Destination of output to wsgi.errors
311 1 Alan Kennedy
312 1 Alan Kennedy
313 1 Alan Kennedy
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 1 Alan Kennedy
315 1 Alan Kennedy
316 1 Alan Kennedy
317 1 Alan Kennedy
h2(#bulk_transfers). Bulk transfers of file contents.
318 1 Alan Kennedy
319 1 Alan Kennedy
320 1 Alan Kennedy
321 1 Alan Kennedy
The WSGI spec describes optional support for bulk file transfers. Modjy currently does not support this feature, but may in the future.
Add picture from clipboard (Maximum size: 10 MB)