close_encounters 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be9653e9826ea4a3ba675cc0a35c68eb9ff77404e8ae5569a2834682b4800a61
-  data.tar.gz: 8d61d965ce13c0e67a960bc90a4ace544ad215aa6d58f7c28c04a140258f6ab9
+  metadata.gz: 153aff29d52784d224dc23d3cb5606fe7a1478c2522bff75dc80678d236f3a47
+  data.tar.gz: c2de654d365fe8ec5330b2254b45a56029e75895a808c90fc261d9e0aae333b2
 SHA512:
-  metadata.gz: 8f279069dfbdaa9aff1e4802d15950dbc03f6ad411bcb174f4935efb4a2bbe245cf920c6cd00a522365c8a45c56202ae5a06568a67ba6fdc4965ed101586bdba
-  data.tar.gz: 207655591aedb84b5cbf5b0e5a5c78e4d7239f3dd00d57978a46c227b3aca59cb52c89c99137adb46e0d7e50412785063b86579edc252b6428ded9c81e21333e
+  metadata.gz: 2e1105a5a609dd0a34a0bd1d14bae3f043ab6757e6fe4d0634ba03e3eb101238007da02aea099c892668bc0c5f93614074fbd1b82597730a1534f4595b00b59a
+  data.tar.gz: 775ff7eb0f7d5d61523e1b47eeb3da245ef4c27b5b9ed740f31d22d15d6550dd81caa2fd333a9d4a6e1aebef39cb2e88cc932206143532681de8081a8421af32

data/CHANGELOG.md

@@ -5,10 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-## [0.2.4] - 2026-04-06
+## [0.3.0] - 2026-07-24
+
+### Added
+
+- Publish an `event_recorded.close_encounters` notification whenever a status change is recorded (83ed88c)
+- CloseEncounters.record and pluggable response adapters (Adapters::NetHTTP) for tracking any HTTP client (d86e4e8)
+
+### Changed
 
-## [0.2.3] - 2025-09-08
+- Update dependencies (reissue 0.5.1, standard, sqlite3, puma, and others) and migrate the SimpleCov config to 1.0 (83ed88c)
+- Develop and release on Ruby 4.0.6; CI now tests on 3.4 and 4.0.6 (83ed88c)
+- Align the release workflow with reissue's shared workflow, adding checksum generation and a dry-run input (83ed88c)
+
+### Deprecated
+
+- CloseEncounters::Middleware, which tracked inbound requests; use CloseEncounters.record for outbound responses (d86e4e8)
 
 ### Fixed
 
-- Fix duplicate event creation in `scan` method when status and verification state are unchanged
+- The tracking middleware no longer breaks the request it observes, rebuilds its service map each request, and ignores services without a domain (83ed88c)
+- The newest-event lookup is now deterministic on timestamp ties and backed by a composite index (e94afe5)
+
+## [0.2.4] - 2026-04-06

data/README.md

@@ -15,33 +15,69 @@ Then when you have it installed and migrated you can start tracking events.
 
 ```ruby
 response = SomeThirdPartyService.call
-CloseEncounters.contact("SomeThirdPartyService", status: response.status.to_i, response.body)
+CloseEncounters.contact("SomeThirdPartyService", status: response.status.to_i, response: response.body)
 ```
 
-If the services regularly returns 200 responses, no new events will be recorded.
+If the service regularly returns 200 responses, no new events will be recorded.
 When it switches to a different status, a new event will be recorded.
 
 ```ruby
 CloseEncounters.status("SomeThirdPartyService") # => 200
-# evuntually you use `contact` and it records a 500 and you'll be able to get
+# eventually you use `contact` and it records a 500 and you'll be able to get
 CloseEncounters.status("SomeThirdPartyService") # => 500
 ```
 
-### Rack Middleware
+### Recording a response from any HTTP client
 
-Setup your middleware in your `config/application.rb` or `config/environments/production.rb`.
+`CloseEncounters.record` records a contact straight from an HTTP client's
+response object, using an *adapter* to read the status and body. This keeps the
+gem independent of any particular HTTP library.
 
 ```ruby
-config.middleware.use CloseEncounters::Middleware
+response = SomeThirdPartyService.call # a Net::HTTP response
+CloseEncounters.record("SomeThirdPartyService", response, adapter: CloseEncounters::Adapters::NetHTTP)
 ```
 
-This will automatically track responses from third-party services when you store a "domain" key in the
-`connection_info` in the ParticipantService records.
+Pass a `verifier` to record a verified scan instead of a plain contact:
 
-Alternatively, you can use the `auto_contact!` method to automatically turn on the rack middleware:
+```ruby
+CloseEncounters.record("SomeService", response, adapter: CloseEncounters::Adapters::NetHTTP, verifier: my_verifier)
+```
+
+An adapter is any object that responds to `status(response)` and
+`body(response)`, so supporting another client is a few lines:
+
+```ruby
+module FaradayAdapter
+  module_function
+  def status(response) = response.status
+  def body(response) = response.body
+end
+
+CloseEncounters.record("SomeApi", faraday_response, adapter: FaradayAdapter)
+```
+
+### Rack Middleware (deprecated)
+
+> **Deprecated.** `CloseEncounters::Middleware` keys on the *inbound* request
+> host (`SERVER_NAME`), so it tracks requests arriving at your app rather than
+> the outbound responses this gem is meant to monitor. Track responses with
+> `CloseEncounters.record` (above) instead. The middleware will be removed in a
+> future release.
+
+### Reacting to status changes
+
+Rather than polling `CloseEncounters.status`, you can subscribe to be notified
+whenever a new event is recorded (by either `contact` or `scan`). A
+notification is only published when an event is actually created — i.e. when
+the status or verification signature changes.
 
 ```ruby
-CloseEncounters.auto_contact!
+ActiveSupport::Notifications.subscribe("event_recorded.close_encounters") do |*args|
+  payload = ActiveSupport::Notifications::Event.new(*args).payload
+  # payload => { name:, service:, event:, status: }
+  AlertMailer.status_changed(payload[:name], payload[:status]).deliver_later
+end
 ```
 
 ### TODO
@@ -71,5 +107,7 @@ $ gem install close_encounters
 
 This project is managed with [Reissue](https://github.com/SOFware/reissue). Releases are automated via the [shared release workflow](https://github.com/SOFware/reissue/blob/main/.github/workflows/SHARED_WORKFLOW_README.md). Trigger a release by running the "Release gem to RubyGems.org" workflow from the Actions tab.
 
+Changelog entries come from git trailers (`Added:`, `Fixed:`, …) on your commits and/or hand-edits to the `## [Unreleased]` section of `CHANGELOG.md`; Reissue merges both. See [CONTRIBUTING.md](CONTRIBUTING.md#changelog-entries).
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -20,6 +20,7 @@ require "reissue/gem"
 
 Reissue::Task.create :reissue do |task|
   task.version_file = "lib/close_encounters/version.rb"
+  task.fragment = :git  # Use git trailers for changelog entries
   task.push_finalize = :branch
 end
 

data/app/models/close_encounters/participant_event.rb

@@ -5,7 +5,9 @@ module CloseEncounters
       class_name: "CloseEncounters::ParticipantService",
       foreign_key: "close_encounters_participant_service_id"
 
-    scope :newest, -> { order(created_at: :desc).limit(1) }
+    # id breaks ties so "newest" is deterministic when two events share a
+    # created_at (common under bulk inserts and sub-second traffic).
+    scope :newest, -> { order(created_at: :desc, id: :desc).limit(1) }
 
     unless ActiveRecord::Base.connection.adapter_name.downcase.include?("postgresql")
       serialize :metadata, coder: JSON

data/db/migrate/20260724000001_add_service_created_at_index_to_participant_events.rb

@@ -0,0 +1,18 @@
+class AddServiceCreatedAtIndexToParticipantEvents < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  def change
+    options = if self.class.adapter_name.match?(/postgres/i)
+      {algorithm: :concurrently}
+    else
+      {}
+    end
+
+    # Supports the hot "newest event for a service" lookup:
+    # WHERE close_encounters_participant_service_id = ? ORDER BY created_at DESC.
+    add_index :close_encounters_participant_events,
+      [:close_encounters_participant_service_id, :created_at],
+      name: "idx_ce_events_on_service_and_created_at",
+      **options
+  end
+end

data/lib/close_encounters/adapters/net_http.rb

@@ -0,0 +1,14 @@
+module CloseEncounters
+  module Adapters
+    # Adapter for Net::HTTP responses. An adapter is any object responding to
+    # #status(response) and #body(response); see CloseEncounters.record.
+    module NetHTTP
+      module_function
+
+      # Net::HTTP exposes the status as a String (e.g. "200").
+      def status(response) = response.code.to_i
+
+      def body(response) = response.body
+    end
+  end
+end

data/lib/close_encounters/engine.rb

@@ -7,6 +7,10 @@ module CloseEncounters
       g.test_framework :minitest, spec: true
     end
 
+    initializer "close_encounters.deprecator" do |app|
+      app.deprecators[:close_encounters] = CloseEncounters.deprecator if app.respond_to?(:deprecators)
+    end
+
     initializer "close_encounters.middleware" do |app|
       app.middleware.use CloseEncounters::Middleware if CloseEncounters.auto_contact?
     end

data/lib/close_encounters/middleware.rb

@@ -1,6 +1,12 @@
 module CloseEncounters
   class Middleware
     def initialize(app, tracker: CloseEncounters)
+      CloseEncounters.deprecator.warn(
+        "CloseEncounters::Middleware tracks inbound requests by host, not the " \
+        "outbound responses this gem is meant to monitor. Track a service's " \
+        "response with CloseEncounters.record(name, response, adapter:) instead. " \
+        "The middleware will be removed in a future release."
+      )
       @app = app
       @tracker = tracker
     end
@@ -19,13 +25,20 @@ module CloseEncounters
       if (name = participant_services[host])
         @tracker.contact(name, status:, response:)
       end
+    rescue => e
+      # Tracking must never break the request it is observing.
+      Rails.logger&.error("[CloseEncounters] middleware tracking failed: #{e.class}: #{e.message}")
+      nil
     end
 
+    # Built per request rather than memoized: the middleware is instantiated
+    # once per process, so caching here would never reflect services added or
+    # changed after boot.
     def participant_services
-      @participant_services ||= CloseEncounters::ParticipantService.all
-        .map do |service|
-          [service.connection_info["domain"], service.name]
-        end.to_h
+      CloseEncounters::ParticipantService.all.each_with_object({}) do |service, map|
+        domain = service.connection_info&.[]("domain")
+        map[domain] = service.name if domain
+      end
     end
   end
 end

data/lib/close_encounters/version.rb

@@ -1,3 +1,3 @@
 module CloseEncounters
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/lib/close_encounters.rb

@@ -7,6 +7,10 @@ module CloseEncounters
   autoload :ParticipantService, "close_encounters/participant_service"
   autoload :ParticipantEvent, "close_encounters/participant_event"
 
+  module Adapters
+    autoload :NetHTTP, "close_encounters/adapters/net_http"
+  end
+
   class Configuration
     attr_accessor :auto_contact, :verify_scan_statuses
 
@@ -20,6 +24,12 @@ module CloseEncounters
     @configuration ||= Configuration.new
   end
 
+  # Deprecator for CloseEncounters. Registered with the host app in the engine
+  # so warnings flow through the app's configured deprecation behavior.
+  def self.deprecator
+    @deprecator ||= ActiveSupport::Deprecation.new("a future release", "CloseEncounters")
+  end
+
   def self.configure
     yield(configuration)
   end
@@ -33,14 +43,59 @@ module CloseEncounters
     service = ParticipantService.find_by!(name:)
     status = status.to_i # Ensure status is always an integer
 
+    created = nil
     # Use a transaction with a lock to prevent race conditions
     service.with_lock do
       unless service.events.newest.pick(:status) == status
-        service.events.create!(status: status, response:)
+        created = service.events.create!(status: status, response:)
       end
     end
+
+    # Instrument after the transaction commits so subscribers see a persisted event.
+    instrument(name, created) if created
+    created
+  end
+
+  # Record the outcome of an HTTP request to a service straight from the
+  # client's response object, using an adapter to read the status and body.
+  #
+  # An adapter is any object responding to #status(response) and
+  # #body(response); CloseEncounters::Adapters::NetHTTP ships for Net::HTTP.
+  # Delegates to #scan when a verifier is given, otherwise #contact.
+  #
+  #   CloseEncounters.record("SomeService", response, adapter: Adapters::NetHTTP)
+  #   CloseEncounters.record("SomeService", response, adapter: Adapters::NetHTTP, verifier: my_verifier)
+  #
+  # @param name [String] the name of the service
+  # @param response [Object] the HTTP client's response object
+  # @param adapter [#status, #body] reads the status and body from the response
+  # @param verifier [#call, #to_s, nil] when given, records a verified scan
+  def record(name, response, adapter:, verifier: nil)
+    status = adapter.status(response)
+    body = adapter.body(response)
+    if verifier
+      scan(name, status:, response: body, verifier:)
+    else
+      contact(name, status:, response: body)
+    end
   end
 
+  # Publish an ActiveSupport::Notifications event whenever a new
+  # ParticipantEvent is recorded, so consumers can react to status changes
+  # instead of polling. Subscribe with:
+  #
+  #   ActiveSupport::Notifications.subscribe("event_recorded.close_encounters") do |*args|
+  #     payload = ActiveSupport::Notifications::Event.new(*args).payload
+  #     # payload => { name:, service:, event:, status: }
+  #   end
+  def instrument(name, event)
+    ActiveSupport::Notifications.instrument(
+      "event_recorded.close_encounters",
+      name:, service: event.participant_service, event:, status: event.status
+    )
+  end
+  private_class_method :instrument
+
   VERIFIED_SIGNATURE = "ok"
   UNVERIFIED_SIGNATURE = "unverified"
 
@@ -69,6 +124,7 @@ module CloseEncounters
     service = ParticipantService.find_by!(name:)
     status = status.to_i # Ensure status is always an integer
 
+    created = nil
     service.with_lock do
       last_event = service.events.newest.first
       last_status = last_event&.status
@@ -80,11 +136,14 @@ module CloseEncounters
       metadata = {verified:, signature:, verification: verifier.to_s}
 
       if last_status != status
-        service.events.create!(status:, response:, metadata:)
+        created = service.events.create!(status:, response:, metadata:)
       elsif verify_scan_statuses.include?(status) && last_signature != signature
-        service.events.create!(status:, response:, metadata:)
+        created = service.events.create!(status:, response:, metadata:)
       end
     end
+
+    instrument(name, created) if created
+    created
   end
 
   # Normalize a verifier return value into a stable signature string.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: close_encounters
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Jim Gay
@@ -116,7 +116,9 @@ files:
 - db/migrate/20240430173725_create_close_encounters_participant_events.rb
 - db/migrate/20240508190642_add_close_ecounters_indexes.rb
 - db/migrate/20250225232551_add_metadata_to_close_encounters_participant_events.rb
+- db/migrate/20260724000001_add_service_created_at_index_to_participant_events.rb
 - lib/close_encounters.rb
+- lib/close_encounters/adapters/net_http.rb
 - lib/close_encounters/engine.rb
 - lib/close_encounters/middleware.rb
 - lib/close_encounters/version.rb
@@ -142,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Close Encounters of the Third Party
 test_files: []