Class: PatientHttp::CallbackArgs

Inherits:
Object
  • Object
show all
Defined in:
lib/patient_http/callback_args.rb

Overview

Container for callback arguments that are passed to completion and error callbacks.

CallbackArgs provides a structured way to access arguments passed from the original job to the callback workers. Arguments are stored with string keys internally (for JSON serialization compatibility) but can be accessed using either strings or symbols. All hash keys, including nested hashes and hashes within arrays, are deeply converted to strings.

Examples:

Basic usage

args = CallbackArgs.new(user_id: 123, action: "fetch")
args[:user_id]      # => 123
args["user_id"]     # => 123
args.fetch(:missing, "default")  # => "default"
args.include?(:user_id)  # => true
args.to_h           # => {user_id: 123, action: "fetch"}

Nested hashes

args = CallbackArgs.new(metadata: {tags: ["a", "b"], level: 1})
args[:metadata]     # => {"tags" => ["a", "b"], "level" => 1}

From a response object

response.callback_args[:user_id]

Constant Summary collapse

ALLOWED_TYPES =

JSON-native types that are allowed as values

[NilClass, TrueClass, FalseClass, String, Integer, Float].freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args = nil, validate: true) ⇒ CallbackArgs

Initialize a CallbackArgs with a hash.

Parameters:

  • args (Hash, nil) (defaults to: nil) —

    arguments to store (keys will be deeply converted to strings)

  • validate (Boolean) (defaults to: true) —

    whether to validate values are JSON-native types

Raises:

  • (ArgumentError) —

    if args is not nil and doesn’t respond to to_h

  • (ArgumentError) —

    if any value is not a JSON-native type (when validate is true)



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/patient_http/callback_args.rb', line 88

def initialize(args = nil, validate: true)
  if args.nil?
    @data = {}
  elsif args.respond_to?(:to_h)
    hash = args.to_h
    if validate
      hash.each do |key, value|
        self.class.validate_value!(value, key.to_s)
      end
    end
    @data = self.class.deep_stringify_keys(hash)
  else
    raise ArgumentError.new("callback_args must respond to to_h, got #{args.class.name}")
  end
end

Class Method Details

.deep_stringify_keys(value) ⇒ Object

Deep convert all hash keys to strings, including nested hashes and hashes in arrays.

Parameters:

  • value (Object) —

    the value to convert

Returns:

  • (Object) —

    the converted value with all hash keys as strings



70
71
72
73
74
75
76
77
78
79
 
# File 'lib/patient_http/callback_args.rb', line 70

def deep_stringify_keys(value)
  case value
  when Hash
    value.transform_keys(&:to_s).transform_values { |v| deep_stringify_keys(v) }
  when Array
    value.map { |element| deep_stringify_keys(element) }
  else
    value
  end
end

.load(hash) ⇒ CallbackArgs

Reconstruct a CallbackArgs from a hash (used during deserialization).

Parameters:

  • hash (Hash, nil) —

    hash with string keys

Returns:



35
36
37
 
# File 'lib/patient_http/callback_args.rb', line 35

def load(hash)
  new(hash || {}, validate: false)
end

.validate_value!(value, path = "value") ⇒ void

This method returns an undefined value.

Validate that a value is a JSON-native type (recursively for arrays and hashes).

Parameters:

  • value (Object) —

    the value to validate

  • path (String) (defaults to: "value") —

    the path to the value (for error messages)

Raises:

  • (ArgumentError) —

    if the value is not a JSON-native type



45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/patient_http/callback_args.rb', line 45

def validate_value!(value, path = "value")
  case value
  when *ALLOWED_TYPES
    # Valid primitive type
  when Array
    value.each_with_index do |element, index|
      validate_value!(element, "#{path}[#{index}]")
    end
  when Hash
    value.each do |key, val|
      unless key.is_a?(String) || key.is_a?(Symbol)
        raise ArgumentError.new("#{path} hash key must be a String or Symbol, got #{key.class.name}")
      end

      validate_value!(val, "#{path}[#{key.inspect}]")
    end
  else
    raise ArgumentError.new("#{path} must be a JSON-native type (nil, true, false, String, Integer, Float, Array, or Hash), got #{value.class.name}")
  end
end

Instance Method Details

#[](key) ⇒ Object

Access an argument by key.

Parameters:

  • key (String, Symbol) —

    the key to access

Returns:

  • (Object) —

    the value

Raises:

  • (KeyError) —

    if the key does not exist



109
110
111
112
113
114
115
116
 
# File 'lib/patient_http/callback_args.rb', line 109

def [](key)
  string_key = key.to_s
  unless @data.include?(string_key)
    raise KeyError.new("key not found: #{key.inspect}. Available keys: #{@data.keys.join(", ")}")
  end

  @data[string_key]
end

#as_json ⇒ Hash Also known as: dump

Convert to hash with string keys for serialization.

Returns:

  • (Hash) —

    hash with string keys



147
148
149
 
# File 'lib/patient_http/callback_args.rb', line 147

def as_json
  @data.dup
end

#empty? ⇒ Boolean

Check if there are no arguments.

Returns:

  • (Boolean) —

    true if empty



156
157
158
 
# File 'lib/patient_http/callback_args.rb', line 156

def empty?
  @data.empty?
end

#fetch(key, default = nil) ⇒ Object

Access an argument by key with an optional default.

Parameters:

  • key (String, Symbol) —

    the key to access

  • default (Object) (defaults to: nil) —

    the default value to return if key doesn’t exist

Returns:

  • (Object) —

    the value or default



123
124
125
 
# File 'lib/patient_http/callback_args.rb', line 123

def fetch(key, default = nil)
  @data.fetch(key.to_s, default)
end

#include?(key) ⇒ Boolean

Check if a key exists.

Parameters:

  • key (String, Symbol) —

    the key to check

Returns:

  • (Boolean) —

    true if the key exists



131
132
133
 
# File 'lib/patient_http/callback_args.rb', line 131

def include?(key)
  @data.include?(key.to_s)
end

#keys ⇒ Array<String>

Return the keys.

Returns:

  • (Array<String>) —

    the keys



172
173
174
 
# File 'lib/patient_http/callback_args.rb', line 172

def keys
  @data.keys
end

#size ⇒ Integer Also known as: length

Return the number of arguments.

Returns:

  • (Integer) —

    the count



163
164
165
 
# File 'lib/patient_http/callback_args.rb', line 163

def size
  @data.size
end

#to_h ⇒ Hash

Convert to a hash with symbol keys (shallow).

Only top-level keys are symbolized. Nested hash keys remain as strings.

Returns:

  • (Hash) —

    hash with symbol keys



140
141
142
 
# File 'lib/patient_http/callback_args.rb', line 140

def to_h
  @data.transform_keys(&:to_sym)
end