Heartbeat

For a short summary of a Heartbeat, see Reventless Components Overview.

Framework Implementation

This component follows the Reventless Component Structure Pattern, using separate files for interface definitions (Heartbeat.res), builder logic (Heartbeat_Builder.res), adapter interface (Heartbeat_Adapter.res), and callback handlers (Heartbeat_Callback.res).

Overview

The Heartbeat component provides periodic health check signals and keepalive mechanisms, specifically designed to integrate with the platform admin's Plugin ExtensionPoint system. It enables health monitoring, periodic extension invocations, and watchdog timer functionality.

Purpose and Responsibilities

• Responsibility: Generate periodic heartbeat signals for health monitoring and extension triggering
• In: Timeout configuration and admin Plugin ExtensionPoint connection details
• Out: Periodic heartbeat messages sent to admin Plugin ExtensionPoint

Component Configuration

The Heartbeat component requires minimal configuration, focusing on timing and admin Plugin ExtensionPoint integration:

Basic Setup

// Create a heartbeat component
let heartbeat = Reventless.Heartbeat.make(~name="system-heartbeat")

// Connect to admin Plugin ExtensionPoint with timeout configuration
let connectHeartbeat = (~adminCommandTopic, ~runtime) => {
  heartbeat->Reventless.Heartbeat.connect(
    ~runtime,
    ~remoteChannel=adminCommandTopic.outputs,
    ~timeout=5, // Send heartbeat every 5 minutes
  )
}

Handler Creation

// Create a heartbeat handler for runtime use
let heartbeatHandler = Reventless.Heartbeat.makeHandler(
  ~id="health-monitor",
  ~timeout=10, // 10 minute timeout
  ~publishToCorePluginExtensionPoint=adminPublisher,
)

Runtime Behavior

The Heartbeat component operates through a simple, automated flow:

Heartbeat Generation Flow

Message Structure

The heartbeat generates standardized messages for the admin Plugin ExtensionPoint:

// Generated heartbeat message structure
{
  Message.id: "health-monitor", // Configured ID
  meta: {
    service: "CorePluginExtensionPoint",
    time: "2024-01-26T10:30:00.000Z", // Current timestamp
    ip: "",
    user: "Heartbeat",
    msgId: "uuid-generated",
    correlationId: "uuid-generated",
  },
  commandJson: "Heartbeat(10)", // Timeout value encoded
}

Integration Points

The Heartbeat component is specifically designed to integrate with the platform admin architecture:

Admin Plugin ExtensionPoint Integration

Extension Response Patterns

Extensions can respond to heartbeat signals in various ways:

// Health check extension responding to heartbeat
let healthCheckExtension = (heartbeatCommand) => {
  switch heartbeatCommand {
  | Heartbeat(timeout) =>
    // Perform health checks
    checkDatabaseConnection()
    ->Promise.then(dbStatus =>
      checkExternalAPIs()
      ->Promise.then(apiStatus => {
        // Publish health status events
        publishHealthStatus(dbStatus, apiStatus)
      })
    )
  }
}

Common Patterns

Health Monitoring Pattern

// Set up heartbeat for health monitoring
let healthMonitorHeartbeat = Reventless.Heartbeat.make(~name="health-monitor")

// Connect with appropriate timeout for health checks
healthMonitorHeartbeat->Reventless.Heartbeat.connect(
  ~runtime,
  ~remoteChannel=adminCommandTopic.outputs,
  ~timeout=5, // Check health every 5 minutes
)

Cleanup Pattern

// Heartbeat for periodic cleanup tasks
let cleanupHeartbeat = Reventless.Heartbeat.make(~name="cleanup-scheduler")

cleanupHeartbeat->Reventless.Heartbeat.connect(
  ~runtime,
  ~remoteChannel=adminCommandTopic.outputs,
  ~timeout=60, // Run cleanup every hour
)

Watchdog Pattern

// Short-interval heartbeat for watchdog functionality
let watchdogHeartbeat = Reventless.Heartbeat.make(~name="watchdog")

watchdogHeartbeat->Reventless.Heartbeat.connect(
  ~runtime,
  ~remoteChannel=adminCommandTopic.outputs,
  ~timeout=1, // Check every minute for quick response
)

Multi-Purpose Monitoring

// Single heartbeat triggering multiple monitoring extensions
let systemHeartbeat = Reventless.Heartbeat.make(~name="system-monitor")

// Extensions can differentiate based on heartbeat ID
let multiHandler = Reventless.Heartbeat.makeHandler(
  ~id="system-monitor",
  ~timeout=15,
  ~publishToCorePluginExtensionPoint=adminPublisher,
)

Comparison with Scheduler

The Heartbeat component serves a specific purpose compared to the general-purpose Scheduler:

Feature	Heartbeat	Scheduler
Target	Admin Plugin ExtensionPoint only	Any component/service
Purpose	Health monitoring, keepalive	General scheduled workflows
Configuration	Fixed at deploy-time	Dynamic at runtime
Operations	None (automatic)	createSchedule, deleteSchedule
Message Format	Standardized heartbeat	Custom payload
Integration	Tightly coupled to admin Plugin ExtensionPoint	Loosely coupled

When to Use Heartbeat

Choose Heartbeat for:

• Health monitoring and system checks
• Periodic extension invocations via admin Plugin ExtensionPoint
• Simple, fixed-interval triggers
• Framework-level monitoring needs
• Keepalive mechanisms

Choose Scheduler for:

• Application-specific scheduled workflows
• Dynamic schedule management
• Custom payload delivery
• Flexible target configuration
• User-configurable timing

Pulumi

The Heartbeat component is deployed as infrastructure that creates CloudWatch Event Rules, Lambda permissions, and IAM policies. All execution happens automatically once deployed.

// Deployment creates all necessary infrastructure
let heartbeat = Reventless.Heartbeat.make(~name="system-heartbeat", ~opts=pulumiOpts)

// Connection configures the runtime integration
heartbeat->Reventless.Heartbeat.connect(~runtime, ~remoteChannel, ~timeout=10)

AWS Implementation

For detailed AWS-specific implementation including CloudWatch Events integration, Lambda permissions, IAM policies, and admin Plugin SQS integration, see Heartbeat → EventBridge Rule + Lambda.