Add custom working directory support to remote/3. (#174)

Author: holetse

README.md

@@ -382,9 +382,15 @@ remote :app do
 end
 
 # filtering - only runs on app hosts with an option of primary set to true
-remote :app, primary: true do
+remote :app, filter: [primary: true] do
   "mix ecto.migrate"
 end
+
+# change working directory - creates a file `/tmp/foo`, regardless of the role
+# workspace configuration
+remote :app, cd: "/tmp" do
+  "touch ./foo"
+end
 ```
 
 ## Phoenix Support

lib/bootleg/config.ex

@@ -338,18 +338,18 @@ defmodule Bootleg.Config do
   @doc """
   Executes commands on all remote hosts within a role.
 
-  This is equivalent to calling `remote/3` with a `filter` of `[]`.
+  This is equivalent to calling `remote/3` with an `options` of `[]`.
   """
   defmacro remote(role, lines) do
     quote do: remote(unquote(role), [], unquote(lines))
   end
 
-  defmacro remote(role, filter, do: {:__block__, _, lines}) do
-    quote do: remote(unquote(role), unquote(filter), unquote(lines))
+  defmacro remote(role, options, do: {:__block__, _, lines}) do
+    quote do: remote(unquote(role), unquote(options), unquote(lines))
   end
 
-  defmacro remote(role, filter, do: lines) do
-    quote do: remote(unquote(role), unquote(filter), unquote(lines))
+  defmacro remote(role, options, do: lines) do
+    quote do: remote(unquote(role), unquote(options), unquote(lines))
   end
 
   @doc """
@@ -363,9 +363,16 @@ defmodule Bootleg.Config do
   used as a command. Each command will be simulataneously executed on all hosts in the role. Once
   all hosts have finished executing the command, the next command in the list will be sent.
 
-  `filter` is an optional `Keyword` list of host options to filter with. Any host whose options match
+  `options` is an optional `Keyword` list of options to customize the remote invocation. Currently two
+  keys are supported:
+  
+    * `filter` takes a `Keyword` list of host options to filter with. Any host whose options match
   the filter will be included in the remote execution. A host matches if it has all of the filtering
   options defined and the values match (via `==/2`) the filter.
+    * `cd` changes the working directory of the remote shell prior to executing the remote
+    commands. The options takes either an absolute or relative path, with relative paths being
+    defined relative to the workspace configured for the role, or the default working directory
+    of the shell if no workspace is defined.
 
   `role` can be a single role, a list of roles, or the special role `:all` (all roles). If the same host
   exists in multiple roles, the commands will be run once for each role where the host shows up. In the
@@ -394,19 +401,24 @@ defmodule Bootleg.Config do
 
   # only runs on `host1.example.com`
   role :build, "host2.example.com"
-  role :build, "host1.example.com", primary: true, another_attr: :cat
+  role :build, "host1.example.com", filter: [primary: true, another_attr: :cat]
 
-  remote :build, primary: true do
+  remote :build, filter: [primary: true] do
+    "hostname"
+  end
+
+  # runs on `host1.example.com` inside the `tmp` directory found in the workspace
+  remote :build, filter: [primary: true], cd: "tmp/" do
     "hostname"
   end
   ```
   """
-  defmacro remote(role, filter, lines) do
+  defmacro remote(role, options, lines) do
     roles = unpack_role(role)
     quote bind_quoted: binding() do
       Enum.reduce(roles, [], fn role, outputs ->
         role
-        |> SSH.init([], filter)
+        |> SSH.init([cd: options[:cd]], Keyword.get(options, :filter, []))
         |> SSH.run!(lines)
         |> SSH.merge_run_results(outputs)
       end)

lib/bootleg/ssh.ex

@@ -37,6 +37,7 @@ defmodule Bootleg.SSH do
   def init(hosts, options) do
     workspace = Keyword.get(options, :workspace, ".")
     create_workspace = Keyword.get(options, :create_workspace, true)
+    working_directory = Keyword.get(options, :cd)
     UI.puts "Creating remote context at '#{workspace}'"
 
     :ssh.start()
@@ -46,6 +47,7 @@ defmodule Bootleg.SSH do
     |> Enum.map(&ssh_host_options/1)
     |> SSHKit.context()
     |> validate_workspace(workspace, create_workspace)
+    |> working_directory(working_directory)
   end
 
   def ssh_host_options(%Host{} = host) do
@@ -84,6 +86,16 @@ defmodule Bootleg.SSH do
     SSHKit.path context, workspace
   end
 
+  defp working_directory(context, path) when path == "." or path == false or is_nil(path) do
+    context
+  end
+  defp working_directory(context, path) do
+    case Path.type(path) do
+      :absolute -> %Context{context | path: path}
+      _ -> %Context{context | path: Path.join(context.path, path)}
+    end
+  end
+
   defp capture(message, {buffer, status} = state, host) do
     next = case message do
       {:data, _, 0, data} ->

test/bootleg/config_functional_test.exs

@@ -136,19 +136,22 @@ defmodule Bootleg.ConfigFunctionalTest do
   end
 
   @tag boot: 3
-  test "remote/3 filtering" do
+  test "remote/3 options" do
     capture_io(fn ->
       use Bootleg.Config
 
-      assert [{:ok, out_0, 0, _}] = remote :build, [foo: 0], "hostname"
-      assert [{:ok, out_1, 0, _}] = remote :build, [foo: 1], do: "hostname"
+      assert [{:ok, out_0, 0, _}] = remote :build, [filter: [foo: 0]], "hostname"
+      assert [{:ok, out_1, 0, _}] = remote :build, [filter: [foo: 1]], do: "hostname"
       assert out_1 != out_0
 
-      assert [] = remote :build, [foo: :bar], "hostname"
-      assert [{:ok, out_all, 0, _}] = remote :all, [foo: :bar], "hostname"
+      assert [] = remote :build, [filter: [foo: :bar]], "hostname"
+      assert [{:ok, out_all, 0, _}] = remote :all, [filter: [foo: :bar]], "hostname"
       assert out_1 != out_0 != out_all
 
-      remote :all, [foo: :bar] do "hostname" end
+      remote :all, filter: [foo: :bar] do "hostname" end
+
+      [{:ok, [stdout: "/tmp\n"], 0, _}] = remote :app, cd: "/tmp" do "pwd" end
+      [{:ok, [stdout: "/home\n"], 0, _}] = remote :app, cd: "../.." do "pwd" end
     end)
   end
 

test/bootleg/config_test.exs

@@ -447,48 +447,69 @@ defmodule Bootleg.ConfigTest do
     assert called SSH.run!({:bar}, ["echo Multi Hello", "echo Multi World!"])
   end
 
-  test_with_mock "remote/3 filtering", SSH, [:passthrough], [
+  test_with_mock "remote/3", SSH, [:passthrough], [
       init: fn(role, options, filter) -> {role, options, filter} end,
       run!: fn(_, _cmd) -> [:ok] end
     ] do
     use Bootleg.Config
 
     task :remote_test_role_one_line_filtered do
-      remote :one_line, [a_filter: true], "echo Multi Hello"
+      remote :one_line, [filter: [a_filter: true]], "echo Multi Hello"
     end
 
     task :remote_test_role_inline_filtered do
-      remote :inline, [b_filter: true], do: "echo Multi Hello"
+      remote :inline, [filter: [b_filter: true]], do: "echo Multi Hello"
     end
 
     task :remote_test_role_filtered do
-      remote :car, passenger: true do
+      remote :car, filter: [passenger: true] do
         "echo Multi Hello"
       end
     end
 
     task :remote_test_roles_filtered do
-      remote [:foo, :bar], primary: true do
+      remote [:foo, :bar], filter: [primary: true] do
         "echo Multi Hello"
       end
     end
 
+    task :remote_working_directory_option do
+      remote :foo, cd: "/bar" do "echo bar!" end
+    end
+
+    task :remote_working_directory_option_nil do
+      remote :foo, cd: nil do "echo bar!" end
+    end
+
+    task :remote_working_directory_option_none do
+      remote :foo do "echo bar!" end
+    end
+
     invoke :remote_test_role_one_line_filtered
 
-    assert called SSH.init(:one_line, [], a_filter: true)
+    assert called SSH.init(:one_line, :_, a_filter: true)
 
     invoke :remote_test_role_inline_filtered
 
-    assert called SSH.init(:inline, [], b_filter: true)
+    assert called SSH.init(:inline, :_, b_filter: true)
 
     invoke :remote_test_role_filtered
 
-    assert called SSH.init(:car, [], passenger: true)
+    assert called SSH.init(:car, :_, passenger: true)
 
     invoke :remote_test_roles_filtered
 
-    assert called SSH.init(:foo, [], [primary: true])
-    assert called SSH.init(:bar, [], [primary: true])
+    assert called SSH.init(:foo, :_, [primary: true])
+    assert called SSH.init(:bar, :_, [primary: true])
+
+    invoke :remote_working_directory_option
+    assert called SSH.init(:foo, [cd: "/bar"], [])
+
+    invoke :remote_working_directory_option_nil
+    assert called SSH.init(:foo, [cd: nil], [])
+
+    invoke :remote_working_directory_option_none
+    assert called SSH.init(:foo, [cd: nil], [])
   end
 
   test_with_mock "upload/3", SSH, [:passthrough], [

test/bootleg/ssh_functional_test.exs

@@ -85,7 +85,6 @@ defmodule Bootleg.SSHFunctionalTest do
 
   @tag boot: 2
   test "init/3 host filtering for roles", %{hosts: [host_1, host_2]} do
-    # credo:disable-for-next-line Credo.Check.Consistency.MultiAliasImportRequireUse
     use Bootleg.Config
 
     ip_1 = host_1.ip
@@ -100,6 +99,23 @@ defmodule Bootleg.SSHFunctionalTest do
     end)
   end
 
+  test "init/3 working directory option", %{hosts: [host]} do
+    # credo:disable-for-next-line Credo.Check.Consistency.MultiAliasImportRequireUse
+    use Bootleg.Config
+
+    role :valid_workspace, host.ip, port: host.port, user: host.user,
+      workspace: "./woo/bar", silently_accept_hosts: true, identity: host.private_key_path
+    role :bad_workspace, host.ip, port: host.port, user: host.user,
+      workspace: "/woo/bar", silently_accept_hosts: true, identity: host.private_key_path
+    capture_io(fn ->
+      assert %SSHKitContext{path: "/foo"} = SSH.init(:valid_workspace, [cd: "/foo"])
+      assert %SSHKitContext{path: "./woo/bar/foo"} = SSH.init(:valid_workspace, [cd: "foo"])
+      assert %SSHKitContext{path: "./woo/bar"} = SSH.init(:valid_workspace, [cd: nil])
+      assert_raise SSHError, fn -> SSH.init(:bad_workspace, [cd: "/foo"]) end
+      assert_raise SSHError, fn -> SSH.init(:bad_workspace, [cd: "foo"]) end
+    end)
+  end
+
   test "run!/2 raises an error if the host refuses the connection", %{hosts: [host]} do
     capture_io(fn ->
       conn = SSHKit.context(SSHKit.host(host.ip))