Module: Jamf::Validate

Extended by:
OAPIValidate
Defined in:
lib/jamf/validate.rb

Overview

A collection of methods for validating values.

Some of these methods can take multiple input types, such as a String or an Array. All of them will either raise an exception if the value isn’t valid, or will return a standardized form of the input (e.g. an Array, even if given a String)

Constant Summary collapse

MAC_ADDR_RE =

The regular expression that matches a valid MAC address.

/^[a-f0-9]{2}(:[a-f0-9]{2}){5}$/i.freeze
IPV4_ADDR_RE =

The Regexp that matches a valid IPv4 address

/^((25[0-5]|2[0-4]\d|1\d{2}|[1-9]?\d)(\.|$)){4}/.freeze
UUID_RE =

the regular expression that matches a valid UDID/UUID

/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.freeze

Class Method Summary collapse

Class Method Details

.app_store_country_code(country, msg: nil) ⇒ String

validate a country name or code from Jamf::APP_STORE_COUNTRY_CODES returning the validated code, or raising an error

Parameters:

  • country (String) —

    The country name or code

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid two-letter country code



175
176
177
178
179
180
181
182
183
184
 
# File 'lib/jamf/validate.rb', line 175

def self.app_store_country_code(country, msg: nil)
  country = country.to_s.upcase
  return country if Jamf::APP_STORE_COUNTRY_CODES.value? country

  Jamf::APP_STORE_COUNTRY_CODES.each do |name, code|
    return code if name.upcase == country
  end

  raise_invalid_data_error(msg || "Unknown country name or code '#{country}'. See Jamf::APP_STORE_COUNTRY_CODES or JSS.country_code_match(str)")
end

.boolean(val, attr_name: nil, msg: nil) ⇒ Boolean Originally defined in module OAPIValidate

Confirm that the given value is a boolean value, accepting strings and symbols and returning real booleans as needed Accepts: true, false, ‘true’, ‘false’, ‘yes’, ‘no’, ‘t’,‘f’, ‘y’, or ‘n’ as strings or symbols, case insensitive

TODO: use this throughout ruby-jss

Parameters:

  • val (Boolean, String, Symbol) —

    The value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Boolean) —

    the valid boolean

.class_instance(val, klass:, attr_name: nil, msg: nil) ⇒ Object Originally defined in module OAPIValidate

validate that a value is of a specific class

Parameters:

  • val (Object) —

    The value to validate

  • klass (Class, Symbol) —

    The class which the val must be an instance of

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Object) —

    the valid value

.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx) ⇒ Object

Validate that a value doesn’t already exist for a given identifier of a given class

e.g. when klass = Jamf::Computer, identifier = :name, and val = ‘foo’ will raise an error when a computer named ‘foo’ exists

Otherwise returns val.

Parameters:

  • klass (Jamf::APIObject) —

    A subclass of Jamf::APIObject, e.g. Jamf::Computer

  • identifier (Symbol) —

    One of the keys of an Item of the class’s #all Array

  • val (Object) —

    The value to check for uniqueness

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The api connection to use for validation

Returns:

  • (Object) —

    the validated unique value



84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/jamf/validate.rb', line 84

def self.doesnt_already_exist(klass, identifier, val, msg: nil, api: nil, cnx: Jamf.cnx)
  cnx = api if api

  return val unless klass.all(:refresh, cnx: cnx).map { |i| i[identifier] }.include? val

  key = klass.real_lookup_key identifier

  # use map_all_ids_to cuz it works with any identifer, even non-existing
  existing_values = klass.map_all_ids_to(key, cnx: cnx).values
  matches = existing_values.select { |existing_val| existing_val.casecmp? val }
  return val if matches.empty?

  raise_invalid_data_error(msg || "A #{klass} already exists with #{identifier} '#{val}'")
end

.email_address(email, msg: nil) ⇒ String

validate an email address - must match the RegEx /^S+@S+.S+$/ i.e.:

1 or more non-whitespace chars, followed by
an @ character, followed by
1 or more non-whitespace chars, followed by
a dot, followed by
1 or more non-whitespace chars

Parameters:

  • email (String) —

    The email address

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the validly formatted email address



200
201
202
203
204
205
 
# File 'lib/jamf/validate.rb', line 200

def self.email_address(email, msg: nil)
  email = email.to_s
  return email if email =~ /^\S+@\S+\.\S+$/

  raise_invalid_data_error(msg || "'#{email}' is not formatted as a valid email address")
end

.float(val, attr_name: nil, msg: nil) ⇒ Float Originally defined in module OAPIValidate

Confirm that a value is a Float or a string representation of a Float Return the Float, or raise an error

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Float)

.fully_validate_integer(val, attr_def:, attr_name: nil) ⇒ Object Originally defined in module OAPIValidate

run all the possible validations on an integer

.fully_validate_number(val, attr_def:, attr_name: nil) ⇒ Object Originally defined in module OAPIValidate

run all the possible validations on a ‘number’

.fully_validate_string(val, attr_def:, attr_name: nil) ⇒ Object Originally defined in module OAPIValidate

run all the possible validations on a string

.ibeacon_major_minor(val, msg: nil) ⇒ String

validate that the given value is an integer in the Jamf::IBeacon::MAJOR_MINOR_RANGE

Parameters:

  • val (Object) —

    the thing to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid integer



157
158
159
160
161
162
163
164
 
# File 'lib/jamf/validate.rb', line 157

def self.ibeacon_major_minor(val, msg: nil)
  val = val.to_i if val.is_a?(String) && val.jss_integer?
  ok = val.is_a? Integer
  ok = Jamf::IBeacon::MAJOR_MINOR_RANGE.include? val if ok
  return val if ok

  raise_invalid_data_error(msg || "value must be an integer in the range #{Jamf::IBeacon::MAJOR_MINOR_RANGE}")
end

.in_enum(val, enum:, attr_name: nil, msg: nil) ⇒ Object Originally defined in module OAPIValidate

Does a value exist in a given enum array?

Parameters:

  • val (Object) —

    The thing that must be in the enum

  • enum (Array) —

    the enum of allowed values

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Object) —

    The valid object

.integer(val, attr_name: nil, msg: nil) ⇒ Integer Originally defined in module OAPIValidate

Confirm that a value is an integer or a string representation of an integer. Return the integer, or raise an error

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Integer)

.ip_address(val, msg: nil) ⇒ String

Validate the format and content of an IPv4 address

Parameters:

  • val (String) —

    The value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    The valid value



57
58
59
60
61
62
 
# File 'lib/jamf/validate.rb', line 57

def self.ip_address(val, msg: nil)
  val = val.strip
  return val if val =~ IPV4_ADDR_RE

  raise_invalid_data_error(msg || "Not a valid IPv4 address: '#{val}'")
end

.j_id(val, attr_name: nil, msg: nil) ⇒ String

Confirm that a value provided is an integer or a string version of an integer, and return the string version

The JPAPI specs say that all IDs are integers in strings tho, some endpoints are still using actual integers.

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid integer-in-a-string



125
126
127
128
129
130
131
132
133
 
# File 'lib/jamf/validate.rb', line 125

def self.j_id(val, attr_name: nil, msg: nil)
  case val
  when Integer
    return val.to_s
  when String
    return val if val.j_integer?
  end
  raise_invalid_data_error(msg || "#{attr_name} value must be an Integer or an Integer in a String, e.g. \"42\"")
end

.mac_address(val, msg: nil) ⇒ String

Validate the format and content of a MAC address

Parameters:

  • val (String) —

    The value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    The valid value



43
44
45
46
47
 
# File 'lib/jamf/validate.rb', line 43

def self.mac_address(val, msg: nil)
  return val if val =~ MAC_ADDR_RE

  raise_invalid_data_error(msg || "Not a valid MAC address: '#{val}'")
end

.matches_pattern(val, pattern:, attr_name: nil, msg: nil) ⇒ Object Originally defined in module OAPIValidate

Does a string match a given regular expression?

Parameters:

  • val (String) —

    The value to match

  • pattern (pattern) —

    the regular expression

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Object) —

    The valid object

.max_items(val, max:, attr_name: nil, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value contains no more than some maximum number of items

While this is intended for Arrays, it will work for any object that responds to #size

Parameters:

  • val (Object) —

    the value to validate

  • max (Object) —

    the maximum number of items allowed

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

Raises:

  • (ArgumentError)

.max_length(val, max:, attr_name: nil, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value’s length is less than or equal to some maximum

While this is intended for Strings, it will work for any object that responds to #length

Parameters:

  • val (Object) —

    the value to validate

  • max (Object) —

    the maximum length allowed

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

Raises:

  • (ArgumentError)

.maximum(val, max:, attr_name: nil, exclusive: false, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value is less than or equal to some maximum

While intended for Numbers, this will work for any Comparable objects

If exclusive, the max value is excluded from the range and the value must be less than the max.

Parameters:

  • val (Object) —

    the thing to validate

  • max (Object) —

    A value that the val must be less than or equal to

  • exclusuve (Boolean) —

    Should the max be excluded from the valid range? true: val must be < max, false: val must be <= max

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

.min_items(val, min:, attr_name: nil, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value contains at least some minimum number of items

While this is intended for Arrays, it will work for any object that responds to #size

Parameters:

  • val (Object) —

    the value to validate

  • min (Object) —

    the minimum number of items allowed

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

Raises:

  • (ArgumentError)

.min_length(val, min:, attr_name: nil, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value’s length is greater than or equal to some minimum

While this is intended for Strings, it will work for any object that responds to #length

Parameters:

  • val (Object) —

    the value to validate

  • min (Object) —

    The minimum length allowed

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

Raises:

  • (ArgumentError)

.minimum(val, min:, attr_name: nil, exclusive: false, msg: nil) ⇒ String Originally defined in module OAPIValidate

validate that the given value is greater than or equal to some minimum

If exclusive, the min value is excluded from the range and the value must be greater than the min.

While intended for Numbers, this will work for any Comparable objects

Parameters:

  • val (Object) —

    the thing to validate

  • min (Object) —

    A value that the val must be greater than or equal to

  • exclusuve (Boolean) —

    Should the min be excluded from the valid range? true: val must be > min, false: val must be >= min

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

.multiple_of(val, multiplier:, attr_name: nil, msg: nil) ⇒ String Originally defined in module OAPIValidate

Validate that a given number is multiple of some other given number

Parameters:

  • val (Number) —

    the number to validate

  • multiplier (Number) —

    the number what the val must be a multiple of. this must be positive.

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid value

Raises:

  • (ArgumentError)

.non_empty_string(val, attr_name: nil, msg: nil) ⇒ String

validate that the given value is a non-empty string

Parameters:

  • val (Object) —

    the thing to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid non-empty string



107
108
109
110
111
 
# File 'lib/jamf/validate.rb', line 107

def self.non_empty_string(val, attr_name: nil, msg: nil)
  return val if val.is_a?(String) && !val.empty?

  raise_invalid_data_error(msg || "#{attr_name} value must be a non-empty String")
end

.not_nil(val, attr_name: nil, msg: nil) ⇒ Object Originally defined in module OAPIValidate

validate that a value is not nil

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Object) —

    the valid value

.number(val, attr_name: nil, msg: nil) ⇒ Integer Originally defined in module OAPIValidate

Confirm that a value is an number or a string representation of an number. Return the number, or raise an error

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (Integer)

.oapi_attr(val, attr_def:, attr_name: nil) ⇒ Boolean Originally defined in module OAPIValidate

Validate that a value is valid based on its definition in an objects OAPI_PROPERTIES constant.

Parameters:

  • val (Object) —

    The value to validate

  • klass (Class, Symbol) —

    The class which the val must be

  • msg (String) —

    A custom error message when the value is invalid

Returns:

  • (Boolean) —

    the valid boolean

.object(val, attr_name: nil, msg: nil) ⇒ Hash Originally defined in module OAPIValidate

Confirm that a value is a Hash Return the Hash, or raise an error

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

.raise_invalid_data_error(msg) ⇒ Object

Raise an invalid data error

Raises:



20
21
22
 
# File 'lib/jamf/validate.rb', line 20

def self.raise_invalid_data_error(msg)
  raise Jamf::InvalidDataError, msg.strip
end

.string(val, attr_name: nil, msg: nil, to_s: false) ⇒ Hash Originally defined in module OAPIValidate

Confirm that a value is a String Return the String, or raise an error

Parameters:

  • val (Object) —

    the value to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

  • to_s: (Boolean) (defaults to: false) —

    If true, this method always succeds and returns the result of calling #to_s on the value

Returns:

.unique_array(val, attr_name: nil, msg: nil) ⇒ Object Originally defined in module OAPIValidate

validate that an array has only unique items, no duplicate values

Parameters:

  • val (Array) —

    The array to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

  • return (Array) —

    the valid array

Raises:

  • (ArgumentError)

.uuid(val, msg: nil) ⇒ String

validate that the given value is a valid uuid string

Parameters:

  • val (Object) —

    the thing to validate

  • msg (String) (defaults to: nil) —

    A custom error message when the value is invalid

Returns:

  • (String) —

    the valid uuid string



143
144
145
146
147
 
# File 'lib/jamf/validate.rb', line 143

def self.uuid(val, msg: nil)
  return val if val.is_a?(String) && val =~ UUID_RE

  raise_invalid_data_error(msg || 'value must be valid uuid')
end

.validate_array_constraints(val, attr_def:, attr_name: nil) ⇒ Object Originally defined in module OAPIValidate

run the array constraint validations for an array value. The individual array items must already be validated

.validate_numeric_constraints(val, attr_def:, attr_name: nil) ⇒ Object Originally defined in module OAPIValidate

run the numeric constraint validations for any numeric value The number itself must already be validated