heartbeat/REFACTORING.md

HBD/HBC Separation Refactoring

Overview

The heartbeat monitoring system has been refactored into a modular package structure with separate client and server components. This allows users to install only what they need and provides clear separation of concerns.

New Package Structure

hbd/
├── __init__.py                 # Main package (minimal)
├── client/                     # HBC - System monitoring client
│   ├── __init__.py
│   ├── main.py                # Entry point (was hbc.py)
│   ├── config.py              # Client-specific configuration
│   ├── plugin.py              # Plugin framework
│   ├── threshold.py           # Threshold checking
│   └── plugins/               # Monitoring plugins
│       ├── cpu_monitor.py
│       ├── disk_monitor.py
│       ├── memory_monitor.py
│       ├── network_monitor.py
│       ├── filesystem_info.py
│       ├── os_info.py
│       └── nagios_runner.py
├── server/                     # HBD - Heartbeat daemon/server
│   ├── __init__.py
│   ├── main.py                # Server runtime (was server.py)
│   ├── cli.py                 # Command-line interface
│   ├── config.py              # Server-specific configuration
│   ├── http.py                # HTTP/REST API
│   ├── ws.py                  # WebSocket server
│   ├── udp.py                 # UDP heartbeat listener
│   ├── dns.py                 # DNS update functionality
│   ├── notify.py              # Notification handlers
│   ├── monitor.py             # Host monitoring
│   ├── hbdclass.py            # Host class definitions
│   ├── journal.py             # Message journaling
│   ├── templates/             # Jinja2 web templates
│   └── static/                # Web UI assets
└── common/                     # Shared utilities
    ├── __init__.py
    ├── proto.py               # Protocol encoding/decoding
    └── utils.py               # Common utilities

## Configuration Files

### Client Configuration (hbd/client/config.py)

Client-specific defaults:
- `hb_port`: Port where hbd servers listen (default: 50003)
- `interval`: Heartbeat interval in seconds (default: 10)
- `plugins`: Per-plugin configuration
- `thresholds`: Threshold configuration for monitoring

### Server Configuration (hbd/server/config.py)

Server-specific defaults:
- `hb_port`: Port to listen for heartbeats (default: 50003)
- `hbd_port`: HTTP API port (default: 50004)
- `ws_port`: WebSocket port (default: 50005)
- `logfile`: Log file path
- `pushsrv`, `pushover_token`, etc.: Notification settings
- `watchhosts`, `dyndnshosts`: Host monitoring
- `smtpserver`, etc.: Email settings
- `journal_*`: Message journaling settings

## Installation Options

### Install Core Only (minimal, PyYAML only)
```bash
pip install hbd

Install Client Only (for monitoring)

pip install hbd[client]
# Installs: PyYAML, psutil

Install Server Only (for daemon)

pip install hbd[server]
# Installs: PyYAML, websockets, mattermostdriver, aiohttp, Jinja2

Install Everything

pip install hbd[all]
# Installs all dependencies for both client and server

Development Installation

pip install -e ".[dev]"
# Includes all dependencies plus testing/linting tools

Command-Line Interfaces

HBC (Client)

hbc [options] host1 [host2 ...]

# Entry point: hbd.client.main:main
# Location: hbd/client/main.py

HBD (Server)

hbd [options]

# Entry point: hbd.server.cli:main
# Location: hbd/server/cli.py → hbd/server/main.py

Import Changes

Client Code

# Old imports
from .config import load_config
from .proto import dicttos, stodict
from .plugin import PluginRegistry

# New imports
from .config import load_config          # Still in client/
from ..common.proto import dicttos       # Moved to common/
from .plugin import PluginRegistry       # Still in client/

Server Code

# Old imports
from .config import load_config
from .proto import stodict
from .threshold import AlertLevel

# New imports
from .config import load_config          # Server-specific config
from ..common.proto import stodict       # Moved to common/
from ..client.threshold import AlertLevel # Client module

Plugin Code

# Old import
from hbd.plugin import MonitorPlugin

# New import
from hbd.client.plugin import MonitorPlugin

Benefits

1. Modular Installation: Install only what you need

   • Client-only systems don't need web server dependencies
   • Server-only systems don't need psutil

2. Clearer Architecture: Explicit separation of concerns

   • Client: System monitoring and data collection
   • Server: Heartbeat reception, web UI, notifications
   • Common: Shared protocol and utilities

3. Independent Evolution: Client and server can evolve separately

   • Different release cycles possible
   • Clear API boundaries via common/

4. Smaller Footprint: Reduced dependency installation

   • Client: ~1 dependency (psutil)
   • Server: ~4 dependencies (websockets, aiohttp, Jinja2, mattermostdriver)

Migration Guide

For Existing Installations

1. Reinstall the package:

   pip install -e ".[all]"  # For development
   # or
   pip install hbd[all]     # For production
   

2. Configuration files remain unchanged:

   • Both client and server read from ~/.hb.yaml
   • All existing config keys are supported in both configs
   • Server has additional keys (journal, websocket, email, etc.)
   • Client has minimal keys (interval, plugins, thresholds)

3. Commands remain the same:

   • hbc command works identically
   • hbd command works identically

For New Deployments

1. Client-only system (monitoring host):

   pip install hbd[client]
   hbc server1.example.com server2.example.com
   

2. Server-only system (monitoring daemon):

   pip install hbd[server]
   hbd -c /etc/hbd.yaml -f
   

3. Combined system (dev/test):

   pip install hbd[all]
   

Testing

All imports and entry points have been tested and validated:

• ✅ Package imports work correctly
• ✅ hbc command entry point functional
• ✅ hbd command entry point functional
• ✅ Optional dependencies properly configured
• ✅ All internal imports updated

Files Archived

The following files were renamed to avoid conflicts:

• hbd/config.py → hbd/config.py.old (split into client/server configs)
• hbd/hbc_old.py → hbd/hbc_old.py.bak (backup file)

Next Steps

1. Test client functionality with a monitoring host
2. Test server functionality with web UI and notifications
3. Update documentation (README.md) with new structure
4. Consider publishing to PyPI with new structure
5. Update any deployment scripts/Dockerfiles to use optional dependencies