Configuring HTTP/2 in uWSGI: Performance Trade-offs and Implementation

The HTTP/2 Decision: When to Move Beyond HTTP/1.1

The primary problem when scaling a uWSGI-backed application is the "head-of-line blocking" inherent to HTTP/1.1, where a single slow request can stall subsequent requests on the same TCP connection. While HTTP/2 solves this through multiplexing—allowing multiple requests and responses to be interleaved over one connection—it introduces specific architectural constraints regarding TLS and CPU overhead.

The key takeaway is that uWSGI should only handle HTTP/2 directly if it is also managing the TLS termination. If you use a reverse proxy (like Nginx or HAProxy) to handle SSL/TLS, the proxy should manage the HTTP/2 connection with the client, while communicating with uWSGI via the faster, binary uwsgi protocol or HTTP/1.1.

Comparing uWSGI Connection Strategies

Strategy	Configuration	Best Use Case	Primary Trade-off
Direct HTTP/1.1	--http	Internal services, simple APIs	High latency for multi-asset pages
Direct HTTP/2	--http2	Standalone apps, low-proxy environments	Increased CPU/Memory per worker
Proxy-Terminated	--socket	Production web apps (Nginx/uWSGI)	Additional hop in network path

Technical Trade-offs and Constraints

Implementing HTTP/2 within uWSGI requires the libnghttp2 library to be present during the build process. Because HTTP/2 is almost exclusively used over encrypted connections, TLS is a practical requirement.

• CPU and Memory: Parsing HTTP/2 frames is more computationally expensive than parsing plain text HTTP/1.1 headers. Under high concurrency, you may see a slight increase in CPU utilization per worker.
• Protocol Negotiation: uWSGI uses ALPN (Application-Layer Protocol Negotiation) to determine if a client supports HTTP/2. If the client does not, uWSGI gracefully falls back to HTTP/1.1 on the same socket.
• Kernel Dependencies: Ensure your Linux kernel is version 4.9 or newer. Older kernels may exhibit instability or dropped streams when handling the specific TCP behaviors required by nghttp2.

Implementation Guide

To enable HTTP/2, you must ensure uWSGI version 2.0.20 or higher is installed. This configuration assumes you are running uWSGI as a standalone server handling its own TLS termination.

Required Permissions: The user running the uWSGI process must have read access to the SSL certificate and private key files, and permission to bind to the specified port (ports below 1024 require root or CAP_NET_BIND_SERVICE).

# Example uwsgi.ini configuration
[uwsgi]
# Bind to port 443 with HTTP/2 enabled
http-socket = :443
http2 = true

# TLS Configuration (Required for practical HTTP/2) 
https-socket = :443
ssl-cert-file = /etc/uwsgi/certs/server.crt
ssl-private-key-file = /etc/uwsgi/certs/server.key

# Application settings
module = myapp.wsgi:application
master = true
processes = 4

Validation and Diagnostics

To verify that the server is correctly negotiating HTTP/2, use curl with the --http2 flag. Run this command from a client machine or the server itself:

# Run as a standard user
curl --http2 -I https://localhost:443

Expected Result: The first line of the response header should be HTTP/2 200. If the response begins with HTTP/1.1 200, the server has fallen back to the older protocol, likely due to a missing libnghttp2 library or a TLS handshake failure during ALPN.

Limitations and Risks

• Server Push: While uWSGI supports server push, it is generally discouraged unless you have a highly specific asset-loading strategy. Incorrect use of push can waste bandwidth and confuse intermediate caching proxies.
• Proxy Interference: If you place a TLS-terminating proxy in front of this configuration, the --http2 flag in uWSGI becomes redundant and potentially problematic. The proxy will communicate with uWSGI via HTTP/1.1 or the uwsgi protocol, meaning the performance gains of multiplexing only exist between the client and the proxy, not the proxy and the app server.

Rollback Procedure

If you encounter stability issues or unexpected CPU spikes, revert to HTTP/1.1 by modifying the configuration file:

1. Remove the http2 = true line from your .ini file.
2. Change http-socket or https-socket back to standard --http if you are disabling TLS.
3. Restart the uWSGI service: systemctl restart uwsgi or uwsgi --reload.