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.