Command-line Interface

When hface is installed, it can be run using the hface command:

hface --help

Alternatively, you can run it as a Python package:

python3 -m hface --help

Server

An HTTP server can be started using the hface server subcommand:

hface server \
    --cert certs/cert.pem --key certs/key.pem \
    hface.server.examples.hello \
    http://localhost:5080 https://localhost:5443

The first positional argument is a dotted path to a Python module with an ASGI application. The ASGI standard is supported by many application frameworks.

The rest of positional arguments specify endpoints where the server should listen. The server can listen to both secure (HTTPS) and insecure (HTTP) connections simultaneously. It can listen at both IPv4 and IPv6.

The server supports all HTTP versions: HTTP/1, HTTP/2, and HTTP/3. To check HTTP/3 support in a browser, your application has to send the Alt-Svc header. You can use hface.server.examples.alt_svc for that purpose.

Hint

Google Chrome may not switch to HTTP/3 if you are not using a TLS certificate from a well-known certificate authority.

To bypass that limitation, you can run Chrome with a command-line option --origin-to-force-quic-on=localhost:5443 or similar.

Run hface server --help to see all server options.

Client

A command-line HTTP client is included too:

hface client --cacert certs/cacert.pem https://localhost:5443

Hint

To test the client with a public server, do not set --cacert.

By default, the client opens a TPC connection and chooses between HTTP/1 or HTTP/2 based on ALPN in a TLS handshake. The client does not process the Alt-Svc header. Use the --http3 option to open a QUIC (HTTP/3) connection.

Run hface client --help to see all client options.

Proxy

An HTTP proxy is included in hface.

The proxy works in the tunneling mode only (the tunneling mode is typically used for HTTPS URLs, but can be used for insecure requests too).

hface proxy \
    --cert certs/cert.pem --key certs/key.pem \
    http://localhost:6080 https://localhost:6443

The hface client has proxy support:

hface client \
    --cacert certs/cacert.pem \
    --proxy https://localhost:6443 \
    https://localhost:5443

The proxy can accept HTTP/1, HTTP/2, and HTTP/3 connections. In the tunneling mode, HTTP proxies can tunnel any TCP traffic. Try to pass combination of --proxy-http{1,2,3} --http{1,2} options to the client. Support for proxying UDP (HTTP/3) traffic is planned.

Run hface proxy --help to see all proxy options.