# SWIM P2P
A production-ready Python implementation of the SWIM protocol (Scalable Weakly-consistent Infection-style Process Group Membership) for peer-to-peer membership and failure detection in distributed systems.
## Overview
SWIM is a gossip-based protocol for maintaining membership in distributed systems. This implementation provides:
* **Scalable** membership management with constant message load per node
* **Weakly-consistent** membership view across all nodes
* **Failure detection** with configurable timeouts and suspicion mechanisms
* **Efficient dissemination** of membership changes via piggybacked gossip
* **ZeroMQ integration** for reliable application-level messaging
* **Comprehensive metrics** and monitoring capabilities
* **Production-ready** with extensive testing and documentation
## 📦 Installation
Install from PyPI:
```bash
pip install swim_p2p
```
Or for development (editable install):
```bash
git clone <your-repo-url>
cd swim_p2p
pip install -e .
```
## Quick Start
### Using the CLI (`swim-node`)
After installation, you can run a standalone SWIM node:
```bash
swim-node --addr 127.0.0.1:5000 --seeds 127.0.0.1:5001
```
* `--addr` specifies the bind address (`host:port`).
* `--seeds` is a comma-separated list of existing node addresses to join.
### As a library in your Python code
```python
from swim.protocol.node import Node
from swim.transport.hybrid import HybridTransport
from swim.protocol.member import MemberList
from swim.protocol.failure_detector import FailureDetector
from swim.protocol.disseminator import GossipService
# Create transport
transport = HybridTransport()
await transport.bind(("127.0.0.1", 5000))
# Create SWIM components
members = MemberList()
failure_detector = FailureDetector(transport, members)
gossip = GossipService(transport, members)
# Create and start node
node = Node(transport, members, failure_detector, gossip)
await node.start()
# Join cluster
await node.join_cluster([("127.0.0.1", 5001)])
# Get cluster state
alive_members = members.get_alive_members()
print(f"Cluster members: {alive_members}")
```
### ZeroMQ Integration
For reliable messaging between nodes:
```python
from swim.integration.agent import ZMQAgentIntegration
# Create ZMQ agent
zmq_agent = ZMQAgentIntegration(
node_id="127.0.0.1:5000",
bind_address="127.0.0.1:6000",
event_dispatcher=event_dispatcher,
config={"NODE_NAME": "NodeA"}
)
await zmq_agent.start()
# Send reliable message
success = await zmq_agent.send_automated_check_in("127.0.0.1:5001")
```
## Architecture
The library is organized into several key components:
### Core Protocol (`swim.protocol`)
- **Member Management**: Track cluster membership and metadata
- **Failure Detection**: Detect node failures using SWIM algorithm
- **Gossip Dissemination**: Spread membership changes efficiently
- **Node Coordination**: Orchestrate all protocol components
### Transport Layer (`swim.transport`)
- **UDP Transport**: High-performance for local networks
- **TCP Transport**: Reliable for WAN deployments
- **Hybrid Transport**: Automatic selection based on conditions
### ZeroMQ Integration (`swim.integration`)
- **Reliable Messaging**: Guaranteed message delivery with acknowledgments
- **Circuit Breakers**: Fail-fast behavior for unhealthy nodes
- **Flow Control**: Prevent overwhelming slow nodes
- **Connection Management**: Automatic connection pooling
### Metrics & Monitoring (`swim.metrics`)
- **Protocol Metrics**: Membership changes, failure detection times
- **Network Metrics**: Bandwidth usage, message rates, latency
- **Performance Metrics**: CPU usage, memory consumption
- **Prometheus Integration**: Compatible metrics endpoint
### Lifeguard Enhancements (`swim.lifeguard`)
- **Adaptive Probe Rates**: Dynamic adjustment based on network conditions
- **Suspicion Timeout Optimization**: Intelligent timeout calculation
- **Network Condition Awareness**: Automatic adaptation to network quality
- **False Positive Reduction**: Advanced algorithms to minimize incorrect failures
## Project Structure
```
swim_p2p/ # Repository root
├── pyproject.toml # Build configuration and dependencies
├── README.md # This file - project overview and quick start
├── CHANGELOG.md # Version history and release notes
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # MIT license
├── MANIFEST.in # Package manifest for non-Python files
├── requirements.txt # Development dependencies
│
├── src/ # Source code directory
│ └── swim/ # Main package
│ ├── __init__.py # Package initialization and exports
│ ├── __version__.py # Version information
│ ├── py.typed # Type checking marker
│ ├── main.py # CLI entry point (swim-node command)
│ ├── config.py # Configuration management and validation
│ │
│ ├── protocol/ # Core SWIM protocol implementation
│ │ ├── __init__.py
│ │ ├── member.py # Cluster membership management
│ │ ├── failure_detector.py # SWIM failure detection algorithm
│ │ ├── disseminator.py # Gossip-based message dissemination
│ │ ├── node.py # Main node coordination and orchestration
│ │ ├── message.py # Protocol message definitions and serialization
│ │ └── sync.py # Cluster synchronization mechanisms
│ │
│ ├── transport/ # Network transport layer
│ │ ├── __init__.py
│ │ ├── base.py # Abstract transport interface
│ │ ├── udp.py # High-performance UDP transport
│ │ ├── tcp.py # Reliable TCP transport
│ │ └── hybrid.py # Intelligent transport selection
│ │
│ ├── integration/ # ZeroMQ integration layer
│ │ ├── __init__.py
│ │ ├── agent.py # Main ZMQ agent integration orchestrator
│ │ ├── load_balancer.py # Load balancing for ZMQ connections
│ │ ├── message_router.py # Message routing and distribution
│ │ │
│ │ ├── messaging/ # Reliable messaging components
│ │ │ ├── __init__.py
│ │ │ ├── ack_system.py # Message acknowledgment system
│ │ │ ├── buffer_monitor.py # Buffer overflow monitoring
│ │ │ ├── circuit_breaker.py # Circuit breaker pattern implementation
│ │ │ ├── congestion.py # Congestion control mechanisms
│ │ │ ├── message_registry.py # Message tracking and management
│ │ │ ├── reliability.py # Reliable message delivery
│ │ │ ├── trace.py # Distributed tracing support
│ │ │ └── workflow.py # Message workflow management
│ │ │
│ │ └── zmq/ # ZeroMQ-specific components
│ │ ├── __init__.py
│ │ ├── capacity_tracker.py # Connection capacity monitoring
│ │ ├── connection_manager.py # ZMQ connection lifecycle
│ │ ├── dealer.py # DEALER socket management
│ │ ├── flow_control.py # Flow control and backpressure
│ │ ├── monitoring.py # ZMQ socket monitoring
│ │ ├── ordering.py # Message ordering guarantees
│ │ └── router.py # ROUTER socket management
│ │
│ ├── lifeguard/ # Reliability enhancements
│ │ ├── __init__.py
│ │ ├── awareness.py # Network condition awareness
│ │ ├── probe_rate.py # Adaptive probe rate adjustment
│ │ └── timing.py # Intelligent timeout calculation
│ │
│ ├── metrics/ # Metrics and monitoring
│ │ ├── __init__.py
│ │ ├── collector.py # Metrics collection and aggregation
│ │ ├── latency.py # Latency measurement and tracking
│ │ ├── bandwidth.py # Bandwidth usage monitoring
│ │ ├── metrics_cli.py # CLI for metrics access
│ │ │
│ │ └── api/ # Metrics API components
│ │ ├── __init__.py
│ │ ├── cli.py # Command-line metrics interface
│ │ ├── client.py # Metrics API client
│ │ ├── integration.py # Integration with external systems
│ │ └── server.py # Metrics API server
│ │
│ ├── events/ # Event-driven architecture
│ │ ├── __init__.py
│ │ ├── dispatcher.py # Event dispatching and routing
│ │ ├── handlers.py # Event handler implementations
│ │ └── types.py # Event type definitions
│ │
│ ├── diagnostics/ # Diagnostic and debugging tools
│ │ ├── __init__.py
│ │ ├── health_checker.py # Health check implementations
│ │ ├── message_tracer.py # Message tracing and debugging
│ │ └── performance_analyzer.py # Performance analysis tools
│ │
│ └── utils/ # Utility functions and helpers
│ ├── __init__.py
│ ├── logging.py # Structured logging configuration
│ ├── network.py # Network utility functions
│ ├── rate_limiter.py # Rate limiting utilities
│ └── serialization.py # Data serialization helpers
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── unit/ # Unit tests
│ │ ├── __init__.py
│ │ ├── events/ # Event system tests
│ │ │ ├── test_dispatcher.py
│ │ │ ├── test_handlers.py
│ │ │ └── test_types.py
│ │ ├── lifeguard/ # Reliability enhancement tests
│ │ │ ├── test_awareness.py
│ │ │ ├── test_network_stress.py
│ │ │ ├── test_probe_rate.py
│ │ │ └── test_timing.py
│ │ ├── metrics/ # Metrics system tests
│ │ │ ├── test_bandwidth_monitor.py
│ │ │ ├── test_latency_tracker.py
│ │ │ └── test_metrics_collector.py
│ │ ├── protocol/ # Core protocol tests
│ │ │ ├── test_disseminator.py
│ │ │ ├── test_failure_detector.py
│ │ │ ├── test_member.py
│ │ │ ├── test_message.py
│ │ │ ├── test_node.py
│ │ │ └── test_sync.py
│ │ ├── transport/ # Transport layer tests
│ │ │ ├── __init__.py
│ │ │ ├── test_base.py
│ │ │ ├── test_hybrid.py
│ │ │ ├── test_tcp.py
│ │ │ ├── test_transport_fallback.py
│ │ │ └── test_udp.py
│ │ └── utils/ # Utility function tests
│ │ ├── test_logging.py
│ │ ├── test_network.py
│ │ ├── test_rate_limiter.py
│ │ └── test_serialization.py
│ │
│ ├── integration/ # Integration tests
│ │ ├── network_stress.py # Network stress testing
│ │ ├── send_big_message.py # Large message handling tests
│ │ ├── test_message_size.py # Message size limit tests
│ │ ├── test_swim_integration.py # End-to-end SWIM tests
│ │ └── test_udp_fallback.py # Transport fallback tests
│ │
│ └── swim_zmq/ # ZMQ integration tests
│ ├── test_both_one_n_two.py # Multi-node ZMQ tests
│ ├── test_enhanced_phase2.py # Enhanced ZMQ functionality tests
│ ├── test_phase_one.py # Basic ZMQ integration tests
│ └── test_phase_two.py # Advanced ZMQ feature tests
│
├── examples/ # Example applications
│ └── transport_example.py # Transport layer usage example
│
└── docs/ # Additional documentation
└── COMPREHENSIVE_DOCUMENTATION.md # Complete API reference
```
## Testing
Run the comprehensive test suite:
```bash
# Unit tests
pytest tests/unit/ -v
# Integration tests
pytest tests/integration/ -v
# All tests with coverage
pytest --cov=swim --cov-report=html
```
## Performance
- **Cluster Size**: Successfully tested with 1000+ nodes
- **Message Throughput**: 10,000+ messages/second per node
- **Failure Detection Time**: < 5 seconds average (configurable)
- **Memory Usage**: ~50MB per node baseline
- **CPU Usage**: < 5% on modern hardware for typical workloads
## Configuration
The library supports extensive configuration options:
```python
config = {
# Protocol timing
"protocol_period": 1.0,
"failure_timeout": 5.0,
"suspect_timeout": 3.0,
# Transport settings
"transport_type": "hybrid",
"udp_max_size": 1400,
# ZMQ settings
"zmq_port_offset": 1000,
"circuit_breaker_threshold": 5,
# Metrics
"enable_metrics": True,
"metrics_port": 8080
}
```
## Documentation
- **[Comprehensive Documentation](COMPREHENSIVE_DOCUMENTATION.md)**: Complete API reference and usage examples
- **[Agent Integration Patterns](COMPREHENSIVE_DOCUMENTATION.md#agent-integration-patterns)**: Theoretical guidance for building distributed agent systems
- **[Configuration Guide](COMPREHENSIVE_DOCUMENTATION.md#configuration)**: Detailed configuration options
- **[Performance Tuning](COMPREHENSIVE_DOCUMENTATION.md#performance-tuning)**: Optimization guidelines
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- SWIM protocol paper authors: Abhinandan Das, Indranil Gupta, Ashish Motivala
- HashiCorp Serf and Memberlist projects for Lifeguard enhancements
- ZeroMQ community for messaging patterns and best practices
## Roadmap
- **v1.1.0**: Encryption and authentication support
- **v1.2.0**: IPv6 support and enhanced security features
- **v1.3.0**: Advanced clustering algorithms and optimizations
---
**SWIM P2P v1.0.0** - Production-ready distributed membership protocol implementation
Raw data
{
"_id": null,
"home_page": null,
"name": "swim-p2p",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "swim, p2p, distributed, membership, failure-detection, zeromq",
"author": null,
"author_email": "Ruth Mutua <ruthmutua20@gmail.com>, Marriane Akeyo <annemarrieakeyo42@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/ba/6b3be5028dc65228ab204b75617bfe739a381a31734b204d85b5579c35c4/swim_p2p-1.0.0.tar.gz",
"platform": null,
"description": "# SWIM P2P\n\nA production-ready Python implementation of the SWIM protocol (Scalable Weakly-consistent Infection-style Process Group Membership) for peer-to-peer membership and failure detection in distributed systems.\n\n## Overview\n\nSWIM is a gossip-based protocol for maintaining membership in distributed systems. This implementation provides:\n\n* **Scalable** membership management with constant message load per node\n* **Weakly-consistent** membership view across all nodes\n* **Failure detection** with configurable timeouts and suspicion mechanisms\n* **Efficient dissemination** of membership changes via piggybacked gossip\n* **ZeroMQ integration** for reliable application-level messaging\n* **Comprehensive metrics** and monitoring capabilities\n* **Production-ready** with extensive testing and documentation\n\n## \ud83d\udce6 Installation\n\nInstall from PyPI:\n\n```bash\npip install swim_p2p\n```\n\nOr for development (editable install):\n\n```bash\ngit clone <your-repo-url>\ncd swim_p2p\npip install -e .\n```\n\n## Quick Start\n\n### Using the CLI (`swim-node`)\n\nAfter installation, you can run a standalone SWIM node:\n\n```bash\nswim-node --addr 127.0.0.1:5000 --seeds 127.0.0.1:5001\n```\n\n* `--addr` specifies the bind address (`host:port`).\n* `--seeds` is a comma-separated list of existing node addresses to join.\n\n### As a library in your Python code\n\n```python\nfrom swim.protocol.node import Node\nfrom swim.transport.hybrid import HybridTransport\nfrom swim.protocol.member import MemberList\nfrom swim.protocol.failure_detector import FailureDetector\nfrom swim.protocol.disseminator import GossipService\n\n# Create transport\ntransport = HybridTransport()\nawait transport.bind((\"127.0.0.1\", 5000))\n\n# Create SWIM components\nmembers = MemberList()\nfailure_detector = FailureDetector(transport, members)\ngossip = GossipService(transport, members)\n\n# Create and start node\nnode = Node(transport, members, failure_detector, gossip)\nawait node.start()\n\n# Join cluster\nawait node.join_cluster([(\"127.0.0.1\", 5001)])\n\n# Get cluster state\nalive_members = members.get_alive_members()\nprint(f\"Cluster members: {alive_members}\")\n```\n\n### ZeroMQ Integration\n\nFor reliable messaging between nodes:\n\n```python\nfrom swim.integration.agent import ZMQAgentIntegration\n\n# Create ZMQ agent\nzmq_agent = ZMQAgentIntegration(\n node_id=\"127.0.0.1:5000\",\n bind_address=\"127.0.0.1:6000\",\n event_dispatcher=event_dispatcher,\n config={\"NODE_NAME\": \"NodeA\"}\n)\n\nawait zmq_agent.start()\n\n# Send reliable message\nsuccess = await zmq_agent.send_automated_check_in(\"127.0.0.1:5001\")\n```\n\n## Architecture\n\nThe library is organized into several key components:\n\n### Core Protocol (`swim.protocol`)\n- **Member Management**: Track cluster membership and metadata\n- **Failure Detection**: Detect node failures using SWIM algorithm\n- **Gossip Dissemination**: Spread membership changes efficiently\n- **Node Coordination**: Orchestrate all protocol components\n\n### Transport Layer (`swim.transport`)\n- **UDP Transport**: High-performance for local networks\n- **TCP Transport**: Reliable for WAN deployments\n- **Hybrid Transport**: Automatic selection based on conditions\n\n### ZeroMQ Integration (`swim.integration`)\n- **Reliable Messaging**: Guaranteed message delivery with acknowledgments\n- **Circuit Breakers**: Fail-fast behavior for unhealthy nodes\n- **Flow Control**: Prevent overwhelming slow nodes\n- **Connection Management**: Automatic connection pooling\n\n### Metrics & Monitoring (`swim.metrics`)\n- **Protocol Metrics**: Membership changes, failure detection times\n- **Network Metrics**: Bandwidth usage, message rates, latency\n- **Performance Metrics**: CPU usage, memory consumption\n- **Prometheus Integration**: Compatible metrics endpoint\n\n### Lifeguard Enhancements (`swim.lifeguard`)\n- **Adaptive Probe Rates**: Dynamic adjustment based on network conditions\n- **Suspicion Timeout Optimization**: Intelligent timeout calculation\n- **Network Condition Awareness**: Automatic adaptation to network quality\n- **False Positive Reduction**: Advanced algorithms to minimize incorrect failures\n\n## Project Structure\n\n```\nswim_p2p/ # Repository root\n\u251c\u2500\u2500 pyproject.toml # Build configuration and dependencies\n\u251c\u2500\u2500 README.md # This file - project overview and quick start\n\u251c\u2500\u2500 CHANGELOG.md # Version history and release notes\n\u251c\u2500\u2500 CONTRIBUTING.md # Contribution guidelines\n\u251c\u2500\u2500 LICENSE # MIT license\n\u251c\u2500\u2500 MANIFEST.in # Package manifest for non-Python files\n\u251c\u2500\u2500 requirements.txt # Development dependencies\n\u2502\n\u251c\u2500\u2500 src/ # Source code directory\n\u2502 \u2514\u2500\u2500 swim/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization and exports\n\u2502 \u251c\u2500\u2500 __version__.py # Version information\n\u2502 \u251c\u2500\u2500 py.typed # Type checking marker\n\u2502 \u251c\u2500\u2500 main.py # CLI entry point (swim-node command)\n\u2502 \u251c\u2500\u2500 config.py # Configuration management and validation\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 protocol/ # Core SWIM protocol implementation\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 member.py # Cluster membership management\n\u2502 \u2502 \u251c\u2500\u2500 failure_detector.py # SWIM failure detection algorithm\n\u2502 \u2502 \u251c\u2500\u2500 disseminator.py # Gossip-based message dissemination\n\u2502 \u2502 \u251c\u2500\u2500 node.py # Main node coordination and orchestration\n\u2502 \u2502 \u251c\u2500\u2500 message.py # Protocol message definitions and serialization\n\u2502 \u2502 \u2514\u2500\u2500 sync.py # Cluster synchronization mechanisms\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 transport/ # Network transport layer\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 base.py # Abstract transport interface\n\u2502 \u2502 \u251c\u2500\u2500 udp.py # High-performance UDP transport\n\u2502 \u2502 \u251c\u2500\u2500 tcp.py # Reliable TCP transport\n\u2502 \u2502 \u2514\u2500\u2500 hybrid.py # Intelligent transport selection\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 integration/ # ZeroMQ integration layer\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 agent.py # Main ZMQ agent integration orchestrator\n\u2502 \u2502 \u251c\u2500\u2500 load_balancer.py # Load balancing for ZMQ connections\n\u2502 \u2502 \u251c\u2500\u2500 message_router.py # Message routing and distribution\n\u2502 \u2502 \u2502\n\u2502 \u2502 \u251c\u2500\u2500 messaging/ # Reliable messaging components\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 ack_system.py # Message acknowledgment system\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 buffer_monitor.py # Buffer overflow monitoring\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 circuit_breaker.py # Circuit breaker pattern implementation\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 congestion.py # Congestion control mechanisms\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 message_registry.py # Message tracking and management\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 reliability.py # Reliable message delivery\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 trace.py # Distributed tracing support\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 workflow.py # Message workflow management\n\u2502 \u2502 \u2502\n\u2502 \u2502 \u2514\u2500\u2500 zmq/ # ZeroMQ-specific components\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 capacity_tracker.py # Connection capacity monitoring\n\u2502 \u2502 \u251c\u2500\u2500 connection_manager.py # ZMQ connection lifecycle\n\u2502 \u2502 \u251c\u2500\u2500 dealer.py # DEALER socket management\n\u2502 \u2502 \u251c\u2500\u2500 flow_control.py # Flow control and backpressure\n\u2502 \u2502 \u251c\u2500\u2500 monitoring.py # ZMQ socket monitoring\n\u2502 \u2502 \u251c\u2500\u2500 ordering.py # Message ordering guarantees\n\u2502 \u2502 \u2514\u2500\u2500 router.py # ROUTER socket management\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 lifeguard/ # Reliability enhancements\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 awareness.py # Network condition awareness\n\u2502 \u2502 \u251c\u2500\u2500 probe_rate.py # Adaptive probe rate adjustment\n\u2502 \u2502 \u2514\u2500\u2500 timing.py # Intelligent timeout calculation\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 metrics/ # Metrics and monitoring\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 collector.py # Metrics collection and aggregation\n\u2502 \u2502 \u251c\u2500\u2500 latency.py # Latency measurement and tracking\n\u2502 \u2502 \u251c\u2500\u2500 bandwidth.py # Bandwidth usage monitoring\n\u2502 \u2502 \u251c\u2500\u2500 metrics_cli.py # CLI for metrics access\n\u2502 \u2502 \u2502\n\u2502 \u2502 \u2514\u2500\u2500 api/ # Metrics API components\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 cli.py # Command-line metrics interface\n\u2502 \u2502 \u251c\u2500\u2500 client.py # Metrics API client\n\u2502 \u2502 \u251c\u2500\u2500 integration.py # Integration with external systems\n\u2502 \u2502 \u2514\u2500\u2500 server.py # Metrics API server\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 events/ # Event-driven architecture\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 dispatcher.py # Event dispatching and routing\n\u2502 \u2502 \u251c\u2500\u2500 handlers.py # Event handler implementations\n\u2502 \u2502 \u2514\u2500\u2500 types.py # Event type definitions\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 diagnostics/ # Diagnostic and debugging tools\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 health_checker.py # Health check implementations\n\u2502 \u2502 \u251c\u2500\u2500 message_tracer.py # Message tracing and debugging\n\u2502 \u2502 \u2514\u2500\u2500 performance_analyzer.py # Performance analysis tools\n\u2502 \u2502\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions and helpers\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 logging.py # Structured logging configuration\n\u2502 \u251c\u2500\u2500 network.py # Network utility functions\n\u2502 \u251c\u2500\u2500 rate_limiter.py # Rate limiting utilities\n\u2502 \u2514\u2500\u2500 serialization.py # Data serialization helpers\n\u2502\n\u251c\u2500\u2500 tests/ # Test suite\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 unit/ # Unit tests\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 events/ # Event system tests\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_dispatcher.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_handlers.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 test_types.py\n\u2502 \u2502 \u251c\u2500\u2500 lifeguard/ # Reliability enhancement tests\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_awareness.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_network_stress.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_probe_rate.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 test_timing.py\n\u2502 \u2502 \u251c\u2500\u2500 metrics/ # Metrics system tests\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_bandwidth_monitor.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_latency_tracker.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 test_metrics_collector.py\n\u2502 \u2502 \u251c\u2500\u2500 protocol/ # Core protocol tests\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_disseminator.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_failure_detector.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_member.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_message.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_node.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 test_sync.py\n\u2502 \u2502 \u251c\u2500\u2500 transport/ # Transport layer tests\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_base.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_hybrid.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_tcp.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 test_transport_fallback.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 test_udp.py\n\u2502 \u2502 \u2514\u2500\u2500 utils/ # Utility function tests\n\u2502 \u2502 \u251c\u2500\u2500 test_logging.py\n\u2502 \u2502 \u251c\u2500\u2500 test_network.py\n\u2502 \u2502 \u251c\u2500\u2500 test_rate_limiter.py\n\u2502 \u2502 \u2514\u2500\u2500 test_serialization.py\n\u2502 \u2502\n\u2502 \u251c\u2500\u2500 integration/ # Integration tests\n\u2502 \u2502 \u251c\u2500\u2500 network_stress.py # Network stress testing\n\u2502 \u2502 \u251c\u2500\u2500 send_big_message.py # Large message handling tests\n\u2502 \u2502 \u251c\u2500\u2500 test_message_size.py # Message size limit tests\n\u2502 \u2502 \u251c\u2500\u2500 test_swim_integration.py # End-to-end SWIM tests\n\u2502 \u2502 \u2514\u2500\u2500 test_udp_fallback.py # Transport fallback tests\n\u2502 \u2502\n\u2502 \u2514\u2500\u2500 swim_zmq/ # ZMQ integration tests\n\u2502 \u251c\u2500\u2500 test_both_one_n_two.py # Multi-node ZMQ tests\n\u2502 \u251c\u2500\u2500 test_enhanced_phase2.py # Enhanced ZMQ functionality tests\n\u2502 \u251c\u2500\u2500 test_phase_one.py # Basic ZMQ integration tests\n\u2502 \u2514\u2500\u2500 test_phase_two.py # Advanced ZMQ feature tests\n\u2502\n\u251c\u2500\u2500 examples/ # Example applications\n\u2502 \u2514\u2500\u2500 transport_example.py # Transport layer usage example\n\u2502\n\u2514\u2500\u2500 docs/ # Additional documentation\n \u2514\u2500\u2500 COMPREHENSIVE_DOCUMENTATION.md # Complete API reference\n```\n\n## Testing\n\nRun the comprehensive test suite:\n\n```bash\n# Unit tests\npytest tests/unit/ -v\n\n# Integration tests\npytest tests/integration/ -v\n\n# All tests with coverage\npytest --cov=swim --cov-report=html\n```\n\n## Performance\n\n- **Cluster Size**: Successfully tested with 1000+ nodes\n- **Message Throughput**: 10,000+ messages/second per node\n- **Failure Detection Time**: < 5 seconds average (configurable)\n- **Memory Usage**: ~50MB per node baseline\n- **CPU Usage**: < 5% on modern hardware for typical workloads\n\n## Configuration\n\nThe library supports extensive configuration options:\n\n```python\nconfig = {\n # Protocol timing\n \"protocol_period\": 1.0,\n \"failure_timeout\": 5.0,\n \"suspect_timeout\": 3.0,\n \n # Transport settings\n \"transport_type\": \"hybrid\",\n \"udp_max_size\": 1400,\n \n # ZMQ settings\n \"zmq_port_offset\": 1000,\n \"circuit_breaker_threshold\": 5,\n \n # Metrics\n \"enable_metrics\": True,\n \"metrics_port\": 8080\n}\n```\n\n## Documentation\n\n- **[Comprehensive Documentation](COMPREHENSIVE_DOCUMENTATION.md)**: Complete API reference and usage examples\n- **[Agent Integration Patterns](COMPREHENSIVE_DOCUMENTATION.md#agent-integration-patterns)**: Theoretical guidance for building distributed agent systems\n- **[Configuration Guide](COMPREHENSIVE_DOCUMENTATION.md#configuration)**: Detailed configuration options\n- **[Performance Tuning](COMPREHENSIVE_DOCUMENTATION.md#performance-tuning)**: Optimization guidelines\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- SWIM protocol paper authors: Abhinandan Das, Indranil Gupta, Ashish Motivala\n- HashiCorp Serf and Memberlist projects for Lifeguard enhancements\n- ZeroMQ community for messaging patterns and best practices\n\n## Roadmap\n\n- **v1.1.0**: Encryption and authentication support\n- **v1.2.0**: IPv6 support and enhanced security features\n- **v1.3.0**: Advanced clustering algorithms and optimizations\n\n---\n\n**SWIM P2P v1.0.0** - Production-ready distributed membership protocol implementation\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SWIM Protocol implementation for P2P membership and failure detection with ZeroMQ integration",
"version": "1.0.0",
"project_urls": null,
"split_keywords": [
"swim",
" p2p",
" distributed",
" membership",
" failure-detection",
" zeromq"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "758089cab025b4254b72f6ff2070eb683ae5e55580bb6aa1f948df9f14ae667d",
"md5": "a018579436506aec51c3ec2da0252bb1",
"sha256": "d35e174a007b1305dc544c71794f7cf664b8aa1b7a02d01b34176c6a3651f180"
},
"downloads": -1,
"filename": "swim_p2p-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a018579436506aec51c3ec2da0252bb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 245120,
"upload_time": "2025-07-18T17:23:39",
"upload_time_iso_8601": "2025-07-18T17:23:39.118691Z",
"url": "https://files.pythonhosted.org/packages/75/80/89cab025b4254b72f6ff2070eb683ae5e55580bb6aa1f948df9f14ae667d/swim_p2p-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0fba6b3be5028dc65228ab204b75617bfe739a381a31734b204d85b5579c35c4",
"md5": "dcb1ade6adc537578b10cac8c799191e",
"sha256": "24aa1cd7dcc626f8210e113cd461171c624212bc99670b6dd3c4ff8cc33277a2"
},
"downloads": -1,
"filename": "swim_p2p-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dcb1ade6adc537578b10cac8c799191e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 290454,
"upload_time": "2025-07-18T17:23:41",
"upload_time_iso_8601": "2025-07-18T17:23:41.673180Z",
"url": "https://files.pythonhosted.org/packages/0f/ba/6b3be5028dc65228ab204b75617bfe739a381a31734b204d85b5579c35c4/swim_p2p-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 17:23:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "swim-p2p"
}
JSON