traject-solr_pool 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ba919dd1768bd1f05ff1e29af8236790aee47bd0333f97c9be2cd66b691fa0a
-  data.tar.gz: 01e411c06eb9dd7f101630e42829c0dddacb13931ee1bb0c38f4966383fdcb5a
+  metadata.gz: cfec86e670097a69b2497eec78b34d942a3607c2235a35f5141ae7e5c12709dd
+  data.tar.gz: c67b4176576d49edb174c18c52dbdc8c0a1ae3cf3e6c45d8e32270a59d961dca
 SHA512:
-  metadata.gz: 131acdc7092f6f935ba9d16b1aa4c50047b86694d06dc4ba571c4d8415624ff461efe549351e4c8db76d106ab58539f469fd3491bc8bd709d1875d65eaa73794
-  data.tar.gz: '0687c890c8944c6b2b024c49b09748f78c8626a7a8531ce0aac553cc5c5bd173537e7ef9cf0a30f23c33976022e7a41f40d2587cb4056bfe5fb23a1e0f8cd040'
+  metadata.gz: 7a1a91726739555f50720e8290346b2d4563294de41fd5d59093cef7375db54e68c7a50dd5ef2c9d236da26162293dae5321fb8e4b26abd0269d530c2f8297b3
+  data.tar.gz: 9ae93346c8a65de4c826f62ccc872fea715cefdc22f85d121f253008dc1b72d71ba5d1c6cdc629dd157974354f0f08aa502491102c3a43f487ca1353fa05ebd3

data/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # create the GitHub Release and attach assets
+      id-token: write   # OIDC token for RubyGems Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Verify tag matches gem version
+        run: |
+          gem_version="$(ruby -Ilib -r traject/solr_pool/version \
+            -e 'print Traject::SolrPool::VERSION')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          if [ "$gem_version" != "$tag_version" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match VERSION $gem_version" >&2
+            exit 1
+          fi
+
+      # Re-run the specs (not RuboCop) before publishing. A tag push does not
+      # trigger ci.yml, and dependencies resolve fresh (Gemfile.lock is
+      # gitignored), so this guards against a broken artifact under a newer
+      # in-range dependency the last main CI run never saw. A yanked version
+      # number can never be reused, so publishing red is uniquely costly.
+      - run: bundle exec rake spec
+
+      # Builds via `rake release` and pushes over OIDC. It leaves the exact
+      # published .gem in pkg/, which the steps below checksum and attach.
+      - uses: rubygems/release-gem@v1
+
+      # Record digests of the artifact that was actually published (pkg/*.gem
+      # from the step above). .gem builds are not byte-stable across
+      # zlib/RubyGems versions, so the published gem is the source of truth
+      # rather than a repo-committed checksum compared against a fresh build.
+      - name: Checksum the published gem
+        run: bundle exec rake build:checksum
+
+      - name: Create GitHub Release with gem and checksums
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            pkg/traject-solr_pool-*.gem \
+            checksums/traject-solr_pool-*.sha256 \
+            checksums/traject-solr_pool-*.sha512

data/CLAUDE.md

@@ -207,6 +207,10 @@ matching the file tree.
 | `rake spec`               | RSpec only                                            |
 | `rake rubocop`            | RuboCop only                                          |
 | `rake bundle:audit:check` | Offline CVE scan                                      |
+| `rake build:checksum`     | Build, then write SHA-256 + SHA-512 to `checksums/` (gitignored) |
+| `rake bump:patch`         | Bump patch version in version.rb, print release commands |
+| `rake bump:minor`         | Bump minor version in version.rb, print release commands |
+| `rake bump:major`         | Bump major version in version.rb, print release commands |
 
 `rake ci` must run clean before any commit. Never bypass bundler-audit.
 
@@ -218,8 +222,13 @@ RSpec), plus a separate `security` job running `rake audit` (network advisory-DB
 refresh + check). MRI only — mirrors `http_connection_pool`'s CI. `Gemfile.lock`
 is gitignored, so CI resolves dependencies fresh each run.
 
-Automated publishing (`release.yml` / OIDC Trusted Publishing) is planned but
-not yet wired; the initial release is published manually by the maintainer.
+`.github/workflows/release.yml` triggers on a `v*.*.*` tag: it verifies the tag
+matches `Traject::SolrPool::VERSION`, re-runs the specs, publishes via
+`rubygems/release-gem` (OIDC Trusted Publishing — no stored API key), then
+checksums the published gem and creates a GitHub Release with the gem and
+checksum files attached. `gem push` / `git push` / pushing a tag remain
+user-only actions; `rake bump:*` only edits `version.rb` and prints the next
+commands.
 
 ---
 

data/README.md

@@ -68,6 +68,21 @@ auth credentials are sent as an `Authorization` header, never baked into the
 origin, so distinct credentials resolve to distinct pools and never share
 connections.
 
+### Health check
+
+```ruby
+writer = Traject::SolrPool::SolrJsonWriter.new(settings)
+abort 'Solr unreachable' unless writer.ready?
+```
+
+`ready?` returns `true` for any HTTP response (the server answered — including
+`405`/`404`), and `false` only on a transport failure (refused/timeout/DNS). It
+uses a HEAD request so the pooled persistent connection stays clean for reuse.
+Use `writer.ping` for the raw response. Configure the endpoint with
+`solr_writer.ping_path` (default `<core>/admin/ping`) and the timeout with
+`solr_writer.ping_timeout` (default 5s). See [docs/usage.md](docs/usage.md) for
+the full reference, including reusing the pool from another class.
+
 ## Settings
 
 The writer honours the stock `solr.*` / `solr_writer.*` vocabulary, plus one
@@ -160,6 +175,22 @@ also available.
 Bug reports and pull requests are welcome. Releasing and pushing are maintainer
 responsibilities — contributors should not push tags or publish gems.
 
+## Releasing
+
+Releases are published to RubyGems via OIDC Trusted Publishing on a version
+tag — no API key is stored. The maintainer:
+
+1. Bumps the version: `rake bump:patch` (or `:minor` / `:major`). This edits
+   `lib/traject/solr_pool/version.rb` and prints the next commands.
+2. Commits and tags: `git commit -am 'Release vX.Y.Z' && git tag vX.Y.Z`.
+3. Pushes the tag: `git push && git push --tags`.
+
+Pushing the `v*.*.*` tag triggers `.github/workflows/release.yml`, which
+verifies the tag matches `Traject::SolrPool::VERSION`, re-runs the specs,
+publishes the gem, and creates a GitHub Release with the gem and its SHA-256 /
+SHA-512 checksums attached. `gem push` and `git push` are maintainer actions;
+CI never pushes on its own.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License][mit].

data/Rakefile

@@ -4,6 +4,7 @@ require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
 require 'bundler/audit/task'
+require_relative 'tasks/version_bumper'
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new
@@ -19,3 +20,69 @@ desc 'Audit dependencies (offline), run RuboCop, then the RSpec suite'
 task ci: %i[bundle:audit:check rubocop spec]
 
 task default: :ci
+
+VERSION_FILE = 'lib/traject/solr_pool/version.rb'
+
+namespace :bump do
+  VersionBumper::LEVELS.each do |level|
+    desc "Bump the #{level} version and print the release commands"
+    task(level) { bump_version(level) }
+  end
+end
+
+def bump_version(level)
+  contents = File.read(VERSION_FILE)
+  current  = contents[/VERSION = '([^']+)'/, 1]
+  raise "could not find VERSION in #{VERSION_FILE}" unless current
+
+  bumped = VersionBumper.next(current, level)
+  File.write(VERSION_FILE, contents.sub(/VERSION = '[^']+'/, "VERSION = '#{bumped}'"))
+  puts "Bumped #{current} -> #{bumped}"
+  print_release_steps(bumped)
+end
+
+def print_release_steps(bumped)
+  puts <<~NEXT
+    Next steps (run these yourself):
+      git add #{VERSION_FILE}
+      git commit -m 'Release v#{bumped}'
+      git tag v#{bumped}
+      git push && git push --tags
+  NEXT
+end
+
+# `bundler/gem_tasks` provides `build` (into pkg/). We extend it to record
+# SHA-256 and SHA-512 digests of the built .gem in the standard
+# `sha256sum -c` / `sha512sum -c` format. These describe THIS build's artifact;
+# the release workflow runs this against the exact gem it just published and
+# attaches the digests to the GitHub Release. .gem builds are not byte-stable
+# across zlib/RubyGems versions, so checksums are recorded per published
+# artifact rather than committed to the repo and byte-compared in CI.
+namespace :build do
+  desc 'Build the gem, then write SHA-256 and SHA-512 checksums to checksums/'
+  task :checksum do
+    require 'digest'
+    require_relative 'lib/traject/solr_pool/version'
+
+    gem_path = File.join('pkg', "traject-solr_pool-#{Traject::SolrPool::VERSION}.gem")
+    Rake::Task['build'].invoke unless File.exist?(gem_path)
+
+    write_checksum(gem_path, Digest::SHA256, 'sha256')
+    write_checksum(gem_path, Digest::SHA512, 'sha512')
+
+    # bundler/gem_tasks' build writes its own raw-format `<name>.gem.sha512`
+    # (digest only, no filename). Remove it so checksums/ holds exactly one
+    # sha256 and one sha512, both in the standard `<digest>  <file>` format.
+    redundant = File.join('checksums', "#{File.basename(gem_path)}.sha512")
+    rm_f redundant
+  end
+end
+
+def write_checksum(gem_path, digest_class, extension)
+  mkdir_p 'checksums'
+  digest = digest_class.file(gem_path).hexdigest
+  basename = File.basename(gem_path, '.gem')
+  out = File.join('checksums', "#{basename}.#{extension}")
+  File.write(out, "#{digest}  #{File.basename(gem_path)}\n")
+  puts "#{extension}: #{digest}  -> #{out}"
+end

data/lib/traject/solr_pool/connection.rb

@@ -18,6 +18,17 @@ module Traject
         end
       end
 
+      # Transport-level failures that mean the server is unreachable. A returned
+      # HTTP response of ANY status (2xx/4xx/5xx) is NOT in this set — it proves
+      # the server answered. Kept independent of the writer's skippable list.
+      TRANSPORT_ERRORS = [
+        HTTP::TimeoutError,
+        HttpConnectionPool::TimeoutError,
+        HTTP::ConnectionError,
+        SocketError,
+        Errno::ECONNREFUSED
+      ].freeze
+
       attr_reader :origin
 
       def initialize(origin:, pool_size:, pool_timeout: nil, **opts)
@@ -45,6 +56,28 @@ module Traject
         end
       end
 
+      def head(path, timeout: nil)
+        @adapter.with_connection do |conn|
+          client = timeout ? conn.timeout(timeout) : conn
+          client.head(path)
+        end
+      end
+
+      # Raw health probe: returns the HTTP::Response (any status) so callers can
+      # inspect it. Raises on transport failure. HEAD has no body to drain, so
+      # it leaves the pooled persistent socket clean for reuse.
+      def ping(path, timeout: nil)
+        head(path, timeout: timeout)
+      end
+
+      # Liveness predicate. Any HTTP response means reachable -> true. Only a
+      # transport failure means down -> false. Never raises.
+      def ready?(path, timeout: nil)
+        !ping(path, timeout: timeout).nil?
+      rescue *TRANSPORT_ERRORS
+        false
+      end
+
       def release
         @adapter.release_connection_pool
       end

data/lib/traject/solr_pool/solr_json_writer.rb

@@ -140,6 +140,14 @@ module Traject
         delete(query: '*:*')
       end
 
+      def ping(timeout: nil)
+        connection.ping(@ping_path, timeout: timeout || @ping_timeout)
+      end
+
+      def ready?(timeout: nil)
+        connection.ready?(@ping_path, timeout: timeout || @ping_timeout)
+      end
+
       private
 
       def shutdown_thread_pool
@@ -207,6 +215,7 @@ module Traject
         configure_batching
         configure_pools
         configure_commit
+        configure_ping
       end
 
       def configure_skipped
@@ -240,6 +249,21 @@ module Traject
         @commit_timeout = (@settings['solr_writer.commit_timeout'] || 600).to_i
       end
 
+      def configure_ping
+        @ping_path    = @settings['solr_writer.ping_path'] || derive_ping_path
+        @ping_timeout = (@settings['solr_writer.ping_timeout'] || 5).to_i
+      end
+
+      # Derive <core>/admin/ping from the update URL path by stripping a
+      # trailing /update or /update/json segment. Falls back to appending
+      # /admin/ping to the whole path when no update segment is present.
+      def derive_ping_path
+        path = URI.parse(@solr_update_url).path
+        base = path.sub(%r{/update(/json)?/?\z}, '')
+        base = path if base.empty?
+        "#{base}/admin/ping"
+      end
+
       # Splits origin (scheme://host:port) from request path; auth goes to
       # Connection as an Authorization header, never baked into the origin.
       def build_connection(user, password)

data/lib/traject/solr_pool/version.rb

@@ -2,6 +2,6 @@
 
 module Traject
   module SolrPool
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: traject-solr_pool
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - bbarberBPL
@@ -52,15 +52,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
 - CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/agents/README.md
-- docs/skills/README.md
-- docs/superpowers/plans/2026-07-01-traject-solr-pool-writer.md
-- docs/superpowers/specs/2026-07-01-traject-solr-pool-writer-design.md
-- docs/usage.md
 - lib/traject/solr_pool.rb
 - lib/traject/solr_pool/connection.rb
 - lib/traject/solr_pool/solr_json_writer.rb
@@ -88,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Traject Solr JSON writer backed by a persistent, pooled, thread-safe HTTP
   client

data/docs/agents/README.md

@@ -1,41 +0,0 @@
-# Agents
-
-Project-specific subagent definitions for `traject-solr_pool`.
-
-When a task in this project benefits from a dedicated subagent (a focused
-reviewer, a migration helper, a release auditor, etc.), define it here as one
-Markdown file per agent. Keep each agent's responsibility narrow and its
-instructions self-contained, so it can run without the parent session's
-context.
-
-## File convention
-
-- One file per agent: `docs/agents/<agent-name>.md`.
-- Start with a short purpose line: what the agent does and when to reach for it.
-- List the tools it needs and the inputs it expects (file paths, not pasted
-  context).
-- Describe the report format it must return.
-
-## Reusable from the sibling `http_connection_pool` gem
-
-This gem shares that gem's thread-safety and security constraints, so several of
-its agents transfer directly (see `../../../http_connection_pool/docs/agents/`).
-Adapt the file paths/tags to this project when reused:
-
-- `concurrency-spec-reviewer` — reviews concurrency specs for assertions a race
-  can invalidate, then stress-loops them for flakiness. Directly applicable to
-  our `:thread_safety` and `:background_jobs` integration specs.
-- `dependency-security-auditor` — audits the dependency tree against primary
-  sources (RubyGems API, GitHub advisory DB). Applicable to our gemspec/Gemfile
-  whenever a dependency floor changes.
-- `memory-leak-auditor` — hunts unbounded retention with `ObjectSpace`/`GC`
-  probes. Applicable to verifying the writer/pool do not accumulate objects
-  per-batch or per-job.
-
-## Defined agents
-
-_None yet. Candidate for this project:_
-
-- **writer-parity-reviewer** — diff our `Traject::SolrPool::SolrJsonWriter`
-  against the stock `Traject::SolrJsonWriter` to confirm settings/method-surface
-  parity and flag any silently-dropped behaviour. Advisory only.

data/docs/skills/README.md

@@ -1,42 +0,0 @@
-# Skills
-
-Project-specific skills for `traject-solr_pool`.
-
-When a repeatable workflow emerges in this project (a release checklist, a
-dependency-audit routine, a Solr round-trip verification), capture it here as a
-skill so future sessions follow the same steps instead of rediscovering them.
-
-## File convention
-
-- One directory per skill: `docs/skills/<skill-name>/SKILL.md`.
-- The `SKILL.md` opens with YAML frontmatter (`name`, `description`) describing
-  when the skill applies, followed by the steps.
-- Keep steps concrete and ordered; prefer checklists the session can turn into
-  todos.
-- Reference supporting files by relative path within the skill directory.
-
-## Reusable from the sibling `http_connection_pool` gem
-
-See `../../../http_connection_pool/docs/skills/`. These transfer with minor path
-changes:
-
-- `dependency-audit` — security sweep that verifies every advisory/version claim
-  against primary sources before recommending a change. Reuse verbatim whenever
-  a dependency floor changes.
-- `memory-leak-audit` — drives churn and measures retention with
-  `ObjectSpace`/`GC` rather than reading code. Adapt the churn driver to enqueue
-  writer batches / background jobs against a WebMock-stubbed Solr.
-
-## Defined skills
-
-_None yet. Candidates for this project:_
-
-- **edge-traject-cutover** — _done (2026-07-27)._ traject 3.9.0 lifted the
-  `http < 6` cap; the gemspec now pins `traject '~> 3.9'` and the Gemfile
-  `path:` override is commented out. Retained here as a record of the cutover
-  procedure (verify the published version via the RubyGems API, update the
-  gemspec constraint, drop the override, re-run `rake ci`) in case a similar
-  edge-dependency bridge is needed again.
-- **solr-roundtrip-verify** — bring up a local Solr, run a real index + commit +
-  delete round-trip through the pooled writer, and confirm connection reuse via
-  registry stats (mirrors the sibling gem's `examples/solr_update_demo.rb`).