close_encounters 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67adeb4fe53671ebcc9e37f040245dd7650ec3afc83433e13415c290617ee356
-  data.tar.gz: e7afee308898aa7a25cf3ddfaa652369c74fdb074c014054ee37438babe0b714
+  metadata.gz: 153aff29d52784d224dc23d3cb5606fe7a1478c2522bff75dc80678d236f3a47
+  data.tar.gz: c2de654d365fe8ec5330b2254b45a56029e75895a808c90fc261d9e0aae333b2
 SHA512:
-  metadata.gz: e0131dcd0a979e6bf3583fe3b90c91b597defbf0f660b8bfaaf2f8d2988a3b1714177148a6cec10078f1a69b8175de7c27d6bccc29523001264ca8c6f667e381
-  data.tar.gz: 117c8347983b35986897f55920c4d8472be867598901ca2e83bbf51f2560f083e8c6b9e27559f67c327faa66cbde30b93c1cdb19abd1e9356e792411992ff385
+  metadata.gz: 2e1105a5a609dd0a34a0bd1d14bae3f043ab6757e6fe4d0634ba03e3eb101238007da02aea099c892668bc0c5f93614074fbd1b82597730a1534f4595b00b59a
+  data.tar.gz: 775ff7eb0f7d5d61523e1b47eeb3da245ef4c27b5b9ed740f31d22d15d6550dd81caa2fd333a9d4a6e1aebef39cb2e88cc932206143532681de8081a8421af32

data/CHANGELOG.md

@@ -5,18 +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.3] - 2025-09-08
+## [0.3.0] - 2026-07-24
 
-### Fixed
-
-- Fix duplicate event creation in `scan` method when status and verification state are unchanged
+### Added
 
-## [0.2.2] - 2025-09-04
+- 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
 
-- Update handling of the same status for multiple requests when creating events.
+- 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
 
-- Ensure that status is an integer when creating events and comparing results.
+- 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
@@ -67,5 +103,11 @@ Or install it yourself as:
 $ gem install close_encounters
 ```
 
+## Releasing
+
+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,8 @@ 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
 
 require "standard/rake"

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.3"
+  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,48 +43,125 @@ 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"
+
   # Record a verification of a contact with a third party service where the
   # verification is a callable which must also respond to to_s.
   #
+  # The verifier may return:
+  #   * true / :ok           — response is verified
+  #   * false / nil          — response failed verification (generic)
+  #   * any other value      — failed verification with a distinguishing
+  #                            "signature" (e.g. "missing:user.email").
+  #                            Stable signatures let scan suppress repeated
+  #                            identical failures while still recording when
+  #                            the failure mode changes meaningfully.
+  #
   # Creates a new event if:
-  # 1. The status has changed from the last recorded status
-  # 2. OR the status is in the verify_scan list AND verification fails
+  # 1. The status has changed from the last recorded status, OR
+  # 2. The status is in the verify_scan list AND the verification signature
+  #    differs from the last recorded signature.
   #
   # @param name [String] the name of the service
   # @param status [Integer] the HTTP status of the contact
   # @param response [String] the response object
-  # @param verifier [Proc] the verification callable which must also respond to to_s
+  # @param verifier [#call, #to_s] the verification callable
   def scan(name, status:, response:, verifier:)
     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
-      last_verified = last_event&.verified?
 
-      # Calculate current verification result
-      verified = verifier.call(response)
+      signature = signature_for(verifier.call(response))
+      verified = (signature == VERIFIED_SIGNATURE)
+      last_signature = signature_for_event(last_event)
+
+      metadata = {verified:, signature:, verification: verifier.to_s}
 
-      # Create a new event if:
-      # 1. Status has changed OR
-      # 2. Status is in verify_scan_statuses AND verified flag has changed
       if last_status != status
-        # Status changed, always create new event
-        service.events.create!(status:, response:, metadata: {verified:, verification: verifier.to_s})
-      elsif verify_scan_statuses.include?(status) && last_verified != verified
-        # Status same but verification result changed for a monitored status
-        service.events.create!(status:, response:, metadata: {verified:, verification: verifier.to_s})
+        created = service.events.create!(status:, response:, metadata:)
+      elsif verify_scan_statuses.include?(status) && last_signature != signature
+        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.
+  def signature_for(result)
+    case result
+    when true, :ok then VERIFIED_SIGNATURE
+    when false, nil then UNVERIFIED_SIGNATURE
+    else result.to_s
+    end
+  end
+
+  # Read the signature off a previously stored event, falling back to the
+  # legacy verified flag for events created before signatures existed.
+  def signature_for_event(event)
+    return nil unless event
+    stored = event.metadata.to_h["signature"]
+    return stored if stored
+    event.verified? ? VERIFIED_SIGNATURE : UNVERIFIED_SIGNATURE
   end
   alias_method :verify, :scan
   module_function :verify

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: close_encounters
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  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.6.7
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Close Encounters of the Third Party
 test_files: []