backburner 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83834669d5d4ccf208c32935bccba313a04b097611c10f5ebe071f81aae32b6d
-  data.tar.gz: 97d85b5bf0a1e9c623f5c9fd35d2d130d27599b53b9f554a56d36dd0eeab8ea1
+  metadata.gz: 50e2f0b2644659644c0789a09a93c786e1bf7ab914bdadc40e80be8cdf941fb7
+  data.tar.gz: e86d98085d8fbeb91079d9d52095d2ba62f9c4ec114e28053c8d457398003b35
 SHA512:
-  metadata.gz: b6eafd91259c9a156077451cbc5ff243317a70b92af17f45887566bfd50a358eff365aa407554760e1781482623fe96882fbc6473cc0541ed058eb0f5aa643e2
-  data.tar.gz: 9d90985cdbc5040961f183cfb560223b2bce8c547a10eeedf460c0f5c3db56726849888903668e8d201b43c5d7b2498f9cf1f1ffbcedd6501316c4222ad4e78f
+  metadata.gz: f707e632bc937197959a4e919b8f12b010a201b7e18add316c3cb66bf1598219a1089c480f7012f9d888debc63fc1d0c4eb0be85b4a943ac3220dce2453c22e6
+  data.tar.gz: c79112e436fd4bff2b68cc417de9fe23b782b433882697bae60b937f8c36ae76177e056a3a86cff1ab714da48a59d5a548e8113469382a387967295dc697aee1

data/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (${{ matrix.ruby-version }}${{ matrix.activejob-version && format(', activejob {0}', matrix.activejob-version) || '' }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', '3.2', '3.3', '3.4', '4.0']
+        activejob-version: [''] # the newest the Ruby version allows
+        include:
+          # Rails before 7.2 ship their own Active Job adapter and have no AbstractAdapter
+          - ruby-version: '3.1'
+            activejob-version: '6.1'
+    env:
+      ACTIVEJOB_VERSION: ${{ matrix.activejob-version }} # read by the Gemfile
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Download & Extract beanstalkd
+      run: curl -fsSL https://github.com/beanstalkd/beanstalkd/archive/refs/tags/v1.13.tar.gz | tar xz
+    - name: Make beanstalkd
+      run: make
+      working-directory: beanstalkd-1.13
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Daemonize beanstalkd
+      run: ./beanstalkd-1.13/beanstalkd -l 127.0.0.1 -p 11300 &
+    - name: Run tests
+      run: bundle exec rake test
+      env:
+        BEANSTALKD_BIN: ${{ github.workspace }}/beanstalkd-1.13/beanstalkd # for the outage test, which stops and restarts its own server

data/.github/workflows/github-release.yml

@@ -0,0 +1,58 @@
+# Creates the GitHub release page for a tag that already exists, with GitHub's generated notes (merged
+# PRs and new contributors since the previous release) after a link to that version's CHANGELOG.md.
+# release.yml runs it after it publishes; "Run workflow" here (with the tag) creates the page for an
+# earlier release. A tag that already has a release is left alone, so running it twice is harmless.
+# A tag that isn't the newest vX.Y.Z tag is created with --latest=false; the API otherwise marks every
+# new release as Latest.
+
+name: github-release
+run-name: github release ${{ inputs.tag }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'An existing tag, e.g. v1.2.0'
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      tag:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release-page:
+    if: github.repository == 'nesquena/backburner'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # creates the release
+    steps:
+      - name: Create the GitHub release
+        shell: bash -eo pipefail {0}
+        env:
+          TAG: ${{ inputs.tag }}
+          CHANGELOG: CHANGELOG.md
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::'$TAG' is not a tag like v1.2.3"; exit 1; }
+          if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            echo "$TAG already has a release; leaving it alone"
+            exit 0
+          fi
+          # Compare with the newest vX.Y.Z tag rather than the "Latest" release, so a failed lookup stops the
+          # step (pipefail) instead of letting an older tag become Latest
+          newest=$(gh api --paginate "repos/$GITHUB_REPOSITORY/git/matching-refs/tags/v" --jq '.[].ref' |
+            sed 's#^refs/tags/##' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
+          flags=()
+          if [ "$newest" != "$TAG" ]; then
+            echo "$TAG is not the newest tag ($newest): not marking it as latest"
+            flags=(--latest=false)
+          fi
+          # --verify-tag: refuse rather than create the tag. With --generate-notes, GitHub puts these notes
+          # before the generated ones.
+          gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --title "$TAG" --generate-notes "${flags[@]}" \
+            --notes "What changed, and what to do when upgrading: [$CHANGELOG](https://github.com/$GITHUB_REPOSITORY/blob/$TAG/$CHANGELOG)."

data/.github/workflows/release.yml

@@ -0,0 +1,221 @@
+# Publishes a backburner release to rubygems.org with trusted publishing, gated by the "release"
+# environment: the owner approves each publish.
+#
+# Usual path: merge the release PR (the version in lib/backburner/version.rb and the CHANGELOG.md
+# heading stamped with the date, e.g. "## Version 1.8.0 (Nov 1 2026)"), then "Run workflow" on master
+# with the version. build checks the version, that the changelog's first heading is that version with
+# a date, and the branch, and builds the gem reproducibly; publish waits for approval, pushes the gem
+# with short-lived trusted-publishing credentials, then creates the tag vX.Y.Z on the built commit.
+# Pushing a vX.Y.Z tag on a master commit runs the same checks. "Re-run failed jobs" (not "Re-run all
+# jobs", which rebuilds) resumes a release that stopped partway.
+# If the gem is pushed but the tag step keeps failing, push the tag by hand at the built commit: that
+# tag push's run skips the push (same sum).
+# Then github-release.yml creates the GitHub release page for the tag (it can also be run by hand for
+# an earlier tag).
+#
+# Dry run: tick dry_run to check the wiring. Everything runs except the changelog checks, the tag, the
+# push and the release page; the credential exchange fails unless the trusted publisher is set up.
+#
+# The "release" environment's protection rules are the ONLY gate on publishing (required reviewer, no
+# admin bypass, deployments only from master and v*.*.* tags): RubyGems trusts any run of this file
+# that uses that environment, and a branch or tag can carry its own modified copy of it. The trusted
+# publisher on rubygems.org must name the environment. Before approving a deployment, check
+# who started the run, the event, that the commit is the release PR's merge commit, and the build
+# log's "is on master" line. Reject any run you won't approve: a waiting run blocks the next one.
+# A deployment rule for X.Y-stable lets anyone with write access create such a branch carrying its own
+# copy of this file: add one only for a maintenance release, and remove it after.
+
+name: release
+run-name: release ${{ inputs.version || github.ref_name }}${{ inputs.dry_run && ' (dry run)' || '' }}
+
+on:
+  push:
+    tags: ['v[0-9]+.[0-9]+.[0-9]+']
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (already in the version file of this branch), e.g. 1.2.0'
+        required: true
+        type: string
+      dry_run:
+        description: 'Dry run: check, build and exchange credentials, but create no tag and push nothing'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  build:
+    if: github.repository == 'nesquena/backburner'
+    runs-on: ubuntu-latest
+    env:
+      TRUNK: master
+      TAG_PREFIX: v
+      GEMS: 'backburner:.'
+      VERSION_FILE: lib/backburner/version.rb
+      CHANGELOG: CHANGELOG.md
+      CHANGELOG_HEADING: '^## '
+      CHANGELOG_TOP: '^## Version ([0-9]+\.[0-9]+\.[0-9]+)( |$)'
+    outputs:
+      version: ${{ steps.check.outputs.version }}
+      tag: ${{ steps.check.outputs.tag }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+      - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
+        with:
+          ruby-version: '3.3'
+      - name: Check the version
+        id: check
+        shell: bash -eo pipefail {0}
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+          DRY_RUN: ${{ inputs.dry_run }}
+        run: |
+          if [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
+            version="$INPUT_VERSION"
+            [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::the version input is not a plain version like 1.2.3"; exit 1; }
+            case "$GITHUB_REF" in
+              "refs/heads/$TRUNK"|"refs/heads/${version%.*}-stable") ;;
+              *) echo "::error::run this on $TRUNK or ${version%.*}-stable, not $GITHUB_REF"; exit 1 ;;
+            esac
+            tag="$TAG_PREFIX$version"
+            tagged=$(git ls-remote origin "refs/tags/$tag*" | awk -v t="refs/tags/$tag" '$2 == t || $2 == t "^{}" { print $1 }')
+            [ -z "$tagged" ] || echo "$tagged" | grep -qx "$GITHUB_SHA" ||
+              { echo "::error::tag $tag already exists at another commit"; exit 1; }
+          else
+            tag="$GITHUB_REF_NAME"
+            version="${tag#"$TAG_PREFIX"}"
+            [[ "$tag" == "$TAG_PREFIX"* && "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::tag $tag is not ${TAG_PREFIX}X.Y.Z"; exit 1; }
+          fi
+          file_version=$(ruby -e 'puts File.binread(ENV["VERSION_FILE"])[/\bVERSION\s*=\s*["\x27]([^"\x27]+)/, 1]')
+          [ "$version" = "$file_version" ] || { echo "::error::version $version but $VERSION_FILE says $file_version"; exit 1; }
+          if [ "$DRY_RUN" = true ]; then
+            echo "::warning::dry run: not checking $CHANGELOG"
+          else
+            heading=$(grep -m1 -E "$CHANGELOG_HEADING" "$CHANGELOG") || { echo "::error::$CHANGELOG has no heading matching '$CHANGELOG_HEADING'"; exit 1; }
+            top=$(echo "$heading" | sed -nE "s/$CHANGELOG_TOP.*/\1/p")
+            [ "$top" = "$version" ] || { echo "::error::$CHANGELOG starts with '$heading', not release $version: merge the release PR first, and nothing after it"; exit 1; }
+            rest="${heading#*"$version"}"
+            [[ "$rest" =~ (19|20)[0-9][0-9] ]] && ! echo "$rest" | grep -qiwE 'unreleased|tbd|tba' ||
+              { echo "::error::$CHANGELOG's '$heading' isn't stamped with a date yet"; exit 1; }
+          fi
+          series="${version%.*}-stable"
+          on=""
+          for b in "$series" "$TRUNK"; do
+            git merge-base --is-ancestor "$GITHUB_SHA" "refs/remotes/origin/$b" 2>/dev/null && on="$b"
+          done
+          [ -n "$on" ] || { echo "::error::$version ($GITHUB_SHA) is not on $TRUNK or $series"; exit 1; }
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+          echo "$version ($GITHUB_SHA) is on $on"
+      - name: Build the gems
+        shell: bash -eo pipefail {0}
+        env:
+          VERSION: ${{ steps.check.outputs.version }}
+        run: |
+          SOURCE_DATE_EPOCH=$(git log -1 --format=%ct "$GITHUB_SHA"); export SOURCE_DATE_EPOCH
+          mkdir dist
+          for spec in $GEMS; do
+            g="${spec%%:*}"; dir="${spec#*:}"; [ "$dir" = "$spec" ] && dir=.
+            out="$GITHUB_WORKSPACE/dist/$g-$VERSION.gem"
+            (cd "$dir" && gem build "$g.gemspec" --output "$out")
+            [ "$(gem spec "$out" name)" = "--- $g" ] && [ "$(gem spec "$out" version | sed -n 's/^version: //p')" = "$VERSION" ] ||
+              { echo "::error::$out is not $g $VERSION:"; gem spec "$out" name; gem spec "$out" version; exit 1; }
+            echo "$g" >> dist/ORDER
+          done
+          echo "SOURCE_DATE_EPOCH=$SOURCE_DATE_EPOCH (ruby $(ruby -e 'print RUBY_VERSION'), rubygems $(gem -v))"
+          (cd dist && sha256sum *.gem > SHA256SUMS && cat ORDER SHA256SUMS)
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: gems-${{ steps.check.outputs.version }}
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: write   # creates the tag on a dispatched release
+      id-token: write   # the RubyGems trusted-publishing exchange
+    steps:
+      - name: Refuse a stale run (the tag is somewhere else)
+        shell: bash -eo pipefail {0}
+        env:
+          TAG: ${{ needs.build.outputs.tag }}
+        run: |
+          tagged=$(git ls-remote "https://github.com/$GITHUB_REPOSITORY" "refs/tags/$TAG*" |
+            awk -v t="refs/tags/$TAG" '$2 == t || $2 == t "^{}" { print $1 }')
+          if [ -z "$tagged" ] && [ "$GITHUB_EVENT_NAME" = workflow_dispatch ]; then
+            echo "tag $TAG will be created at $GITHUB_SHA"
+          else
+            echo "$tagged" | grep -qx "$GITHUB_SHA" || { echo "::error::tag $TAG is not at $GITHUB_SHA (now: ${tagged:-gone}); this run is stale"; exit 1; }
+          fi
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: gems-${{ needs.build.outputs.version }}
+          path: dist
+      - name: Check the sums
+        working-directory: dist
+        run: sha256sum -c SHA256SUMS
+      - uses: ruby/setup-ruby@de492cf36cbab201753d720ce4f4e336cd688c94 # v1.336.0
+        with:
+          ruby-version: '3.3'
+      - uses: rubygems/configure-rubygems-credentials@dc5a8d8553e6ee01fc26761a49e99e733d17954a # v2.1.0
+      - name: Dry run ends here
+        if: inputs.dry_run
+        run: echo "Credentials exchange succeeded, so the trusted publisher works. No tag created, nothing pushed."
+      - name: Push the gems
+        if: ${{ !inputs.dry_run }}
+        shell: bash -eo pipefail {0}
+        working-directory: dist
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          while read -r g; do
+            sum=$(sha256sum "$g-$VERSION.gem" | cut -d' ' -f1)
+            published=$(curl -fsS "https://rubygems.org/api/v1/versions/$g.json" 2>/dev/null |
+              ruby -rjson -e 'b = $stdin.read; v = (b.empty? ? [] : JSON.parse(b)).find { |x| x["number"] == ENV["VERSION"] && x["platform"] == "ruby" }; print v ? v["sha"].to_s : ""' || true)
+            if [ -z "$published" ]; then
+              gem push "$g-$VERSION.gem" </dev/null
+            elif [ "$published" = "$sum" ]; then
+              echo "$g $VERSION is already on rubygems.org with this sum; skipping"
+            else
+              echo "::error::$g $VERSION is already on rubygems.org with sha256 $published, not this build's $sum"; exit 1
+            fi
+          done < ORDER
+      - name: Create the tag
+        if: github.event_name == 'workflow_dispatch' && !inputs.dry_run
+        shell: bash -eo pipefail {0}
+        env:
+          TAG: ${{ needs.build.outputs.tag }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tagged=$(git ls-remote "https://github.com/$GITHUB_REPOSITORY" "refs/tags/$TAG*" |
+            awk -v t="refs/tags/$TAG" '$2 == t || $2 == t "^{}" { print $1 }')
+          if [ -z "$tagged" ]; then
+            gh api "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/tags/$TAG" -f sha="$GITHUB_SHA"
+          elif echo "$tagged" | grep -qx "$GITHUB_SHA"; then
+            echo "tag $TAG is already at $GITHUB_SHA"
+          else
+            echo "::error::tag $TAG is not at $GITHUB_SHA (now: $tagged)"; exit 1
+          fi
+
+  release-page:
+    needs: [build, publish]
+    if: ${{ !inputs.dry_run }}
+    permissions:
+      contents: write   # github-release.yml creates the release
+    uses: ./.github/workflows/github-release.yml
+    with:
+      tag: ${{ needs.build.outputs.tag }}

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## Version 1.8.0 (Oct 31 2026)
+
+* Fix ThreadsOnFork and Forking children crashing on Ruby 3.3 with `[BUG] lazy sweeping underway when freeing object space` when they stopped on a `TERM` or `INT`, on an error, or when a job called `exit`, if a thread in the parent was running finalizers when the child was forked (an interpreter bug fixed in Ruby 3.4). On Ruby 3.3 a forked child now disables the GC as it exits, so its `at_exit` handlers (the app's, and those it inherited from the parent) run with the GC off, and a child running several threads stops its job threads before those handlers run (a job they were working on goes back to the queue and runs again). Other Rubies are unchanged. **What to do:** nothing; on Ruby 3.3 an `at_exit` handler that allocates a lot in a child now grows the child's memory until it exits
+* Fix a delay of a fraction of a second being cut short: `delay` is now rounded up to whole seconds instead of down, so a job never becomes ready before its delay is up. Before, `delay: 0.5` enqueued a job that was ready at once, and an Active Job `set(wait: 1)` or `set(wait_until: ...)`, whose delay is always a little under the time asked for once it reaches the adapter, ran up to a second early (`wait: 1` ran at once). Whole-second delays are unchanged; a fractional one now waits up to a second longer than asked, never less. A fractional retry delay (a `retry_delay_proc` that returns a Float, or a Float `config.retry_delay`) is rounded up the same way; before, beanstalkd refused it (`Beaneater::BadFormatError`), which stopped the worker (the simple worker exited, and a ThreadsOnFork or Forking child died) instead of retrying the job. A fractional TTR (`:ttr` when enqueueing, a class's `queue_respond_timeout` or `config.respond_timeout`) is rounded up to whole seconds too; a Float `config.respond_timeout` used to fail every enqueue (`Beaneater::BadFormatError`). **Behaviour change:** a Float `:ttr`, `queue_respond_timeout` or `queue_retry_delay` (such as `queue_retry_delay 1.5`) used to be ignored in favour of the global default (`config.respond_timeout`, `config.retry_delay`); it is now used, rounded up. The same goes for a fractional `ActiveSupport::Duration` or Rational (`queue_respond_timeout 1.5.minutes` now gives a TTR of 90 instead of the default). If you set one by mistake, remove it to keep the default. `on_retry` hooks now get the rounded delay, and a `retry_delay_proc` that returns `nil`, a String that isn't a number, or a negative number now retries at once (delay 0) instead of stopping the worker with `Beaneater::BadFormatError`; a `:ttr`, `queue_respond_timeout` or `queue_retry_delay` that isn't finite (`Float::INFINITY`, `NaN`) is still ignored in favour of the default
+* Fix a ThreadsOnFork child running more than one thread (`threads_number` or a tube's threads limit above 1) with `garbage_after` set stopping after its first `garbage_after` jobs on Ruby 3.2 and newer: once its threads had worked them, it waited for every thread in the process to finish, including the one the `timeout` gem keeps running since Ruby 3.2 (`timeout` 0.3), so it never exited to be forked again and the tube's jobs piled up. It now waits only for its own threads, so a thread a job leaves running no longer holds it up either. Ruby 3.1 and older with their bundled `timeout` weren't affected. **What to do:** nothing; a worker stuck this way recovers once upgraded and restarted
+* Fix the usage comment in `bin/backburner`: queues are given with `-q` (`backburner -q foo,bar`); a bare `backburner foo,bar` ignores them and works every known queue
+* Fix the ThreadsOnFork worker logging "Catastrophic failure: tube ... exited with code 0" for every child on a normal shutdown: while the worker shuts down, a child that exits with code 0 is now logged as "Tube ... exited normally.", and one that exits with another code or is killed (by the shutdown's `SIGKILL`) as "Tube ... stopped.", without being forked again. A child that exits with code 0 at another time (a signal sent to the child alone, or a job that called `exit`) is logged as a warning, "Tube ... exited with code 0. Forking it again in Ns."
+* Fix an error raised by `config.on_error` (an error reporter that can't reach its service, say) stopping the worker: it escaped `work_one_job`, which ended the simple worker and killed a ThreadsOnFork or Forking child; it is now logged ("The on_error handler failed for ..."). The failed job is still retried or buried as before
+* Fix the ThreadsOnFork worker forking children in a busy loop when they fail at once (hundreds a second while beanstalkd is down, each logging a "Catastrophic failure"): after a child fails, the parent now waits 1 second before forking the next one, doubling up to 30 seconds while children keep failing, and starts over once a child is recycled or runs for 30 seconds; recycling a child after `garbage_after` jobs is still immediate. A child running several threads now exits with code 1 (instead of 99) when one of its threads died of an error, so it backs off too
+* Fix a job whose class can't be found or fails to load stopping the worker: the `Backburner::Job::JobNotFound` raised while handling its failure escaped `work_one_job` (so the simple worker exited and a ThreadsOnFork child died and was forked again in a busy loop), and so did any error other than a `NameError` raised while its class's file loaded (a `LoadError`, `KeyError`, `SyntaxError` and so on). When the class is missing (renamed or removed, or enqueued by code deployed before the workers: there is no such constant, or its autoload file isn't there), the worker now logs a warning ("... class not found; released for Ns") and releases the job with a delay of its TTR (at most 60 seconds), so a worker that has the class picks it up; it is never buried for this and doesn't use up its retries (beanstalkd still counts the releases, so a later failure gets fewer retries), and `on_error` and the failure hooks aren't called for it, as before. **What to do:** jobs of a class you removed on purpose now keep coming back, with a warning each time, instead of stopping the worker: delete them (with a beanstalkd client, say) or keep a stub class whose `perform` does nothing until they are drained. When the class's file fails to load (it raises a `NameError` for another constant, `NoMethodError`, `ArgumentError` or any other error, has a syntax error, or requires a missing gem), or the job names something that can't be a class (`"not a class"`), the job fails like any other: it is retried and then buried, `on_error` gets the `JobNotFound`, and its message names the cause on one line (`JobNotFound: SomeJob (LoadError: cannot load such file -- some_gem)`). **What to do:** fix the file and deploy, then kick the buried jobs
+* Fix `handle_asynchronously` and `handle_static_asynchronously` wiping the class's queue settings: its jobs went to the primary queue (`backburner-jobs`) with the default priority and TTR instead of the class's `queue`, `queue_priority` and `queue_respond_timeout`. Including `Backburner::Performable` in a class that already includes `Backburner::Queue` no longer resets the settings it set either. **Behaviour change:** jobs of a class that calls `handle_asynchronously`/`handle_static_asynchronously` (including its `async` calls) now use the class's `queue`, `queue_priority` and `queue_respond_timeout` (before, the settings declared ahead of the call were lost). Workers started with `-q` or `default_queues` must also watch the class's tube (a worker started with no queues already does). Jobs enqueued before the upgrade stay on the primary queue, so keep a worker on it until they are drained
+* Fix apps on Rails 6.1, 7.0 and 7.1 failing to boot with backburner 1.7.0 (`uninitialized constant ActiveJob::QueueAdapters::AbstractAdapter` from `require 'backburner'`, or from `config.active_job.queue_adapter = :backburner`): the gem's Active Job adapter subclasses `AbstractAdapter` only on Rails 7.2+, which added it, and `require 'backburner'` loads it only there; older Rails autoload the adapter as before. Where the gem's adapter loads in place of Rails' own (whenever the gem's lib comes first on the load path, as Bundler puts it), it also sets `provider_job_id` on Rails 6.1 and 7.0. The adapter now requires backburner itself, as Rails' own adapter did, so apps with `gem 'backburner', require: false` can enqueue again (since 1.7.0 the first enqueue raised `uninitialized constant Backburner::Worker`). CI now also runs the suite with Active Job 6.1
+* Fix a worker started without queues (`backburner` with no `-q`) never working the tubes it found on the server when the namespace has capitals (`MyApp`), an underscore or regexp characters (`jobs(eu)`, `app+`), when the separator isn't `.`, or for queue names such as ActiveJob's `production_mailers` under the namespace `production` (tube `production.-mailers`) and `report_2026`: it expanded those tube names again and watched tubes nobody enqueues on (`MyApp.my-app.default` instead of `MyApp.default`). It now watches the server's tubes this configuration could have produced (they start with the namespace and separator, and the rest has no capitals or underscores), under their own names, and a found tube with `--` in its name (queue `a__b`) no longer stops it at start with `NoMethodError`. The tube names jobs are enqueued on don't change
+* Fix a `tube_namespace` that isn't a valid regexp (such as `app(`) failing every enqueue and stopping workers with `RegexpError`
+* Fix `namespace_separator = ''` failing every enqueue with `RegexpError`: the namespace and the queue name are now joined directly (`appdefault`, or `app.default` for the namespace `app.`)
+* Fix a failing job stopping the worker when it runs in a directory whose name has regexp characters (such as `jobs[`): logging the error raised `RegexpError`
+* Fix ThreadsOnFork with one thread per tube: each forked child now opens its own beanstalkd connection instead of sharing the parent's socket, which mixed up replies between children (`undefined method 'ttr' for nil`, lost jobs) (reported by @Haerezis in #169 and @supremoUL in #175)
+* Fix workers never recovering after beanstalkd is down for more than a few seconds: a failed reconnect no longer leaves the connection unusable (`undefined method 'tubes'` in a busy loop), and the simple worker watches its tubes again after reconnecting; a job that fails while the connection is down no longer stops the simple worker either. A job that finishes while beanstalkd can't be reached (past beaneater's reconnect attempts) can't be deleted: `on_error` gets the `Beaneater::NotConnected`, and beanstalkd hands the job out again if it still has it (reported by @activestylus in #137)
+* Fix `Connection#retryable` raising `NameError` instead of `Beaneater::NotConnected` once its retries are used up
+* Fix a job that outlives its TTR stopping the worker: when beanstalkd has already taken the job back, the `NOT_FOUND` from the retry or bury is now logged instead of escaping `work_one_job` (reported by @boncey in #82)
+* Behaviour change: a `before_perform` hook returning false now deletes the job, as HOOKS.md describes; before, the job stayed reserved and beanstalkd handed it out again after every TTR (reported by @inoce1e in #145)
+* Fix docs: a TTR of 0 does not disable the timeout, beanstalkd stores it as 1 (reported by @pnabutovsky in #126); the HOOKS.md failure-hook examples no longer call `self.bury`, which raised `NoMethodError` and hid the original error (reported by @contentfree in #172); the README no longer points to the removed `retry_connection!` (reported by @att14 in #62)
+* Fix queue settings not being inherited: a subclass of a `Backburner::Queue` job class now uses its parent's `queue`, `queue_priority`, `queue_respond_timeout`, `queue_max_job_retries`, `queue_retry_delay`, `queue_retry_delay_proc`, `queue_jobs_limit`, `queue_garbage_limit` and `queue_retry_limit` unless it sets its own, and is registered in `Backburner::Worker.known_queue_classes` (anonymous classes, such as `Class.new(SomeJob)`, are left out when workers list the known queues). For the Threading and ThreadsOnFork workers, a tube's `queue_jobs_limit`, `queue_garbage_limit` and `queue_retry_limit` come from the class that declares the tube; subclasses that share it only fill in the limits it leaves unset. **Behaviour change:** a subclass that didn't set `queue` used to enqueue on the primary queue (`backburner-jobs`); it now enqueues on its parent's queue (tube). Jobs it enqueued before the upgrade stay on the primary queue, so keep a worker on that tube until they are drained. A subclass can't unset an inherited setting: the setters ignore `nil` and `false` (reported by @contentfree in #141)
+* Fix every enqueue opening a new TCP connection to beanstalkd (closed sockets piled up in `TIME_WAIT` until enqueueing failed with `Beaneater::NotConnected`): enqueueing reuses pooled connections (up to 5 idle per process, each reused for up to `config.enqueue_connection_max_idle` seconds, default 60), a forked child opens its own, and a connection that an error interrupted is closed rather than reused. While beanstalkd is down, each enqueue that picks up an idle pooled connection (up to 5) now takes about 2 seconds of retries before raising `Beaneater::NotConnected`, instead of failing at once; later ones fail at once (reported by @xinuc in #125, confirmed by @funkyboy)
+* Allow `config.tube_namespace = nil` (or `false`) for tubes without a prefix: jobs go to `backburner-jobs`, `newsletter-sender` and so on. `nil` and `false` used to raise `NoMethodError`; `''` still gives tube names that start with the separator (`.backburner-jobs`), as before. With no namespace, a worker started without tubes watches every tube on the server without capitals or underscores (including `default`), so give your tubes distinct names on a shared beanstalkd (@forresty in #94)
+* Fix `config.default_priority` set to a priority label (such as `:high`) failing every enqueue with `Beaneater::BadFormatError`: the label now resolves like a job's priority label (reported by @rewritten in #52, tracked in #54)
+* Fix `require 'backburner'` on Ruby 4.0 in a bundle without ActiveSupport (`cannot load such file -- logger`): `logger` is no longer a default gem, so the gemspec now depends on it
+* Require Ruby 2.7 or newer (the gemspec now says so; CI covers 2.7 to 4.0)
+
 ## Version 1.7.0 (Jan 2 2026)
 
 * Changes to ActiveJob Rails adapter to remove default adapter and associated tests

data/Gemfile

@@ -1,4 +1,7 @@
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in backburner.gemspec
-gemspec
+gemspec
+
+# Test against an older Active Job (and the Active Support it needs), as CI does: ACTIVEJOB_VERSION=7.1 bundle install
+gem 'activejob', "~> #{ENV['ACTIVEJOB_VERSION']}.0" unless ENV['ACTIVEJOB_VERSION'].to_s.empty?

data/HOOKS.md

@@ -17,7 +17,7 @@ There are a variety of hooks available that are triggered during the lifecycle o
   Any exception raised propagates up to the code which queued the job.
 
 * `before_perform`: Called with the job args before perform. If a hook returns false,
-  the job is aborted. Other exceptions are treated like regular job exceptions.
+  the job is aborted and deleted from the queue. Other exceptions are treated like regular job exceptions.
 
 * `after_perform`: Called with the job args after it performs. Uncaught
   exceptions will be treated like regular job exceptions.
@@ -41,9 +41,8 @@ class SomeJob
     logger.info "About to perform #{self} with #{args.inspect}"
   end
 
-  def self.on_failure_bury(e, *args)
+  def self.on_failure_log_job(e, *args)
     logger.info "Performing #{self} caused an exception (#{e})"
-    self.bury
   end
 
   def self.perform(*args)
@@ -56,25 +55,27 @@ class SomeJob
 end
 ```
 
+A failure hook doesn't need to retry or bury the job: the worker retries a failed job up to `max_job_retries`
+times and then buries it. Use an `on_retry` or `on_bury` hook to act on those.
+
 You can also setup modules to create compose-able and reusable hooks for your jobs. For example:
 
 ```ruby
 module LoggedJob
   def before_perform_log_job(*args)
-    Logger.info "About to perform #{self} with #{args.inspect}"
+    puts "About to perform #{self} with #{args.inspect}"
   end
 end
 
-module BuriedJob
-  def on_failure_bury(e, *args)
-    Logger.info "Performing #{self} caused an exception (#{e}). Retrying..."
-    self.bury
+module NotifiedJob
+  def on_failure_notify(e, *args)
+    puts "Performing #{self} caused an exception (#{e})"
   end
 end
 
 class MyJob
   extend LoggedJob
-  extend BuriedJob
+  extend NotifiedJob
 
   def self.perform(*args)
     # ...
@@ -86,14 +87,22 @@ end
 
 Currently, there is just one hook:
 
-* `on_reconnect`: Called on the worker whose connection has been reset. The connection
-  is given as the argument
+* `on_reconnect`: Called on a Simple or ThreadsOnFork worker after Backburner re-establishes
+  a lost connection, with the new connection as the argument. A short outage that beanstalk's
+  client library rides out on its own reconnects without it (and keeps the watched tubes). The
+  Threading worker never calls it (each thread's connection re-watches its own tube), and
+  Forking workers' children reconnect through the client library, so it doesn't fire there either.
+  Every public method whose name starts with `on_reconnect` is called, so add your own as
+  `on_reconnect_<something>`. The Simple, Forking and ThreadsOnFork
+  workers define `on_reconnect` itself to watch their tubes again; if you override
+  `on_reconnect` in a subclass of one of them, call `super`.
 
 An example:
 
 ```ruby
-class MyWorker < Backburner::Worker
-  def on_reconnect(conn)
-    prepare
+class MyWorker < Backburner::Workers::Simple
+  def on_reconnect_log(conn)
+    log_info "reconnected to beanstalkd"
   end
 end
+```

data/README.md

@@ -1,4 +1,4 @@
-# Backburner [![Build Status](https://travis-ci.org/nesquena/backburner.svg?branch=master)](https://travis-ci.org/nesquena/backburner)
+# Backburner [![CI](https://github.com/nesquena/backburner/actions/workflows/ci.yml/badge.svg)](https://github.com/nesquena/backburner/actions/workflows/ci.yml)
 
 Backburner is a [beanstalkd](https://beanstalkd.github.io/)-powered job queue that can handle a very high volume of jobs.
 You create background jobs and place them on multiple work queues to be processed later.
@@ -113,14 +113,14 @@ The key options available are:
 | Option                | Description                                                          |
 | -----------------     | -------------------------------                                      |
 | `beanstalk_url`       | Address for beanstalkd connection i.e 'beanstalk://127.0.0.1'        |
-| `tube_namespace`      | Prefix used for all tubes related to this backburner queue.          |
+| `tube_namespace`      | Prefix used for all tubes related to this backburner queue (`nil` or `false` for no prefix; a worker given no tubes then watches every tube on the server without capitals or underscores, so give your tubes distinct names on a shared beanstalkd; `''` gives tube names that start with the separator, such as `.backburner-jobs`, as before). |
 | `namespace_separator` | Separator used for namespace and queue name                          |
 | `on_error`            | Lambda invoked with the error whenever any job in the system fails.  |
 | `max_job_retries`     | Integer defines how many times to retry a job before burying.        |
-| `retry_delay`         | Integer defines the base time to wait (in secs) between job retries. |
+| `retry_delay`         | Number defines the base time to wait (in secs) between job retries.  |
 | `retry_delay_proc`    | Lambda calculates the delay used, allowing for exponential back-off. |
-| `default_priority`    | Integer The default priority of jobs                                 |
-| `respond_timeout`     | Integer defines how long a job has to complete its task              |
+| `default_priority`    | Integer or priority label: the default priority of jobs              |
+| `respond_timeout`     | Number defines how long a job has to complete its task (in secs)     |
 | `default_worker`      | Worker class that will be used if no other worker is specified.      |
 | `logger`              | Logger recorded to when backburner wants to report info or errors.   |
 | `primary_queue`       | Primary queue used for a job when an alternate queue is not given.   |
@@ -128,6 +128,17 @@ The key options available are:
 | `reserve_timeout`     | Duration to wait for work from a single server, or nil for forever.  |
 | `job_serializer_proc` | Lambda serializes a job body to a string to write to the task        |
 | `job_parser_proc`     | Lambda parses a task body string to a hash                           |
+| `enqueue_connection_max_idle` | Seconds an idle enqueue connection is reused for before it is replaced (default 60; `nil` for no limit; 0 or less opens a new connection for every enqueue). |
+
+A tube's name is the namespace, the separator and the queue name, dasherized (`some.app.production.newsletter-sender`).
+Don't start queue names with the namespace: that part of the queue name is dropped, so with the namespace `app` the queues
+`mail` and `appmail` share the tube `app.mail` and `apple-sync` uses `app.le-sync` (an ActiveJob `queue_name_prefix` equal
+to the namespace does the same: `production_mailers` uses `production.-mailers`). It stays that way because changing it
+would leave queued jobs in the old tubes. A worker given no tubes watches the tubes on the server whose names start with the
+namespace and separator and whose rest has no capitals or underscores (the names this configuration could have produced),
+the tubes of the job classes it has loaded and the primary queue. On a shared beanstalkd, don't give one app a namespace
+that starts with another's namespace and separator (`app` and `app.prod`, `MyApp` and `MyApp.admin`): workers of the
+shorter one given no tubes reserve the other's jobs, which they can't run.
 
 ## Breaking Changes
 
@@ -165,7 +176,7 @@ class NewsletterJob
 
   # optional, defaults to respond_timeout in config
   def self.queue_respond_timeout
-    300 # number of seconds before job times out, 0 to avoid timeout. NB: A timeout of 1 second will likely lead to race conditions between Backburner and beanstalkd and should be avoided
+    300 # number of seconds before job times out; the minimum is 1 (beanstalkd turns 0 into 1), so give long jobs a generous value. NB: A timeout of 1 second will likely lead to race conditions between Backburner and beanstalkd and should be avoided
   end
 
   # optional, defaults to retry_delay_proc in config
@@ -192,7 +203,7 @@ class NewsletterJob
   include Backburner::Queue
   queue "newsletter-sender"  # defaults to 'backburner-jobs' tube
   queue_priority 1000 # most urgent priority is 0
-  queue_respond_timeout 300 # number of seconds before job times out, 0 to avoid timeout
+  queue_respond_timeout 300 # number of seconds before job times out (minimum 1; 0 does not disable it)
 
   def self.perform(email, body)
     NewsletterMailer.deliver_text_to_email(email, body)
@@ -200,6 +211,11 @@ class NewsletterJob
 end
 ```
 
+A subclass of such a job uses its parent's settings (including its tube) unless it sets its own.
+It can't unset one: the setters ignore `nil` and `false`. For the Threading and ThreadsOnFork workers, a shared
+tube's limits (`queue_jobs_limit`, `queue_garbage_limit`, `queue_retry_limit`) come from the class that declares the
+tube; subclasses only fill in the limits it leaves unset.
+
 Jobs can be enqueued with:
 
 ```ruby
@@ -224,7 +240,7 @@ class User
   include Backburner::Performable
   queue "user-jobs"  # defaults to 'user'
   queue_priority 500 # most urgent priority is 0
-  queue_respond_timeout 300 # number of seconds before job times out, 0 to avoid timeout
+  queue_respond_timeout 300 # number of seconds before job times out (minimum 1; 0 does not disable it)
 
   def activate(device_id)
     @device = Device.find(device_id)
@@ -408,6 +424,8 @@ Backburner::Worker.enqueue NewsletterJob, ["foo", "bar"], :pri => :custom
 User.async(:pri => :useful, :delay => 10.seconds).reset_password(@user.id)
 ```
 
+They work for `config.default_priority` too (e.g. `config.default_priority = :custom`).
+
 Using named priorities can greatly simplify priority management.
 
 ### Processing Strategies
@@ -611,7 +629,12 @@ backburner -e $environment
 
 In Backburner, if the beanstalkd connection is temporarily severed, several retries to establish the connection will be attempted.
 After several retries, if the connection is still not able to be made, a `Beaneater::NotConnected` exception will be raised.
-You can manually catch this exception, and attempt another manual retry using `Backburner::Worker.retry_connection!`.
+Workers log the exception and try again on their next reserve, and watch their tubes again once the connection is back.
+Elsewhere (when enqueuing, for example) you can catch the exception and retry the call yourself.
+
+Enqueueing reuses a small pool of connections (up to 5 idle per process). While beanstalkd is down, each enqueue
+that picks up one of those idle connections takes about 2 seconds of retries before raising `Beaneater::NotConnected`;
+once they are used up, enqueues fail at once until beanstalkd is back.
 
 ### Web Front-end
 

data/backburner.gemspec

@@ -15,13 +15,16 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.version       = Backburner::VERSION
   s.license       = 'MIT'
+  s.required_ruby_version = '>= 2.7'
 
   s.add_runtime_dependency 'beaneater', '~> 1.0'
   s.add_runtime_dependency 'dante', '> 0.1.5'
   s.add_runtime_dependency 'concurrent-ruby', '~> 1.0', '>= 1.0.1'
+  s.add_runtime_dependency 'logger' # a bundled gem (no longer a default one) since Ruby 4.0
 
   s.add_development_dependency 'rake'
   s.add_development_dependency 'minitest', '5.1.0'
+  s.add_development_dependency 'mutex_m' # minitest 5.1.0 requires it; a bundled gem (not a default one) since Ruby 3.4
   s.add_development_dependency 'mocha'
   s.add_development_dependency 'activejob', '>= 6.0'
   s.add_development_dependency 'activesupport', '>= 6.0'

data/bin/backburner

@@ -3,5 +3,5 @@
 require 'backburner'
 require 'backburner/cli'
 
-# bundle exec backburner foo,bar
+# bundle exec backburner -q foo,bar
 Backburner::CLI.start(ARGV)

data/lib/active_job/queue_adapters/backburner_adapter.rb

@@ -1,14 +1,21 @@
+# Rails' own adapter files require backburner too, for apps that don't require it themselves
+require 'backburner' unless defined?(Backburner::Worker)
+
 module ActiveJob
   module QueueAdapters
-    # Explicitly remove the implementation existing in older rails'.
-    remove_const(:BackburnerAdapter) if const_defined?(:BackburnerAdapter)
+    # Rails 7.2 added AbstractAdapter; the adapters of older Rails have no superclass
+    rails_7_2_or_newer = const_defined?(:AbstractAdapter, false)
+
+    # Explicitly remove the implementation rails' 7.2+ ship. Older rails' keep theirs, unless their autoload
+    # loads this file instead (it shadows theirs when this gem's lib comes first on the load path).
+    remove_const(:BackburnerAdapter) if rails_7_2_or_newer && const_defined?(:BackburnerAdapter)
 
     # = Backburner adapter for Active Job
     #
     # To use Backburner set the queue_adapter config to +:backburner+.
     #
     #   Rails.application.config.active_job.queue_adapter = :backburner
-    class BackburnerAdapter < ::ActiveJob::QueueAdapters::AbstractAdapter
+    class BackburnerAdapter < (rails_7_2_or_newer ? ::ActiveJob::QueueAdapters::AbstractAdapter : Object)
       def enqueue(job)
         response = Backburner::Worker.enqueue(JobWrapper, [job.serialize], queue: job.queue_name, pri: job.priority)
         job.provider_job_id = response[:id] if response.is_a?(Hash)