Module: Kaal::Backend::DispatchLogging

Included in:
MemoryAdapter, RedisAdapter, Internal::ActiveRecord::DatabaseBackend, Internal::ActiveRecord::MySQLBackend, Internal::ActiveRecord::PostgresBackend, Internal::Sequel::DatabaseBackend, Internal::Sequel::MySQLBackend, Internal::Sequel::PostgresBackend
Defined in:
lib/kaal/backend/dispatch_logging.rb

Overview

Shared module for dispatch logging across backend adapters.

Provides methods to log cron job dispatch attempts via the dispatch registry for audit and observability purposes. Adapters that support dispatch logging should include this module and implement a dispatch_registry method.

Examples:

Implementing in an adapter

class MyAdapter < Adapter
  include DispatchLogging

  def dispatch_registry
    @dispatch_registry ||= Kaal::Dispatch::MemoryEngine.new
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.parse_lock_key(key) ⇒ Object 



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/kaal/backend/dispatch_logging.rb', line 55

def self.parse_lock_key(key)
  parts = key.split(':')
  invalid_message = "Invalid dispatch lock key format: #{key.inspect}"
  dispatch_index = parts[0...-1].rindex('dispatch')
  timestamp = parts[-1]
  valid_key = parts.length >= 4 && dispatch_index&.positive? && timestamp.match?(/\A\d+\z/)
  validate_lock_key!(valid_key, invalid_message)

  fire_time_unix = timestamp.to_i
  cron_key = parts[(dispatch_index + 1)...-1].join(':')
  validate_lock_key!(!cron_key.empty?, invalid_message)

  fire_time = Time.at(fire_time_unix).utc

  [cron_key, fire_time]
end

Instance Method Details

#dispatch_registry ⇒ Object 



27
28
29
 
# File 'lib/kaal/backend/dispatch_logging.rb', line 27

def dispatch_registry
  nil
end

#log_dispatch_attempt(key) ⇒ void

This method returns an undefined value.

Log a dispatch attempt via the dispatch registry.

Only logs if Kaal.configuration.enable_log_dispatch_registry is true.

Parameters:

  • key (String) —

    the lock key (format: “namespace:dispatch:cron_key:fire_time”)



38
39
40
 
# File 'lib/kaal/backend/dispatch_logging.rb', line 38

def log_dispatch_attempt(key)
  dispatch_attempt_logger.call(key)
end

#parse_lock_key(key) ⇒ Array<String, Time>

Parse a lock key to extract cron job key and fire time.

Lock key format: “namespace:dispatch:cron_key:fire_time” Parses by splitting on colon: removes namespace and “dispatch”, then rejoins remaining parts as the cron key.

Parameters:

  • key (String) —

    the lock key to parse

Returns:

  • (Array<String, Time>) —

    tuple of [cron_key, fire_time]



51
52
53
 
# File 'lib/kaal/backend/dispatch_logging.rb', line 51

def parse_lock_key(key)
  DispatchLogging.parse_lock_key(key)
end