Merge remote-tracking branch 'origin/main' into feat/pg

Author: asmit27rai

.pre-commit-config.yaml

@@ -49,3 +49,11 @@ repos:
         language: system
         always_run: true
         pass_filenames: false
+  - repo: local
+    hooks:
+      - id: path-audit
+        name: Cross-platform path handling audit (P0/P1)
+        entry: python scripts/audit_paths.py --summary-only --fail-on-p1
+        language: system
+        always_run: true
+        pass_filenames: false

docs/conf.py

@@ -12,23 +12,26 @@
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
+# documentation root, use pathlib to resolve it cross-platform.
 
 import doctest
-import os
+from pathlib import Path
 import sys
-
-sys.path.insert(0, os.path.abspath(".."))
 from unittest.mock import MagicMock
 
+# Add project root to path (cross-platform)
+_docs_dir = Path(__file__).resolve().parent
+_project_root = _docs_dir.parent
+sys.path.insert(0, str(_project_root))
+
 try:
     import tomllib
 except ModuleNotFoundError:
     # For Python < 3.11
     import tomli as tomllib  # type: ignore (In case of >3.11 Pyrefly doesnt find tomli , which is right but a false flag)
 
-# Path to pyproject.toml (assuming conf.py is in a 'docs' subdirectory)
-pyproject_path = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
+# Path to pyproject.toml (conf.py is in 'docs', project root is parent)
+pyproject_path = _project_root / "pyproject.toml"
 
 with open(pyproject_path, "rb") as f:
     pyproject_data = tomllib.load(f)

docs/contributing.rst

@@ -354,6 +354,16 @@ This library uses type hints, which are enforced by the ``mypy`` tool (part of t
 ``pre-commit`` checks). All new code is required to land with type hints, with the
 exception of code within the ``tests`` directory.
 
+Path handling
+^^^^^^^^^^^^^
+
+Use the cross-platform path utilities in ``libp2p.utils.paths`` instead of ``os.path``
+or hard-coded separators. Prefer ``join_paths()`` over ``os.path.join()``,
+``get_script_dir(__file__)`` over ``os.path.dirname(__file__)``, and ``create_temp_file()``
+or ``get_temp_dir()`` over hard-coded ``/tmp/`` or ``C:\\``. This keeps the codebase
+working on Windows, macOS, and Linux. Run ``python scripts/audit_paths.py`` to check
+for path issues; the same audit runs in ``pre-commit`` and fails on P0/P1 issues.
+
 Documentation
 ~~~~~~~~~~~~~
 
@@ -393,14 +403,15 @@ To add a new example (e.g., identify):
     .. code:: sh
 
         .....
-        Activate with `source /tmp/tmpb9ybjgtg/package-smoke-test/bin/activate`
+        Activate with ``source <temp-dir>/package-smoke-test/bin/activate``
+        (The exact path is shown by the script; use that path.)
         Press enter when the test has completed. The directory will be deleted.
 
     Then test the example:
 
     .. code:: sh
 
-        source /tmp/tmpb9ybjgtg/package-smoke-test/bin/activate
+        source <temp-dir>/package-smoke-test/bin/activate
         (package-smoke-test) $ identify-demo
 
 Pull Requests

docs/examples.bitswap.rst

@@ -153,7 +153,7 @@ Client Output
     ======================================================================
     Size: 2.5 MB
     Filename: document.pdf (from metadata)
-    ✓ Saved to: /tmp/document.pdf
+    ✓ Saved to: <temp-dir>/document.pdf
     ======================================================================
 
 Features

docs/examples.perf.rst

@@ -0,0 +1,69 @@
+Perf Protocol Demo
+==================
+
+This example demonstrates how to use the libp2p ``perf`` protocol to measure
+transfer performance between two nodes.
+
+The perf protocol sends and receives data to measure throughput, reporting
+both intermediary progress and final results.
+
+Running the Example
+-------------------
+
+First, start the server in one terminal:
+
+.. code-block:: console
+
+    $ python examples/perf/perf_example.py -p 8000
+
+    Perf server ready, listening on:
+      /ip4/127.0.0.1/tcp/8000/p2p/QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+
+    Protocol: /perf/1.0.0
+
+    Run client with:
+      python perf_example.py -d /ip4/127.0.0.1/tcp/8000/p2p/QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+
+    Waiting for incoming perf requests...
+
+Then, in another terminal, run the client with the multiaddr from the server:
+
+.. code-block:: console
+
+    $ python examples/perf/perf_example.py -d /ip4/127.0.0.1/tcp/8000/p2p/QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN
+
+    Connecting to QmXfptdHU6hqG95JswxYVUH4bphcK8y18mhFcgUQFe6fCN...
+    Connected!
+
+    Measuring performance:
+      Upload:   2560 bytes
+      Download: 2560 bytes
+
+      Uploading: 2560 bytes in 0.01s (256000 bytes/s)
+      Downloading: 2560 bytes in 0.01s (256000 bytes/s)
+
+    ==================================================
+    Performance Results:
+      Total time:     0.025 seconds
+      Uploaded:       2560 bytes
+      Downloaded:     2560 bytes
+      Total data:     5120 bytes
+      Throughput:     204800 bytes/s
+    ==================================================
+
+Command Line Options
+--------------------
+
+.. code-block:: text
+
+    -p, --port          Listening port (default: random free port)
+    -d, --destination   Destination multiaddr (if not set, runs as server)
+    -u, --upload        Upload size in units of 256 bytes (default: 10)
+    -D, --download      Download size in units of 256 bytes (default: 10)
+
+Source Code
+-----------
+
+.. literalinclude:: ../examples/perf/perf_example.py
+    :language: python
+    :linenos:

docs/examples.rst

@@ -27,3 +27,4 @@ Examples
    examples.websocket
    examples.tls
    examples.autotls
+   examples.perf

docs/libp2p.perf.rst

@@ -0,0 +1,41 @@
+libp2p.perf package
+===================
+
+The perf module implements the libp2p performance measurement protocol,
+which allows measuring throughput between two libp2p nodes by sending
+and receiving configurable amounts of data.
+
+Submodules
+----------
+
+libp2p.perf.constants module
+----------------------------
+
+.. automodule:: libp2p.perf.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+libp2p.perf.types module
+------------------------
+
+.. automodule:: libp2p.perf.types
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+libp2p.perf.perf\_service module
+--------------------------------
+
+.. automodule:: libp2p.perf.perf_service
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: libp2p.perf
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/libp2p.rst

@@ -16,6 +16,7 @@ Subpackages
    libp2p.kad_dht
    libp2p.network
    libp2p.peer
+   libp2p.perf
    libp2p.protocol_muxer
    libp2p.pubsub
    libp2p.rcmgr

examples/autotls/autotls.py

@@ -120,8 +120,17 @@ async def run(port: int, destination: str, new: int, transport: str, tls: int) -
 
     if transport == "tcp":
         listen_addrs = get_available_interfaces(port)
-    if transport == "ws":
+    elif transport == "ws":
         listen_addrs = [multiaddr.Multiaddr(f"/ip4/127.0.0.1/tcp/{port}/ws")]
+    elif transport == "quic":
+        # QUIC uses UDP addresses with /quic-v1 suffix
+        quic_addrs = []
+        for addr in get_available_interfaces(port):
+            addr_str = str(addr).replace("/tcp/", "/udp/") + "/quic-v1"
+            quic_addrs.append(multiaddr.Multiaddr(addr_str))
+        listen_addrs = quic_addrs
+    else:
+        raise ValueError(f"Unknown transport: {transport}. Use tcp, ws, or quic.")
 
     if new == 1:
         libp2p.utils.paths.ED25519_PATH = Path("libp2p-forge/peer2/ed25519.pem")
@@ -148,11 +157,15 @@ async def run(port: int, destination: str, new: int, transport: str, tls: int) -
         NOISE_PROTOCOL_ID: noise_transport,
     }
 
+    # Create host with QUIC support if transport is quic
+    enable_quic = transport == "quic"
+
     host = new_host(
         key_pair=key_pair,
         listen_addrs=listen_addrs,
         sec_opt=security_options,
         enable_autotls=enable_autotls,
+        enable_quic=enable_quic,
     )
 
     base_identify_handler = identify_handler_for(host, use_varint_format=False)
@@ -242,7 +255,7 @@ def main() -> None:
         "--transport",
         default="tcp",
         type=str,
-        help="Choose the transport layer for ping TCP/WS",
+        help="Choose the transport layer: tcp, ws, or quic",
     )
 
     args = parser.parse_args()