[ashd.git] / python3 / doc / ashd-wsgi3.doc

ashd-wsgi3(1)
=============

NAME
----
ashd-wsgi3 - WSGI adapter for ashd(7)

SYNOPSIS
--------
*ashd-wsgi3* [*-hAL*] [*-m* 'PDM-SPEC'] [*-p* 'MODPATH'] [*-t* 'HANDLING-MODEL'] 'HANDLER-MODULE' ['ARGS'...]

DESCRIPTION
-----------

The *ashd-wsgi3* handler translates *ashd*(7) requests to WSGI
requests, and passes them to a specified Python handler module. The
precise Python convention for doing so is described in the PROTOCOL
section, below.

*ashd-wsgi3* is a persistent handler, as defined in *ashd*(7). It uses
multithreaded dispatching in a single Python interpreter, which means
that WSGI applications that use it need to be thread-safe, but that
they can also share all Python data structures and global variables
between requests. More precisely, *ashd-wsgi* implements a couple of
slightly different ways to handle requests and threads, which can be
configured using the *-t* option, as described in the REQUEST HANDLING
section, below.

The Python module that *ashd-wsgi3* comes with also contains a
standard handler module, `ashd.wsgidir`, which serves individual WSGI
applications directly from the files in which they reside and as such
makes this program useful as a *dirplex*(1) handler. Please see its
Python documentation for further details.

*ashd-wsgi3* requires the `ashd.proto` and `ashd.util` modules, which
are only available for CPython. If you want to use some other Python
implementation instead, you may want to use the *scgi-wsgi*(1) program
instead, along with *callscgi*(1).

OPTIONS
-------

*-h*::

	Print a brief help message to standard output and exit.

*-A*::

	Use the convention used by Apache's mod_wsgi module to find
	the WSGI application object. See the PROTOCOL section, below,
	for details.

*-L*::
	By default, *ashd-wsgi3* sets up the Python logging with a
	logging format and for logging to standard error. The *-L*
	option suppresses that behavior, so that any handler module
	may set up logging itself.

*-p* 'MODPATH'::

	Prepend 'MODPATH' to Python's `sys.path`; can be given multiple
	times. Note that the working directory of *ashd-wsgi3* is not
	on Python's module path by default, so if you want to use a
	module in that directory, you will need to specify "`-p .`".

*-t* 'HANDLING-MODEL'::

	Specify the way *ashd-wsgi* handles requests. See below, under
	REQUEST HANDLING.

*-m* 'PDM-SPEC'::

	If the PDM library is installed on the system, create a
	listening socket for connecting PDM clients according to
	'PDM-SPEC'.

PROTOCOL
--------

When starting, *ashd-wsgi3* will attempt to import the module named by
'HANDLER-MODULE', look for an object named `wmain` in that module,
call that object passing the 'ARGS' (as Python strings) as positional
parameters, and use the returned object as the WSGI application
object. If the *-A* option was specified, it will look for an object
named `application` instead of `wmain`, and use that object directly
as the WSGI application object.

When calling the WSGI application, a new thread is started for each
request, in which the WSGI application object is called (but see
below, under REQUEST HANDLING, for details). All requests run in the
same interpreter, so it is guaranteed that data structures and global
variables can be shared between requests.

The WSGI environment is the standard CGI environment, including the
`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
included in the request.

REQUEST HANDLING
----------------

*ashd-wsgi3* can be configured to handle requests in various ways,
using the *-t* command-line option. The argument to the *-t* option
takes the form 'HANDLER'[*:*'PAR'[*=*'VAL'][(*,*'PAR'[*=*'VAL'])...]],
in order to specify the handler model, along with parameters to the
same (using the same syntax as the port specifications of
*htparser*(1)). The 'HANDLER' can be any of the following:

*free*[*:max=*'MAX-THREADS'*,timeout=*'TIMEOUT']::

	The *free* handler, which is the default, starts a new thread
	for every incoming request, which runs the whole request in
	its entirety, from running the WSGI handler function to
	sending the contents of the response iterator. Optionally,
	'MAX-THREADS' may be specified to an integer, in which case no
	more than that many request-handler threads will be allowed to
	run at any one time (by default, any number of threads are
	allowed to run, without limit). If further requests come in
	while 'MAX-THREADS' handlers are running, the request dispatch
	thread itself will block until one exits, making new requests
	queue up in the socket over which they arrive, eventually
	filling up its buffers if no threads exit, in turn making the
	parent handler either block or receive *EAGAIN* errors. Also,
	if 'MAX-THREADS' is specified, 'TIMEOUT' may also be
	specified, to tell the dispatcher thread to never block more
	than so many seconds for a handler thread to exit. If it is
	forced to wait longer than 'TIMEOUT' seconds, it will assume
	the whole process is somehow foobar and will *abort*(3).

*rplex*[*:max=*'MAX-THREADS']::

	The *rplex* handler starts a new thread for every incoming
	request, but unlike the *free* handler, only the WSGI handler
	function runs in that thread. Whenever any such thread, then,
	returns its response iterator, all such iterators will be
	passed to a single independent thread which sends their
	contents to the clients, multiplexing between them whenever
	their respective clients are ready to receive data. Like the
	*free* handler, a 'MAX-THREADS' argument may be given to
	specify how many handler threads are allowed to run at the
	same time. The main advantage, compared to the *free* handler,
	is that the *rplex* handler allows an arbitrary number of
	response iterators to run simultaneously without tying up
	handler threads, therefore not counting towards 'MAX-THREADS',
	which may be necessary for applications handling large
	files. However, it must be noted that no response iterators in
	the application may block on returning data, since that would
	also block all other running responses. Also, the *rplex*
	handler does not support the `write` function returned by
	`start_request`, according to the WSGI specification.

*single*::

	The *single* handler starts no threads at all, running all
	received requests directly in the main dispatch thread. It is
	probably not good for much except as the simplest possible
	example of a request handling model.

EXAMPLES
--------

The following *dirplex*(1) configuration can be used for serving WSGI
modules directly from the filesystem.

--------
child wsgidir
  exec ashd-wsgi3 ashd.wsgidir
match
  filename *.wsgi
  xset python-handler chain
  handler wsgidir
--------

Since *ashd-wsgi3* is a persistent handler, it can be used directly as
a root handler for *htparser*(1). For instance, if the directory
`/srv/www/foo` contains a `wsgi.py` file, which declares a standard
WSGI `application` object, it can be served with the following
command:

--------
htparser plain:port=8080 -- ashd-wsgi3 -Ap /srv/www/foo wsgi
--------

AUTHOR
------
Fredrik Tolf <fredrik@dolda2000.com>

SEE ALSO
--------
*scgi-wsgi3*(1), *ashd*(7), <http://wsgi.org/>
Commit	Line	Data
	1	ashd-wsgi3(1)
	2	=============
	3
	4	NAME
	5	----
	6	ashd-wsgi3 - WSGI adapter for ashd(7)
	7
	8	SYNOPSIS
	9	--------
	10	ashd-wsgi3 [-hAL] [-m 'PDM-SPEC'] [-p 'MODPATH'] [-t 'HANDLING-MODEL'] 'HANDLER-MODULE' ['ARGS'...]
	11
	12	DESCRIPTION
	13	-----------
	14
	15	The ashd-wsgi3 handler translates ashd(7) requests to WSGI
	16	requests, and passes them to a specified Python handler module. The
	17	precise Python convention for doing so is described in the PROTOCOL
	18	section, below.
	19
	20	ashd-wsgi3 is a persistent handler, as defined in ashd(7). It uses
	21	multithreaded dispatching in a single Python interpreter, which means
	22	that WSGI applications that use it need to be thread-safe, but that
	23	they can also share all Python data structures and global variables
	24	between requests. More precisely, ashd-wsgi implements a couple of
	25	slightly different ways to handle requests and threads, which can be
	26	configured using the -t option, as described in the REQUEST HANDLING
	27	section, below.
	28
	29	The Python module that ashd-wsgi3 comes with also contains a
	30	standard handler module, `ashd.wsgidir`, which serves individual WSGI
	31	applications directly from the files in which they reside and as such
	32	makes this program useful as a dirplex(1) handler. Please see its
	33	Python documentation for further details.
	34
	35	ashd-wsgi3 requires the `ashd.proto` and `ashd.util` modules, which
	36	are only available for CPython. If you want to use some other Python
	37	implementation instead, you may want to use the scgi-wsgi(1) program
	38	instead, along with callscgi(1).
	39
	40	OPTIONS
	41	-------
	42
	43	-h::
	44
	45	Print a brief help message to standard output and exit.
	46
	47	-A::
	48
	49	Use the convention used by Apache's mod_wsgi module to find
	50	the WSGI application object. See the PROTOCOL section, below,
	51	for details.
	52
	53	-L::
	54	By default, ashd-wsgi3 sets up the Python logging with a
	55	logging format and for logging to standard error. The -L
	56	option suppresses that behavior, so that any handler module
	57	may set up logging itself.
	58
	59	-p 'MODPATH'::
	60
	61	Prepend 'MODPATH' to Python's `sys.path`; can be given multiple
	62	times. Note that the working directory of ashd-wsgi3 is not
	63	on Python's module path by default, so if you want to use a
	64	module in that directory, you will need to specify "`-p .`".
	65
	66	-t 'HANDLING-MODEL'::
	67
	68	Specify the way ashd-wsgi handles requests. See below, under
	69	REQUEST HANDLING.
	70
	71	-m 'PDM-SPEC'::
	72
	73	If the PDM library is installed on the system, create a
	74	listening socket for connecting PDM clients according to
	75	'PDM-SPEC'.
	76
	77	PROTOCOL
	78	--------
	79
	80	When starting, ashd-wsgi3 will attempt to import the module named by
	81	'HANDLER-MODULE', look for an object named `wmain` in that module,
	82	call that object passing the 'ARGS' (as Python strings) as positional
	83	parameters, and use the returned object as the WSGI application
	84	object. If the -A option was specified, it will look for an object
	85	named `application` instead of `wmain`, and use that object directly
	86	as the WSGI application object.
	87
	88	When calling the WSGI application, a new thread is started for each
	89	request, in which the WSGI application object is called (but see
	90	below, under REQUEST HANDLING, for details). All requests run in the
	91	same interpreter, so it is guaranteed that data structures and global
	92	variables can be shared between requests.
	93
	94	The WSGI environment is the standard CGI environment, including the
	95	`SCRIPT_FILENAME` variable whenever the `X-Ash-File` header was
	96	included in the request.
	97
	98	REQUEST HANDLING
	99	----------------
	100
	101	ashd-wsgi3 can be configured to handle requests in various ways,
	102	using the -t command-line option. The argument to the -t option
	103	takes the form 'HANDLER'[:'PAR'[='VAL'][(,'PAR'[='VAL'])...]],
	104	in order to specify the handler model, along with parameters to the
	105	same (using the same syntax as the port specifications of
	106	htparser(1)). The 'HANDLER' can be any of the following:
	107
	108	free[:max='MAX-THREADS',timeout='TIMEOUT']::
	109
	110	The free handler, which is the default, starts a new thread
	111	for every incoming request, which runs the whole request in
	112	its entirety, from running the WSGI handler function to
	113	sending the contents of the response iterator. Optionally,
	114	'MAX-THREADS' may be specified to an integer, in which case no
	115	more than that many request-handler threads will be allowed to
	116	run at any one time (by default, any number of threads are
	117	allowed to run, without limit). If further requests come in
	118	while 'MAX-THREADS' handlers are running, the request dispatch
	119	thread itself will block until one exits, making new requests
	120	queue up in the socket over which they arrive, eventually
	121	filling up its buffers if no threads exit, in turn making the
	122	parent handler either block or receive EAGAIN errors. Also,
	123	if 'MAX-THREADS' is specified, 'TIMEOUT' may also be
	124	specified, to tell the dispatcher thread to never block more
	125	than so many seconds for a handler thread to exit. If it is
	126	forced to wait longer than 'TIMEOUT' seconds, it will assume
	127	the whole process is somehow foobar and will abort(3).
	128
	129	rplex[:max='MAX-THREADS']::
	130
	131	The rplex handler starts a new thread for every incoming
	132	request, but unlike the free handler, only the WSGI handler
	133	function runs in that thread. Whenever any such thread, then,
	134	returns its response iterator, all such iterators will be
	135	passed to a single independent thread which sends their
	136	contents to the clients, multiplexing between them whenever
	137	their respective clients are ready to receive data. Like the
	138	free handler, a 'MAX-THREADS' argument may be given to
	139	specify how many handler threads are allowed to run at the
	140	same time. The main advantage, compared to the free handler,
	141	is that the rplex handler allows an arbitrary number of
	142	response iterators to run simultaneously without tying up
	143	handler threads, therefore not counting towards 'MAX-THREADS',
	144	which may be necessary for applications handling large
	145	files. However, it must be noted that no response iterators in
	146	the application may block on returning data, since that would
	147	also block all other running responses. Also, the rplex
	148	handler does not support the `write` function returned by
	149	`start_request`, according to the WSGI specification.
	150
	151	single::
	152
	153	The single handler starts no threads at all, running all
	154	received requests directly in the main dispatch thread. It is
	155	probably not good for much except as the simplest possible
	156	example of a request handling model.
	157
	158	EXAMPLES
	159	--------
	160
	161	The following dirplex(1) configuration can be used for serving WSGI
	162	modules directly from the filesystem.
	163
	164	--------
	165	child wsgidir
	166	exec ashd-wsgi3 ashd.wsgidir
	167	match
	168	filename *.wsgi
	169	xset python-handler chain
	170	handler wsgidir
	171	--------
	172
	173	Since ashd-wsgi3 is a persistent handler, it can be used directly as
	174	a root handler for htparser(1). For instance, if the directory
	175	`/srv/www/foo` contains a `wsgi.py` file, which declares a standard
	176	WSGI `application` object, it can be served with the following
	177	command:
	178
	179	--------
	180	htparser plain:port=8080 -- ashd-wsgi3 -Ap /srv/www/foo wsgi
	181	--------
	182
	183	AUTHOR
	184	------
	185	Fredrik Tolf <fredrik@dolda2000.com>
	186
	187	SEE ALSO
	188	--------
	189	scgi-wsgi3(1), ashd(7), <http://wsgi.org/>