Module: JSS::Validate

Defined in:
lib/jss/validate.rb

Overview

A collection of methods for validating values. Mostly for ensuring the validity of data being set as attributes of APIObject subclass instances.

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
IP_SEGMENT_RANGE =

Segments of a valid IPv4 address are integers in this range.

0..255
UUID_RE = 
/^[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 JSS::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

Raises:



212
213
214
215
216
217
218
219
220
221
222
 
# File 'lib/jss/validate.rb', line 212

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

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

  msg ||= 'Unknown country name or code. See JSS::APP_STORE_COUNTRY_CODES or JSS.country_code_match(str)'
  raise JSS::InvalidDataError, msg
end

.boolean(bool, msg = nil) ⇒ Boolean

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:

  • bool (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

Raises:



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

def self.boolean(bool, msg = nil)
  return bool if JSS::TRUE_FALSE.include? bool
  return true if bool.to_s =~ /^(t(rue)?|y(es)?)$/i
  return false if bool.to_s =~ /^(f(alse)?|no?)$/i

  msg ||= 'Value must be boolean true or false, or an equivalent string or symbol'
  raise JSS::InvalidDataError, msg
end

.doesnt_already_exist(klass, identifier, val, msg = nil, api: JSS.api) ⇒ Object

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

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

Otherwise returns val.

Parameters:

  • klass (JSS::APIObject) —

    A subclass of JSS::APIObject, e.g. JSS::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

  • api (JSS::APIConnection) (defaults to: JSS.api) —

    The api connection to use for validation

Returns:

  • (Object) —

    the validated unique value

Raises:



98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/jss/validate.rb', line 98

def self.doesnt_already_exist(klass, identifier, val, msg = nil, api: JSS.api)
  msg ||= "A #{klass} already exists with #{identifier} '#{val}'"
  return val unless klass.all(:refresh, api: api).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, api: api).values
  matches = existing_values.select { |existing_val| existing_val.casecmp? val }
  return val if matches.empty?

  raise JSS::AlreadyExistsError, msg
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

Raises:



238
239
240
241
242
243
244
 
# File 'lib/jss/validate.rb', line 238

def self.email_address(email, msg = nil)
  msg ||= "'#{email}' is not formatted as a valid email address"
  email = email.to_s
  return email if email =~ /^\S+@\S+\.\S+$/

  raise JSS::InvalidDataError, msg
end

.ibeacon_major_minor(val, msg = nil) ⇒ String

validate that the given value is an integer in the JSS::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

Raises:



193
194
195
196
197
198
199
200
201
 
# File 'lib/jss/validate.rb', line 193

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 = JSS::IBeacon::MAJOR_MINOR_RANGE.include? val if ok
  return val if ok

  msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
  raise JSS::InvalidDataError, msg unless ok
end

.integer(val, msg = nil) ⇒ void

This method returns an undefined value.

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

TODO: use this throughout ruby-jss

Parameters:

  • val (Object) —

    the value to validate

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

    A custom error message when the value is invalid

Raises:



145
146
147
148
149
150
151
 
# File 'lib/jss/validate.rb', line 145

def self.integer(val, msg = nil)
  msg ||= 'Value must be an integer'
  val = val.to_i if val.is_a?(String) && val.jss_integer?
  raise JSS::InvalidDataError, msg unless val.is_a? Integer

  val
end

.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

Raises:



67
68
69
70
71
72
73
74
75
76
 
# File 'lib/jss/validate.rb', line 67

def self.ip_address(val, msg = nil)
  msg ||= "Not a valid IPv4 address: '#{val}'"
  ok = true
  parts = val.strip.split '.'
  ok = false unless parts.size == 4
  parts.each { |p| ok = false unless p.jss_integer? && IP_SEGMENT_RANGE.include?(p.to_i) }
  raise JSS::InvalidDataError, msg unless ok

  val
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

Raises:



49
50
51
52
53
54
 
# File 'lib/jss/validate.rb', line 49

def self.mac_address(val, msg = nil)
  msg ||= "Not a valid MAC address: '#{val}'"
  raise JSS::InvalidDataError, msg unless val =~ MAC_ADDR_RE

  val
end

.non_empty_string(val, 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

Raises:



161
162
163
164
165
166
 
# File 'lib/jss/validate.rb', line 161

def self.non_empty_string(val, msg = nil)
  msg ||= 'value must be a non-empty String'
  raise JSS::InvalidDataError, msg unless val.is_a?(String) && !val.empty?

  val
end

.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

Raises:



178
179
180
181
182
183
 
# File 'lib/jss/validate.rb', line 178

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

  msg ||= 'value must be valid uuid'
  raise JSS::InvalidDataError, msg
end