Skip to content

Events Module¤

Overview¤

The Events module provides a comprehensive event-driven architecture for PANTHER's network testing framework. It implements a type-safe, hierarchical event system that enables real-time monitoring, logging, and coordination across all testing components.

Architecture¤

The module follows a domain-driven design with specialized event types for different aspects of network testing:

Event Categories¤

  • Test Events - Test lifecycle, execution, and result events
  • Environment Events - Network and execution environment state changes
  • Service Events - Service deployment, health, and lifecycle management
  • Assertion Events - Test assertion validation and results
  • Step Events - Individual test step execution tracking
  • Plugin Events - Plugin loading, initialization, and lifecycle
  • Metrics Events - Performance metrics collection and aggregation
  • Experiment Events - Experiment-level execution coordination

Core Components¤

events/
├── base/                    # Foundation classes and interfaces
│   ├── event_base.py       # BaseEvent class and UUID generation
│   ├── event_emitter_base.py # Event emission abstractions
│   └── state_base.py       # State management foundation
├── {domain}/               # Domain-specific event implementations
│   ├── events.py          # Event type definitions
│   ├── states.py          # State management
│   └── emitter.py         # Event emission logic
└── emitter_registry.py    # Global emitter coordination

Design Principles¤

Event Deduplication¤

Events use content-based UUID generation to prevent duplicate processing across distributed test environments.

Type Safety¤

Strong typing through dataclasses and enums ensures compile-time validation of event structure and content.

State Tracking¤

Each domain maintains state managers that track entity lifecycle and enable sophisticated workflow coordination.

Immutable Events¤

Events are immutable once created, ensuring reliable audit trails and preventing race conditions.

Event Lifecycle¤

  1. Creation - Events created with deterministic UUIDs and timestamps
  2. Emission - Domain emitters broadcast events to registered observers
  3. Processing - Observers filter and handle relevant events
  4. State Updates - State managers update entity status based on events
  5. Persistence - Events stored for audit, debugging, and analytics

Integration Points¤

Observer System¤

Events integrate seamlessly with the Observer module through the IObserver interface.

Plugin Architecture¤

Plugin events enable dynamic service loading and lifecycle management.

Metrics Collection¤

Metrics events drive performance monitoring and system health tracking.

Test Coordination¤

Test and step events orchestrate complex multi-service test scenarios.

Performance Characteristics¤

  • Memory Efficient - Events use slots for reduced memory footprint
  • Thread Safe - Immutable design prevents concurrent access issues
  • Scalable - Content-based deduplication handles high event volumes
  • Fast Lookups - Enum-based event types enable O(1) filtering

Extension Points¤

The module supports extension through:

  • Custom event types inheriting from domain base classes
  • Additional state managers for new entity types
  • Specialized emitters for custom distribution logic
  • Plugin-based event processors

Dependencies¤

  • dataclasses - Event structure definition
  • enum - Type-safe event categorization
  • uuid - Deterministic event identification
  • datetime - Temporal event tracking
  • typing - Type hints and generic support

Error Handling¤

Events include error tracking capabilities: - Exception capture in error events - Stack trace preservation for debugging - Error severity classification - Automatic error event generation on failures

The Events module forms the nervous system of PANTHER's testing infrastructure, enabling sophisticated monitoring, coordination, and analytics across all testing components.