paste.httpserver – HTTP server

WSGI HTTP Server

This is a minimalistic WSGI server using Python’s built-in BaseHTTPServer; if pyOpenSSL is installed, it also provides SSL capabilities.

Module Contents

paste.httpserver.serve(application, host=None, port=None, handler=None, ssl_pem=None, ssl_context=None, server_version=None, protocol_version=None, start_loop=True, daemon_threads=None, socket_timeout=None, use_threadpool=None, threadpool_workers=10, threadpool_options=None, request_queue_size=5)

Serves your application over HTTP(S) via WSGI interface

host

This is the ipaddress to bind to (or a hostname if your nameserver is properly configured). This defaults to 127.0.0.1, which is not a public interface.

port

The port to run on, defaults to 8080 for HTTP, or 4443 for HTTPS. This can be a string or an integer value.

handler

This is the HTTP request handler to use, it defaults to WSGIHandler in this module.

ssl_pem

This an optional SSL certificate file (via OpenSSL). You can supply * and a development-only certificate will be created for you, or you can generate a self-signed test PEM certificate file as follows:

$ openssl genrsa 1024 > host.key
$ chmod 400 host.key
$ openssl req -new -x509 -nodes -sha1 -days 365  \
              -key host.key > host.cert
$ cat host.cert host.key > host.pem
$ chmod 400 host.pem

ssl_context

This an optional SSL context object for the server. A SSL context will be automatically constructed for you if you supply ssl_pem. Supply this to use a context of your own construction.

server_version

The version of the server as reported in HTTP response line. This defaults to something like “PasteWSGIServer/0.5”. Many servers hide their code-base identity with a name like ‘Amnesiac/1.0’

protocol_version

This sets the protocol used by the server, by default HTTP/1.0. There is some support for HTTP/1.1, which defaults to nicer keep-alive connections. This server supports 100 Continue, but does not yet support HTTP/1.1 Chunked Encoding. Hence, if you use HTTP/1.1, you’re somewhat in error since chunked coding is a mandatory requirement of a HTTP/1.1 server. If you specify HTTP/1.1, every response must have a Content-Length and you must be careful not to read past the end of the socket.

start_loop

This specifies if the server loop (aka server.serve_forever()) should be called; it defaults to True.

daemon_threads

This flag specifies if when your webserver terminates all in-progress client connections should be droppped. It defaults to False. You might want to set this to True if you are using HTTP/1.1 and don’t set a socket_timeout.

socket_timeout

This specifies the maximum amount of time that a connection to a given client will be kept open. At this time, it is a rude disconnect, but at a later time it might follow the RFC a bit more closely.

use_threadpool

Server requests from a pool of worker threads (threadpool_workers) rather than creating a new thread for each request. This can substantially reduce latency since there is a high cost associated with thread creation.

threadpool_workers

Number of worker threads to create when use_threadpool is true. This can be a string or an integer value.

threadpool_options

A dictionary of options to be used when instantiating the threadpool. See paste.httpserver.ThreadPool for specific options (threadpool_workers is a specific option that can also go here).

request_queue_size

The ‘backlog’ argument to socket.listen(); specifies the maximum number of queued connections.

paste.httpserver.server_runner(wsgi_app, global_conf, **kwargs)

Serves your application over HTTP(S) via WSGI interface

host

This is the ipaddress to bind to (or a hostname if your nameserver is properly configured). This defaults to 127.0.0.1, which is not a public interface.

port

The port to run on, defaults to 8080 for HTTP, or 4443 for HTTPS. This can be a string or an integer value.

handler

This is the HTTP request handler to use, it defaults to WSGIHandler in this module.

ssl_pem

This an optional SSL certificate file (via OpenSSL). You can supply * and a development-only certificate will be created for you, or you can generate a self-signed test PEM certificate file as follows:

$ openssl genrsa 1024 > host.key
$ chmod 400 host.key
$ openssl req -new -x509 -nodes -sha1 -days 365  \
              -key host.key > host.cert
$ cat host.cert host.key > host.pem
$ chmod 400 host.pem

ssl_context

This an optional SSL context object for the server. A SSL context will be automatically constructed for you if you supply ssl_pem. Supply this to use a context of your own construction.

server_version

The version of the server as reported in HTTP response line. This defaults to something like “PasteWSGIServer/0.5”. Many servers hide their code-base identity with a name like ‘Amnesiac/1.0’

protocol_version

This sets the protocol used by the server, by default HTTP/1.0. There is some support for HTTP/1.1, which defaults to nicer keep-alive connections. This server supports 100 Continue, but does not yet support HTTP/1.1 Chunked Encoding. Hence, if you use HTTP/1.1, you’re somewhat in error since chunked coding is a mandatory requirement of a HTTP/1.1 server. If you specify HTTP/1.1, every response must have a Content-Length and you must be careful not to read past the end of the socket.

start_loop

This specifies if the server loop (aka server.serve_forever()) should be called; it defaults to True.

daemon_threads

This flag specifies if when your webserver terminates all in-progress client connections should be droppped. It defaults to False. You might want to set this to True if you are using HTTP/1.1 and don’t set a socket_timeout.

socket_timeout

This specifies the maximum amount of time that a connection to a given client will be kept open. At this time, it is a rude disconnect, but at a later time it might follow the RFC a bit more closely.

use_threadpool

Server requests from a pool of worker threads (threadpool_workers) rather than creating a new thread for each request. This can substantially reduce latency since there is a high cost associated with thread creation.

threadpool_workers

Number of worker threads to create when use_threadpool is true. This can be a string or an integer value.

threadpool_options

A dictionary of options to be used when instantiating the threadpool. See paste.httpserver.ThreadPool for specific options (threadpool_workers is a specific option that can also go here).

request_queue_size

The ‘backlog’ argument to socket.listen(); specifies the maximum number of queued connections.

You can also set these threadpool options:

threadpool_max_requests:

The maximum number of requests a worker thread will process before dying (and replacing itself with a new worker thread). Default 100.

threadpool_hung_thread_limit:

The number of seconds a thread can work on a task before it is considered hung (stuck). Default 30 seconds.

threadpool_kill_thread_limit:

The number of seconds a thread can work before you should kill it (assuming it will never finish). Default 600 seconds (10 minutes).

threadpool_dying_limit:

The length of time after killing a thread that it should actually disappear. If it lives longer than this, it is considered a “zombie”. Note that even in easy situations killing a thread can be very slow. Default 300 seconds (5 minutes).

threadpool_spawn_if_under:

If there are no idle threads and a request comes in, and there are less than this number of busy threads, then add workers to the pool. Busy threads are threads that have taken less than threadpool_hung_thread_limit seconds so far. So if you get lots of requests but they complete in a reasonable amount of time, the requests will simply queue up (adding more threads probably wouldn’t speed them up). But if you have lots of hung threads and one more request comes in, this will add workers to handle it. Default 5.

threadpool_max_zombie_threads_before_die:

If there are more zombies than this, just kill the process. This is only good if you have a monitor that will automatically restart the server. This can clean up the mess. Default 0 (disabled).

threadpool_hung_check_period`:

Every X requests, check for hung threads that need to be killed, or for zombie threads that should cause a restart. Default 100 requests.

threadpool_logger:

Logging messages will go the logger named here.

threadpool_error_email (or global error_email setting):

When threads are killed or the process restarted, this email address will be contacted (using an SMTP server on localhost).