Modernise the gem for 2.0 (Ruby 3.4, typed, retrying transport)

.github/dependabot.yml

@@ -5,7 +5,18 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      actions:
+        patterns: ["*"]
   - package-ecosystem: "bundler"
     directory: "/"
     schedule:
       interval: "weekly"
+    groups:
+      # Lint and type tooling churns often and never affects the shipped gem.
+      development:
+        dependency-type: "development"
+        patterns: ["*"]
+      runtime:
+        dependency-type: "production"
+        patterns: ["*"]

.github/workflows/ci.yml

@@ -1,27 +1,93 @@
 name: CI
+
 on:
   push:
     branches: [master]
   pull_request:
   schedule:
-    # Run every on Friday to ensure everything works as expected.
-    - cron:  '0 6 * * 5'
+    # Weekly, to catch breakage from new Ruby or Zammad releases.
+    - cron: '0 6 * * 5'
+  workflow_dispatch:
+    inputs:
+      zammad_ref:
+        description: 'Zammad git ref to run the integration specs against'
+        default: 'develop'
+        type: string
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
 jobs:
   lint:
+    name: RuboCop
     runs-on: ubuntu-latest
-    container:
-      image: zammad/zammad-ci:latest
     steps:
       - uses: actions/checkout@v7
-      - name: Run lint actions
-        shell: bash
-        run: |
-          source /etc/profile.d/rvm.sh # ensure RVM is loaded
-          bundle update --bundler
-          bundle install -j $(nproc)
-          bundle exec rubocop
-  test:
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec rubocop --format github
+
+  types:
+    name: Steep
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      - run: bundle exec steep check
+      # sig/vendor is always on the load path here but never in the gem, so
+      # the published set is checked on its own as well.
+      - run: bundle exec rake rbs_published
+
+  unit:
+    name: Unit specs (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Stable releases only, from required_ruby_version up to the current
+        # stable line. There is no 3.5: that line was abandoned after
+        # 3.5.0-preview1 and became 4.0.
+        #
+        # 'head' is absent because it cannot install at all, for two reasons
+        # outside this gem. With Gemfile.lock present, bundler honours
+        # `BUNDLED WITH 2.6.9`, self-downgrades from head's 4.1.0.dev and dies
+        # with NameError on the removed Pathname::SEPARATOR_PAT. Without the
+        # lockfile, a fresh resolution pulls steep -> listen -> rb-inotify ->
+        # ffi, which requires Ruby < 4.1.dev.
+        ruby: ['3.4', '4.0']
+    env:
+      # The unit specs do not need the type-checking toolchain, and skipping it
+      # keeps this job fast. The `types` job installs it separately.
+      BUNDLE_WITHOUT: development
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: Run unit specs
+        run: bundle exec rake spec:unit
+        env:
+          COVERAGE: 'true'
+
+  integration:
+    name: Integration specs (live Zammad)
     runs-on: ubuntu-latest
+    # Booting Zammad costs far more runner time than the unit suite, so there
+    # is no point paying for it when the unit specs are already failing.
+    needs: unit
+    # A full Zammad boot takes many minutes; without a cap a hung boot would
+    # occupy a runner until the six hour default expires.
+    timeout-minutes: 45
     container:
       image: zammad/zammad-ci:latest
     services:
@@ -32,26 +98,89 @@ jobs:
           POSTGRES_PASSWORD: zammad
       redis:
         image: redis:7
+    env:
+      ZAMMAD_REF: ${{ inputs.zammad_ref || 'develop' }}
+      TEST_USER: admin@example.com
+      TEST_PASSWORD: test
     steps:
       - uses: actions/checkout@v7
-      - name: Set up Zammad
+
+      - name: Report the toolchain
         shell: bash
         run: |
-          git clone --depth 1 https://github.com/zammad/zammad.git
+          source /etc/profile.d/rvm.sh
+          # The gem requires Ruby >= 3.4; fail here with a clear message rather
+          # than inside a confusing bundler resolution error.
+          ruby -v
+          ruby -e 'abort "zammad-ci image ships Ruby #{RUBY_VERSION}, this gem needs >= 3.4" if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.4")'
+
+      - name: Boot Zammad
+        shell: bash
+        run: |
+          # No `set -u`: /etc/profile.d/rvm.sh reads unset variables and aborts
+          # under nounset.
+          set -eo pipefail
+          git clone --depth 1 --branch "$ZAMMAD_REF" https://github.com/zammad/zammad.git
           cd zammad
-          source /etc/profile.d/rvm.sh # ensure RVM is loaded
+          source /etc/profile.d/rvm.sh
           bundle config set --local frozen 'true'
           bundle config set --local path 'vendor'
-          bundle install -j $(nproc)
+          bundle install -j "$(nproc)"
           bundle exec ruby .gitlab/configure_environment.rb
+          # Each workflow step runs in its own shell, so Zammad's generated
+          # environment has to be promoted to the job environment to survive.
+          sed -E 's/^export +//' .gitlab/environment.env \
+            | grep -E '^[A-Za-z_][A-Za-z0-9_]*=' >> "$GITHUB_ENV"
           source .gitlab/environment.env
           RAILS_ENV=test bundle exec rake db:create
           cp contrib/auto_wizard_test.json auto_wizard.json
           bundle exec rake zammad:ci:test:start
-      - name: Run Ruby API integration tests
+          echo "TEST_URL=http://localhost:${RAILS_PORT:-3000}/" >> "$GITHUB_ENV"
+
+      - name: Wait for Zammad to answer
+        shell: bash
+        run: |
+          probe="${TEST_URL%/}/api/v1/getting_started"
+          for attempt in $(seq 1 60); do
+            if curl -sSf --max-time 5 "$probe" >/dev/null 2>&1; then
+              echo "Zammad answered at $TEST_URL after ${attempt} attempt(s)"
+              exit 0
+            fi
+            sleep 5
+          done
+          echo "::error::Zammad never answered at $probe"
+          exit 1
+
+      - name: Install the gem's dependencies
+        shell: bash
+        run: |
+          source /etc/profile.d/rvm.sh
+          bundle install -j "$(nproc)"
+
+      - name: Drive Zammad with this gem
+        shell: bash
+        run: |
+          source /etc/profile.d/rvm.sh
+          bundle exec ruby script/check_connection.rb
+
+      - name: Run the integration specs
+        shell: bash
+        run: |
+          source /etc/profile.d/rvm.sh
+          bundle exec rake spec:integration
+
+      - name: Collect Zammad logs on failure
+        if: failure()
         shell: bash
         run: |
-          source /etc/profile.d/rvm.sh # ensure RVM is loaded
-          bundle update --bundler
-          bundle install -j $(nproc)
-          bundle exec rspec
+          echo '--- zammad/log ---'
+          tail -n 200 zammad/log/*.log 2>/dev/null || echo 'no logs found'
+
+      - name: Upload Zammad logs
+        if: failure()
+        uses: actions/upload-artifact@v5
+        with:
+          name: zammad-logs
+          path: zammad/log/
+          if-no-files-found: ignore
+          retention-days: 7

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+# Publishes to RubyGems via trusted publishing (OIDC), so no API key is
+# stored in this repository. Configure the trusted publisher once at
+# https://rubygems.org/gems/zammad_api/trusted_publishers
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: rubygems
+    permissions:
+      contents: write # create the GitHub release and push the tag commit
+      id-token: write # request the OIDC token for trusted publishing
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+      # The tag is what triggers this workflow, and nothing downstream reads
+      # it: the gem is built from the gemspec, so a tag that disagrees with
+      # ZammadAPI::VERSION publishes a gem under a version nobody tagged and
+      # leaves a GitHub release pointing at one that does not exist.
+      - name: Check the tag against the gem version and the changelog
+        run: |
+          tagged="${GITHUB_REF_NAME#v}"
+          declared="$(ruby -Ilib -rzammad_api/version -e 'print ZammadAPI::VERSION')"
+          if [ "$tagged" != "$declared" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} does not match ZammadAPI::VERSION ($declared)"
+            exit 1
+          fi
+          if ! grep -q "^## \[${declared}\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no '## [${declared}]' heading"
+            exit 1
+          fi
+      - name: Verify the release candidate
+        run: bundle exec rake spec:unit rubocop steep rbs_published
+      - uses: rubygems/release-gem@v1

.gitignore

@@ -1,6 +1,6 @@
 /.bundle/
-/.ruby-version
-/.yardoc
+/.steep/
+/.yardoc/
 /_yardoc/
 /coverage/
 /doc/

.overcommit.yml

@@ -1,33 +1,23 @@
-# Use this file to configure the Overcommit hooks you wish to use. This will
-# extend the default configuration defined in:
-# https://github.com/sds/overcommit/blob/master/config/default.yml
+# See https://github.com/sds/overcommit#configuration
 #
-# At the topmost level of this YAML file is a key representing type of hook
-# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can
-# customize each hook, such as whether to only run it on certain files (via
-# `include`), whether to only display output if it fails (via `quiet`), etc.
-#
-# For a complete list of hooks, see:
-# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook
-#
-# For a complete list of options that you can use to customize hooks, see:
-# https://github.com/sds/overcommit#configuration
-#
-# Uncomment the following lines to make the configuration take effect.
+# Install with: bundle exec overcommit --install
 
 PreCommit:
- RuboCop:
-   enabled: true
-   on_warn: fail # Treat all warnings as failures
-#
-#  TrailingWhitespace:
-#    enabled: true
-#    exclude:
-#      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
-#
-#PostCheckout:
-#  ALL: # Special hook name that customizes all hooks of this type
-#    quiet: true # Change all post-checkout hooks to only display output on failure
-#
-#  IndexTags:
-#    enabled: true # Generate a tags file with `ctags` each time HEAD changes
+  RuboCop:
+    enabled: true
+    on_warn: fail # Treat all warnings as failures
+    command: ['bundle', 'exec', 'rubocop']
+
+  TrailingWhitespace:
+    enabled: true
+
+  YamlSyntax:
+    enabled: true
+
+  BundleCheck:
+    enabled: true
+
+  RSpec:
+    enabled: true
+    description: 'Run the unit specs'
+    command: ['bundle', 'exec', 'rspec', 'spec/unit']

.rspec

@@ -1,2 +1,3 @@
+--require spec_helper
 --format documentation
 --color