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,
sig/kaal/backend/dispatch_logging.rbs

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) ⇒ ::Array[Kaal::rbs_any]

Parameters:

  • key (Kaal::rbs_any)

Returns:

  • (::Array[Kaal::rbs_any]) 


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_attempt_logger ⇒ Kaal::rbs_any

Returns:

  • (Kaal::rbs_any) 


84
85
86
87
88
89
 
# File 'lib/kaal/backend/dispatch_logging.rb', line 84

def dispatch_attempt_logger
  @dispatch_attempt_logger ||= DispatchAttemptLogger.new(
    configuration: Kaal.configuration,
    dispatch_registry_provider: -> { dispatch_registry }
  )
end

#dispatch_registry ⇒ nil

Returns:

  • (nil) 


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