WSGI standards compliance and portability

Introduction

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.

The WSGI environment.

WSGI variables

Modjy's WSGI environment contains all of the required WSGI environment variables. They are listed here, along with modjy-specific notes where appropriate.

Variable Description Modjy Default Modjy notes
wsgi.version The version of the WSGI standard with which modjy complies. (1,0) Modjy is designed against version 1.0 of the WSGI standard.
wsgi.url_scheme A string representing the scheme portion of the URL. e.g. http or https  
wsgi.input The input stream for this request. The supplied input stream is WSGI-compliant See below for notes about the "WSGI input stream.":#input_stream
wsgi.errors The error stream for this request. An output stream to which applications can write diagnostic output. See below for notes about the "destination of diagnostic output":#error_stream.
wsgi.multithread A boolean value indicating whether or not an application object may be called simultaneously from multiple threads. 1 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.
wsgi.multiprocess A boolean value indicating whether or not similar application objects will be called from multiple operating system processes. 0 This value will always be false on modjy.
wsgi.run_once A boolean value indicating if the server expects to call the application object only once. 0 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.
wsgi.file_wrapper TBD TBD TBD

Required CGI environment variables

All of the following variables appear in the WSGI dictionary as string values.

Variable Description Example values Modjy notes
REQUEST_METHOD The HTTP request method for this request. GET, PUT, POST, etc.  
SCRIPT_NAME The initial portion of the request URL's path that corresponds to the application object.    
PATH_INFO The remainder of the request URL's path, after the SCRIPT_NAME has been subtracted.    
QUERY_STRING A string containing the query portion of the URL request. "name1=value&name2=value2", etc.  
CONTENT_TYPE The mime type of the body content being uploaded for this request. "application/octet-stream", etc. May be the empty string, e.g. if there is no body being uploaded.
CONTENT_LENGTH The length of the body content being uploaded for this request.   May be the empty string, e.g. if there is no body being uploaded.
SERVER_NAME The name of the network host on which this request was received. "www.myserver.com", etc. 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 and the CGI specification, section 4.1.14.
SERVER_PORT The number of the network port on which this request was received. "8080", "80", etc. This value is that returned by the HttpServletRequest method getLocalPort(). See the notes above under SERVER_NAME for a discussion.

Optional CGI environment variables.

In addition to the CGI variables required by WSGI, modjy also supplies values for the following CGI environment variables, both standard and non-standard.

All of the following variables appear in the WSGI dictionary as string values.

Variable Description Example values Modjy notes
PATH_TRANSLATED      
SERVER_PROTOCOL The HTTP version in use for this request. HTTP/1.1, HTTP/1.0, etc.  
REMOTE_HOST The host name for the remote machine making this request. machine.domain.com 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 for standalone Tomcats or AJP Connectors if you're hosting your Tomcat inside an Apache server.
REMOTE_ADDR The IP address of the remote machine making this request. "192.168.0.1", "127.0.0.1", etc. This will contain a string representation of the numeric IP address of the remote machine.
REMOTE_PORT The TCP port number through which this request was made from the client machine. "1234", "2345", etc. This will contain a string representation of the port number of the socket from the remote machine which provided the request.
HTTPS A string indicating if the request was received through a secure HTTPS connection. either "on", "off", etc.  
AUTH_TYPE A string indicating the type of authentication credentials included in this request. "BASIC", "DIGEST", etc. If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.
REMOTE_USER A string indicating the login name of the user making this request.   If there was no authentication information supplied with this request, this variable will not appear in the WSGI environment.

Container specific environment variables.

The following is a table of the modjy-specific environment variables that appear in the WSGI environment.

Variable Description Value Notes
modjy.version The version of modjy currently running. (0, 25, 4) The value will always be a 3-tuple, containing the (major, minor, micro) release numbers.
modjy.params.* The parameters with which this modjy servlet instance was configured. This allows the WSGI application to inspect the configuration of the container.

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

J2EE specific environment variables.

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.

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!

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.

Variable Value
j2ee.request The javax.servlet.http.HttpRequest object corresponding to this WSGI request.
j2ee.response The javax.servlet.http.HttpResponse object corresponding to this WSGI request.
j2ee.servlet The javax.servlet.http.HttpServlet under which this WSGI request is running, i.e. the modjy servlet.
j2ee.servlet_context The javax.servlet.ServletContext object for the j2ee.servlet defined above.
j2ee.servlet_config The javax.servlet.ServletConfig object for the j2ee.servlet defined above.

The WSGI input stream.

Reading beyond content-length on wsgi.input

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.

Currently, modjy's behaviour in this situation is defined by the J2EE container. This is because the standard J2EE javax.servlet.ServletInputStream (on which the modjy wsgi.input is layered) is container-defined, and will thus have container-specific behaviour.

This means that applications can potentially expect any of the following behaviours, depending on the J2EE container

  1. That an exception be raised by the container when more bytes are read than should be.
  2. That the container insert an EOF file marker when the input-stream reaches the content-length.
  3. That the reads silently fail?

In the future, I may implement a wrapper for wsgi.input that provides uniform, and perhaps configurable, behaviour across J2EE containers in this scenario.

100 Continue

TBD.

Destination of output to wsgi.errors

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

Bulk transfers of file contents.

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)