Merge pull request #836 from Sahilgill24/feat/resource-management

feat: implementing a resource manager to prevent resource exhaustion attacks

Author: seetadev

docs/conf.py

@@ -50,6 +50,21 @@
     "sphinx_rtd_theme",
 ]
 
+# Configure Python domain to prefer canonical imports
+# This helps resolve ambiguous references like ResourceManager
+python_use_unqualified_type_names = False
+
+# Configure autodoc to prefer specific imports for ambiguous references
+autodoc_type_aliases = {
+    "ResourceManager": "libp2p.rcmgr.ResourceManager",
+}
+
+# Suppress specific warnings about ambiguous cross-references
+# Since ResourceManager is intentionally re-exported, both locations are valid
+suppress_warnings = [
+    "ref.python",  # Suppress ambiguous cross-reference warnings
+]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/getting_started.rst

@@ -79,6 +79,25 @@ Now that you have configured a **Transport**, **Crypto** and **Stream Multiplexe
 .. literalinclude:: ../examples/doc-examples/example_running.py
    :language: python
 
+Resource Management
+^^^^^^^^^^^^^^^^^^^
+
+py-libp2p enables resource protection by default. When you create a host with
+``new_host()`` (or a network service with ``new_swarm()``), a default
+``ResourceManager`` is created automatically if you do not provide one. This
+guards connections and streams out of the box.
+
+If you want to customize limits, construct and pass your own manager:
+
+.. code-block:: python
+
+    from libp2p import new_host
+    from libp2p.rcmgr import ResourceLimits, new_resource_manager
+
+    limits = ResourceLimits(max_connections=512, max_streams=4096, max_memory_mb=256)
+    rm = new_resource_manager(limits=limits)
+    host = new_host(resource_manager=rm)
+
 Custom Setup
 ~~~~~~~~~~~~
 

docs/libp2p.rcmgr.rst

@@ -0,0 +1,54 @@
+libp2p.rcmgr package
+====================
+
+Submodules
+----------
+
+libp2p.rcmgr.allowlist module
+-----------------------------
+
+.. automodule:: libp2p.rcmgr.allowlist
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.rcmgr.exceptions module
+------------------------------
+
+.. automodule:: libp2p.rcmgr.exceptions
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.rcmgr.limits module
+--------------------------
+
+.. automodule:: libp2p.rcmgr.limits
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.rcmgr.manager module
+---------------------------
+
+.. automodule:: libp2p.rcmgr.manager
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+libp2p.rcmgr.metrics module
+---------------------------
+
+.. automodule:: libp2p.rcmgr.metrics
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+
+Module contents
+---------------
+
+.. automodule:: libp2p.rcmgr
+   :members:
+   :show-inheritance:
+   :undoc-members:

docs/libp2p.rst

@@ -17,6 +17,7 @@ Subpackages
    libp2p.peer
    libp2p.protocol_muxer
    libp2p.pubsub
+   libp2p.rcmgr
    libp2p.records
    libp2p.relay
    libp2p.security

examples/monitoring-demo/README.md

@@ -0,0 +1,30 @@
+# Monitoring Demo
+
+Configure Prometheus target (match exporter port):
+```bash
+cd examples/monitoring-demo
+python configure.py --port 8000   # or: DEMO_EXPORTER_PORT=8010 python configure.py
+docker compose up -d
+```
+
+Run exporter (auto-picks a free port; you can also set DEMO_EXPORTER_PORT):
+```bash
+cd ../../
+. .venv/bin/activate
+python examples/monitoring-demo/run_demo.py  # or: DEMO_EXPORTER_PORT=8010 python examples/monitoring-demo/run_demo.py
+```
+
+Open UIs:
+- Prometheus: http://localhost:9090/targets
+- Grafana: http://localhost:3000
+
+Notes:
+- The Grafana dashboard `py-libp2p Resource Manager` is auto-provisioned.
+- If you change the exporter port, re-run `configure.py` and `docker compose restart prometheus`.
+
+Stop:
+```bash
+pkill -f run_demo.py || true
+cd examples/monitoring-demo
+docker compose down
+```

examples/monitoring-demo/configure.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+import argparse
+import os
+from pathlib import Path
+import re
+
+PROM_PATH = Path(__file__).parent / "prometheus.yml"
+
+
+def set_exporter_port(port: int) -> None:
+    content = PROM_PATH.read_text()
+    pattern = r"host\\.docker\\.internal:\\d+"
+    replacement = f"host.docker.internal:{port}"
+    new = re.sub(pattern, replacement, content)
+    PROM_PATH.write_text(new)
+    print(f"Updated Prometheus target to host.docker.internal:{port}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=int(os.getenv("DEMO_EXPORTER_PORT", "8000")),
+    )
+    args = parser.parse_args()
+    set_exporter_port(args.port)
+
+
+if __name__ == "__main__":
+    main()
+
+

examples/monitoring-demo/docker-compose.yml

@@ -0,0 +1,42 @@
+services:
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: py-libp2p-prometheus
+    ports:
+      - "9090:9090"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    volumes:
+      - ./prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus_data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--web.enable-lifecycle'
+      - '--storage.tsdb.retention.time=30d'
+    restart: unless-stopped
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: py-libp2p-grafana
+    depends_on:
+      - prometheus
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_SECURITY_ALLOW_EMBEDDING=true
+    volumes:
+      - ./grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards
+      - ./grafana/provisioning/datasources:/etc/grafana/provisioning/datasources
+      - ./grafana/dashboards:/var/lib/grafana/dashboards
+      - grafana_data:/var/lib/grafana
+    restart: unless-stopped
+
+volumes:
+  prometheus_data:
+  grafana_data:
+
+