simplerubysteps 0.0.7 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41e3a9ed5b8d6c32357fa880c2826cdf18a16fb9195260c5d10c7063b7dcb474
-  data.tar.gz: '07180493d6f6456f41164cd74f1410fb8bcd6649a645d109011c85ec9133c463'
+  metadata.gz: 2eca7ec6018c9962f0d8186ed64c50fc068550705f9105eeb67e73069435964a
+  data.tar.gz: 8a17b50a46fe226c1d55cd235ab25c5540356c08517345f2323a2708c131d265
 SHA512:
-  metadata.gz: 0620c89b84893c3e58078ab8dc66a211aaef5a52101a45e7392bde32bfdab3be3cc9d83bdee6e9adcfd1f3ecdc1e3420dd9068f58bea07550aad1993d0775a90
-  data.tar.gz: 50f9d29b51926176a2a3edc900694233f38d44511ef5115433cc756f88c74df5ffca90bc924406644580c43e1f9ca6e2b1e2f79187aa0b3c9eca003f14b2daae
+  metadata.gz: b5424b35119552d84924e1741c7b1ecfd8964058ad203db7fa0bceb5bf5dcd9880507a3d47aa1129b4664f9200da00b5e1275afb6a8725e1450119d99a2f3c6e
+  data.tar.gz: 59d20879dcdddaad13bad9744e92334b89efb7e5eb432bb66a2c0fba7c4f09894d56b34cebf378f4ffd28f3951d35f16202c03bfaf2618ef2dbabf39187e0916

data/README.md

@@ -1,55 +1,94 @@
 # Simplerubysteps
 
-Simplerubysteps simplifies the administration of AWS Step Functions with ruby (eventually - this is an early alpha version)
+Simplerubysteps makes it easy to manage AWS Step Functions with ruby (this is an early alpha version and should not really be used by anyone).
 
-This is software in the experimental stage and should not really be used by anyone. Be warned.
+## Installation and Usage
 
-## Installation
+### Prerequisites
 
-Prerequisites (for alpha version):
-* AWS CLI installed
+* AWS CLI installed (mainly for debugging privileges)
+* Configured AWS CLI profile with sufficient permissions to create IAM roles and policies, create Lambda functions, create and run Step Functions state machines, run CloudWatch log queries, etc.
 
-## Usage
-
-### Install the gem and the simplerubysteps CLI
+### Install the gem and the srs CLI
 
 ```
 gem install simplerubysteps
 ```
 
-### Create AWS Step Functions State Machine with ruby DSL
+### Create an AWS Step Function State Machine with the simplerubysteps Ruby DSL
 
 ```
-cd samples/sample1
+mkdir -p samples/hello-world
+cd samples/hello-world
+
 vi workflow.rb
 ```
 
-### Create CloudFormation stack with Step Functions State Machine and supporting Lambda function
+#### Hello World State Machine (workflow.rb)
+
+```
+require "simplerubysteps"
+include Simplerubysteps
+
+kind "EXPRESS"
+
+task :start do
+  transition_to :even do |data|
+    data["number"] % 2 == 0
+  end
+
+  default_transition_to :odd
+end
+
+task :even do
+  action do |data|
+    number = data["number"]
+
+    puts "Just for the record, I've discovered an even number: #{number}"
+
+    {
+      result: "#{number} is even",
+    }
+  end
+end
+
+task :odd do
+  action do |data|
+    {
+      result: "#{data["number"]} is odd",
+    }
+  end
+end
+```
+
+### Deploy the Step Functions State Machine and the Lambda function that implements the Task Actions.
 
 ```
-export AWS_PROFILE=...
-cd samples/sample1
-simplerubysteps deploy
+export AWS_PROFILE=<AWS CLI profile name with sufficient privileges>
+cd samples/hello-world
+
+srs deploy
 ```
 
-### Trigger State Machine Execution and wait for completion
+### Trigger State Machine executions
 
 ```
-export AWS_PROFILE=...          
-cd samples/sample1
+export AWS_PROFILE=<AWS CLI profile name with sufficient privileges>
+cd samples/hello-world
 
-./start-directbranch.sh
+echo "Enter a number"
+read NUMBER
 
-./sample-task-worker.sh &
-./start-callbackbranch.sh
+echo "{\"number\":$NUMBER}" | srs start | jq -r ".output" | jq -r ".result"
+# Above: will print "123 is odd" for input "123"
 ```
 
 ### Delete CloudFormation stack
 
 ```
-export AWS_PROFILE=...
-cd samples/sample1
-simplerubysteps destroy
+export AWS_PROFILE=<AWS CLI profile name with sufficient privileges>
+
+srs destroy
 ```
 
 ## Development
@@ -58,8 +97,9 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### TODOs
 
-* Custom IAM policies per Lambda task
+* Custom IAM policies per Lambda task (e.g. to allow a task to send a message to an SQS queue)
 * Workflow action unit test support
+* Better error handling and reporting
 * ...
 
 ## Contributing

data/exe/simplerubysteps

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-bin_dir = File.expand_path(File.dirname(__FILE__))
-include_path = File.join(bin_dir, "../lib/tool.rb")
+require "simplerubysteps"
+require "simplerubysteps/tool"
 
-require include_path
+Simplerubysteps::Tool.new.run

data/exe/srs

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require "simplerubysteps"
+require "simplerubysteps/tool"
+
+Simplerubysteps::Tool.new.run

data/lib/function.rb

@@ -1,6 +1,9 @@
-require "json"
+require "simplerubysteps"
+
 require "./workflow.rb"
 
+include Simplerubysteps
+
 def handler(event:, context:)
   puts ENV.inspect if ENV["DEBUG"]
   puts event if ENV["DEBUG"]

data/lib/simplerubysteps/dsl.rb

@@ -0,0 +1,86 @@
+require "json"
+
+module Simplerubysteps
+  $sm = StateMachine.new
+  $tasks = []
+
+  def kind(k)
+    $sm.kind = k
+  end
+
+  def task(name)
+    t = $sm.add Task.new(name)
+
+    $tasks.last.next = t if $tasks.last
+
+    $tasks.push t
+    yield if block_given?
+    $tasks.pop
+  end
+
+  def callback(name)
+    t = $sm.add Callback.new(name)
+
+    $tasks.last.next = t if $tasks.last
+
+    $tasks.push t
+    yield if block_given?
+    $tasks.pop
+  end
+
+  def action(&action_block)
+    $tasks.last.action &action_block
+  end
+
+  def transition(state)
+    $tasks.last.next = state
+  end
+
+  def transition_to(state, &condition_block)
+    choice = $tasks.last.implicit_choice
+
+    c = ChoiceItem.new({
+      :Variable => "$.#{choice.name}_#{state}",
+      :StringMatches => "yes",
+    })
+    c.next = state
+    c.implicit_condition_block = condition_block
+
+    choice.add c
+  end
+
+  def default_transition_to(state)
+    choice = $tasks.last.implicit_choice
+
+    choice.default = state
+  end
+
+  def choice(name)
+    t = $sm.add Choice.new(name)
+
+    $tasks.last.next = t if $tasks.last
+
+    $tasks.push t
+    yield if block_given?
+    $tasks.pop
+  end
+
+  def string_matches(var, match)
+    c = ChoiceItem.new({
+      :Variable => var,
+      :StringMatches => match,
+    })
+
+    $tasks.last.add c
+
+    $tasks.push c
+    yield if block_given?
+    $tasks.pop
+  end
+
+  def default
+    $tasks.push $tasks.last
+    yield if block_given?
+    $tasks.pop
+  end
+end

data/lib/simplerubysteps/model.rb

@@ -0,0 +1,186 @@
+module Simplerubysteps
+  $FUNCTION_ARN = ENV["LAMBDA_FUNCTION_ARN"] ? ENV["LAMBDA_FUNCTION_ARN"] : "unknown"
+
+  def function_name
+    return "unknown" unless $FUNCTION_ARN =~ /.+\:function\:(.+)/
+    $1
+  end
+
+  class StateMachine
+    attr_reader :states
+    attr_reader :start_at
+    attr_accessor :kind
+
+    def initialize()
+      @states = {}
+      @kind = "STANDARD"
+    end
+
+    def add(state)
+      @start_at = state.name unless @start_at
+
+      @states[state.name] = state
+      state.state_machine = self
+
+      state
+    end
+
+    def render
+      {
+        :StartAt => @start_at,
+        :States => @states.map { |name, state| [name, state.render] }.to_h,
+      }
+    end
+  end
+
+  class State
+    attr_reader :name
+    attr_accessor :state_machine
+
+    def initialize(name)
+      @name = name
+      @dict = {}
+    end
+
+    def []=(key, value)
+      @dict[key] = value
+    end
+
+    def next=(state)
+      @dict[:Next] = (state.is_a? Symbol) ? state : state.name
+    end
+
+    def render
+      dict = @dict
+      dict[:End] = true unless dict[:Next]
+      dict
+    end
+  end
+
+  class Task < State
+    def initialize(name)
+      super
+      @dict[:Type] = "Task"
+      @dict[:Resource] = $FUNCTION_ARN
+      @dict[:Parameters] = {
+        :Task => name,
+        "Input.$" => "$",
+      }
+
+      action { |input| input } # default: pass through
+    end
+
+    def action(&action_block)
+      @action_block = action_block
+    end
+
+    def perform_action(input)
+      output = nil
+      output = @action_block.call(input) if @action_block
+
+      if @implicit_choice
+        output = {} unless output
+        @implicit_choice.perform_action(output)
+      end
+
+      output
+    end
+
+    def implicit_choice
+      unless @implicit_choice
+        @implicit_choice = Choice.new("#{name}_choice")
+        $sm.add @implicit_choice
+        self.next = @implicit_choice
+      end
+      @implicit_choice
+    end
+  end
+
+  class Callback < State
+    def initialize(name)
+      super
+      @dict[:Type] = "Task"
+      @dict[:Resource] = "arn:aws:states:::lambda:invoke.waitForTaskToken"
+      @dict[:Parameters] = {
+        :FunctionName => function_name,
+        :Payload => {
+          :Task => name,
+          "Input.$" => "$",
+          "Token.$" => "$$.Task.Token",
+        },
+      }
+    end
+
+    def action(&action_block)
+      @action_block = action_block
+    end
+
+    def perform_action(input, token)
+      @action_block.call(input, token) if @action_block
+    end
+  end
+
+  class ChoiceItem
+    attr_accessor :implicit_condition_block
+
+    def initialize(dict = {}, state = nil)
+      @dict = dict
+      self.next = state if state
+    end
+
+    def next=(state)
+      @dict[:Next] = (state.is_a? Symbol) ? state : state.name
+    end
+
+    def render
+      @dict
+    end
+
+    def perform_action(choice_name, output)
+      if @implicit_condition_block
+        output["#{choice_name}_#{@dict[:Next]}"] = @implicit_condition_block.call(output) ? "yes" : "no"
+      end
+    end
+  end
+
+  class Choice < State
+    attr_reader :choices
+
+    def initialize(name)
+      super
+      @choices = []
+      @dict[:Type] = "Choice"
+    end
+
+    def add(item)
+      @choices.push item
+    end
+
+    def add_string_matches(var, match, state)
+      add ChoiceItem.new({
+            :Variable => var,
+            :StringMatches => match,
+          }, state)
+    end
+
+    def default=(state)
+      @dict[:Default] = (state.is_a? Symbol) ? state : state.name
+    end
+
+    def next=(state)
+      self.default = state
+    end
+
+    def render
+      dict = @dict.clone
+      dict[:Choices] = @choices.map { |item| item.render }
+      dict
+    end
+
+    def perform_action(output)
+      @choices.each do |choice|
+        choice.perform_action name, output
+      end
+    end
+  end
+end

data/lib/{statemachine.yaml → simplerubysteps/statemachine.yaml}

@@ -125,3 +125,5 @@ Outputs:
   StepFunctionsStateMachineARN:
     Value: !GetAtt StepFunctionsStateMachine.Arn
     Condition: CreateStepfunctions
+  StateMachineType:
+    Value: !Ref StateMachineType