Skip to main content

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 pfrelay 0.16 and aioquic 1.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 as https://hub.example.com:8443/xzfe-aeeg-e2da/. See "The server URL" in pfrelay's README.
  • Discovery. GET <prefix>/api/tunnel/quic (/pf/api/tunnel/quic at 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. connect is one stream per connection; serve keeps 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)

Source distribution for pfrelay-quic 0.16.2
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)

Table of built distributions (wheels) for pfrelay-quic 0.16.2
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page