Add flood publishing in py-libp2p

docs/examples.floodsub.rst

@@ -0,0 +1,25 @@
+FloodSub Examples
+=================
+
+This section contains examples demonstrating the FloodSub pubsub implementation.
+
+.. toctree::
+   :maxdepth: 1
+
+Simple PubSub Example
+---------------------
+
+.. automodule:: examples.floodsub.simple_pubsub
+   :members:
+
+Basic Example
+-------------
+
+.. automodule:: examples.floodsub.basic_example
+   :members:
+
+Multi-Node PubSub Example
+-------------------------
+
+.. automodule:: examples.floodsub.multi_node_pubsub
+   :members:

docs/examples.rst

@@ -12,6 +12,7 @@ Examples
    examples.echo_quic
    examples.ping
    examples.pubsub
+   examples.floodsub
    examples.circuit_relay
    examples.kademlia
    examples.mDNS

docs/floodsub_discussion.rst

@@ -0,0 +1,174 @@
+FloodSub Implementation Discussion
+==================================
+
+This document provides a comprehensive discussion of the FloodSub implementation in py-libp2p, including the new flood_publish feature for GossipSub.
+
+Overview
+--------
+
+FloodSub is a simple pubsub protocol that implements a flooding-based message distribution mechanism. Unlike more sophisticated protocols like GossipSub, FloodSub forwards every message to all connected peers, ensuring maximum message propagation at the cost of bandwidth efficiency.
+
+Key Features
+------------
+
+1. **Simple Flooding Algorithm**: Messages are forwarded to all peers subscribed to a topic
+2. **No Message Caching**: Each message is processed and forwarded immediately
+3. **Guaranteed Delivery**: High probability of message delivery due to flooding behavior
+4. **Bandwidth Intensive**: Uses more bandwidth compared to selective forwarding protocols
+
+Implementation Details
+----------------------
+
+The FloodSub implementation in py-libp2p follows the libp2p specification and provides:
+
+- Protocol ID: ``/floodsub/1.0.0``
+- Message validation and forwarding
+- Peer management and topic subscriptions
+- Integration with the libp2p pubsub framework
+
+Flood Publish Feature for GossipSub
+-----------------------------------
+
+A significant enhancement to the pubsub system is the introduction of the ``flood_publish`` option for GossipSub. This feature provides a hybrid approach that combines the benefits of both FloodSub and GossipSub.
+
+How It Works
+~~~~~~~~~~~~
+
+When ``flood_publish=True`` is set on a GossipSub instance:
+
+1. **Initial Publishing**: Messages originating from the local node are sent to ALL peers subscribed to the topic (flooding behavior)
+2. **Message Forwarding**: Subsequent message forwarding follows normal GossipSub mesh-based routing
+3. **Selective Application**: Only affects messages published by the local node, not forwarded messages
+
+Benefits
+~~~~~~~~
+
+- **Improved Reliability**: Ensures better initial message propagation in sparse networks
+- **Hybrid Efficiency**: Combines FloodSub's reliability with GossipSub's bandwidth efficiency
+- **Backward Compatibility**: Normal GossipSub behavior when ``flood_publish=False``
+- **Configurable**: Can be enabled/disabled based on network requirements
+
+Use Cases
+~~~~~~~~~
+
+The flood_publish feature is particularly useful for:
+
+- **Sparse Networks**: Where normal GossipSub mesh formation might be insufficient
+- **Critical Messages**: When maximum propagation probability is required
+- **Bootstrap Scenarios**: Initial message distribution in new networks
+- **Debugging**: Ensuring message delivery during development
+
+Configuration
+~~~~~~~~~~~~~
+
+The flood_publish feature can be configured when creating a GossipSub instance:
+
+.. code-block:: python
+
+    from libp2p.pubsub.gossipsub import GossipSub
+    from libp2p.tools.constants import GOSSIPSUB_PROTOCOL_ID
+
+    # Create GossipSub with flood_publish enabled
+    gossipsub = GossipSub(
+        protocols=[GOSSIPSUB_PROTOCOL_ID],
+        flood_publish=True  # Enable flooding for initial publishes
+    )
+
+Performance Considerations
+--------------------------
+
+Bandwidth Usage
+~~~~~~~~~~~~~~~
+
+- **FloodSub**: High bandwidth usage due to flooding all messages
+- **GossipSub**: Lower bandwidth usage with selective forwarding
+- **GossipSub + flood_publish**: Moderate bandwidth usage (flooding only for initial publishes)
+
+Network Scalability
+~~~~~~~~~~~~~~~~~~~
+
+- **FloodSub**: Limited scalability due to O(n) message forwarding
+- **GossipSub**: Better scalability with mesh-based routing
+- **GossipSub + flood_publish**: Good scalability with improved reliability
+
+Message Delivery
+~~~~~~~~~~~~~~~~
+
+- **FloodSub**: High delivery probability but with redundancy
+- **GossipSub**: Good delivery probability with efficiency
+- **GossipSub + flood_publish**: High delivery probability with controlled redundancy
+
+Interoperability
+----------------
+
+The py-libp2p FloodSub implementation is designed to be interoperable with other libp2p implementations:
+
+- **Protocol Compliance**: Follows the libp2p FloodSub specification
+- **Message Format**: Uses standard protobuf message format
+- **Peer Discovery**: Compatible with standard libp2p peer discovery mechanisms
+
+Testing and Validation
+----------------------
+
+The implementation includes comprehensive testing:
+
+- **Unit Tests**: Core functionality and edge cases
+- **Integration Tests**: End-to-end message flow testing
+- **Interoperability Tests**: Compatibility with other libp2p implementations
+- **Performance Tests**: Bandwidth and latency measurements
+
+Examples
+--------
+
+Basic FloodSub Usage
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from libp2p import new_host
+    from libp2p.pubsub.floodsub import FloodSub
+    from libp2p.pubsub.pubsub import Pubsub
+    from libp2p.tools.constants import FLOODSUB_PROTOCOL_ID
+
+    # Create host and FloodSub router
+    host = new_host()
+    floodsub = FloodSub(protocols=[FLOODSUB_PROTOCOL_ID])
+    pubsub = Pubsub(host=host, router=floodsub)
+
+    # Subscribe to topic
+    subscription = await pubsub.subscribe("my-topic")
+
+    # Publish message
+    await pubsub.publish("my-topic", b"Hello, FloodSub!")
+
+GossipSub with Flood Publish
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from libp2p.pubsub.gossipsub import GossipSub
+    from libp2p.tools.constants import GOSSIPSUB_PROTOCOL_ID
+
+    # Create GossipSub with flood_publish enabled
+    gossipsub = GossipSub(
+        protocols=[GOSSIPSUB_PROTOCOL_ID],
+        degree=10,
+        flood_publish=True  # Enable flooding for initial publishes
+    )
+
+Future Considerations
+---------------------
+
+Potential improvements and considerations for future development:
+
+1. **Peer Scoring Integration**: When peer scoring is implemented, flood_publish should respect score thresholds
+2. **Dynamic Configuration**: Runtime configuration of flood_publish based on network conditions
+3. **Metrics and Monitoring**: Enhanced metrics for flood_publish usage and effectiveness
+4. **Advanced Routing**: Integration with more sophisticated routing algorithms
+
+Conclusion
+----------
+
+The FloodSub implementation provides a reliable, simple pubsub solution for libp2p networks. The addition of the flood_publish feature to GossipSub offers a valuable hybrid approach that balances reliability and efficiency, making it suitable for a wide range of network scenarios and use cases.
+
+The implementation maintains compatibility with the libp2p specification while providing the flexibility needed for different network requirements and performance characteristics.

examples/floodsub/README.md

@@ -0,0 +1,150 @@
+# FloodSub Examples
+
+This directory contains examples demonstrating FloodSub functionality in py-libp2p.
+
+## What is FloodSub?
+
+FloodSub is the simplest pubsub routing algorithm in libp2p. It works by flooding messages to all connected peers that are subscribed to a topic. While not as efficient as more advanced algorithms like GossipSub, FloodSub is:
+
+- Simple to understand and implement
+- Reliable for small networks
+- Useful for testing and development
+- A good foundation for learning pubsub concepts
+
+## Examples
+
+### 1. Simple PubSub (`simple_pubsub.py`)
+
+A basic example showing:
+
+- Creating two libp2p hosts with FloodSub
+- Connecting them together
+- Publishing and subscribing to messages
+- Basic message flow
+
+**Run it:**
+
+```bash
+python examples/floodsub/simple_pubsub.py
+```
+
+**What it does:**
+
+1. Creates two libp2p nodes with FloodSub
+1. Connects them
+1. One node subscribes to a topic
+1. The other node publishes messages
+1. Shows received messages
+
+### 2. Multi-Node PubSub (`multi_node_pubsub.py`)
+
+A more advanced example showing:
+
+- Multiple nodes (3) in a network
+- Different nodes subscribing to different topics
+- Publishing from multiple nodes
+- Message flooding across the network
+
+**Run it:**
+
+```bash
+python examples/floodsub/multi_node_pubsub.py
+```
+
+**What it does:**
+
+1. Creates 3 libp2p nodes with FloodSub
+1. Connects them in a chain: A -> B -> C
+1. Each node subscribes to different topics
+1. Each node publishes messages to different topics
+1. Shows how messages flood through the network
+
+## Key Concepts
+
+### Publishing Messages
+
+```python
+# Publish a message to a topic
+await pubsub.publish("my-topic", b"Hello, FloodSub!")
+```
+
+### Subscribing to Topics
+
+```python
+# Subscribe to a topic
+subscription = await pubsub.subscribe("my-topic")
+
+# Receive messages
+message = await subscription.get()
+print(f"Received: {message.data.decode()}")
+```
+
+### Creating FloodSub
+
+```python
+from libp2p.pubsub.floodsub import FloodSub
+from libp2p.pubsub.pubsub import Pubsub
+from libp2p.tools.constants import FLOODSUB_PROTOCOL_ID
+
+# Create FloodSub router
+floodsub = FloodSub(protocols=[FLOODSUB_PROTOCOL_ID])
+
+# Create Pubsub with FloodSub
+pubsub = Pubsub(
+    host=host,
+    router=floodsub,
+    strict_signing=False,  # Disable for simplicity
+)
+```
+
+## Interoperability
+
+FloodSub in py-libp2p is designed to be compatible with other libp2p implementations:
+
+- **go-libp2p**: Uses the same FloodSub protocol
+- **js-libp2p**: Compatible with js-libp2p FloodSub
+- **rust-libp2p**: Should work with rust-libp2p FloodSub
+
+See the interoperability tests in `tests/interop/` for examples of cross-language communication.
+
+## Protocol Details
+
+FloodSub uses the `/floodsub/1.0.0` protocol and follows the libp2p pubsub specification:
+
+1. **Message Format**: Uses protobuf messages as defined in the libp2p pubsub spec
+1. **Flooding Algorithm**: Forwards messages to all connected peers subscribed to the topic
+1. **Deduplication**: Uses message IDs to prevent duplicate message processing
+1. **Subscription Management**: Handles topic subscriptions and unsubscriptions
+
+## Performance Characteristics
+
+- **Latency**: Low (direct flooding)
+- **Bandwidth**: High (floods to all peers)
+- **Scalability**: Poor (doesn't scale well with network size)
+- **Reliability**: High (simple, no complex routing)
+
+## Use Cases
+
+FloodSub is suitable for:
+
+- Small networks (< 100 peers)
+- Testing and development
+- Learning pubsub concepts
+- Networks where simplicity is more important than efficiency
+- Bootstrapping more complex pubsub algorithms
+
+## Limitations
+
+- Doesn't scale well with network size
+- High bandwidth usage
+- No intelligent routing or optimization
+- All peers receive all messages for subscribed topics
+
+## Next Steps
+
+After understanding FloodSub, consider exploring:
+
+- **GossipSub**: More efficient pubsub algorithm
+- **Custom Validators**: Message validation and filtering
+- **Message Signing**: Cryptographic message authentication
+- **Topic Discovery**: Finding peers interested in topics

examples/floodsub/__init__.py

@@ -0,0 +1 @@
+# FloodSub examples for py-libp2p