diff --git a/docs/examples.echo_quic.rst b/docs/examples.echo_quic.rst new file mode 100644 index 00000000..0e3313df --- /dev/null +++ b/docs/examples.echo_quic.rst @@ -0,0 +1,43 @@ +QUIC Echo Demo +============== + +This example demonstrates a simple ``echo`` protocol using **QUIC transport**. + +QUIC provides built-in TLS security and stream multiplexing over UDP, making it an excellent transport choice for libp2p applications. + +.. code-block:: console + + $ python -m pip install libp2p + Collecting libp2p + ... + Successfully installed libp2p-x.x.x + $ echo-quic-demo + Run this from the same folder in another console: + + echo-quic-demo -d /ip4/127.0.0.1/udp/8000/quic-v1/p2p/16Uiu2HAmAsbxRR1HiGJRNVPQLNMeNsBCsXT3rDjoYBQzgzNpM5mJ + + Waiting for incoming connection... + +Copy the line that starts with ``echo-quic-demo -p 8001``, open a new terminal in the same +folder and paste it in: + +.. code-block:: console + + $ echo-quic-demo -d /ip4/127.0.0.1/udp/8000/quic-v1/p2p/16Uiu2HAmE3N7KauPTmHddYPsbMcBp2C6XAmprELX3YcFEN9iXiBu + + I am 16Uiu2HAmE3N7KauPTmHddYPsbMcBp2C6XAmprELX3YcFEN9iXiBu + STARTING CLIENT CONNECTION PROCESS + CLIENT CONNECTED TO SERVER + Sent: hi, there! + Got: ECHO: hi, there! + +**Key differences from TCP Echo:** + +- Uses UDP instead of TCP: ``/udp/8000`` instead of ``/tcp/8000`` +- Includes QUIC protocol identifier: ``/quic-v1`` in the multiaddr +- Built-in TLS security (no separate security transport needed) +- Native stream multiplexing over a single QUIC connection + +.. literalinclude:: ../examples/echo/echo_quic.py + :language: python + :linenos: diff --git a/docs/examples.rst b/docs/examples.rst index 74864cbe..9f149ad0 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -9,6 +9,7 @@ Examples examples.identify_push examples.chat examples.echo + examples.echo_quic examples.ping examples.pubsub examples.circuit_relay diff --git a/docs/getting_started.rst b/docs/getting_started.rst index a8303ce0..b5de85bc 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -28,6 +28,11 @@ For Python, the most common transport is TCP. Here's how to set up a basic TCP t .. literalinclude:: ../examples/doc-examples/example_transport.py :language: python +Also, QUIC is a modern transport protocol that provides built-in TLS security and stream multiplexing over UDP: + +.. literalinclude:: ../examples/doc-examples/example_quic_transport.py + :language: python + Connection Encryption ^^^^^^^^^^^^^^^^^^^^^ diff --git a/examples/doc-examples/example_quic_transport.py b/examples/doc-examples/example_quic_transport.py new file mode 100644 index 00000000..da2f5395 --- /dev/null +++ b/examples/doc-examples/example_quic_transport.py @@ -0,0 +1,35 @@ +import secrets + +import multiaddr +import trio + +from libp2p import ( + new_host, +) +from libp2p.crypto.secp256k1 import ( + create_new_key_pair, +) + + +async def main(): + # Create a key pair for the host + secret = secrets.token_bytes(32) + key_pair = create_new_key_pair(secret) + + # Create a host with the key pair + host = new_host(key_pair=key_pair, enable_quic=True) + + # Configure the listening address + port = 8000 + listen_addr = multiaddr.Multiaddr(f"/ip4/0.0.0.0/udp/{port}/quic-v1") + + # Start the host + async with host.run(listen_addrs=[listen_addr]): + print("libp2p has started with QUIC transport") + print("libp2p is listening on:", host.get_addrs()) + # Keep the host running + await trio.sleep_forever() + + +# Run the async function +trio.run(main) diff --git a/examples/echo/echo_quic.py b/examples/echo/echo_quic.py index aebc866a..248aed9f 100644 --- a/examples/echo/echo_quic.py +++ b/examples/echo/echo_quic.py @@ -142,9 +142,9 @@ def main() -> None: QUIC provides built-in TLS security and stream multiplexing over UDP. - To use it, first run 'python ./echo_quic_fixed.py -p ', where is + To use it, first run 'echo-quic-demo -p ', where is the UDP port number. Then, run another host with , - 'python ./echo_quic_fixed.py -d ' + 'echo-quic-demo -d ' where is the QUIC multiaddress of the previous listener host. """ diff --git a/pyproject.toml b/pyproject.toml index 8af0f5a6..b06d639c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -53,6 +53,7 @@ Homepage = "https://github.com/libp2p/py-libp2p" [project.scripts] chat-demo = "examples.chat.chat:main" echo-demo = "examples.echo.echo:main" +echo-quic-demo="examples.echo.echo_quic:main" ping-demo = "examples.ping.ping:main" identify-demo = "examples.identify.identify:main" identify-push-demo = "examples.identify_push.identify_push_demo:run_main" diff --git a/tests/examples/test_quic_echo_example.py b/tests/examples/test_quic_echo_example.py new file mode 100644 index 00000000..fc843f4b --- /dev/null +++ b/tests/examples/test_quic_echo_example.py @@ -0,0 +1,6 @@ +def test_echo_quic_example(): + """Test that the QUIC echo example can be imported and has required functions.""" + from examples.echo import echo_quic + + assert hasattr(echo_quic, "main") + assert hasattr(echo_quic, "run")