capistrano-nomad 0.16.2 → 0.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 408063f04626ace5215b232901a72869fb5aabfe336017ce0e33aa1f1b53b02c
-  data.tar.gz: 4f3019490d7fa5042f1efe94ba7bedf1725fe3f25d391c19ae87fd45b051d79e
+  metadata.gz: 56224de9c341668aba37b58d2b0b404decfce7ee5f488364c325319fea262572
+  data.tar.gz: 49275ee4444defa39b4de8e6d193342d63b8a1edd08deb6f4946451c8c4b9cf2
 SHA512:
-  metadata.gz: ae43c669814a9ba3ccd7462d4cd862b97cc79bdeefed86966fa251fbe45fa184cb8ac570b35bfd811907f1e276af4c6c6c6e3d57823c4fdea6922f891822b2c1
-  data.tar.gz: bb552095171a362745db10f63a45c3ca24ee9f7fb715d52738fa18802472798b695090a55a5d79bb5a7457dbad84d44e1b03b5112a132f7cdda1b0d1c8ca8051
+  metadata.gz: 10e0218ac88de63102cb0af504e7eec43985535516d6fcd91c5404224003b4a652e500bef48895707f4532ca83ebac128aef143d6b38571e490eca632bac91c2
+  data.tar.gz: 7b53eee7196177a352c757527911ccfb601c8075918f49c8a3557cfc61da571fb707341802affb138fbcb903b13c92e09a619431a6f657ee2bc651ddced4df5f

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    capistrano-nomad (0.16.2)
+    capistrano-nomad (0.16.3)
       activesupport (<= 7.0.8)
       byebug
       capistrano (~> 3.0)

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,7 @@ 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.
 
-Run `bundle exec rake test` to test the generated Capistrano `upload_plan` task through the CLI. The tests use local transport and controlled Nomad exit codes. To also check rejection of invalid HCL with a real Nomad binary, run `NOMAD_REAL_BINARY=/path/to/nomad bundle exec rake test`.
+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).
 

data/capistrano-nomad.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "capistrano-nomad"
-  spec.version = "0.16.2"
+  spec.version = "0.16.3"
   spec.authors = ["James Hu"]
 
   spec.summary = "Capistrano plugin for deploying and managing Nomad jobs"

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

@@ -142,7 +142,7 @@ 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)
+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)
@@ -173,30 +173,30 @@ def capistrano_nomad_run_nomad_command(kind, *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
-      # Ignore errors for commands other than plans
-      public_send(kind, :nomad, *converted_args, raise_on_non_zero_exit: false)
+      # 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|
-    if capistrano_nomad_plan_command?(args)
-      # Use SSHKit's checked execution because the interactive backend does not raise on failure
-      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)
+        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
@@ -634,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

@@ -23,6 +23,10 @@ class UploadPlanTest < Minitest::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]
@@ -36,6 +40,21 @@ class UploadPlanTest < Minitest::Test
       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
@@ -65,6 +84,52 @@ class UploadPlanTest < Minitest::Test
         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)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-nomad
 version: !ruby/object:Gem::Version
-  version: 0.16.2
+  version: 0.16.3
 platform: ruby
 authors:
 - James Hu
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-06 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport