# `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).