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

  • Discovery. GET /pf/api/tunnel/quic 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.1

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.1
File Size Uploaded Provenance Actions
pfrelay_quic-0.16.1.tar.gz 27.4 kB With provenance Details for pfrelay_quic-0.16.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pfrelay-quic 0.16.1
File Interpreter ABI Platform Actions
pfrelay_quic-0.16.1-py3-none-any.whl Python 3 none any Details for pfrelay_quic-0.16.1-py3-none-any.whl

Total release size: 49.9 kB

Release files / pfrelay_quic-0.16.1.tar.gz

Download URL pfrelay_quic-0.16.1.tar.gz
Size 27.4 kB
Tags Source
SHA-256 checksum
How to use checksums
c8e6657b8ad913a897c9ff14630c03538d0f4fe9c45d6f0c7f6e83595a49ff1c
BLAKE2b-256 checksum
How to use checksums
356713e83d7700c460aba58e16116888188e2bec908714d2a5b658b8b15e8a0a
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 16, 2026.

Transparency log

Release files / pfrelay_quic-0.16.1-py3-none-any.whl

Download URL pfrelay_quic-0.16.1-py3-none-any.whl
Size 22.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
561bc4c8e6ff4bdfebc82f8cc234563af8e7a7441dbec2c01d5192a2497304bc
BLAKE2b-256 checksum
How to use checksums
383fbfa2767e36d21e29a2250b0971e916a37c62c0c5d0599eb4dfdccec8bf08
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 16, 2026.

Transparency log

Security for pfrelay-quic 0.16.1

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.1.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 16, 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