Module: Macker

Extended by:
Macker
Included in:
Macker
Defined in:
lib/macker.rb,
lib/macker/config.rb,
lib/macker/address.rb,
lib/macker/version.rb

Overview

Macker namespace

Defined Under Namespace

Classes: Address, Config, InvalidAddress, InvalidCache, InvalidOptions, InvalidRawData, NotFoundOuiVendor

Constant Summary collapse

VERSION =

Macker version

'0.1.1'.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#mem_timestampTime (readonly)

Get the timestamp of vendor list in memory

Returns:

  • (Time)

    time object or nil


30
31
32
# File 'lib/macker.rb', line 30

def mem_timestamp
  @mem_timestamp
end

#proc_timestampTime

Proc timestamp accessor to set external timestamp

Parameters:

  • value (Time)

    proc timestamp

Returns:

  • (Time)

    proc timestamp


26
27
28
# File 'lib/macker.rb', line 26

def proc_timestamp
  @proc_timestamp
end

Instance Method Details

#configOpenStruct

Get or initialize Macker config.

Returns:

  • (OpenStruct)

    Macker configuration


34
35
36
# File 'lib/macker.rb', line 34

def config
  @config ||= Macker::Config.new
end

#configure {|config| ... } ⇒ OpenStruct

Set configuration of Macker in a block.

Yields:

Returns:

  • (OpenStruct)

    Macker configuration


40
41
42
# File 'lib/macker.rb', line 40

def configure
  yield config if block_given?
end

#expire!Boolean

Fetch new vendor list if cached list is expired or stale

Returns:

  • (Boolean)

    true if vendor list is expired and updated from remote


158
159
160
161
162
163
164
165
166
167
168
# File 'lib/macker.rb', line 158

def expire!
  if expired?
    update(true)
    true
  elsif stale?
    update
    true
  else
    false
  end
end

#expired?Boolean

Check if vendor list is expired

Returns:

  • (Boolean)

    true if vendor list is expired


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

def expired?
  Time.now > vendors_expiration
end

#generate(opts = {}) ⇒ Address

Generate a MAC address.

  • No options for random MAC.

  • Vendor option to get a valid OUI MAC.

  • Vendor Name option to get a random MAC from vendor.

Examples:

generate
generate(vendor: true)
generate(vendor: 'IEEE Registration Authority')

Parameters:

  • opts (Hash) (defaults to: {})

    options for the method

Returns:

  • (Address)

    MAC address with data


102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
# File 'lib/macker.rb', line 102

def generate(opts = {})
  expire! if config.auto_expiration
  return generate_by_iso_code(opts.delete(:iso_code), opts) if opts[:iso_code]
  vendor = opts.delete(:vendor)
  case vendor
  when nil, false
    Address.new(rand(2**48))
  when true
    generate_by_vendor(prefix_table[prefix_table.keys.shuffle.sample][:name], opts)
  when String
    generate_by_vendor(vendor, opts)
  else
    raise(InvalidOptions, "Incompatible option vendor for generate: #{vendor.class}")
  end
end

#generate!(opts = {}) ⇒ Address

Generate a MAC address.

  • No options for random MAC address.

  • Vendor option to get a valid OUI MAC address.

  • Vendor name option to get a random MAC address from vendor.

Raises an error if an error occurs.

Examples:

generate
generate(vendor: true)
generate(vendor: 'No vendor')

Parameters:

  • opts (Hash) (defaults to: {})

    options for the method

Returns:

  • (Address)

    MAC address with vendor data


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

def generate!(opts = {})
  generate(opts.merge(raising: true))
end

#iso_code_tableHash

Vendor table with all country iso codes as keys

Returns:

  • (Hash)

    vendor iso codes table


144
145
146
147
# File 'lib/macker.rb', line 144

def iso_code_table
  update unless @iso_code_table
  @iso_code_table
end

#lookup(mac, opts = {}) ⇒ Address

Lookup for a vendor with given MAC address.

Examples:

lookup('00:04:A9:6D:B8:AC')
lookup(20022409388)

Parameters:

  • mac (Address, Integer, String)

    MAC address

  • opts (Hash) (defaults to: {})

    options for the method

Returns:

  • (Address)

    MAC address with vendor data


68
69
70
71
72
73
74
75
# File 'lib/macker.rb', line 68

def lookup(mac, opts = {})
  expire! if config.auto_expiration
  data = prefix_table[Address.new(mac).prefix]
  if data.nil?
    opts[:raising] ? raise(NotFoundOuiVendor, "OUI not found for MAC: #{mac}") : (return nil)
  end
  Address.new(mac, data)
end

#lookup!(mac) ⇒ Address

Lookup for a vendor with given MAC address. Raises an error if no vendor found.

Examples:

lookup!('00:04:A9:6D:B8:AC')
lookup!('80:47:FB:B2:9E:D6')

Parameters:

  • mac (Address, Integer, String)

    MAC address

Returns:

  • (Address)

    MAC address with vendor data


86
87
88
# File 'lib/macker.rb', line 86

def lookup!(mac)
  lookup(mac, raising: true)
end

#prefix_tableHash

Vendor table with all base16 MAC prefixes as keys

Returns:

  • (Hash)

    vendor prefixes table


137
138
139
140
# File 'lib/macker.rb', line 137

def prefix_table
  update unless @prefix_table
  @prefix_table
end

#stale?Boolean

Check if vendor list is stale Stale is true if vendor list is updated straight by another thread. The actual thread has always old vendor list in memory store.

Returns:

  • (Boolean)

    true if vendor list is stale


180
181
182
183
184
185
186
# File 'lib/macker.rb', line 180

def stale?
  if config.cache.is_a?(Proc)
    proc_timestamp != mem_timestamp
  else
    file_timestamp != mem_timestamp
  end
end

#update(straight = false) ⇒ Time

Update all OUI tables

Parameters:

  • straight (Boolean) (defaults to: false)

    true for straight, default is careful

Returns:

  • (Time)

    timestamp of the update


47
48
49
50
51
52
53
54
55
56
57
# File 'lib/macker.rb', line 47

def update(straight = false)
  @prefix_table = {}
  @iso_code_table = {}
  @vendor_table = {}
  vendor_list(straight)
  @mem_timestamp = if config.cache.is_a?(Proc)
                     proc_timestamp
                   else
                     file_timestamp
                   end
end

#vendor_tableHash

Vendor table with all country vendor names as keys

Returns:

  • (Hash)

    vendor names table


151
152
153
154
# File 'lib/macker.rb', line 151

def vendor_table
  update unless @vendor_table
  @vendor_table
end

#vendors_expirationTime

Get vendor list expiration time based on ttl

Returns:

  • (Time)

    vendor list expiration time


190
191
192
193
194
195
196
# File 'lib/macker.rb', line 190

def vendors_expiration
  if config.cache.is_a?(Proc)
    proc_timestamp + config.ttl_in_seconds
  else
    file_timestamp + config.ttl_in_seconds
  end
end