Overview

This page gives you a quick overview of how Whowas works, including what you need to do to get it up and running.

How Whowas works and terminology

Whowas is built on the middleware pattern, and more specifically uses mitchellh's middleware gem for implementation. If you are unfamiliar with the middleware pattern, you can read a basic introduction to it.

Whowas is built on the following components, from specific to general:

• An adapter is the class which connects to and searches a third-party service or API. Examples of third-party services include Splunk, ElasticSearch, Bluecat Proteus, etc.
• A search method is a class specifying a particular search pattern for an API. For example, you may want to search DHCP logs in Splunk. The DHCP search would be the Search Method, and Splunk would be the API. The search method is what comprises our middleware. All search methods take input and return results which can serve as input to other search methods.
• A recipe is a middleware stack, or a chain of search methods where the output from each search method becomes the input to the next search method. Recipes are actually methods defined on the Whowas module.
• The recipe table is a hash of input possibilities to recipes, which allows for automatic recipe selection based on the type of input provided.

A Very Simple Example

This is a macro-level example to illustrate how the different components work together. A number of things have been simplified here, so don't copy this code into your app. For a full example of working code, please check the demo app.

For this example, our goal is to input an IP address and retrieve a username (the canonical Whowas example). There are two search methods required: IP to mac address via DhcpLog, and mac address to username via WifiLog. Both search methods will use the same adapter.

class SomeAdapter
  def search(input_in_api_format)
    connection = API.connect!
    connection.search(input_in_api_format) # returns results
  end
end

The search method takes input, formats it for the adapter, runs a search, takes the result, and formats it for use by the next search method. DhcpLog returns the input to WifiLog, and WifiLog returns the information we're looking for -- the username!

class DhcpLog
  @@adapter = SomeAdapter

  def search(hash_including_ip_address)
    input = convert_input_to_adapter_format(ip_address)
    results = @@adapter.new.search(input)
    format_results_to_standard_output(results)
  end
end

class WifiLog
  @@adapter = SomeAdapter

  def search(hash_including_mac_address)
    input = convert_input_to_adapter_format(hash_including_mac_address)
    results = @@adapter.new.search(input)
    format_results_to_standard_output(results)
  end
end

The recipe chains the search methods in the order they should run.

module Whowas
  def self.ip_to_username
    use DhcpLog
    use WifiLog
  end
end

The recipe table defines which recipe should be used with which input. Since we only have one recipe, we'll set it as the default. (The recipe table is set in the initializers/whowas.rb configuration file.)

We finally run the search by calling search on Whowas itself with the correct input:

Whowas.search(ip_address)