Pyjo.Server.Hot - Production web server with hot deployment

from Pyjo.Server.Hot import Hot

hot = Hot()
hot.run('/home/sri/myapp.py')

# Or import the module, as in Google Python Style Guide

import Pyjo.Server.Hot

hot = Pyjo.Server.Hot.new()
hot.run('/home/sri/myapp.py')

Pyjo.Server.Hot is a full featured, UNIX optimized, pre-forking non-blocking I/O HTTP and WebSocket server, built around the very well tested and reliable Pyjo.Server.Prefork, with IPv6, TLS, SNI, UNIX domain socket, Comet (long polling), keep-alive, multiple event loop and hot deployment support that just works. Note that the server uses signals for process management, so you should avoid modifying signal handlers in your applications.

To start applications with it you can use the pyjo-hot script, or python -m Pyjo.Server.Hot, which listens on port 8080, automatically daemonizes the server process and defaults to production mode for Pyjoyment applications.

$ pyjo-hot ./myapp.py

You can run the same command again for automatic hot deployment.

$ pyjo-hot ./myapp.py
Starting hot deployment for Hot server 31841.

This second invocation will load the application again, detect the process id file with it, and send a HUP signal to the already running server.

The server runs the command line of its process again, sys.orig_argv, for a clean start and for the new manager of a hot deployment, and the workers are forks of the manager, made with os.fork(), so it runs where os.fork() exists, not on Windows. Name resolution in a thread, SOCKS5 and TLS support can be disabled with the PYJO_NO_NNR, PYJO_NO_SOCKS and PYJO_NO_TLS environment variables.

Manager signals

The Pyjo.Server.Hot manager process can be controlled at runtime with the following signals.

INT, TERM

Shut down server gracefully. The manager and the workers close the listen sockets, so that a new connection is refused, and the workers finish the accepted ones; after a hot deployment, the new manager keeps the sockets that it has inherited open. A second INT, as of Ctrl-C pressed twice, shuts it down immediately, a second TERM does nothing.

QUIT

Shut down server immediately.

TTIN

Increase worker pool by one.

TTOU

Decrease worker pool by one.

HUP

Attempt zero downtime software upgrade (hot deployment) without losing any incoming connections.

Manager (old)
|- Worker [1]
|- Worker [2]
|- Worker [3]
|- Worker [4]
+- Manager (new)
   |- Worker [1]
   |- Worker [2]
   |- Worker [3]
   +- Worker [4]

The new manager will automatically send a TERM signal to the old manager and take over serving requests after starting up successfully.

Worker signals

Pyjo.Server.Hot worker processes can be controlled at runtime with the following signals.

TERM

Stop worker gracefully, with its copies of the listen sockets closed.

QUIT

Stop worker immediately.

Settings

Pyjo.Server.Hot can be configured with the following settings, in the hot key of the configuration of the application.

app.config(hot={'listen': ['http://*:80'], 'workers': 10})

accepts

'accepts': 100

Maximum number of connections a worker is allowed to accept, before stopping gracefully and then getting replaced with a newly started worker, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.accepts. Setting the value to 0 will allow workers to accept new connections indefinitely. Note that up to half of this value can be subtracted randomly to improve load balancing, and to make sure that not all workers restart at the same time.

backlog

'backlog': 128

Listen backlog size, defaults to the value of Pyjo.Server.Daemon.Pyjo_Server_Daemon.backlog.

clients

'clients': 100

Maximum number of accepted connections each worker process is allowed to handle concurrently, before stopping to accept new incoming connections, defaults to the value of Pyjo.IOLoop.Pyjo_IOLoop.max_connections. Note that high concurrency works best with applications that perform mostly non-blocking operations, to optimize for blocking operations you can decrease this value and increase workers instead for better performance.

graceful_timeout

'graceful_timeout': 15

Maximum amount of time in seconds stopping a worker gracefully may take before being forced, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.graceful_timeout. Note that this value should usually be a little larger than the maximum amount of time you expect any one request to take.

heartbeat_interval

'heartbeat_interval': 3

Heartbeat interval in seconds, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.heartbeat_interval.

heartbeat_timeout

'heartbeat_timeout': 2

Maximum amount of time in seconds before a worker without a heartbeat will be stopped gracefully, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.heartbeat_timeout. Note that this value should usually be a little larger than the maximum amount of time you expect any one operation to block the event loop.

inactivity_timeout

'inactivity_timeout': 10

Maximum amount of time in seconds a connection with an active request can be inactive before getting closed, defaults to the value of Pyjo.Server.Daemon.Pyjo_Server_Daemon.inactivity_timeout. Setting the value to 0 will allow connections to be inactive indefinitely.

keep_alive_timeout

'keep_alive_timeout': 10

Maximum amount of time in seconds a connection without an active request can be inactive before getting closed, defaults to the value of Pyjo.Server.Daemon.Pyjo_Server_Daemon.keep_alive_timeout. Setting the value to 0 will allow connections to be inactive indefinitely.

listen

'listen': ['http://*:80']

List with one or more locations to listen on, defaults to http://*:8080. See also Pyjo.Server.Daemon.Pyjo_Server_Daemon.listen for more examples.

pid_file

'pid_file': '/var/run/hot.pid'

Full path to process id file, defaults to hot.pid in the same directory as the application. Note that this value can only be changed after the server has been stopped.

proxy

'proxy': True

Activate reverse proxy support, which allows for the X-Forwarded-For and X-Forwarded-Proto headers to be picked up automatically, defaults to the value of Pyjo.Server.Pyjo_Server.reverse_proxy.

requests

'requests': 50

Number of keep-alive requests per connection, defaults to the value of Pyjo.Server.Daemon.Pyjo_Server_Daemon.max_requests.

spare

'spare': 4

Temporarily spawn up to this number of additional workers if there is a need, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.spare. This allows for new workers to be started while old ones are still shutting down gracefully, drastically reducing the performance cost of worker restarts.

threads

'threads': True

Run the workers as threads of a Pyjo.Server.Prethread in the place of the processes of Pyjo.Server.Prefork, as the option --threads of pyjo-hot does, which sets the PYJO_HOT_THREADS environment variable, defaults to a false value. The server, its manager and the hot deployment are the same.

trusted_proxies

'trusted_proxies': ['10.0.0.0/8', '127.0.0.1', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7']

Trusted reverse proxies, addresses or networks in CIDR form.

upgrade_timeout

'upgrade_timeout': 45

Maximum amount of time in seconds a zero downtime software upgrade may take before getting canceled, defaults to 180.

workers

'workers': 10

Number of worker processes, defaults to the value of Pyjo.Server.Prefork.Pyjo_Server_Prefork.workers. A good rule of thumb is two worker processes per CPU core for applications that perform mostly non-blocking operations, blocking operations often require more and benefit from decreasing concurrency with clients (often as low as 1). Note that during zero downtime software upgrades there will be twice as many workers active for a short amount of time.

pyjo-hot

Usage: pyjo-hot [OPTIONS] [APPLICATION]

  pyjo-hot ./myapp.py
  pyjo-hot -f ./myapp.py

Options:
  -f, --foreground   Keep manager process in foreground
  -h, --help         Show this message
  -s, --stop         Stop server gracefully
  -t, --test         Test application and exit
      --threads      Run the workers as threads

Start Pyjoyment applications with the Pyjo.Server.Hot web server.

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::Server::Hypnotoad and script/hypnotoad of Mojolicious 9.49.

Classes

class Pyjo.Server.Hot.Pyjo_Server_Hot(*, prefork: Pyjo_Server_Prefork | None = None, upgrade_timeout: float = 180)[source]

Pyjo.Server.Hot inherits all methods from Pyjo.Base and implements the following new ones.

configure(name: str) → None[source]
hot.configure('hot')

Configure server from application settings.

property prefork: Pyjo_Server_Prefork[source]
prefork = hot.prefork
hot.prefork = Pyjo.Server.Prefork.new()

Pyjo.Server.Prefork object this server manages.

run(app: str | PathLike[str]) → None[source]
hot.run('myapp.py')

Run server for application and wait for the manager signals.

upgrade_timeout
timeout = hot.upgrade_timeout
hot.upgrade_timeout = 15

Maximum amount of time in seconds a zero downtime software upgrade may take before getting canceled, defaults to 180.

Pyjo.Server.Hot.main(argv: Sequence[str] | None = None) → None[source]
main(['-f', 'myapp.py'])

The command line interface of pyjo-hot: parse the options and run the server for the application.