capistrano-nomad 0.16.1 → 0.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 137c81e55b24eb37ce7b3e39722c378d2addea5c5b331ceadeb6d5614f24402e
-  data.tar.gz: 24f1a3cd917263e2c9a34e2baad7968696f0fff7845b9a943a55c4b4742e09a7
+  metadata.gz: 56224de9c341668aba37b58d2b0b404decfce7ee5f488364c325319fea262572
+  data.tar.gz: 49275ee4444defa39b4de8e6d193342d63b8a1edd08deb6f4946451c8c4b9cf2
 SHA512:
-  metadata.gz: 342ae22edc3a3a423ae62a92710ed7dec2445023cd7164f299406fc423bc8e5acbee77a4bd475c2fd82f3cfe26b18eb0c864e58023fb8af1928f00d47a32d89e
-  data.tar.gz: eff30623ea4be4debcdee3c2c31645ab928e4ef9eeef83dbd4c6a295131bffdd6c1d7c38a68c9dc97f29bfb2667791a5be3e55eb0090b4c901000e898cb55dbf
+  metadata.gz: 10e0218ac88de63102cb0af504e7eec43985535516d6fcd91c5404224003b4a652e500bef48895707f4532ca83ebac128aef143d6b38571e490eca632bac91c2
+  data.tar.gz: 7b53eee7196177a352c757527911ccfb601c8075918f49c8a3557cfc61da571fb707341802affb138fbcb903b13c92e09a619431a6f657ee2bc651ddced4df5f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.16.3]
+
+- Add a generated `:force` task to launch a periodic child through the configured manager host and Nomad token
+- Reject non-periodic and disabled periodic jobs before submitting a force request
+- Fail the Capistrano command when job inspection or periodic force fails
+
+## [0.16.2]
+
+- Fail `upload_plan` and other plan operations when Nomad rejects a job or cannot determine the plan
+- Keep successful plans with allocation changes successful despite Nomad's exit code 1
+- Include CLI regression tests in the gem
+
 ## [0.16.1]
 
 - Pass every configured variable file to `nomad plan` and `nomad run`

data/Gemfile

@@ -4,3 +4,5 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in capistrano-nomad.gemspec
 gemspec
+
+gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capistrano-nomad (0.16.0)
+    capistrano-nomad (0.16.3)
       activesupport (<= 7.0.8)
       byebug
       capistrano (~> 3.0)
@@ -52,9 +52,11 @@ GEM
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-23
+  x86_64-linux-gnu
 
 DEPENDENCIES
   capistrano-nomad!
+  minitest (~> 5.0)
 
 BUNDLED WITH
    2.4.20

data/README.md

@@ -145,6 +145,15 @@ cap production nomad:analytics:grafana:restart
 cap production nomad:postgres:status
 ```
 
+Force a periodic job without uploading, deploying, or restarting its parent:
+
+```shell
+cap production nomad:maintenance:force
+cap production nomad:analytics:archive:force
+```
+
+The per-job `:force` task checks the deployed job before running `nomad job periodic force`. Non-periodic and disabled periodic jobs fail with a clear error. Inspection and force failures produce a nonzero Capistrano exit. The task uses the configured manager host and `:nomad_token`, like other job actions.
+
 Tasks can apply across all namespaces or be filtered by namespaces or tags
 
 ```shell
@@ -213,7 +222,9 @@ cap production nomad:version
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Run `bundle exec rake test` to test the generated Capistrano `upload_plan` and `force` tasks through the CLI. The tests use local transport and controlled Nomad exit codes. Force coverage checks the job, namespace, token, rejected requests, and non-periodic jobs. To also check rejection of invalid HCL with a real Nomad binary, run `NOMAD_REAL_BINARY=/path/to/nomad bundle exec rake test`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version in `capistrano-nomad.gemspec`, run `bundle install`, and update `CHANGELOG.md`. Run `bundle exec rake test` and commit the release changes. Then run `bundle exec rake release`, which creates the version tag, pushes the release commit and tag, and publishes the gem to [RubyGems](https://rubygems.org).
 
 ## Contributing
 

data/Rakefile

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new do |task|
+  task.libs << "test"
+  task.pattern = "test/**/*_test.rb"
+end
+
+task default: :test

data/capistrano-nomad.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "capistrano-nomad"
-  spec.version = "0.16.1"
+  spec.version = "0.16.3"
   spec.authors = ["James Hu"]
 
   spec.summary = "Capistrano plugin for deploying and managing Nomad jobs"
@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released. The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     %x(git ls-files -z).split("\x0").reject do |f|
-      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
     end
   end
   spec.bindir = "exe"

data/lib/capistrano/nomad/helpers/dsl.rb

@@ -91,6 +91,11 @@ def nomad_job(name, attributes = {})
         capistrano_nomad_run_jobs([name], namespace: namespace, is_detached: capistrano_nomad_job_detached_overridden?)
       end
 
+      desc("Force a new periodic child of #{description_name} job")
+      task(:force) do
+        capistrano_nomad_force_job(name, namespace: namespace)
+      end
+
       desc("Purge and run #{description_name} job again")
       task(:rerun) do
         capistrano_nomad_rerun_jobs([name], namespace: namespace, is_detached: capistrano_nomad_job_detached_overridden?)

data/lib/capistrano/nomad/helpers/nomad.rb

@@ -138,7 +138,11 @@ def capistrano_nomad_build_release_var_file_path(name, **options)
   "#{release_path}#{capistrano_nomad_ensure_absolute_path(capistrano_nomad_build_base_var_file_path(name, **options))}"
 end
 
-def capistrano_nomad_run_nomad_command(kind, *args)
+def capistrano_nomad_plan_command?(args)
+  args.first.to_s == "plan" || args.take(2).map(&:to_s) == ["job", "plan"]
+end
+
+def capistrano_nomad_run_nomad_command(kind, *args, raise_on_non_zero_exit: false)
   converted_args = args.each_with_object([]) do |arg, collection|
     # If hash then convert it as options
     if arg.is_a?(Hash)
@@ -165,24 +169,34 @@ def capistrano_nomad_run_nomad_command(kind, *args)
   end
 
   with(env_vars) do
-    # Ignore errors
-    public_send(kind, :nomad, *converted_args, raise_on_non_zero_exit: false)
+    if capistrano_nomad_plan_command?(args)
+      # Nomad returns 1 for a successful plan with changes; all other nonzero exits are errors
+      public_send(kind, :nomad, *converted_args, '; status=$?; if [ "$status" -eq 1 ]; then exit 0; else exit "$status"; fi', raise_on_non_zero_exit: true)
+    else
+      # Preserve unchecked execution unless the caller requires failures to propagate
+      public_send(kind, :nomad, *converted_args, raise_on_non_zero_exit: raise_on_non_zero_exit)
+    end
   end
 end
 
-def capistrano_nomad_execute_nomad_command(*args, **options)
+def capistrano_nomad_execute_nomad_command(*args, raise_on_non_zero_exit: false, **options)
   capistrano_nomad_run_remotely do |host|
-    run_interactively(host) do
-      capistrano_nomad_run_nomad_command(:execute, *args, **options)
+    if capistrano_nomad_plan_command?(args) || raise_on_non_zero_exit
+      # Use checked execution when failures must propagate because the interactive backend does not raise
+      capistrano_nomad_run_nomad_command(:execute, *args, options, raise_on_non_zero_exit: raise_on_non_zero_exit)
+    else
+      run_interactively(host) do
+        capistrano_nomad_run_nomad_command(:execute, *args, options)
+      end
     end
   end
 end
 
-def capistrano_nomad_capture_nomad_command(*args, **options)
+def capistrano_nomad_capture_nomad_command(*args, raise_on_non_zero_exit: false, **options)
   output = nil
 
   capistrano_nomad_run_remotely do
-    output = capistrano_nomad_run_nomad_command(:capture, *args, **options)
+    output = capistrano_nomad_run_nomad_command(:capture, *args, options, raise_on_non_zero_exit: raise_on_non_zero_exit)
   end
 
   output
@@ -620,6 +634,17 @@ def capistrano_nomad_restart_jobs(names, **options)
   end
 end
 
+def capistrano_nomad_force_job(name, **options)
+  capistrano_nomad_ensure_options!(options)
+  job = JSON.parse(capistrano_nomad_capture_nomad_command(:job, :inspect, options, name, raise_on_non_zero_exit: true))
+
+  unless job.dig("Periodic", "Enabled")
+    raise ArgumentError, "Job #{options[:namespace]}/#{name} is not an enabled periodic job"
+  end
+
+  capistrano_nomad_execute_nomad_command(:job, :periodic, :force, options, name, raise_on_non_zero_exit: true)
+end
+
 def capistrano_nomad_start_jobs(names, **options)
   capistrano_nomad_ensure_options!(options)
 

data/test/upload_plan_test.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "fileutils"
+require "open3"
+require "tmpdir"
+
+class UploadPlanTest < Minitest::Test
+  def test_upload_plan_succeeds_for_accepted_plans_and_fails_for_rejected_plans
+    Dir.mktmpdir("capistrano-nomad") do |root|
+      FileUtils.mkdir_p(["#{root}/config/deploy", "#{root}/nomad/jobs", "#{root}/bin"])
+      File.write("#{root}/Capfile", <<~RUBY)
+        require "capistrano/setup"
+        require "capistrano/deploy"
+        require "capistrano/nomad"
+        install_plugin Capistrano::Nomad
+      RUBY
+      File.write("#{root}/config/deploy.rb", <<~RUBY)
+        set :application, "plan-test"
+        set :deploy_to, #{"#{root}/remote".inspect}
+        set :root, #{root.inspect}
+        set :current_revision, "test"
+        set :nomad_docker_image_types, {}
+        SSHKit.config.command_map[:nomad] = #{"#{root}/bin/nomad".inspect}
+        nomad_job :example
+        set :nomad_token, "force-test-token"
+        nomad_namespace :spleencheese do
+          nomad_job :"myanonamouse-maintenance"
+        end
+      RUBY
+      File.write("#{root}/config/deploy/test.rb", <<~RUBY)
+        server "localhost", roles: [:manager]
+        set :sshkit_backend, SSHKit::Backend::Local
+      RUBY
+      File.write("#{root}/bin/ssh", <<~SH)
+        #!/bin/sh
+        for argument do command="$argument"; done
+        exec /bin/sh -c "$command"
+      SH
+      FileUtils.chmod(0755, "#{root}/bin/ssh")
+      File.write("#{root}/bin/nomad", <<~SH)
+        #!/bin/sh
+        if [ "$1" = job ]; then
+          [ "$NOMAD_TOKEN" = force-test-token ] || exit 98
+          printf '%s\n' "$*" >> #{root}/commands
+          if [ "$2" = inspect ]; then
+            printf '%s\n' "$NOMAD_TEST_JOB"
+            exit "${NOMAD_TEST_INSPECT_EXIT:-0}"
+          fi
+          [ "$2 $3" = 'periodic force' ] || exit 99
+          if [ "$NOMAD_TEST_EXIT" = 0 ]; then
+            echo 'Created periodic child'
+          else
+            echo 'Periodic force rejected' >&2
+          fi
+          exit "$NOMAD_TEST_EXIT"
+        fi
+        [ "$1" = plan ] || exit 99
+        cat "$2"
+        case "$NOMAD_TEST_EXIT" in
+          0|1) echo 'Scheduler dry-run: accepted';;
+          *) echo 'Error determining plan results' >&2;;
+        esac
+        exit "$NOMAD_TEST_EXIT"
+      SH
+      FileUtils.chmod(0755, "#{root}/bin/nomad")
+
+      [0, 1, 255, 2].each do |exit_code|
+        job = exit_code < 2 ? 'job "example" {}' : 'job "example" {'
+        File.write("#{root}/nomad/jobs/example.hcl", job)
+        output, status = Open3.capture2e(
+          { "NOMAD_TEST_EXIT" => exit_code.to_s, "PATH" => "#{root}/bin:#{ENV.fetch("PATH")}" },
+          "bundle", "exec", "cap", "test", "nomad:example:upload_plan",
+          chdir: root,
+        )
+
+        assert_includes(output, job, output)
+        if exit_code < 2
+          assert(status.success?, output)
+          assert_includes(output, "Scheduler dry-run: accepted")
+        else
+          refute(status.success?, output)
+          assert_includes(output, "Error determining plan results")
+        end
+      end
+
+      [0, 1, 2].each do |exit_code|
+        File.write("#{root}/commands", "")
+        output, status = Open3.capture2e(
+          { "NOMAD_TEST_EXIT" => exit_code.to_s, "NOMAD_TEST_JOB" => '{"Periodic":{"Enabled":true}}' },
+          "bundle", "exec", "cap", "test", "nomad:spleencheese:myanonamouse-maintenance:force",
+          chdir: root,
+        )
+
+        assert_equal("job inspect -namespace=spleencheese myanonamouse-maintenance\njob periodic force -namespace=spleencheese myanonamouse-maintenance\n", File.read("#{root}/commands"), output)
+        assert_equal(exit_code.zero?, status.success?, output)
+        assert_includes(output, exit_code.zero? ? "Created periodic child" : "Periodic force rejected")
+      end
+
+      ['{"Periodic":null}', '{"Periodic":{"Enabled":false}}'].each do |job|
+        File.write("#{root}/commands", "")
+        output, status = Open3.capture2e(
+          { "NOMAD_TEST_JOB" => job },
+          "bundle", "exec", "cap", "test", "nomad:example:force",
+          chdir: root,
+        )
+
+        refute(status.success?, output)
+        assert_includes(output, "Job default/example is not an enabled periodic job")
+        assert_equal("job inspect -namespace=default example\n", File.read("#{root}/commands"), output)
+      end
+
+      File.write("#{root}/commands", "")
+      output, status = Open3.capture2e(
+        { "NOMAD_TEST_JOB" => '{"Periodic":{"Enabled":true}}', "NOMAD_TEST_INSPECT_EXIT" => "1" },
+        "bundle", "exec", "cap", "test", "nomad:example:force",
+        chdir: root,
+      )
+
+      refute(status.success?, output)
+      assert_equal("job inspect -namespace=default example\n", File.read("#{root}/commands"), output)
+
+      File.write("#{root}/commands", "")
+      output, status = Open3.capture2e(
+        { "NOMAD_TEST_JOB" => '{"Periodic":{"Enabled":true}}', "NOMAD_TEST_EXIT" => "0" },
+        "bundle", "exec", "cap", "test", "nomad:example:force",
+        chdir: root,
+      )
+
+      assert(status.success?, output)
+      assert_equal("job inspect -namespace=default example\njob periodic force -namespace=default example\n", File.read("#{root}/commands"), output)
+
+      if ENV["NOMAD_REAL_BINARY"]
+        FileUtils.cp(ENV.fetch("NOMAD_REAL_BINARY"), "#{root}/bin/nomad")
+        output, status = Open3.capture2e("bundle", "exec", "cap", "test", "nomad:example:upload_plan", chdir: root)
+
+        refute(status.success?, output)
+        assert_includes(output, "Error parsing job file")
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-nomad
 version: !ruby/object:Gem::Version
-  version: 0.16.1
+  version: 0.16.3
 platform: ruby
 authors:
 - James Hu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,6 +130,7 @@ files:
 - lib/capistrano/nomad/helpers/nomad.rb
 - lib/capistrano/nomad/scm/git_local.rb
 - lib/capistrano/nomad/tasks/nomad.rake
+- test/upload_plan_test.rb
 homepage: https://github.com/axsuul/capistrano-nomad
 licenses:
 - MIT
@@ -152,7 +153,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: Capistrano plugin for deploying and managing Nomad jobs