rainman 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/.travis.yml

@@ -0,0 +1,11 @@
+script: "bundle exec rake spec"
+notifications:
+  disabled: true
+rvm:
+  - 1.8.7
+  - 1.9.2
+  - 1.9.3
+  - ree
+  - rbx
+  - rbx-2.0
+  - jruby

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in rainman.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2011 Site5 LLC <http://www.site5.com/>
+
+Permission  is  hereby granted, free of charge, to any person ob-
+taining a copy of  this  software  and  associated  documentation
+files  (the "Software"), to deal in the Software without restric-
+tion, including without limitation the rights to use, copy, modi-
+fy, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is  fur-
+nished to do so, subject to the following conditions:
+
+The  above  copyright  notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF  ANY  KIND,
+EXPRESS  OR  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE  AND  NONIN-
+FRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER  IN  AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN  THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,252 @@
+# Rainman [![Rainman Build Status][Build Icon]][Build Status]
+
+Rainman is an experiment in writing drivers and handlers. It is a Ruby
+implementation of the [abstract factory pattern][1]. Abstract factories provide
+the general API used to interact with any number of interfaces. Interfaces
+perform actual operations. Rainman provides a simple DSL for implementing this
+design.
+
+[1]: http://en.wikipedia.org/wiki/Abstract_factory_pattern
+
+[Build Icon]: https://secure.travis-ci.org/site5/rainman.png?branch=master
+[Build Status]: http://travis-ci.org/site5/rainman
+
+## Drivers & Handlers
+
+In Rainman, drivers represent abstract factories and handlers represent the
+interfaces those factories interact with. In simpler terms, drivers define
+_what_ things you can do; handlers define _how_ to do those things.
+
+## Creating a driver
+
+Rainman drivers are implemented as Modules. They must be extended with
+`Rainman::Driver` and use the driver DSL to define their public API. An
+example Domain driver might look like this:
+
+```ruby
+require 'rainman'
+
+# The Domain module handles creating and deleting domains, and listing
+# nameservers
+module Domain
+  extend Rainman::Driver
+
+  # Register Domain::Abc as a handler.
+  register_handler :abc
+
+  # Register Domain::Xyz as a handler.
+  register_handler :xyz
+
+  # Register Domain.create as a public method
+  define_action :create
+
+  # Register Domain.destroy as a public method
+  define_action :destroy
+
+  # Register Domain.namservers.list as a public method
+  namespace :nameservers do
+    define_action :list
+  end
+end
+```
+
+## Implementing handlers
+
+Driver handlers are implemented as classes. They must be within the namespace
+of the driver Module. Using the example above, here are example handlers for
+Abc and Xyz:
+
+```ruby
+class Domain::Abc
+  # Public: Creates a new domain.
+  #
+  # Returns a Hash.
+  def create(params = {})
+  end
+
+  # Public: Destroy a domain
+  #
+  # Returns true or false.
+  def destroy(params = {})
+  end
+end
+
+class Domain::Xyz
+  # Public: Creates a new domain.
+  #
+  # Returns a Hash.
+  def create(params = {})
+  end
+
+  # Public: Destroy a domain
+  #
+  # Returns true or false.
+  def destroy(params = {})
+  end
+end
+```
+
+The example driver above also defined `nameservers` namespace with a `list`
+action (eg: `Domain.nameservers.list`). To implement this, a Nameservers class
+is created within each handler's namespace:
+
+```ruby
+class Domain::Abc::Nameserver
+
+  # Public: Lists nameservers for this domain.
+  #
+  # Returns an Array.
+  def list(params = {})
+  end
+end
+
+class Domain::Xyz::Nameserver
+
+  # Public: Lists nameservers for this domain.
+  #
+  # Returns an Array.
+  def list(params = {})
+  end
+end
+```
+
+## Handler setup
+If your handler requires any sort of setup that can't be handled in your
+initialize method (e.g. you're subclassing and can't override
+initialize), you can define a setup_handler method. Rainman will
+automatically call this method for you after the class is initialized.
+
+```ruby
+class Domain::Abc
+  attr_accessor :config
+
+  def initialized
+    @config = { :username => 'username', :password => 'password' }
+  end
+end
+
+class Domain::Xyz < Domain::Abc
+  def setup_handler
+    @config[:username] = 'other'
+  end
+end
+```
+
+## Using a driver
+
+With a driver and handler defined, the driver can now be used in a few
+different ways.
+
+### General
+
+A driver's actions are available as singleton methods. By default, actions are
+sent to the current handler, or a default handler if a handler is not currently
+in use.
+
+```ruby
+# Create a domain
+Domain.create({})
+
+# Destroy a domain
+Domain.destroy({})
+
+# List domain nameservers
+Domain.nameservers.list({})
+```
+
+### Changing handlers
+
+It is possible to change the handler used at runtime using the `with_handler`
+method. This method temporarily changes the current handler. This means, if
+you have a default handler set, and use `with_handler`, that default handler
+is preserved.
+
+```ruby
+Domain.with_handler(:abc) do |driver|
+  # Here, current_handler is now set to :abc
+  driver.create
+end
+```
+
+You can also change the current handler for the duration of your code/session.
+
+```ruby
+Domain.set_current_handler :xyz
+Domain.create # create an :xyz domain
+
+Domain.set_current_handler :abc
+Domain.create   # create an :abc domain
+Domain.transfer # transfer an :abc domain
+```
+
+It is highly suggested you stick to using `with_handler` unless you have a
+reason.
+
+### Including drivers in other classes
+
+A driver can be included in another class and its actions are available as
+instance methods.
+
+```ruby
+class Service
+  include Domain
+end
+
+s = Service.new
+
+s.create
+
+s.destroy
+
+s.nameservers.list
+
+s.with_handler(:abc) do |handler|
+  handler.create
+end
+
+s.set_current_handler :xyz
+s.create
+```
+
+If you want to namespace a driver in another class, it's as easy as:
+
+```ruby
+class Service
+  def domain
+    Domain
+  end
+end
+
+s = Service.new
+
+s.domain.create
+
+s.domain.destroy
+
+s.domain.nameservers.list
+
+s.domain.with_handler(:abc) do |handler|
+  handler.create
+end
+
+s.domain.set_current_handler :xyz
+```
+
+## Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version
+  unintentionally.
+* Commit, do not bump version. (If you want to have your own version, that is
+  fine but bump version in a commit by itself I can ignore when I pull).
+* Send me a pull request. Bonus points for topic branches.
+
+## Contributors
+
+* [Justin Mazzi](https://github.com/jmazzi)
+* [Joshua Priddle](https://github.com/itspriddle)
+
+## Copyright
+
+Copyright (c) 2011 Site5 LLC. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+  puts "Please install rspec (bundle install)"
+  exit
+end
+
+RSpec::Core::RakeTask.new :spec
+task :default => :spec
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/rainman.rb -I ./lib -r ./example/domain.rb"
+end

data/example/domain/enom/nameservers.rb

@@ -0,0 +1,10 @@
+module Domain
+  # This class handles interacting with the Enom API's nameserver functions.
+  class Enom::Nameservers
+
+    # List domain nameservers
+    def list(*a)
+      :enom_ns_list
+    end
+  end
+end

data/example/domain/enom.rb

@@ -0,0 +1,13 @@
+module Domain
+  # This class handles interacting with the Enom API.
+  class Enom
+    def list(*a)
+      :enom_list
+    end
+
+    # Transfer a domain name
+    def transfer(*a)
+      :enom_transfer
+    end
+  end
+end

data/example/domain/opensrs/nameservers.rb

@@ -0,0 +1,10 @@
+module Domain
+  # This class handles interacting with the Opensrs API's nameserver functions.
+  class Opensrs::Nameservers
+
+    # List domain nameservers
+    def list(*a)
+      :opensrs_ns_list
+    end
+  end
+end

data/example/domain/opensrs.rb

@@ -0,0 +1,13 @@
+module Domain
+  # This class handles interacting with the Opensrs API.
+  class Opensrs
+    def list(*a)
+      :opensrs_list
+    end
+
+    # Transfer a domain name
+    def transfer(*a)
+      :opensrs_transfer
+    end
+  end
+end

data/example/domain.rb

@@ -0,0 +1,28 @@
+require 'rainman'
+
+# Load handlers
+$:.unshift File.expand_path('..', __FILE__)
+require 'domain/enom'
+require 'domain/enom/nameservers'
+require 'domain/opensrs'
+require 'domain/opensrs/nameservers'
+
+# The Domain module will contain all methods for interacting with various
+# domain handlers.
+module Domain
+  extend Rainman::Driver
+
+  register_handler :enom
+
+  register_handler :opensrs
+
+  namespace :nameservers do
+    define_action :list
+  end
+
+  define_action :list
+
+  define_action :transfer
+
+  set_default_handler :opensrs
+end

data/lib/rainman/driver.rb

@@ -0,0 +1,287 @@
+require "forwardable"
+
+module Rainman
+  # The Rainman::Driver module contains methods for defining Drivers and
+  # proxying their associated actions to the appropriate handlers.
+  module Driver
+    # Public: Extended hook; this is run when a module extends itself with
+    # the Rainman::Driver module.
+    def self.extended(base)
+      all << base
+      base.extend(base)
+    end
+
+    # Public: Get a list of all Drivers (eg: Modules that are extended with
+    # Rainman::Driver).
+    #
+    # Returns an Array.
+    def self.all
+      @all ||= []
+    end
+
+    # Public: Registered handlers.
+    #
+    # Keys are the handler name (eg: :my_handler); values are the handler
+    # class (eg: MyHandler).
+    #
+    # Raises NoHandler if an attempt to access a key of nil is made, (eg:
+    # handlers[nil]).
+    #
+    # Raises InvalidHandler if an attempt to access an invalid key is made.
+    #
+    # Returns a Hash.
+    def handlers
+      @handlers ||= Hash.new do |hash, key|
+        if key.nil?
+          raise NoHandler
+        else
+          raise InvalidHandler, key
+        end
+      end
+    end
+
+    # Public: Temporarily change a Driver's current handler. The handler is
+    # changed for the duration of the block supplied. This is useful to perform
+    # actions using multiple handlers without changing defaults.
+    #
+    # name - The Symbol name of the handler to use.
+    #
+    # Example
+    #
+    #   with_handler(:enom) do |handler|
+    #     handler.transfer
+    #   end
+    #
+    # Yields a Runner instance if a block is given.
+    #
+    # Returns a Runner instance or the result of a block.
+    def with_handler(name, &block)
+      raise MissingBlock, :with_handler unless block_given?
+
+      old_handler = current_handler
+
+      begin
+        set_current_handler name
+        yield current_handler_instance.runner
+      ensure
+        set_current_handler old_handler
+      end
+    end
+
+    # Public: Sets the default handler used for this Driver.
+    #
+    # name - The Symbol name to set as the default handler. Should be a key
+    #        from handlers.
+    #
+    # Returns the Symbol name.
+    def set_default_handler(name)
+      @default_handler = name
+    end
+
+    # Public: Get the default handler used for this Driver.
+    #
+    # Returns the Symbol name of this Driver's default handler.
+    def default_handler
+      @default_handler
+    end
+
+    # Public: Sets the current handler. Name should be an underscored symbol
+    # representing a class name in the current context.
+    #
+    # name - The Symbol name of the handler to use. Can be set to nil to
+    #        clear the current handler.
+    #
+    # Example
+    #
+    #   set_current_handler :my_handler #=> sets handler to MyHandler
+    #   set_current_handler nil         #=> clears handler
+    #
+    # Returns the Symbol name of the current handler or nothing.
+    def set_current_handler(name)
+      @current_handler = name
+    end
+
+    private
+
+    # Private: Included hook; this is invoked when a Driver module is
+    # included in another class. It sets up delegation so that the including
+    # class can access a Driver's singleton methods as instance methods.
+    #
+    # base - The Module/Class that included this module.
+    #
+    # Example
+    #
+    #   class Service
+    #     include Domain
+    #   end
+    #
+    #   s = Service.new
+    #   s.transfer #=> calls Domain.transfer
+    #
+    # Returns nothing.
+    def included(base)
+      base.extend(::Forwardable)
+      base.def_delegators self, *singleton_methods
+    end
+
+    # Private: A hash containing handler instances. This prevents handlers
+    # from being initialized multiple times in a single session.
+    #
+    # Returns a Hash containing instances of handlers that have been
+    # initialized.
+    def handler_instances
+      @handler_instances ||= {}
+    end
+
+    # Private: Get or set an instance of the current handler class. This
+    # method stores the instance in handler_instances, and should be used
+    # instead of manually initializing handlers.
+    #
+    # Returns an instance of the current handler class.
+    def current_handler_instance
+      handler_instances[current_handler] ||= handlers[current_handler].new.tap do |_handler|
+        _handler.setup_handler if _handler.respond_to?(:setup_handler)
+      end
+    end
+
+    # Private: Get the current handler in use by this Driver.
+    #
+    # Returns the Symbol name of the current handler, or default handler if
+    # a current handler is not set.
+    def current_handler
+      @current_handler || @default_handler
+    end
+
+    # Private: Register a handler for use with the current Driver.
+    #
+    # If a block is given it is evaluated within the context of the handler
+    # Class.
+    #
+    # name - The Symbol handler name.
+    # opts - A Hash containing optional arguments:
+    #        :class_name - The class name to use.
+    #
+    # Examples
+    #
+    #   register_handler :bob
+    #
+    # Returns the handler Class.
+    def register_handler(name, opts = {})
+      opts.reverse_merge!(
+        :class_name => "#{self.name}::#{name.to_s.camelize}"
+      )
+
+      klass = opts[:class_name].constantize
+
+      handlers[name] = inject_handler_methods(klass, name.to_sym)
+    end
+
+    # Private: Create a new namespace.
+    #
+    # name  - The Symbol handler name.
+    # opts  - Arguments (unused currently).
+    # block - A required block used to create actions within the namespace
+    #
+    # Example
+    #
+    #   namespace :nameservers do
+    #     define_action :list
+    #   end
+    #
+    # Raises Rainman::MissingBlock if called without a block.
+    #
+    # Returns a Module.
+    def namespace(name, opts = {}, &block)
+      raise MissingBlock, :namespace unless block_given?
+
+      create_method(name) do
+        key = "@#{name}"
+
+        if instance_variable_defined?(key)
+          ns = instance_variable_get(key)
+        else
+          ns = instance_variable_set(key, {})
+        end
+
+        unless ns[current_handler]
+          mod = Module.new do
+            extend self
+            extend ActionMethods
+            class << self
+              attr_accessor :current_handler_instance
+            end
+          end
+
+          klass = current_handler_instance.class.const_get(name.to_s.camelize)
+          mod.current_handler_instance = inject_handler_methods(klass, name).new
+
+          mod.instance_eval(&block)
+          ns[current_handler] = mod
+        end
+
+        ns[current_handler]
+      end
+    end
+
+    # Private: Injects Handler methods into the given class/module.
+    #
+    # base           - The base Class/Module.
+    # handler_name   - The Symbol name of the handler class.
+    #
+    # Example
+    #
+    #   inject_handler_methods(SomeHandler, :some_handler)
+    #
+    # Returns base Class/Module.
+    def inject_handler_methods(base, handler_name)
+      base.extend(Handler)
+      base.instance_variable_set(:@handler_name, handler_name)
+      base.instance_variable_set(:@parent_klass, self)
+      base
+    end
+
+    # These methods are used to create handler actions.
+    module ActionMethods
+      # Private: Define a new action.
+      #
+      # name - The Symbol handler name.
+      # opts - Options (unused currently).
+      #
+      # Example
+      #
+      #   define_action :blah
+      #
+      # Returns a Proc.
+      def define_action(name, opts = {})
+        create_method(name) do |*args, &block|
+          current_handler_instance.runner.send(name, *args, &block)
+        end
+      end
+
+      # Private: Creates a new method.
+      #
+      # method - The method name.
+      # args   - Arguments to be supplied to the method (optional).
+      # block  - Block to be supplied to the method (optional).
+      #
+      # Examples
+      #
+      #   create_method :blah do
+      #     # code to execute
+      #   end
+      #
+      # Raises Rainman::AlreadyImplemented if the method already exists.
+      #
+      # Returns a Proc.
+      def create_method(method, *args, &block)
+        if respond_to?(method, true)
+          raise AlreadyImplemented, "#{inspect}::#{method}"
+        else
+          define_method(method, *args, &block)
+        end
+      end
+    end
+
+    include ActionMethods
+  end
+end