manana 0.0.1 → 0.0.2

data/.yardopts

@@ -5,4 +5,4 @@
 --readme README.md
 - 
 LICENSE.txt
-CHANGELOG.md
+CHANGELOG.md

data/Gemfile

@@ -5,10 +5,26 @@ gemspec
 
 # these aren't strictly needed for development but are nice to have
 unless ENV["TRAVIS"] == "1"
-  gem 'yard'
-  gem 'redcarpet'
-  gem 'simplecov'
-  gem 'pry'
+  
+  group :development do
+    gem 'yard'
+    gem 'redcarpet'
+
+    gem 'pry'
+    gem 'pry-debugger'
+    gem 'pry-rescue'
+    gem 'pry-stack_explorer'
+  end
+
+  group :samples do
+    gem 'savon', '~> 2.3'
+    gem 'webmock'
+  end
+
+  group :test do 
+    gem 'simplecov'
+  end
+
 end
 
 # for travis.cl

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 coldnebo
+Copyright (c) 2013 Larry Kyrala
 
 MIT License
 

data/README.md

@@ -1,12 +1,42 @@
 # Manana
 
-*Manana* lets you defer the initialization of any class to when an instance method is called.
+*Manana* lets you defer the initialization of an object until its methods are called.
 
-This can be useful in cases where class initialization may take a long time or fail due to errors (i.e. a network service). 
-In these situations, you don't want to tie the initialization of service adapters to the initialization of your application, 
-because if the service init fails, then your app fails to init and start (i.e. you want your app to be self-healing and 
-retry initialization when the method is called later)... also it can unncessarily increase the startup
-time of your app for testcases, etc.
+This can be useful in cases where initialization may take a long time or fail due to errors. For example, in rails, if 
+the database specified in `database.yml` doesn't exist at start time, the rails application will fail initialization. Likewise 
+if you tie configuration of SOAP services (e.g. using [Savon](http://savonrb.com/version2/)) to your application initialization, 
+and the service wsdl isn't up, your application will fail to start.
+
+Instead, it is an established best practice in service-oriented architectures to make your application or service *startup order independent*: 
+i.e. your app starts fast and initializes other dependencies afterwards, providing fault detection and *self-healing* properties for the app.
+
+*Manana* is a simple approach that allows you to keep your configuration and initialization code in the same place, while deferring it to method calls. 
+
+### Pros
+
+* Reduces the startup time for your app. (i.e. moves the startup cost from initialization to first use)
+
+* Once initialization is succesful, it stores the object instance for reuse.
+
+* Until the initialization is successful, it will retry every time a method is called.
+
+* You can layer more complex retry semantics such as [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff) using this wrapper.  See [samples/exponential_backoff.rb](https://github.com/coldnebo/manana/blob/master/samples/exponential_backoff.rb)
+
+### Cons
+
+* If your initialization takes a very long time, (i.e. a cache) you may want to pre-warm it instead of taking the hit on the first use of the object.
+
+* Very simple approach.  You may want more complex retry semantics,  or pooling.
+
+### Similar ideas:
+
+* [Connection pool](http://en.wikipedia.org/wiki/Connection_pool) of one?
+
+* [Avoid Start Order Dependencies](http://wiki.osgi.org/wiki/Avoid_Start_Order_Dependencies)
+
+* [Data Centers need shutdown/startup order](http://www.boche.net/blog/index.php/2009/01/01/datacenters-need-shutdownstartup-order/)
+
+* 'self-healing' initialization faults from the practice of [Autonomic computing](http://en.wikipedia.org/wiki/Autonomic_computing)
 
 ## Installation
 
@@ -24,7 +54,7 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+See the [samples](https://github.com/coldnebo/manana/blob/master/samples) for examples of use.
 
 ## Contributing
 

data/Rakefile

@@ -6,3 +6,10 @@ Rake::TestTask.new(:test) do |t|
 end
 
 task :default => :test
+
+desc "install gems for running samples"
+task :samples do
+  Bundler.with_clean_env do
+    sh "bundle install --gemfile=samples/common/samples.gemfile"
+  end
+end

data/lib/manana/version.rb

@@ -1,3 +1,3 @@
 class Manana
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/manana.rb

@@ -1,12 +1,42 @@
 require "manana/version"
 
+
+# *Manana* lets you defer the initialization of an object until its methods are called.
+# @example basic usage - see {https://github.com/coldnebo/manana/blob/master/samples/self_healing.rb samples/self_healing.rb}
+#   #   initialization...
+#   client = Manana.wrap {
+#     Weather.setup
+#     Weather
+#   }
+#  
+#   runtime_loop {
+#     #   wait for next interval
+#     weather = client.city_weather("02201")  # deferred initialization happens here once
+#     puts "At %s the temperature is currently %s F and the humidity is %s." % [weather.city, weather.temperature, weather.relative_humidity]
+#   }
+#
 class Manana
-  attr_reader :deferred_initialization, :instance
 
-  def self.wrap(&block)
-    Manana.new(&block)
+  # wraps an object initialization block so that it can be deferred to a later time when object methods are called.
+  # @example wrap an object - see {https://github.com/coldnebo/manana/blob/master/samples/self_healing.rb samples/self_healing.rb}
+  #   client = Manana.wrap {
+  #     Weather.setup  # initialize the class 
+  #     Weather        # return the Weather class
+  #   }
+  # 
+  # @param initialization_block [Proc] object initialization. the block must return the object to be wrapped.
+  # @return [Manana] a wrapped version of the object.
+  def self.wrap(&initialization_block)
+    Manana.new(&initialization_block)
   end 
 
+  # passes any method call through to the wrapped object after ensuring that the initialization block has 
+  # successfully completed once (setting a valid instance of the object).  
+  # @note Once the initialization block succeeds, it keeps the resulting object instance for subsequent method calls. 
+  #
+  # @example calling a wrapped object - see {https://github.com/coldnebo/manana/blob/master/samples/self_healing.rb samples/self_healing.rb}
+  #   weather = client.city_weather("02201")
+  #
   def method_missing(method, *args, &block)
     instance = get_instance
     instance.send(method, *args, &block);
@@ -14,8 +44,8 @@ class Manana
 
   private
 
-  def initialize(&block)
-    @deferred_initialization = block
+  def initialize(&initialization_block)
+    @deferred_initialization = initialization_block
   end
 
   def get_instance

data/manana.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = Manana::VERSION
   spec.authors       = ["coldnebo"]
   spec.email         = ["larry.kyrala@gmail.com"]
-  spec.description   = %q{provides a simple way to defer initialization of an object to action on an object}
-  spec.summary       = %q{I'll get to your initialization tomorrow...}
-  spec.homepage      = ""
+  spec.description   = %q{provides a simple way to defer initialization of an object until its methods are called}
+  spec.summary       = %q{provides a simple way to defer initialization of an object until its methods are called}
+  spec.homepage      = "https://github.com/coldnebo/manana"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

data/samples/common/samples.gemfile

@@ -0,0 +1,10 @@
+
+source 'https://rubygems.org'
+
+# these are gems used in the samples.
+# install with:
+# $ rake samples
+
+gem 'rack'
+gem 'savon', '~> 2.3'
+gem 'webmock'

data/samples/common/samples.gemfile.lock

@@ -0,0 +1,42 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.5)
+    akami (1.2.0)
+      gyoku (>= 0.4.0)
+      nokogiri (>= 1.4.0)
+    builder (3.2.2)
+    crack (0.4.1)
+      safe_yaml (~> 0.9.0)
+    gyoku (1.1.0)
+      builder (>= 2.1.2)
+    httpi (2.1.0)
+      rack
+      rubyntlm (~> 0.3.2)
+    nokogiri (1.5.10)
+    nori (2.3.0)
+    rack (1.5.2)
+    rubyntlm (0.3.4)
+    safe_yaml (0.9.7)
+    savon (2.3.0)
+      akami (~> 1.2.0)
+      builder (>= 2.1.2)
+      gyoku (~> 1.1.0)
+      httpi (~> 2.1.0)
+      nokogiri (>= 1.4.0, < 1.6)
+      nori (~> 2.3.0)
+      wasabi (~> 3.2.0)
+    wasabi (3.2.0)
+      httpi (~> 2.0)
+      nokogiri (>= 1.4.0, < 1.6)
+    webmock (1.15.2)
+      addressable (>= 2.2.7)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rack
+  savon (~> 2.3)
+  webmock

data/samples/common/samples_helper.rb

@@ -0,0 +1,7 @@
+# sample helper takes care of loading the gem from source without requiring it to be rebuilt and installed.
+# this is useful in allowing the samples in this directory to evolve the behavior of the actual gem.
+
+lp = File.expand_path(File.join(*%w[.. .. lib]), File.dirname(__FILE__))
+unless $LOAD_PATH.include?(lp)
+  $LOAD_PATH.unshift(lp)
+end

data/samples/exponential_backoff.rb

@@ -0,0 +1,65 @@
+# This sample demonstrates how exponential backoff can be layered on top of Manana
+#
+# run from the gem dir with: 
+# $ rake samples
+# $ ruby samples/exponential_backoff.rb 
+
+require_relative 'common/samples_helper.rb'
+
+# ------------------------- sample code starts here -------------------------
+
+require 'manana'
+require 'benchmark'
+
+
+class PoorService
+  @@instance = 0
+
+  def initialize
+    @@instance += 1
+    if @@instance <= 3 
+      raise "failed to init"
+    end
+    puts "successfully inited service."
+  end
+
+  def process
+    puts "successfully called service!"
+  end
+
+end
+
+# ------------ initialization code
+
+client = Manana.wrap {
+  # exponential backkoff logic in the initialization block
+  retries = 0
+  obj = nil
+
+  puts "trying to create service object..."
+  begin
+    obj = PoorService.new
+  rescue RuntimeError => e
+    puts "couldn't create object, sleeping for #{2**retries} seconds before next try..."
+    sleep(2**retries)
+    retries += 1
+
+    if retries <= 3
+      retry
+    else
+      puts "giving up."
+      raise e
+    end
+  end
+  obj
+}
+
+
+# ------------ runtime code
+
+client.process
+client.process
+client.process
+client.process
+
+

data/samples/fast_startup.rb

@@ -0,0 +1,83 @@
+# This sample demonstrates how Manana may be used to defer a long initialization 
+# to the first method call.
+#
+# run from the gem dir with: 
+# $ rake samples
+# $ ruby samples/fast_startup.rb 
+
+require_relative 'common/samples_helper.rb'
+
+# ------------------------- sample code starts here -------------------------
+
+require 'manana'
+require 'benchmark'
+
+
+class DeathStar
+
+  def initialize
+    puts "  DeathStar initialization sequence commencing..."
+    super_complex_startup_sequence
+    puts "  ...sequence complete."
+  end
+
+  def navigate_to(planet)
+    puts "setting course for the planet '#{planet}'"
+  end
+
+  private
+
+  def super_complex_startup_sequence
+    puts "    1. press the 'start' button."
+    puts "    2. snooze while Vader isn't looking."
+    sleep(5)
+    puts "    3. ???"
+    puts "    4. profit!"
+  end
+
+end
+
+# ------------ initialization code
+
+mini_death_star = nil
+
+puts "[Vader]: requsition a new DeathStar and make it snappy!"
+# boss said requisitions have to be faster*!  Manana to the rescue!
+puts Benchmark.measure {
+  mini_death_star = Manana.wrap {
+    DeathStar.new
+  }
+}
+puts "[Expendable Commander]: completed, sir!"
+
+
+puts "-------------------------------------------"
+
+
+# ------------ runtime code
+
+puts "[Vader]: ok, send it towards some rebels..."
+
+# * this first method eats the hidden startup cost... 
+puts Benchmark.measure { 
+  mini_death_star.navigate_to("Yavin")
+}
+puts "[Vader raises an eyebrow and starts to reach towards the commander] \n# first method call was long, but subsequent calls are faster..."
+
+# * subsequent method calls are fast though... maybe tradeoff is good enough for Vader?
+puts Benchmark.measure { 
+  mini_death_star.navigate_to("Bespin")
+}
+
+puts Benchmark.measure { 
+  mini_death_star.navigate_to("Tatooine")
+}
+
+puts "[Vader shrugs]: Well done Expendable Commander!"
+puts "[Expendable Commander sweatly profusely]: Thank you Lord Vader!"
+
+
+
+
+
+

data/samples/self_healing.rb

@@ -0,0 +1,104 @@
+# This sample demonstrates how Manana may be used to create a self-healing soap adapter
+# by wrapping an existing Savon::Model client.
+#
+# run from the gem dir with: 
+# $ rake samples
+# $ ruby samples/self_healing.rb 
+
+require_relative 'common/samples_helper.rb'
+
+# ------------------------- sample code starts here -------------------------
+
+require 'manana'
+require 'savon'
+require 'ostruct'
+
+# used to simulate conn up/down
+require 'webmock'
+include WebMock::API
+# fake a failure to get the wsdl (service down temporarily)
+stub_request(:any, /wsf.cdyne.com\/.*/).
+  to_return(:status => 500, :body => "Internal Server Error", :headers => {})
+
+
+LOGGING_ENABLED = false
+HTTPI.log = false unless LOGGING_ENABLED
+
+class Weather < OpenStruct
+  extend Savon::Model
+
+  client wsdl: "http://wsf.cdyne.com/WeatherWS/Weather.asmx?WSDL", convert_request_keys_to: :none, log: LOGGING_ENABLED
+
+  def self.setup
+    # if this were outside of setup() the class would fail to load if the service was down. 
+    # instead we dynamically initialize the available operations from withing a class method to be used by the Manana wrapper. 
+    operations *client.operations
+  end 
+  
+  def self.city_weather(zip)
+    resp = get_city_weather_by_zip(message: {"ZIP" => zip})
+    weather = resp.body[:get_city_weather_by_zip_response][:get_city_weather_by_zip_result]
+    Weather.new(weather)
+  end
+end
+
+
+# ------------ initialization code
+
+# Before we start, we use Manana to wrap the client setup so that method calls on the client can be self-healing in case of failure.
+# NOTE: that the caller doesn't have to deal with whether or not this initialization succeeded, they can just call the client methods repeatedly.
+client = Manana.wrap {
+  Weather.setup
+  Weather
+}
+
+
+# ------------ runtime code
+
+# first call fails...
+#  a) Weather.setup() called, but raises because the server is 500.
+begin
+  weather = client.city_weather("02201")
+rescue Wasabi::Resolver::HTTPError => e
+  puts "# 1. first call failed as expected, because Weather.setup() couldn't connect to provide the operations for the client."
+end
+
+# server restored
+WebMock.disable!
+
+# second call ok...
+#  a) Weather.setup() succeeds, caches instance for future use.
+#  b) city_weather() succeeds.
+weather = client.city_weather("02201")
+
+puts "# 2. second call should succeed; Weather.setup() runs successfully and returns a successfully intialized Weather class."
+puts "  > At %s the temperature is currently %s F and the humidity is %s." % [weather.city, weather.temperature, weather.relative_humidity]
+
+# server down again
+WebMock.enable!
+
+# third call; service down again...
+# remember, we already have a valid instance, so Weather.setup() is not called this time.
+# a) city_weather() fails because the server is 500.
+begin
+  weather = client.city_weather("02201")
+rescue Savon::HTTPError => e
+  puts "# 3. third call fails; the connection is down again, but this time the failure is in the API call since Weather has successfully intialized opertaions from call #2."
+end
+
+
+# server restored
+WebMock.disable!
+
+# fourth call ok...
+# a) city_weather() succeeds.
+weather = client.city_weather("02201")
+
+puts "# 4. fourth call should succeed; connection is up again, still using cached operations from the first time service was up (call #2)."
+puts "  > At %s the temperature is currently %s F and the humidity is %s." % [weather.city, weather.temperature, weather.relative_humidity]
+
+
+puts "\nThis concludes the demonstration of how Manana provides self-healing capability to a web-service adapter."
+
+
+

data/test/test_manana.rb

@@ -22,11 +22,7 @@ class TestManana < MiniTest::Unit::TestCase
       end
 
       def raise_something
-        raise "kablewey!"       # simulate a call that raises an exception
-      end
-
-      def self.do_another_thing
-        "I did something else"  # simulate a class method call
+        raise "kablooey!"       # simulate a call that raises an exception
       end
     }
   end
@@ -43,6 +39,14 @@ class TestManana < MiniTest::Unit::TestCase
     assert_raises RuntimeError do 
       obj.raise_something
     end
+
+    begin
+      obj.raise_something
+    rescue Exception => e
+      # make sure we get an appropriate stack trace at the point of raise.
+      assert_match(/test_manana.rb:25:in .raise_something./, e.backtrace.first)
+    end
+
   end
 
   def test_deferred_init
@@ -68,6 +72,14 @@ class TestManana < MiniTest::Unit::TestCase
     assert_instance_of(String, result)
 
 
+    begin
+      handle.raise_something
+    rescue Exception => e
+      # make sure we get an appropriate stack trace at the point of raise.
+      assert_match(/test_manana.rb:25:in .raise_something./, e.backtrace.first)
+    end
+
+
   end
 
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: manana
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-08 00:00:00.000000000 Z
+date: 2013-11-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -59,8 +59,8 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: provides a simple way to defer initialization of an object to action
-  on an object
+description: provides a simple way to defer initialization of an object until its
+  methods are called
 email:
 - larry.kyrala@gmail.com
 executables: []
@@ -77,9 +77,15 @@ files:
 - lib/manana.rb
 - lib/manana/version.rb
 - manana.gemspec
+- samples/common/samples.gemfile
+- samples/common/samples.gemfile.lock
+- samples/common/samples_helper.rb
+- samples/exponential_backoff.rb
+- samples/fast_startup.rb
+- samples/self_healing.rb
 - test/minitest_helper.rb
 - test/test_manana.rb
-homepage: ''
+homepage: https://github.com/coldnebo/manana
 licenses:
 - MIT
 post_install_message: 
@@ -94,7 +100,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3461867159210393723
+      hash: -1234298163661349463
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -103,13 +109,14 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -3461867159210393723
+      hash: -1234298163661349463
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
-summary: I'll get to your initialization tomorrow...
+summary: provides a simple way to defer initialization of an object until its methods
+  are called
 test_files:
 - test/minitest_helper.rb
 - test/test_manana.rb