Hypercorn

Warnings

• breaking Hypercorn dropped support for ASGI/2 and now requires ASGI/3 applications. Applications built against older ASGI/2 specifications will need to be updated.
  Fix: Ensure your ASGI application conforms to the ASGI/3 specification. Most modern ASGI frameworks (FastAPI, Starlette, Quart) already support ASGI/3.
• deprecated The command-line arguments `--access-log` and `--error-log` have been deprecated in favor of `--access-logfile` and `--error-logfile` for consistency with Gunicorn's logging settings.
  Fix: Update command-line scripts to use `--access-logfile` and `--error-logfile` respectively.
• gotcha When running Hypercorn with the `--reload` option inside Docker containers, changes to files mounted via Docker volumes may not trigger a reload as expected.
  Fix: Ensure Docker volume mounts are correctly configured for file watching, or consider alternative reloading strategies for development within Docker. Verify that the file changes are indeed reflected inside the container's filesystem.
• gotcha Some users have reported higher-than-expected memory usage or potential memory leaks, particularly in resource-constrained environments like serverless platforms. While improvements have been made, monitoring memory is recommended.
  Fix: Monitor memory usage closely. Consider using `uvloop` or `trio` if applicable, as they might have different memory characteristics. Review application code for potential unclosed resources or large synchronous operations blocking the event loop. The 0.15.0 release included updates to use 'more modern asyncio apis' to help address reported memory leaks.
• gotcha There have been reports of Hypercorn not gracefully closing pending connections on `CTRL+C` or when shutting down without explicit worker management (e.g., `--workers 0`), potentially leading to HTTP 503 errors on clients.
  Fix: For production deployments, utilize a proper process manager (like Gunicorn acting as a supervisor) to manage Hypercorn workers. Ensure the application handles graceful shutdown signals to allow active requests to complete.

Install

• pip install hypercorn Standard Installation
• pip install 'hypercorn[h3]' With HTTP/3 Support
• pip install 'hypercorn[uvloop]' With uvloop for faster asyncio

Imports

• Config

  from hypercorn.config import Config

• serve (asyncio)

  from hypercorn.asyncio import serve

• serve (trio)

  from hypercorn.trio import serve

• run

  from hypercorn.run import run

  While `asyncio.run(serve(app, Config()))` is common, `hypercorn.run.run` provides a higher-level entry point with signal handling and worker management, similar to the CLI. For basic programmatic use with full control over the event loop, `serve` is typically used.

Quickstart

This quickstart demonstrates how to programmatically run a simple ASGI 'Hello, world!' application using Hypercorn's asyncio backend. It configures Hypercorn to bind to an address and port, defaulting to 0.0.0.0:8000, and uses `asyncio.run` to start the server. Alternatively, you can run from the command line: `hypercorn my_module:app` after installing.

import asyncio
from hypercorn.config import Config
from hypercorn.asyncio import serve

async def app(scope, receive, send):
    assert scope['type'] == 'http'
    response_body = b'Hello, world!'
    headers = [
        (b'content-type', b'text/plain'),
        (b'content-length', str(len(response_body)).encode())
    ]
    await send({'type': 'http.response.start', 'status': 200, 'headers': headers})
    await send({'type': 'http.response.body', 'body': response_body})

async def main():
    config = Config()
    config.bind = [f"0.0.0.0:{os.environ.get('PORT', '8000')}"]
    print(f"Serving on {config.bind[0]}...")
    await serve(app, config)

if __name__ == '__main__':
    import os
    asyncio.run(main())