dk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
---- 
-SHA512: 
-  data.tar.gz: 6d18c6023b43628117f27c2b7c60441a125ba6f126cd40a712cf635e7f9956728b68d94387ccfee8d4a4b26047dd1de48328304c428c5477727aa560238c46b9
-  metadata.gz: c3224e1ceea343b4a365dde9955d30e4cb6062365053e44a0fe17c00b90a32363365135259fdaf6b3651a24e6bff0b7f2fc9a704c0902fdf85f6460391610778
-SHA1: 
-  data.tar.gz: 5dc5bf7f2a83491664acdb2a9d55112149eed2e3
-  metadata.gz: 494082902e15484e13409bad7f209d6342ac671a
+---
+SHA256:
+  metadata.gz: c14d5db8726cb02f2fd49b2925a6668c2ba4b2726f2bc8fe09930a59464e3bbf
+  data.tar.gz: 1e15c547e84c278fbe6f00bf3cd03ab87503fdf7cc7f88086389f8f72334da4d
+SHA512:
+  metadata.gz: 35fb927197d925fd5c67b46787a9ca696c048a0796c4cfc684f658e2ef728d379ae4291f6848de0de000c55857831c58c8517e3174ec55e988c134198604a036
+  data.tar.gz: b6ec29e8044f4921a0309a9e40f4ebddb173de26b00917bc3f0f8b6ecc0fa2ef1fc1b354a25d65f16dc6ec595629350d99e9abf8fbf894bc1506782b1a135bb0

data/README.md

@@ -30,6 +30,7 @@ Now route this task with a name so it can be run from the CLI:
 ```ruby
 # in config/dk.rb or whatever
 require 'dk'
+require 'my_task'
 
 Dk.configure do
 
@@ -46,6 +47,8 @@ my-task # my task that does something great
 $ dk my-task
 ```
 
+See [dk-abdeploy](https://github.com/redding/dk-abdeploy#usage) for another example using Dk tasks to deploy code.
+
 ### CLI
 
 ```
@@ -311,6 +314,8 @@ Each callback can be optionally configured with a set of params.  Callbacks can
 
 ##### `ssh_hosts`
 
+Use the `ssh_hosts` helper to set new ssh host lists values like you would on the main config:
+
 ```ruby
 require 'dk/task'
 
@@ -331,10 +336,12 @@ class MyTask
 end
 ```
 
-Use the `ssh_hosts` method to set new ssh host lists values like you would on the main config.  Any subsequent tasks that are run will have these ssh hosts available to their `ssh` commands.
+Any subsequent tasks that are run will have these ssh hosts available to their `ssh` commands.
 
 ##### `run_task`
 
+Use the `run_task` helper to run other tasks:
+
 ```ruby
 require 'dk/task'
 require 'my_other_task'
@@ -353,10 +360,12 @@ class MyTask
 end
 ```
 
-Use the `run_task` helper to run other tasks.  This method takes an optional set of param values.  Any params given will be merged onto the global config params and made available to just the task being run.
+This method takes an optional set of param values.  Any params given will be merged onto the global config params and made available to just the task being run.
 
 ##### `cmd`, `cmd!`
 
+Use the `cmd` and `cmd!` helpers to run local system cmds:
+
 ```ruby
 require 'dk/task'
 
@@ -371,10 +380,55 @@ class MyTask
 end
 ```
 
-Use the `cmd` helper to run local system cmds.  Pass it a string system command to run and it runs it using [Scmd](https://github.com/redding/scmd).  You can [optionally pass in an `:env` param](https://github.com/redding/scmd#environment-variables) with any ENV vars that need to be set.  A `Dk::Local::Cmd` object is returned so you can access data such as the `stdout`, `stderr` and whether the command was successful or not.
+Pass them a string system command to run and it runs it using [Scmd](https://github.com/redding/scmd).  You can [optionally pass in an `:env` param](https://github.com/redding/scmd#environment-variables) with any ENV vars that need to be set.  A `Dk::Local::Cmd` object is returned so you can access data such as the `stdout`, `stderr` and whether the command was successful or not.
 
 The `cmd!` helper is identical to the `cmd` helper except that it raises a `Dk::Task::CmdRunError` if the command was not successful.
 
+##### `start`
+
+Use the `start` helper to asynchronously run a local system cmd:
+
+```ruby
+require 'dk/task'
+
+class MyTask
+  include Dk::Task
+
+  def run!
+    # run, but don't block waiting on an exitstatus
+    server_cmd = start "bin/server"
+
+    server_cmd.running?   # => true
+    server_cmd.pid        # => 12345
+    server_cmd.exitstatus # => nil
+
+    # do other stuff...
+
+    server_cmd.wait       # wait indefinitely until cmd exits
+    server_cmd.running?   # => false
+    server_cmd.pid        # => 12345
+    server_cmd.exitstatus # => 0
+  end
+
+end
+```
+
+OR, you can also asynchorously run with timeouts:
+
+```ruby
+# run, but don't block waiting on an exitstatus
+server_cmd = start "bin/server"
+
+begin
+  server_cmd.wait(10)
+rescue Dk::CmdTimeoutError => err
+  cmd.stop(10) # attempt to stop the cmd nicely, kill if doesn't stop in time
+  cmd.kill     # OR, just kill the cmd now
+end
+```
+
+This helper behaves just like `cmd` and `cmd!`. The only difference is it won't block waiting for the system command to run. It uses [Scmd](https://github.com/redding/scmd) to run system commmands and proxies most of its command API - see [the Scmd usage docs](https://github.com/redding/scmd#usage) for additional reference.
+
 ##### `ssh`, `ssh!`
 
 ```ruby

data/dk.gemspec

@@ -22,6 +22,6 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency("much-plugin", ["~> 0.2.0"])
   gem.add_dependency("scmd",        ["~> 3.0.3"])
-  gem.add_dependency("logsly",      ["~> 1.3.2"])
+  gem.add_dependency("logsly",      ["~> 1.3.3"])
 
 end

data/lib/dk.rb

@@ -20,7 +20,8 @@ module Dk
     @config = Config.new
   end
 
-  NoticeError  = Class.new(RuntimeError)
-  NoParamError = Class.new(ArgumentError)
+  NoticeError     = Class.new(RuntimeError)
+  NoParamError    = Class.new(ArgumentError)
+  CmdTimeoutError = Class.new(RuntimeError)
 
 end

data/lib/dk/local.rb

@@ -16,13 +16,34 @@ module Dk::Local
 
     def to_s; self.cmd_str; end
 
+    def start(input = nil)
+      @scmd.start(input)
+      self
+    end
+
+    def wait(timeout = nil)
+      begin
+        @scmd.wait(timeout)
+      rescue Scmd::TimeoutError => e
+        raise Dk::CmdTimeoutError, e.message
+      end
+      self
+    end
+
+    def stop(timeout = nil)
+      @scmd.stop(timeout)
+      self
+    end
+
     def run(input = nil)
       @scmd.run(input)
       self
     end
 
+    def pid;      @scmd.pid;      end
     def stdout;   @scmd.stdout;   end
     def stderr;   @scmd.stderr;   end
+    def running?; @scmd.running?; end
     def success?; @scmd.success?; end
 
     def output_lines
@@ -65,6 +86,11 @@ module Dk::Local
       @cmd_opts = opts
     end
 
+    def start_input
+      return nil unless self.start_called?
+      self.start_calls.first.input
+    end
+
     def run_input
       return nil unless self.run_called?
       self.run_calls.first.input
@@ -74,6 +100,9 @@ module Dk::Local
     def stderr=(value);     @scmd.stderr     = value; end
     def exitstatus=(value); @scmd.exitstatus = value; end
 
+    def start_calls;   @scmd.start_calls;   end
+    def start_called?; @scmd.start_called?; end
+
     def run_calls;   @scmd.run_calls;   end
     def run_called?; @scmd.run_called?; end
 

data/lib/dk/runner.rb

@@ -109,12 +109,16 @@ module Dk
       self.logger.debug "===================================="
     end
 
-    def cmd(task, cmd_str, input, given_opts)
-      build_and_run_local_cmd(task, cmd_str, input, given_opts)
+    def start(*args)
+      build_and_start_local_cmd(*args)
     end
 
-    def ssh(task, cmd_str, input, given_opts, ssh_opts)
-      build_and_run_remote_cmd(task, cmd_str, input, given_opts, ssh_opts)
+    def cmd(*args)
+      build_and_run_local_cmd(*args)
+    end
+
+    def ssh(*args)
+      build_and_run_remote_cmd(*args)
     end
 
     def has_run_task?(task_class)
@@ -150,9 +154,17 @@ module Dk
       task_class.new(self, params)
     end
 
-    def build_and_run_local_cmd(task, cmd_str, input, given_opts)
+    def build_and_start_local_cmd(*args)
+      build_and_log_local_cmd(*args){ |cmd, input| cmd.start(input) }
+    end
+
+    def build_and_run_local_cmd(*args)
+      build_and_log_local_cmd(*args){ |cmd, input| cmd.run(input) }
+    end
+
+    def build_and_log_local_cmd(task, cmd_str, input, given_opts, &block)
       local_cmd = build_local_cmd(task, cmd_str, input, given_opts)
-      log_local_cmd(local_cmd){ |cmd| cmd.run(input) }
+      log_local_cmd(local_cmd){ |cmd| block.call(cmd, input) }
     end
 
     # input is needed for the `TestRunner` so it can use it with stubbing

data/lib/dk/task.rb

@@ -65,6 +65,12 @@ module Dk
         @dk_runner.run_task(task_class, params)
       end
 
+      def start(cmd_str, *args)
+        given_opts = args.last.kind_of?(::Hash) ? args.pop : nil
+        input      = args.last
+        @dk_runner.start(self, cmd_str, input, given_opts)
+      end
+
       def cmd(cmd_str, *args)
         given_opts = args.last.kind_of?(::Hash) ? args.pop : nil
         input      = args.last

data/lib/dk/test_runner.rb

@@ -23,14 +23,19 @@ module Dk
       TaskRun.new(task_class, params).tap{ |tr| self.runs << tr }
     end
 
+    # track that a local cmd was started
+    def start(*args)
+      super(*args).tap{ |c| self.runs << c }
+    end
+
     # track that a local cmd was run
-    def cmd(task, cmd_str, input, given_opts)
-      super(task, cmd_str, input, given_opts).tap{ |c| self.runs << c }
+    def cmd(*args)
+      super(*args).tap{ |c| self.runs << c }
     end
 
     # track that a remote cmd was run
-    def ssh(task, cmd_str, input, given_opts, ssh_opts)
-      super(task, cmd_str, input, given_opts, ssh_opts).tap{ |c| self.runs << c }
+    def ssh(*args)
+      super(*args).tap{ |c| self.runs << c }
     end
 
     # test task API

data/lib/dk/version.rb

@@ -1,3 +1,3 @@
 module Dk
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/test/unit/local_tests.rb

@@ -50,7 +50,7 @@ module Dk::Local
     end
 
     should have_readers :scmd, :cmd_str
-    should have_imeths :to_s, :run
+    should have_imeths :to_s, :start, :wait, :stop, :run
     should have_imeths :stdout, :stderr, :success?, :output_lines
 
     should "build an scmd with the cmd str and any given :env option" do
@@ -67,15 +67,56 @@ module Dk::Local
       assert_equal subject.cmd_str, subject.to_s
     end
 
-    should "demeter its scmd" do
+    should "demeter its scmd starts" do
+      assert_false @scmd_spy.start_called?
+
+      input = Factory.string
+      subject.start(input)
+      assert_true @scmd_spy.start_called?
+      assert_equal input, @scmd_spy.start_calls.last.input
+
+      wait_timeout = Factory.integer(10)
+      subject.wait(wait_timeout)
+      assert_true @scmd_spy.wait_called?
+      assert_equal wait_timeout, @scmd_spy.wait_calls.last.timeout
+
+      stop_timeout = Factory.integer(10)
+      subject.stop(stop_timeout)
+      assert_true @scmd_spy.stop_called?
+      assert_equal stop_timeout, @scmd_spy.stop_calls.last.timeout
+
+      assert_equal @scmd_spy.pid,      subject.pid
+      assert_equal @scmd_spy.stdout,   subject.stdout
+      assert_equal @scmd_spy.stderr,   subject.stderr
+      assert_equal @scmd_spy.running?, subject.running?
+      assert_equal @scmd_spy.success?, subject.success?
+    end
+
+    should "demeter its scmd timeout errors" do
+      scmd_timeout_error_message = Factory.string
+      Assert.stub(@scmd_spy, :wait) do
+        raise Scmd::TimeoutError, scmd_timeout_error_message
+      end
+
+      subject.start
+      wait_timeout = Factory.integer(10)
+      e = assert_raises { subject.wait(wait_timeout) }
+
+      assert_equal Dk::CmdTimeoutError, e.class
+      assert_equal scmd_timeout_error_message, e.message
+    end
+
+    should "demeter its scmd runs" do
       assert_false @scmd_spy.run_called?
       input = Factory.string
       subject.run(input)
       assert_true @scmd_spy.run_called?
       assert_equal input, @scmd_spy.run_calls.last.input
 
+      assert_equal @scmd_spy.pid,      subject.pid
       assert_equal @scmd_spy.stdout,   subject.stdout
       assert_equal @scmd_spy.stderr,   subject.stderr
+      assert_equal @scmd_spy.running?, subject.running?
       assert_equal @scmd_spy.success?, subject.success?
     end
 

data/test/unit/runner_tests.rb

@@ -56,7 +56,7 @@ class Dk::Runner
     should have_imeths :run, :run_task
     should have_imeths :log_info, :log_debug, :log_error
     should have_imeths :log_task_run, :log_cli_run
-    should have_imeths :cmd, :ssh
+    should have_imeths :start, :cmd, :ssh
     should have_imeths :has_run_task?, :pretty_run_time
 
     should "know its attrs" do
@@ -265,7 +265,7 @@ class Dk::Runner
       exp = "#{(run_time * 10_000).round / 10.0}ms"
       assert_equal exp, subject.pretty_run_time(run_time)
 
-      run_time = Factory.float (0.1) + 1.5
+      run_time = Factory.float(0.1) + 1.5
       exp = "#{run_time.to_i / 60}:#{(run_time.round % 60).to_i.to_s.rjust(2, '0')}s"
       assert_equal exp, subject.pretty_run_time(run_time)
     end
@@ -308,7 +308,20 @@ class Dk::Runner
       Assert.stub(subject, :pretty_run_time){ @pretty_run_time }
     end
 
-    should "build, log and run local cmds" do
+    should "build, log, and start local cmds" do
+      @runner.start(@task, @cmd_str, @cmd_input, @cmd_given_opts)
+
+      exp = [@cmd_str, @cmd_given_opts]
+      assert_equal exp, @local_cmd_new_called_with
+
+      assert_not_nil @local_cmd
+      assert_true @local_cmd.start_called?
+      assert_equal @cmd_input, @local_cmd.start_input
+
+      assert_equal exp_log_output(@local_cmd), @log_out
+    end
+
+    should "build, log, and run local cmds" do
       @runner.cmd(@task, @cmd_str, @cmd_input, @cmd_given_opts)
 
       exp = [@cmd_str, @cmd_given_opts]

data/test/unit/task_tests.rb

@@ -290,6 +290,38 @@ module Dk::Task
 
   end
 
+  class StartPrivateHelpersTests < InitTests
+
+    should "start local cmds, calling to the runner" do
+      runner_start_called_with = nil
+      Assert.stub(@runner, :start) do |*args|
+        runner_start_called_with = args
+        Assert.stub_send(@runner, :start, *args)
+      end
+
+      cmd_str   = Factory.string
+      cmd_input = Factory.string
+      cmd_opts  = { Factory.string => Factory.string }
+
+      subject.instance_eval{ start(cmd_str, cmd_input, cmd_opts) }
+      exp = [subject, cmd_str, cmd_input, cmd_opts]
+      assert_equal exp, runner_start_called_with
+
+      subject.instance_eval{ start(cmd_str) }
+      exp = [subject, cmd_str, nil, nil]
+      assert_equal exp, runner_start_called_with
+
+      subject.instance_eval{ start(cmd_str, cmd_input) }
+      exp = [subject, cmd_str, cmd_input, nil]
+      assert_equal exp, runner_start_called_with
+
+      subject.instance_eval{ start(cmd_str, cmd_opts) }
+      exp = [subject, cmd_str, nil, cmd_opts]
+      assert_equal exp, runner_start_called_with
+    end
+
+  end
+
   class CmdPrivateHelpersTests < InitTests
 
     should "run local cmds, calling to the runner" do

metadata

@@ -1,69 +1,83 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: dk
-version: !ruby/object:Gem::Version 
-  version: 0.1.0
+version: !ruby/object:Gem::Version
+  version: 0.1.1
 platform: ruby
-authors: 
+authors:
 - Kelly Redding
 - Collin Redding
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2016-08-16 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2019-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: assert
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
         version: 2.16.3
   type: :development
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: much-plugin
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.16.3
+- !ruby/object:Gem::Dependency
+  name: much-plugin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
         version: 0.2.0
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: scmd
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: scmd
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
         version: 3.0.3
   type: :runtime
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: logsly
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ~>
-      - !ruby/object:Gem::Version 
-        version: 1.3.2
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.3
+- !ruby/object:Gem::Dependency
+  name: logsly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.3
   type: :runtime
-  version_requirements: *id004
-description: "\"Why'd you name this repo dk?\" \"Don't know\" (this is some automated task runner thingy ala cap/rake)"
-email: 
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.3
+description: '"Why''d you name this repo dk?" "Don''t know" (this is some automated
+  task runner thingy ala cap/rake)'
+email:
 - kelly@kellyredding.com
 - collin.redding@me.com
-executables: 
+executables:
 - dk
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
-- .gitignore
+files:
+- ".gitignore"
 - Gemfile
 - LICENSE
 - README.md
@@ -118,32 +132,31 @@ files:
 - test/unit/tree_runner_tests.rb
 - tmp/.gitkeep
 homepage: https://github.com/redding/dk
-licenses: 
+licenses:
 - MIT
 metadata: {}
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - &id005 
-    - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
-  requirements: 
-  - *id005
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 2.6.4
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
-summary: "\"Why'd you name this repo dk?\" \"Don't know\" (this is some automated task runner thingy ala cap/rake)"
-test_files: 
+summary: '"Why''d you name this repo dk?" "Don''t know" (this is some automated task
+  runner thingy ala cap/rake)'
+test_files:
 - test/helper.rb
 - test/support/config/dk.rb
 - test/support/config/task_defs.rb