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

.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’, :true, :false, ‘yes’, ‘no’, :yes, or :no (all Strings and Symbols are 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)
  msg ||= 'Value must be boolean true or false'
  return bool if JSS::TRUE_FALSE.include? bool
  return true if bool.to_s =~ /^(true|yes)$/i
  return false if bool.to_s =~ /^(false|no)$/i

  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

.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)
  msg ||= "value must be an integer in the range #{JSS::IBeacon::MAJOR_MINOR_RANGE}"
  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
  raise JSS::InvalidDataError, msg unless ok

  val
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)
  msg ||= 'value must be valid uuid'
  raise JSS::InvalidDataError, msg unless val.is_a?(String) && val =~ UUID_RE

  val
end