pfrelay-quic for Python
The Python SDK for the pf-simple relay hub over QUIC:
tunnel protocol 3, as defined in docs/PROTOCOL.md
§13. It runs on asyncio, with aioquic.
It is pfrelay with another way to the hub. The Client it
makes is a pfrelay.Client, with a QUIC transport attached, so listeners,
dial, forwarders, events, stats, drop, watch and the retry loop are
pfrelay's, and behave the same. A QUIC side works with a WebSocket side
through the same hub, in either role.
- Python 3.11 or later (aioquic 1.8 needs it).
- Depends on
pfrelay0.16 andaioquic1.8 or later.
pip install pfrelay-quic
Moving from WebSocket
Make the client from pfrelay_quic instead of pfrelay; the rest of the
program stays as it is.
import asyncio, pfrelay, pfrelay_quic
async def main():
# was: pfrelay.Client(...)
client = pfrelay_quic.Client(
"https://hub.example.com", "k3f9-x2mq-7hpa",
serve_token=SERVE_TOKEN,
name="Echo service",
)
listener = await client.listen()
async for conn in listener: # pfrelay.Conn, as over WebSocket
asyncio.ensure_future(echo(conn))
async def echo(conn: pfrelay.Conn):
async with conn:
while data := await conn.read():
await conn.write(data)
await conn.close_write()
asyncio.run(main())
pfrelay_quic.Client takes pfrelay's settings except those of the
WebSocket protocols (max_proto, leg reuse). ca_file and ssl_context
are for the hub's HTTPS endpoint, where the QUIC listener is discovered.
client.close() closes the QUIC connection; the next request opens a new
one.
How it reaches the hub
- The server URL is the same as pfrelay's:
https://host[:port], optionally followed by the hub's prefix (default/pf), such ashttps://hub.example.com:8443/xzfe-aeeg-e2da/. See "The server URL" in pfrelay's README. - Discovery.
GET <prefix>/api/tunnel/quic(/pf/api/tunnel/quicat the default prefix) on the hub's HTTPS endpoint, with the run's credentials, tells where the QUIC listener is and the SHA-256 fingerprints of its certificate. A 404 means the hub offers no QUIC (this is final); a 501 means its listener is off (retried). - Pinning. The listener's certificate is accepted if and only if the SHA-256 of its DER is one of the fingerprints. The chain, name and dates are not checked; the TLS 1.3 handshake signature is. aioquic offers no verification hook, so the pin is checked right after the handshake, before any stream is opened. On a mismatch the client discovers once more, then fails.
- One QUIC connection per client, made again (after discovering again)
when it is lost. QUIC version 1 only, ALPN
pf-tunnel, no 0-RTT, no session resumption, idle timeout 30 s, no unidirectional streams. aioquic has no keepalive of its own, so the client sends a PING after 10 s in which nothing arrived. - Flow control. A stream's receive credit follows what the application has read, so a connection whose reader stalls holds up only itself. A write waits while too much of its stream is unacknowledged.
- Each request is a stream.
connectis one stream per connection;servekeeps one stream open as the registration, and the hub opens a stream to the serving side for each connection. - No fallback. Where UDP is blocked this fails to connect; use
pfrelay(WebSocket) there.
Tests
From the repository root, with aioquic installed:
python3 -I -m unittest discover -s sdk/python-quic/tests
PF_CONFORMANCE_DRIVER="python3 -I sdk/python-quic/driver.py" go test -count=1 -run TestConformance .
PF_CONFORMANCE_SLOW=1 PF_CONFORMANCE_DRIVER="python3 -I sdk/python-quic/driver.py" go test -count=1 -run 'TestConformance/quic/idle' .
The unit tests run the client against a fake hub's QUIC listener, also on
aioquic (tests/hub.py). driver.py is the conformance driver
(conformance/README.md); it answers
protocols with 3-3, so the suite runs every case with the hub's QUIC
listener on and the Go SDK on WebSocket on the other side.
License
Apache License 2.0; see LICENSE.
Metadata
Release files for pfrelay-quic 0.16.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pfrelay_quic-0.16.2.tar.gz | 27.9 kB | With provenance | Details for pfrelay_quic-0.16.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pfrelay_quic-0.16.2-py3-none-any.whl | Python 3 | none | any | Details for pfrelay_quic-0.16.2-py3-none-any.whl |
Total release size: 50.6 kB
Release files / pfrelay_quic-0.16.2.tar.gz
| Download URL | pfrelay_quic-0.16.2.tar.gz |
|---|---|
| Size | 27.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
677d99540c948c4bf347cd221717e3e4537fc2f4e3aed3cb914b3a0d17102ce2
|
|
BLAKE2b-256 checksum How to use checksums |
a9c7162487310cb4e0a7050a62eb789e99d148058750d9e66d8db5361348d8a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / pfrelay_quic-0.16.2-py3-none-any.whl
| Download URL | pfrelay_quic-0.16.2-py3-none-any.whl |
|---|---|
| Size | 22.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7bdc90c8f2b357eb846f97e4ca89e17e909e7d34164f423d02c448b2bf3350bf
|
|
BLAKE2b-256 checksum How to use checksums |
ff0999ad1447b46c1f77abcf355f9f48617b855e5f71302f49bea574813a71b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for pfrelay-quic 0.16.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pfrelay_quic-0.16.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.