Merge branch 'libp2p:main' into main

Author: seetadev

.github/workflows/oso-health-report.yml

@@ -0,0 +1,52 @@
+name: OSO Health Report
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  health-report:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+
+      - name: Generate report
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OSO_API_KEY: ${{ secrets.OSO_API_KEY }}
+        run: |
+          python scripts/oso/collect_health_metrics.py \
+            --repo-root . \
+            --repo-slug libp2p/py-libp2p \
+            --json-output reports/health_metrics.json \
+            --md-output reports/health_report.md
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: oso-health-report
+          path: |
+            reports/health_metrics.json
+            reports/health_report.md
+
+      - name: Job summary
+        run: |
+          echo "## OSO Health Report" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Generated files:" >> "$GITHUB_STEP_SUMMARY"
+          echo "- reports/health_metrics.json" >> "$GITHUB_STEP_SUMMARY"
+          echo "- reports/health_report.md" >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -138,6 +138,8 @@ fabric.properties
 
 # Django stuff:
 *.log
+*.pem
+*.key
 local_settings.py
 db.sqlite3
 
@@ -190,3 +192,11 @@ tests/interop/js_libp2p/js_node/src/package-lock.json
 
 # Sphinx documentation build
 _build/
+
+# Attack simulation test results
+tests/security/attack_simulation/results/
+libp2p-forge
+
+# OSO health report generated outputs
+reports/*.json
+reports/*.md

.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

Makefile

@@ -65,7 +65,8 @@ PB = libp2p/crypto/pb/crypto.proto \
 	libp2p/discovery/rendezvous/pb/rendezvous.proto \
 	libp2p/bitswap/pb/bitswap.proto \
 	libp2p/bitswap/pb/dag_pb.proto \
-	libp2p/bitswap/pb/unixfs.proto
+	libp2p/bitswap/pb/unixfs.proto \
+	libp2p/records/pb/ipns.proto
 
 PY = $(PB:.proto=_pb2.py)
 PYI = $(PB:.proto=_pb2.pyi)

README.md

@@ -11,7 +11,6 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/libp2p.svg)](https://pypi.python.org/pypi/libp2p)
 [![Build Status](https://img.shields.io/github/actions/workflow/status/libp2p/py-libp2p/tox.yml?branch=main&label=build%20status)](https://github.com/libp2p/py-libp2p/actions/workflows/tox.yml)
 [![Docs build](https://readthedocs.org/projects/py-libp2p/badge/?version=latest)](http://py-libp2p.readthedocs.io/en/latest/?badge=latest)
-<a href="https://filecoin.drips.network/app/projects/github/libp2p/py-libp2p" target="_blank"><img src="https://filecoin.drips.network/api/embed/project/https%3A%2F%2Fgithub.com%2Flibp2p%2Fpy-libp2p/support.png?background=light&style=drips&text=project&stat=support" alt="Support py-libp2p on drips.network" height="32"></a>
 
 > py-libp2p has moved beyond its experimental roots and is steadily progressing toward production readiness. The core features are stable, and we’re focused on refining performance, expanding protocol support, and ensuring smooth interop with other libp2p implementations. We welcome contributions and real-world usage feedback to help us reach full production maturity.
 
@@ -140,3 +139,7 @@ _(non-normative, useful for team notes, not a reference)_
 **Communication over one connection with multiple protocols**: X and Y can communicate over the same connection using different protocols and the multiplexer will appropriately route messages for a given protocol to a particular handler function for that protocol, which allows for each host to handle different protocols with separate functions. Furthermore, we can use multiple streams for a given protocol that allow for the same protocol and same underlying connection to be used for communication about separate topics between nodes X and Y.
 
 **Why use multiple streams?**: The purpose of using the same connection for multiple streams to communicate over is to avoid the overhead of having multiple connections between X and Y. In order for X and Y to differentiate between messages on different streams and different protocols, a multiplexer is used to encode the messages when a message will be sent and decode a message when a message is received. The multiplexer encodes the message by adding a header to the beginning of any message to be sent that contains the stream id (along with some other info). Then, the message is sent across the raw connection and the receiving host will use its multiplexer to decode the message, i.e. determine which stream id the message should be routed to.
+
+### Support
+
+<a href="https://filecoin.drips.network/app/projects/github/libp2p/py-libp2p" target="_blank"><img src="https://filecoin.drips.network/api/embed/project/https%3A%2F%2Fgithub.com%2Flibp2p%2Fpy-libp2p/support.png?background=light&style=drips&text=project&stat=support" alt="Support py-libp2p on drips.network" height="32"></a>

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,19 @@ 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.
+
+For the full API reference, see :mod:`libp2p.utils.paths`. A working example is
+available in :doc:`examples.path_handling`.
+
 Documentation
 ~~~~~~~~~~~~~
 
@@ -393,14 +406,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/dependency_graph/.gitignore

@@ -0,0 +1,18 @@
+# Generated dependency graph files
+# These can be regenerated by running the scripts
+*.png
+*.svg
+*.json
+*.dot
+*.mmd
+
+# Keep documentation files
+!README.md
+!OSO_INFO.md
+!OSO_INTEGRATION.md
+!PREVIEW.md
+!QUICK_PREVIEW.md
+!SUMMARY.md
+
+# Keep the markdown summary (it's documentation, not generated data)
+!dependencies.md

docs/dependency_graph/PREVIEW.md

@@ -0,0 +1,98 @@
+# Previewing the Dependency Graph
+
+This document explains how to preview the generated dependency graphs in different formats.
+
+## 1. Mermaid Format (Recommended for GitHub)
+
+The Mermaid format can be viewed directly in GitHub or using online Mermaid editors.
+
+### Option A: View in GitHub
+
+1. Open `docs/dependency_graph/dependencies.mmd` in GitHub
+1. GitHub will automatically render Mermaid diagrams
+
+### Option B: Online Mermaid Editor
+
+1. Copy the contents of `dependencies.mmd`
+1. Paste into one of these online editors:
+   - https://mermaid.live/
+   - https://mermaid-js.github.io/mermaid-live-editor/
+
+### Option C: View in VS Code
+
+If you have the Mermaid extension installed in VS Code, it will preview automatically.
+
+## 2. DOT Format (Graphviz)
+
+### Option A: Convert to Image (if Graphviz is installed)
+
+```bash
+# Generate PNG
+dot -Tpng docs/dependency_graph/dependencies.dot -o docs/dependency_graph/dependencies.png
+
+# Generate SVG (scalable)
+dot -Tsvg docs/dependency_graph/dependencies.dot -o docs/dependency_graph/dependencies.svg
+
+# Generate PDF
+dot -Tpdf docs/dependency_graph/dependencies.dot -o docs/dependency_graph/dependencies.pdf
+```
+
+### Option B: Online Graphviz Editors
+
+1. Copy the contents of `dependencies.dot`
+1. Paste into one of these online tools:
+   - https://dreampuf.github.io/GraphvizOnline/
+   - https://edotor.net/
+   - https://graphviz.christine.website/
+
+## 3. JSON Format
+
+### Option A: Pretty Print in Terminal
+
+```bash
+cat docs/dependency_graph/dependencies.json | python3 -m json.tool | less
+```
+
+### Option B: View in Browser
+
+```bash
+# Open in default browser (if you have a JSON viewer extension)
+xdg-open docs/dependency_graph/dependencies.json  # Linux
+open docs/dependency_graph/dependencies.json      # macOS
+```
+
+### Option C: Use jq (if installed)
+
+```bash
+jq '.' docs/dependency_graph/dependencies.json | less
+```
+
+## 4. Markdown Summary
+
+Simply view the file:
+
+```bash
+cat docs/dependency_graph/dependencies.md
+# or
+less docs/dependency_graph/dependencies.md
+```
+
+Or open in any Markdown viewer/editor.
+
+## Quick Preview Commands
+
+Here are some quick commands to preview each format:
+
+```bash
+# View Mermaid (copy to online editor)
+cat docs/dependency_graph/dependencies.mmd
+
+# View Markdown summary
+cat docs/dependency_graph/dependencies.md
+
+# View JSON (pretty printed)
+python3 -m json.tool docs/dependency_graph/dependencies.json | less
+
+# Generate PNG from DOT (if Graphviz installed)
+dot -Tpng docs/dependency_graph/dependencies.dot -o /tmp/deps.png && xdg-open /tmp/deps.png
+```

docs/dependency_graph/QUICK_PREVIEW.md

@@ -0,0 +1,66 @@
+# Quick Preview Guide
+
+## 🎯 Fastest Ways to Preview
+
+### 1. **Markdown Summary** (Text-based, instant)
+
+```bash
+cat docs/dependency_graph/dependencies.md
+```
+
+Shows a clean list of all dependencies with version specs.
+
+### 2. **Mermaid Diagram** (Visual, works in GitHub)
+
+```bash
+# Copy the file content and paste into:
+# https://mermaid.live/
+cat docs/dependency_graph/dependencies.mmd
+```
+
+### 3. **PNG Image** (Visual, already generated)
+
+```bash
+# View the generated PNG
+xdg-open docs/dependency_graph/dependencies.png  # Linux
+open docs/dependency_graph/dependencies.png      # macOS
+```
+
+### 4. **SVG Image** (Scalable, already generated)
+
+```bash
+# View the generated SVG
+xdg-open docs/dependency_graph/dependencies.svg  # Linux
+open docs/dependency_graph/dependencies.svg      # macOS
+```
+
+### 5. **DOT Graph** (Online visualization)
+
+```bash
+# Copy content and paste into:
+# https://dreampuf.github.io/GraphvizOnline/
+cat docs/dependency_graph/dependencies.dot
+```
+
+## 📊 Current Graph Stats
+
+- **Project**: libp2p v0.4.0
+- **Runtime dependencies**: 20
+- **Optional dependencies**: 32
+- **Total nodes**: 44
+- **Total edges**: 52
+
+## 🔄 Regenerate Images
+
+If you modify the dependencies and want to regenerate the images:
+
+```bash
+# Regenerate all formats
+python3 scripts/oso/generate_dependency_graph.py
+
+# Regenerate PNG
+dot -Tpng docs/dependency_graph/dependencies.dot -o docs/dependency_graph/dependencies.png
+
+# Regenerate SVG
+dot -Tsvg docs/dependency_graph/dependencies.dot -o docs/dependency_graph/dependencies.svg
+```