Message Bus & Event System

Relevant source files

The following files were used as context for generating this wiki page:

• dev/knowledge/backend/message-bus.md
• backend/infrahub/message_bus/init.py
• dev/knowledge/backend/events.md
• dev/guides/backend/creating-events.md
• dev/guides/backend/creating-messages.md
• dev/adr/0002-events-system.md
• dev/adr/0004-message-bus.md

The Message Bus and Event System provide the communication infrastructure for decoupled interaction between backend components and external consumers. The Event System handles internal notifications and state changes within the application, while the Message Bus facilitates asynchronous messaging and integration with external systems.

These systems allow Infrahub to maintain a reactive architecture, where actions like schema updates or data modifications trigger downstream processes such as artifact regeneration or webhook deliveries without tight coupling.
Sources: dev/knowledge/backend/message-bus.md, dev/knowledge/backend/events.md, dev/adr/0002-events-system.md

Message Bus Architecture

The Message Bus acts as a publisher-subscriber mechanism that decouples message producers from consumers. It supports asynchronous communication, allowing the backend to emit notifications about significant system changes without waiting for consumer processing.

Key Components

Component	Description
Publisher	Emits messages to the bus.
Topic	Logical channel used to categorize messages.
Subscriber	Listens for messages on specific topics.
Message	Data payload containing the event information.

Sources: dev/knowledge/backend/message-bus.md, dev/adr/0004-message-bus.md

Message Flow

The following diagram illustrates the lifecycle of a message from publication to consumption.

The diagram shows how a single producer publishes to the Message Bus, which then routes messages to specific topics for various subscribers.
Sources: dev/knowledge/backend/message-bus.md, dev/adr/0004-message-bus.md

Event System

The Event System manages internal notifications and triggers based on state changes. It is primarily used for synchronous and asynchronous hooks within the Infrahub core logic.

Internal Event Lifecycle

When a significant action occurs (e.g., a branch merge or a node update), the system creates an event. This event is then dispatched to registered handlers.

The sequence shows the internal flow where the core logic requests an event creation, which the Event Manager validates and dispatches to handlers.
Sources: dev/knowledge/backend/events.md, dev/adr/0002-events-system.md

Creating New Events

To create a new event type, you must follow these steps:

1. Define the event class in the backend models.
2. Register the event type in the event registry.
3. Implement the logic to emit the event at the appropriate point in the code.
4. Define handlers that react to the event.

Sources: dev/guides/backend/creating-events.md

Integration and Messaging Patterns

Infrahub uses specific patterns to ensure reliability and scalability in its messaging.

Topic Naming Conventions

Topics follow a structured naming pattern to facilitate easy subscription and filtering:
infrahub.<domain>.<action>

Example topics:

• infrahub.schema.updated
• infrahub.node.created
• infrahub.branch.merged

Sources: dev/knowledge/backend/message-bus.md, dev/guides/backend/creating-messages.md

Message Structure

Messages are structured as JSON payloads. Every message includes a header with metadata and a body containing the specific event data.

{
  "header": {
    "message_id": "uuid-v4",
    "timestamp": "2024-05-20T10:00:00Z",
    "topic": "infrahub.node.created"
  },
  "body": {
    "node_id": "node-123",
    "branch": "main",
    "user": "admin"
  }
}

Sources: dev/knowledge/backend/message-bus.md, dev/guides/backend/creating-messages.md

Configuration and Implementation

The implementation details for the message bus are located in backend/infrahub/message_bus/.

Core Classes

The system utilizes several core classes to manage messaging:

• MessageBusClient: The primary interface for interacting with the bus.
• Message: Represents the data being transmitted.
• Subscriber: Interface for components that wish to receive messages.

Sources: backend/infrahub/message_bus/init.py

Implementation Example

The following Python snippet demonstrates how the MessageBusClient is used to publish a message.

from infrahub.message_bus import MessageBusClient, Message

async def notify_change(node_id: str):
    client = MessageBusClient()
    message = Message(
        topic="infrahub.node.updated",
        data={"id": node_id, "status": "modified"}
    )
    await client.publish(message)

Sources: backend/infrahub/message_bus/init.py:10-25, dev/guides/backend/creating-messages.md

Summary

The Message Bus and Event System are critical for Infrahub's scalability and extensibility. By using the Event System for internal lifecycle hooks and the Message Bus for decoupled asynchronous communication, Infrahub ensures that state changes propagate reliably to both internal workers and external integrations. This architecture enables features like automatic artifact regeneration and real-time synchronization with external sources of truth.