collins_state 0.2.10

data/Gemfile

@@ -0,0 +1,15 @@
+source :rubygems
+
+Encoding.default_external = Encoding::UTF_8
+gem 'collins_client', '~> 0.2.7'
+gem 'escape',         '~> 0.0.4'
+
+group :development do
+  gem "rspec", "~> 2.10.0"
+  gem "yard", "~> 0.8"
+  gem 'redcarpet'
+  gem 'webmock'
+  gem "bundler", "~> 1.1.4"
+  gem "jeweler", "~> 1.8.4"
+  gem 'simplecov'
+end

data/Gemfile.lock

@@ -0,0 +1,55 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.3.2)
+    collins_client (0.2.7)
+      httparty (~> 0.8.3)
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    escape (0.0.4)
+    git (1.2.5)
+    httparty (0.8.3)
+      multi_json (~> 1.0)
+      multi_xml
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.5)
+    multi_json (1.3.6)
+    multi_xml (0.5.1)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    redcarpet (2.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    webmock (1.8.11)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yard (0.8.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.1.4)
+  collins_client (~> 0.2.7)
+  escape (~> 0.0.4)
+  jeweler (~> 1.8.4)
+  redcarpet
+  rspec (~> 2.10.0)
+  simplecov
+  webmock
+  yard (~> 0.8)

data/README.md

@@ -0,0 +1,6 @@
+# collins_state
+
+Collins state is a simple state management framework built on top of collins.
+
+Take a look at some of the specs or the provisioning workflow for some sample
+code.

data/Rakefile

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+jeweler = Jeweler::Tasks.new do |gem|
+  gem.name = "collins_state"
+  gem.homepage = "https://github.com/tumblr/collins/tree/master/support/ruby/collins-state"
+  gem.license = "APL 2.0"
+  gem.summary = %Q{Collins based state management}
+  gem.description = %Q{Provides basic framework for managing stateful processes with collins}
+  gem.email = "bmatheny@tumblr.com"
+  gem.authors = ["Blake Matheny"]
+  gem.files.exclude "spec/**/*"
+  gem.files.exclude '.gitignore'
+  gem.files.exclude '.rspec'
+  gem.files.exclude '.rvmrc'
+  gem.add_runtime_dependency 'collins_client',  '~> 0.2.7'
+  gem.add_runtime_dependency 'escape',          '~> 0.0.4'
+end
+
+task :help do
+  puts("rake -T                  # See available rake tasks")
+  puts("rake publish             # generate gemspec, build it, push it to repo")
+  puts("rake version:bump:patch  # Bump patch number")
+  puts("rake all                 # bump patch and publish")
+  puts("rake                     # Run tests")
+end
+
+task :publish => [:gemspec, :build] do
+  package_abs = jeweler.jeweler.gemspec_helper.gem_path
+  package_name = File.basename(package_abs)
+
+  ["repo.tumblr.net","repo.ewr01.tumblr.net"].each do |host|
+    puts("Copying #{package_abs} to #{host} and installing, you may be prompted for your password")
+    system "scp #{package_abs} #{host}:"
+    system "ssh -t #{host} 'sudo tumblr_gem install #{package_name}'"
+  end
+end
+
+task :all => ["version:bump:patch", :publish] do
+  puts("Done!")
+end
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.fail_on_error = false
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+  t.options = ['--markup', 'markdown']
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.10

data/collins_state.gemspec

@@ -0,0 +1,53 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = "collins_state"
+  s.version = "0.2.10"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Blake Matheny"]
+  s.date = "2012-10-31"
+  s.description = "Provides basic framework for managing stateful processes with collins"
+  s.email = "bmatheny@tumblr.com"
+  s.extra_rdoc_files = [
+    "README.md"
+  ]
+  s.files = [
+    "Gemfile",
+    "Gemfile.lock",
+    "README.md",
+    "Rakefile",
+    "VERSION",
+    "collins_state.gemspec",
+    "lib/collins/persistent_state.rb",
+    "lib/collins/state/mixin.rb",
+    "lib/collins/state/mixin_class_methods.rb",
+    "lib/collins/state/specification.rb",
+    "lib/collins/workflows/provisioning_workflow.rb",
+    "lib/collins_state.rb"
+  ]
+  s.homepage = "https://github.com/tumblr/collins/tree/master/support/ruby/collins-state"
+  s.licenses = ["APL 2.0"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.24"
+  s.summary = "Collins based state management"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<collins_client>, ["~> 0.2.7"])
+      s.add_runtime_dependency(%q<escape>, ["~> 0.0.4"])
+    else
+      s.add_dependency(%q<collins_client>, ["~> 0.2.7"])
+      s.add_dependency(%q<escape>, ["~> 0.0.4"])
+    end
+  else
+    s.add_dependency(%q<collins_client>, ["~> 0.2.7"])
+    s.add_dependency(%q<escape>, ["~> 0.0.4"])
+  end
+end
+

data/lib/collins/persistent_state.rb

@@ -0,0 +1,108 @@
+require 'collins/state/mixin'
+require 'escape'
+
+module Collins
+
+  # Provides state management via collins tags
+  class PersistentState
+
+    include ::Collins::State::Mixin
+    include ::Collins::Util
+
+    attr_reader :collins_client, :path, :exec_type, :logger
+
+    def initialize collins_client, options = {}
+      @collins_client = collins_client
+      @exec_type = :client
+      @logger = get_logger({:logger => collins_client.logger}.merge(options).merge(:progname => 'Collins_PersistentState'))
+    end
+
+    def run
+      self.class.managed_state(collins_client)
+      self
+    end
+
+    # @deprecated Use {#use_netcat} instead. Replace in 0.3.0
+    def use_curl path = nil
+      use_netcat(path)
+    end
+
+    def use_client
+      @path = nil
+      @exec_type = :client
+      self
+    end
+
+    def use_netcat path = nil
+      @path = Collins::Option(path).get_or_else("nc")
+      @exec_type = :netcat
+      self
+    end
+
+    # @override update_asset(asset, key, spec)
+    def update_asset asset, key, spec
+      username = collins_client.username
+      password = collins_client.password
+      host = collins_client.host
+      tag = ::Collins::Util.get_asset_or_tag(asset).tag
+      case @exec_type
+      when :netcat
+        netcat_command = [path, '-i', '1'] + get_hostname_port(host)
+        timestamp_padding, json = format_spec_for_netcat spec
+        body = "attribute=#{key};#{json}"
+        length = body.size + timestamp_padding
+        request = [request_line(tag)] + request_headers(username, password, length)
+        request_string = request.join("\\r\\n") + "\\r\\n\\r\\n" + body
+        current_time = 'TIMESTAMP=$(' + get_time_cmds(host).join(' | ') + ')'
+        args = ['printf', request_string]
+        "#{current_time}\n" + Escape.shell_command(args) + ' $TIMESTAMP | ' + Escape.shell_command(netcat_command)
+      else
+        super(asset, key, spec)
+      end
+    end
+
+    def get_time_cmds host
+      hostname, port = get_hostname_port host
+      get_cmd = %q{printf 'GET /api/timestamp HTTP/1.0\r\n\r\n'}
+      nc = sprintf('%s -i 1 %s %d', path, hostname, port)
+      only_time = %q{grep -e '^[0-9]'}
+      last_line = %q{tail -n 1}
+      [get_cmd, nc, only_time, last_line]
+    end
+
+    def request_line tag
+      "POST /api/asset/#{tag} HTTP/1.0"
+    end
+
+    def request_headers username, password, length
+      [
+        "User-Agent: collins_state",
+        auth_header(username, password),
+        "Content-Type: application/x-www-form-urlencoded",
+        "Content-Length: #{length}",
+        "Connection: Close"
+      ]
+    end
+
+    def auth_header username, password
+      auth = Base64.strict_encode64("#{username}:#{password}")
+      "Authorization: Basic #{auth}"
+    end
+
+    # @return [Array<Fixnum,String>] padding for format string and json to use
+    def format_spec_for_netcat spec
+      expected_timestamp_size = Time.now.utc.to_i.to_s.size
+      spec.timestamp = '%s'
+      actual_timestamp_size = spec.timestamp.to_s.size
+      timestamp_padding = (expected_timestamp_size - actual_timestamp_size).abs
+      json = spec.to_json
+      [timestamp_padding, json]
+    end
+    # @return [Array<String,String>] hostname and port
+    def get_hostname_port host
+      host = URI.parse(host)
+      [host.host, host.port.to_s]
+    end
+  end
+
+end

data/lib/collins/state/mixin.rb

@@ -0,0 +1,435 @@
+require 'collins/state/mixin_class_methods'
+require 'collins/state/specification'
+require 'json'
+
+module Collins; module State; module Mixin
+
+  class << self
+    # Classes that include Mixin will also be extended by ClassMethods
+    def included(base)
+      base.extend Collins::State::Mixin::ClassMethods
+    end
+  end
+
+  # @abstract Classes mixing this in must supply a collins client
+  # @return [Collins::Client] collins client
+  # @raise [NotImplementedError] if not specified
+  def collins_client
+    raise NotImplementedError.new("no collins client available")
+  end
+
+  # @abstract Classes mixing this in must supply a logger
+  # @return [Logger] logger instance
+  # @raise [NotImplementedError] if not specified
+  def logger
+    raise NotImplementedError.new("no logger available")
+  end
+
+  # The attribute name used for storing the sate value
+  # @note we append _json to the managed_state_name since it will serialize this way
+  # @return [String] the key to use for storing the state value on an asset
+  def attribute_name
+    self.class.managed_state_name.to_s + "_json"
+  end
+
+  # Has the specified asset state expired?
+  #
+  # Read the state from the specified asset, and determine whether the state is expired yet or not.
+  # The timestamp + expiration is compared to now.
+  #
+  # @note This method will return true if no specification is associated with the asset
+  # @param [Collins::Asset] asset The asset to look at
+  # @return [Boolean] True if the specification has expired, false otherwise
+  def expired? asset
+    specification_expired?(state_specification(asset))
+  end
+
+  # Whether we are done processing or not
+  # @param [Collins::Asset] asset
+  # @return [Boolean] whether asset is in done state or not
+  def finished? asset
+    state_specification(asset).to_option.map do |spec|
+      specification_expired?(spec) && event(spec.name)[:terminus]
+    end.get_or_else(false)
+  end
+
+  # The things that would be done if the asset was transitioned
+  # @param [Collins::Asset] asset
+  # @return [Array<Array<Symbol,String>>] array of arrays. Each sub array has two elements
+  def plan asset
+    plans = []
+    state_specification(asset).to_option.map { |specification|
+      event(specification.name).to_option.map { |ev|
+        if not specification_expired?(specification) then
+          plans << [:noop, "not yet expired"]
+        else
+          if ev[:transition] then
+            event(ev[:transition]).to_option.map { |ev2|
+              plans << [:event, ev2.name]
+            }.get_or_else {
+              plans << [:exception, "invalid event name #{ev[:transition]}"]
+            }
+          elsif not ev[:on_transition] then
+            plans << [:noop, "no transition specified, and no on_transition action specified"]
+          end
+          if ev[:on_transition] then
+            action(ev[:on_transition]).to_option.map { |ae|
+              plans << [:action, ae.name]
+            }.get_or_else {
+              plans << [:exception, "invalid action specified #{ev[:on_transition]}"]
+            }
+          end
+        end
+      }.get_or_else {
+        plans << [:exception, "invalid event name #{e.name}"]
+      }
+    }.get_or_else {
+      Collins::Option(initial).map { |init|
+        event(init).to_option.map { |ev|
+          if ev[:before_transition] then
+            action(ev[:before_transition]).to_option.map do |act|
+              plans << [:action, act.name]
+            end.get_or_else {
+              plans << [:exception, "action #{ev[:before_transition]} not defined"]
+            }
+          end
+          plans << [:event, init]
+        }.get_or_else {
+          plans << [:exception, "initial state #{init} is undefined"]
+        }
+      }.get_or_else {
+        plans << [:exception, "no initial state defined"]
+      }
+    }
+    plans
+  end
+
+  # Reset (delete) the attribute once the process is complete
+  #
+  # @param [Collins::Asset] asset The asset on which to delete the attribute
+  # @return [Boolean] True if the value was successfully deleted
+  def reset! asset
+    collins_client.delete_attribute! asset, attribute_name
+  end
+
+  # Return the name of the current sate. Will be :None if not initialized
+  # @param [Collins::Asset] asset
+  # @return [Symbol] state name
+  def state_name asset
+    state_specification(asset).name
+  end
+
+  # Get the state specification associated with the asset
+  #
+  # @param [Collins::Asset] asset The asset to retrieve
+  # @return [Collins::State::Specification] The spec (be sure to check `defined?`)
+  def state_specification asset
+    updated = asset_from_cache asset
+    result = updated.send(attribute_name.to_sym)
+    if result then
+      res = JSON.parse(result) rescue nil
+      if res.nil? then # for backwards compatibility
+        res = JSON.parse(result, :create_additions => false)
+        res = ::Collins::State::Specification.json_create(res) if (res.is_a?(Hash) and res.key?('data'))
+      end
+      if res.is_a?(::Collins::State::Specification) then
+        res
+      else
+        logger.warn("Could not deserialize #{result} to a State Specification")
+        ::Collins::State::Specification.empty
+      end
+    else
+      ::Collins::State::Specification.empty
+    end
+  end
+
+  # Transition the asset to the next appropriate state
+  #
+  # This method will either initialize the state on the specified asset (if needed), or process the
+  # current state. If processing the current state, the expiration time will be checked, followed by
+  # running any specified transition event, followed by any `on_transition` action. The transition
+  # event is run before the `on_transition` action, because the `on_transition` action should only be
+  # called if we have successfully transitioned to a new state. In the event that the transition
+  # event has a `before_transition` defined that fails, we don't want to execute the `on_transition`
+  # code since we have not yet successfully transitioned.
+  #
+  # @param [Collins::Asset] asset The asset to transition
+  # @param [Hash] options Transition options
+  # @option options [Boolean] :quiet Don't throw an exception if a transition fails
+  # @raise [CollinsError] if state needs to be initialized and no `:initial` key is found in the manage_state options hash
+  # @raise [CollinsError] if a specification is found on the asset, but the named state isn't found as a registered event
+  # @raise [CollinsError] if an action is specified as a `:before_transition` or `:on_transition` value but not registered
+  # @return [Collins::State::Specification] The current state, after the transition is run
+  def transition asset, options = {}
+    state_specification(asset).to_option.map { |specification|
+      event(specification.name).to_option.or_else {
+        raise CollinsError.new("no event defined with name #{specification.name}")
+      }.filter { |e| specification_expired?(specification) }.map { |e|
+        if e[:transition] then
+          spec = run_event(asset, e[:transition], options)
+          run_action(asset, e[:on_transition]) if e[:on_transition]
+          # If we transitioned and no expiration is set, rerun
+          if specification_expired?(spec) and spec.name != e.name then
+            transition(asset, options)
+          else
+            spec
+          end
+        else
+          logger.debug("No transition event specified for #{e.name}")
+          run_action(asset, e[:on_transition], :log => true) if e[:on_transition]
+          specification
+        end
+      }.get_or_else {
+        logger.trace("Specification #{specification.name} not yet expired")
+        specification
+      }
+    }.get_or_else {
+      init = Collins::Option(initial).get_or_else {
+        raise Collins::CollinsError.new("no initial state defined for transition")
+      }
+      options = Collins::Option(self.class.managed_state_options).get_or_else({})
+      run_event(asset, init, options)
+    }
+  end
+
+  # Allow registered events to be executed. Allow predicate calls to respond true if the asset is
+  # currently in the specified state or false otherwise
+  def method_missing method, *args, &block
+    if args.length == 0 then
+      return super
+    end
+    asset = args[0]
+    options = args[1]
+    if not (asset.is_a?(Collins::Asset) || asset.is_a?(String)) then
+      return super
+    end
+    if not options.nil? and not options.is_a?(Hash) then
+      return super
+    elsif options.nil? then
+      options = {}
+    end
+    question_only = method.to_s.end_with?('?')
+    if question_only then
+      meth = method.to_s[0..-2].to_sym # drop ? at end
+      if event?(meth) then
+        state_name(asset) == meth
+      else
+        false
+      end
+    elsif event?(method) then
+      run_event(asset, method, options)
+    else
+      super
+    end
+  end # method_missing
+
+  def respond_to? method
+    question_only = method.to_s.end_with?('?')
+    if question_only then
+      method = method.to_s[0..-2] # drop? at end
+    end
+    if not event?(method) then
+      super
+    else
+      true
+    end
+  end # respond_to?
+
+  protected
+  # Get the callback associated with the specified action name
+  # @param [Symbol] name Action name
+  # @return [Collins::SimpleCallback] always returns, check `defined?`
+  def action name
+    name_sym = name.to_sym
+    self.class.actions.fetch(name_sym, ::Collins::SimpleCallback.empty)
+  end
+
+  # True if an event with the given name is registered, false otherwise
+  # @param [Symbol] name Event name
+  # @return [Boolean] Registered or not
+  def event? name
+    event(name).defined?
+  end
+
+  # Get the callback associated with the specified event name
+  # @param [Symbol] name Event name
+  # @return [Collins::SimpleCallback] always returns, check `defined?`
+  def event name
+    name_sym = name.to_sym
+    self.class.events.fetch(name_sym, ::Collins::SimpleCallback.empty)
+  end
+
+  # Get the expires time associated with the specified event
+  #
+  # @param [Symbol] name Name of the event
+  # @param [Fixnum] default Value if event not found or expires not specified
+  # @return [Fixnum] An integer representing the number of seconds before expiration
+  def event_expires name, default = 0
+    event(name).to_option.map do |e|
+      e.options.fetch(:expires, default.to_i)
+    end.get_or_else(default.to_i)
+  end
+
+  # Initial event or nil
+  def initial
+    Collins::Option(self.class.managed_state_options).
+      filter{|h| h.key?(:initial)}.
+      map{|h| h[:initial]}.
+      get_or_else(nil)
+  end
+
+  # Run the specified action
+  #
+  # @param [Collins::Asset] asset the asset to run the action for
+  # @param [Symbol] name the action name
+  # @param [Hash] options
+  # @option options [Boolean] :log (true) log action run
+  # @return [Boolean] the result of executing the action
+  def run_action asset, name, options = {}
+    action(name).to_option.map do |a|
+      result = case a.arity
+                when 2
+                  a.call(asset, self)
+                else
+                  a.call(asset)
+                end
+      log_run_action(asset, name, result) if options.fetch(:log, false)
+      result
+    end.get_or_else {
+      raise CollinsError.new("Action #{name} not defined")
+    }
+  end
+
+  # Update the asset spec that the action was run
+  # @param [Collins::Asset] asset
+  # @param [Symbol] action_name
+  # @param [Boolean] result of the action that was run
+  # @return [Collins::State::Specification]
+  def log_run_action asset, action_name, result
+    current_spec = state_specification asset
+    count = current_spec.fetch(:log, []).size
+    log = Hash[:count => count, :timestamp => Time.now.utc.to_i, :name => action_name, :result => result]
+    current_spec.<<(:log, log)
+    asset_cache_delete asset
+    update_asset asset, attribute_name, current_spec
+    current_spec
+  end
+
+  # Run the specified event, and execute :before_transition if specified
+  #
+  # @param [Collins::Asset] asset the asset to process the event for
+  # @param [Symbol] name the name of the event to process
+  # @param [Hash] options Option for executing the event
+  # @option options [Boolean] :quiet Do not throw an exception if an error occurs running actions
+  # @return [Collins::State::Specification] the new state the asset is in
+  def run_event asset, name, options = {}
+    event(name).to_option.map do |e|
+      update_state(asset, e, options)
+    end.get_or_else {
+      raise CollinsError.new("Event #{name} not defined")
+    }
+  end
+
+  # Whether the given specification has expired or not
+  #
+  # This method is primarily useful for testing whether a stored specification has expired yet or
+  # not. If a specification has just been created (and has an expiration set), this will obviously
+  # return false.
+  #
+  # @param [Collins::State::Specification] specification
+  # @return [Boolean] true if expired, false otherwise
+  def specification_expired? specification
+    timestamp = specification.timestamp
+    name = specification.name
+    expires_at = timestamp + event_expires(name)
+    # Must be >= otherwise 0 + Time.now as expires_at will fail
+    Time.now.utc.to_i >= expires_at
+  end
+
+  # Update asset state using the specified event information
+  #
+  # This method also handles executing appropriate transition related actions and managing failures.
+  # The actual code for updating the asset itself is in #update_asset
+  #
+  # @param [Collins::Asset] asset the asset to update
+  # @param [Collins::SimpleCallback] event the event
+  # @param [Hash] options Option for executing the event
+  # @option options [Boolean] :quiet Do not throw an exception if an error occurs running actions
+  def update_state asset, event, options = {}
+    if event[:before_transition] then
+      run_before_transition asset, event[:before_transition], event, options
+    else
+      specification = Collins::State::Specification.new event.name, event[:desc], Time.now
+      specification = specification.merge(state_specification(asset))
+      asset_cache_delete asset
+      res = update_asset asset, attribute_name, specification
+      # Horrible hack to allow update_asset to be overridden such that it can provide a string
+      # for performing an update, in which case we need the actual command
+      if res.is_a?(String) then
+        return res
+      else
+        return specification
+      end
+    end
+  end
+
+  # Run the specified before_transition
+  # We try running the specified action, and if successful update the asset with the specification.
+  # If running the action fails, we update the attempts count on the current specification and
+  # either throw an exception (default behavior) or return the updated spec (options[:quiet] ==
+  # true). On success we return the new specification.
+  def run_before_transition asset, action_name, event, options
+    before_result = 
+      begin
+        run_action(asset, action_name)
+      rescue Exception => e
+        logger.warn("Failed running #{action_name}: #{e}")
+        false
+      end
+    if before_result != false
+      specification = Collins::State::Specification.new event.name, event[:desc], Time.now
+      specification = specification.merge(state_specification(asset))
+      asset_cache_delete asset
+      update_asset asset, attribute_name, specification
+      specification
+    else
+      current_spec = state_specification(asset)
+      count = current_spec.fetch(:attempts, []).size
+      attempts = Hash[:timestamp => Time.now.utc.to_i, :count => count, :name => event.name]
+      current_spec.<<(:attempts, attempts)
+      asset_cache_delete asset
+      update_asset asset, attribute_name, current_spec
+      if options.fetch(:quiet, false) then
+        return current_spec
+      else
+        raise CollinsError.new("Can't transition from #{current_spec.name} to #{event.name}, before_transition failed")
+      end
+    end
+  end
+
+  # Update the asset using the specified key and JSON
+  #
+  # This method is broken out this way so it can be easily overriden
+  # @param [Collins::Asset] asset The asset to update
+  # @param [String] key The attribute to update on the asset
+  # @param [Specification] spec The state specification to set as the value associated with the key
+  # @return [Boolean] indication of success or failure
+  def update_asset asset, key, spec
+    collins_client.set_attribute! asset, key, spec.to_json
+  end
+
+  private
+  def asset_cache_delete asset
+    tag = Collins::Util.get_asset_or_tag(asset).tag
+    @_asset_cache.delete(tag) if (@_asset_cache && @_asset_cache.key?(tag))
+  end
+  def asset_from_cache asset
+    tag = Collins::Util.get_asset_or_tag(asset).tag
+    @_asset_cache = {} unless @_asset_cache
+    if not @_asset_cache.key?(tag) then
+      @_asset_cache[tag] = collins_client.get(tag)
+    end
+    @_asset_cache[tag]
+  end
+
+end; end; end

data/lib/collins/state/mixin_class_methods.rb

@@ -0,0 +1,128 @@
+require 'collins/simple_callback'
+
+module Collins; module State; module Mixin
+
+  # Static (Class) methods to be added to classes that mixin this module. These methods provide
+  # functionality for registering new actions and events, along with access to the managed state.
+  # This is accomplished via class instance variables which allow each class that include the
+  # {Collins::State::Mixin} its own managed state and variables.
+  module ClassMethods
+
+    # @return [Hash<Symbol, Collins::SimpleCallback>] Registered actions for the managed state
+    attr_reader :actions
+
+    # @return [Hash<Symbol, Collins::SimpleCallback>] Registered events for the managed state
+    attr_reader :events
+
+    # Register a managed state for this class
+    #
+    # @note Only one managed state per class is allowed.
+    # @param [Symbol] name The name of the managed state, e.g. `:some_process`
+    # @param [Hash] options Managed state options
+    # @option options [Symbol] :initial First event to fire if the state is being initialized
+    # @yieldparam [Collins::Client] block Managed state description, registering events and actions
+    #
+    # @example
+    #  manage_state :a_process, :initial => :start do |client|
+    #    action :log_it do |asset|
+    #      client.log! asset, "Did some logging"
+    #    end
+    #    event :start, :desc => 'Initial state', :expires => after(30, :minutes), :on_transition => :log_it, :transition => :done
+    #    event :done, :desc => 'Done'
+    #  end
+    def manage_state name, options = {}, &block
+      @actions = {}
+      @events = {}
+      @managed_state = ::Collins::SimpleCallback.new(name, options, block)
+    end
+
+    # @return [String] Name of managed state associated with this class
+    def managed_state_name
+      @managed_state.name
+    end
+
+    # @return [Hash] Options associated with this managed state
+    def managed_state_options
+      @managed_state.options
+    end
+
+    # Get and execute the managed state associated with this class
+    #
+    # @see {#manage_state}
+    # @param [Collins::Client] client Collins client instance
+    def managed_state client
+      @managed_state.call(client)
+    end
+
+    # Register a named action for use as a transition execution target
+    #
+    # Actions are called when specified by a `:before_transition` or `:on_transition` option to an
+    # event. Options are not currently used.
+    #
+    # @param [Symbol] name Action name
+    # @param [Hash] options Action options
+    # @yieldparam [Collins::Asset] block Given an asset, perform the specified action
+    # @yieldreturn [Boolean,Object] indicates success or failure of operation. Only `false` (or an exception) indicate failure. Other return values are fine.
+    # @return [Collins::SimpleCallback] the callback created for the action
+    def action name, options = {}, &block
+      name_sym = name.to_sym
+      new_action = ::Collins::SimpleCallback.new(name_sym, options, block)
+      @actions[name_sym] = new_action
+      new_action
+    end
+
+    # Register a named event associated with the managed state
+    #
+    # Events are typically called as method invocations on the class, or as the result of a state
+    # being expired and a transition being specified.
+    #
+    # The example (and events in general) can be read as: Execute `:before_transition` before
+    # successfully transitioning to this event. Once transitioned, after `:expires` is reached the
+    # `:on_transition` action should be called, followed by the event associated with the specified
+    # `:transition`.
+    #
+    # @param [Symbol] name Event name
+    # @param [Hash] options Event options
+    # @option options [Symbol] :before_transition An action to execute successfully before transitioning to this state
+    # @option options [String] :desc A description of the event, required
+    # @option options [#to_i] :expires Do not consider `:on_transition` or `:transition` until after this amount of time
+    # @option options [Symbol] :on_transition Once the expiration time has passed execute this action
+    # @option options [Symbol] :transition The event to call after its appropriate for transition (due to timeout and successful `:before` calls)
+    # @return [Collins::SimpleCallback] the callback created for the action
+    #
+    # @example
+    #  event :stuff, :desc => 'I do things', :before_transition => :try_action, :expires => after(5, :minutes),
+    #                :transition => :after_stuff_event, :on_transition => :stuff_action
+    #
+    # @note A transition will not occur unless the :before_transition is successful (does not return false or throw an exception)
+    # @raise [KeyError] if the options hash is missing a `:desc` key
+    def event name, options = {}
+      name_sym = name.to_sym
+      ::Collins::Option(options[:desc]).or_else {
+        raise KeyError.new("Event #{name} is missing :desc key")
+      }
+      new_event = ::Collins::SimpleCallback.new(name_sym, options)
+      @events[name_sym] = new_event
+      new_event
+    end
+
+    # Convert a `Fixnum` into seconds based on the specified `time_unit`
+    #
+    # @param [Fixnum] duration Time value
+    # @param [Symbol] time_unit Unit of time, one of `:hour`, `:hours`, `:minute`, `:minutes`.
+    # @return [Fixnum] Value in seconds
+    def after duration, time_unit = :seconds
+      multiplier = case time_unit
+                   when :hours, :hour
+                     60*60
+                   when :minutes, :minute
+                     60
+                   else
+                     1
+                   end
+      multiplier * duration.to_i
+    end
+
+  end # Collins::State::Mixin::ClassMethods
+
+end; end; end

data/lib/collins/state/specification.rb

@@ -0,0 +1,192 @@
+require 'json'
+
+module Collins; module State
+
+  # Represents a managed state
+  #
+  # Modeling a state machine like process in collins is useful for multi-step processes such as
+  # decommissioning hardware (where you want the process to span several days, with several
+  # discrete steps), or monitoring some process and taking action. A
+  # {Specification} provides a common format for storing state information
+  # as a value of an asset.
+  #
+  # This will rarely be used directly, but rather is a byproduct of using
+  # {Collins::State::Mixin}
+  class Specification
+    include ::Collins::Util
+
+    # Used as name placeholder when unspecified
+    EMPTY_NAME = :None
+    # Used as description placeholder when unspecified
+    EMPTY_DESCRIPTION = "Unspecified"
+
+    # Create an empty specification
+    # @return [Collins::State::Specification] spec
+    def self.empty
+      ::Collins::State::Specification.new :none => true
+    end
+
+    # Create an instance from JSON data
+    #
+    # @note This method is required by the JSON module for deserialization
+    # @param [Hash] json JSON data
+    # @return [Collins::State::Specification] spec
+    def self.json_create json
+      ::Collins::State::Specification.new json['data']
+    end
+
+    # @return [Symbol] Name of the specification.
+    # @see Collins::State::Mixin::ClassMethods#event
+    # @note This is a unique key and should not change.
+    attr_reader :name
+
+    # @return [String] State description, for humans
+    # @see Collins::State::Mixin::ClassMethods#event
+    attr_reader :description
+
+    # @return [Fixnum] Unixtime, UTC, when this state was entered
+    attr_accessor :timestamp
+
+    # @return [Hash] Additional meta-data
+    attr_reader :extras
+
+    # Instantiate a new Specification
+    #
+    # @param [Hash,(Symbol,String,Fixnum)] args Arguments for instantiation
+    # @option args [String,Symbol] :name The name of the specification
+    # @option args [String] :description A description of the specification
+    # @option args [Fixnum,Time,String] :timestamp (Time.at(0).utcto_i) The time the event occurred
+    #
+    # @example
+    #  Specification.new :start, 'I am a state', Time.now
+    #  Specification.new :start, :description => 'Hello World', :timestamp => 0
+    # 
+    # @note If the specified timestamp is not a `Fixnum` (unixtime), the value is converted to a fixnum
+    # @raise [ArgumentError] when `timestamp` is not a `Time`, `String` or `Fixnum`
+    # @raise [ArgumentError] when `name` or `description` not specified
+    def initialize *args
+      opts = {}
+      while arg = args.shift do
+        if arg.is_a?(Hash) then
+          opts.update(arg)
+        else
+          key = [:name, :description, :timestamp].select{|k| !opts.key?(k)}.first
+          opts.update(key => arg) unless key.nil?
+        end
+      end
+      opts = symbolize_hash(opts)
+
+      if opts.fetch(:none, false) then
+        @name = EMPTY_NAME
+        @description = EMPTY_DESCRIPTION
+      else
+        @name = ::Collins::Option(opts.delete(:name)).map{|s| s.to_sym}.get_or_else {
+          raise ArgumentError.new("Name not specified")
+        }
+        @description = ::Collins::Option(opts.delete(:description)).get_or_else {
+          raise ArgumentError.new("Description not specified")
+        }
+      end
+      ts = ::Collins::Option(opts.delete(:timestamp)).get_or_else(Time.at(0))
+      @timestamp = parse_timestamp(ts)
+      # Flatten if needed
+      if opts.key?(:extras) then
+        @extras = opts[:extras]
+      else
+        @extras = opts
+      end
+    end
+
+    # merges appropriate extras from the other spec into this one
+    # @param [Collins::State::Specification] other
+    def merge other
+      ext = other.extras.merge(@extras)
+      ext.delete(:none)
+      @extras = ext
+      self
+    end
+
+    # @return [Boolean] Indicate whether Specification is empty or not
+    def empty?
+      !self.defined?
+    end
+
+    # @return [Boolean] Indicate whether Specification is defined or not
+    def defined?
+      @name != EMPTY_NAME || @description != EMPTY_DESCRIPTION
+    end
+
+    # @return [Collins::Option] None if undefined/empty
+    def to_option
+      if self.defined? then
+        ::Collins::Some(self)
+      else
+        ::Collins::None()
+      end
+    end
+
+    def [](key)
+      @extras[key.to_sym]
+    end
+    def key?(key)
+      @extras.key?(key.to_sym)
+    end
+    def fetch(key, default)
+      @extras.fetch(key.to_sym, default)
+    end
+    def []=(key, value)
+      @extras[key.to_sym] = value
+    end
+
+    def <<(key, value)
+      @extras[key.to_sym] = [] unless @extras.key?(key.to_sym)
+      @extras[key.to_sym] << value
+      @extras[key.to_sym]
+    end
+
+    # Convert this instance to JSON
+    #
+    # @note this is required by the JSON module
+    # @return [String] JSON string representation of object
+    def to_json(*a)
+      {
+        'json_class' => self.class.name,
+        'data' => to_hash
+      }.to_json(*a)
+    end
+
+    # @return [Hash] Hash representation of data
+    def to_hash
+      h = Hash[:name => name, :description => description, :timestamp => timestamp]
+      h[:extras] = extras unless extras.empty?
+      h
+    end
+
+    # @return [String] human readable
+    def to_s
+      "Specification(name = #{name}, description = #{description}, timestamp = #{timestamp}, extras = #{extras})"
+    end
+
+    # Mostly used for testing
+    def ==(other)
+      (other.class == self.class) &&
+        other.name == self.name &&
+        other.timestamp == self.timestamp
+    end
+
+    private
+    def parse_timestamp ts
+      if ts.is_a?(String) then
+        ts.to_s.to_i
+      elsif ts.is_a?(Time) then
+        ts.utc.to_i
+      elsif ts.is_a?(Fixnum) then
+        ts
+      else
+        raise ArgumentError.new("timestamp is not a String, Time, or Fixnum")
+      end
+    end
+
+  end # class Specification
+
+end; end

data/lib/collins/workflows/provisioning_workflow.rb

@@ -0,0 +1,57 @@
+require 'collins_state'
+
+module Collins
+  class ProvisioningWorkflow < ::Collins::PersistentState
+
+    manage_state :provisioning_process, :initial => :start do |client|
+
+      action :reboot_hard do |asset, p|
+        p.logger.warn "Calling rebootHard on asset #{Collins::Util.get_asset_or_tag(asset).tag}"
+        client.power! asset, "rebootHard"
+      end
+
+      action :reprovision do |asset, p|
+        detailed = client.get asset
+        p.logger.warn "Reprovisioning #{detailed.tag}"
+        client.set_status! asset, "Maintenance"
+        client.provision asset, detailed.nodeclass, detailed.contact, :suffix => detailed.suffix,
+          :primary_role => detailed.primary_role, :secondary_role => detailed.secondary_role,
+          :pool => detailed.pool
+      end
+
+      action :toggle_status do |asset, p|
+        tag = Collins::Util.get_asset_or_tag(asset).tag
+        p.logger.warn "Toggling status (Provisioning then Provisioned) for #{tag}"
+        client.set_status!(asset, 'Provisioning') && client.set_status!(asset, 'Provisioned')
+      end
+
+      # No transitions are defined here, since they are managed fully asynchronously by the
+      # supervisor process. We only defines actions to take once the timeout has passed. Each
+      # part of the process makes an event call, the supervisor process just continuously does a
+      # collins.managed_process("ProvisioningWorkflow").transition(asset) which will
+      # either execute the on_transition action due to expiration or do nothing.
+
+      # After 30 minutes reprovision if still in the start state - ewr_start_provisioning - collins.managed_process("ProvisioningWorkflow").start(asset)
+      event :start, :desc => 'Provisioning Started', :expires => after(30, :minutes), :on_transition => :reprovision
+      # After 10 minutes if we haven't seen an ipxe request, reprovision (possible failed move) - vlan changer & provisioning status - collins.mp.vlan_moved_to_provisioning(asset)
+      event :vlan_moved_to_provisioning, :desc => 'Moved to provisioning VLAN', :expires => after(15, :minutes), :on_transition => :reprovision
+      # After 5 minutes if we haven't yet seen a kickstart request, reboot (possibly stuck at boot) - phil ipxe
+      event :ipxe_seen, :desc => 'Asset has made iPXE request to Phil', :expires => after(5, :minutes), :on_transition => :reboot_hard
+      # After 5 minutes if the kickstart process hasn't begun, reboot (possibly stuck at boot) - phil kickstart
+      event :kickstart_seen, :desc => 'Asset has made kickstart request to Phil', :expires => after(15, :minutes), :on_transition => :reboot_hard
+      # After 45 minutes if we haven't gotten to post, reboot to reinstall - phil kickstart pre
+      event :kickstart_started, :desc => 'Asset has started kickstart process', :expires => after(45, :minutes), :on_transition => :reboot_hard
+      # After 45 minutes if the kickstart process hasn't completed, reboot to reinstall - phil kickstart post
+      event :kickstart_post_started, :desc => 'Asset has started kickstart post section', :expires => after(45, :minutes), :on_transition => :reboot_hard
+      # After 10 minutes if we haven't been moved to the production VLAN, toggle our status to get us moved - phil kickstart post
+      event :kickstart_finished, :desc => 'Asset has finished kickstart process', :expires => after(15, :minutes), :on_transition => :toggle_status
+      # After another 15 minutes if still not moved toggle our status again - vlan changer when discover=true
+      event :vlan_move_to_production, :desc => 'Moved to production VLAN', :expires => after(15, :minutes), :on_transition => :toggle_status
+      # After another 10 minutes if we're not reachable by IP, toggle the status - supervisor
+      event :reachable_by_ip, :desc => 'Now reachable by IP address', :expires => after(10, :minutes), :on_transition => :toggle_status
+      # Place holder for when we finish
+      event :done, :desc => 'Finished', :terminus => true
+    end
+  end
+
+end

data/lib/collins_state.rb

@@ -0,0 +1,4 @@
+$:.unshift File.join File.dirname(__FILE__)
+require 'collins_client'
+require 'collins/persistent_state'
+Dir[File.join(File.dirname(__FILE__), 'collins', 'workflows', '*.rb')].each {|f| require f}

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: collins_state
+version: !ruby/object:Gem::Version
+  version: 0.2.10
+  prerelease: 
+platform: ruby
+authors:
+- Blake Matheny
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: collins_client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.7
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.2.7
+- !ruby/object:Gem::Dependency
+  name: escape
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.4
+description: Provides basic framework for managing stateful processes with collins
+email: bmatheny@tumblr.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- VERSION
+- collins_state.gemspec
+- lib/collins/persistent_state.rb
+- lib/collins/state/mixin.rb
+- lib/collins/state/mixin_class_methods.rb
+- lib/collins/state/specification.rb
+- lib/collins/workflows/provisioning_workflow.rb
+- lib/collins_state.rb
+homepage: https://github.com/tumblr/collins/tree/master/support/ruby/collins-state
+licenses:
+- APL 2.0
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3397090300883848228
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Collins based state management
+test_files: []