logister-ruby 0.4.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff89324842289ec0925e84131ee9442d4dfed5589b86deb1bb56498e55eb5977
-  data.tar.gz: f262d7ab245a8c5703fb28873e65d4ee11194be7146833f656fd74d85434f2ff
+  metadata.gz: 381dffab29b34b6beffe54e105fcf8dc5151f59bde1e44cfbba1749d21bff763
+  data.tar.gz: 5fe2ef7923ebeb4aa440d4aff35b246b2d407da0fe11dd26e26633e491105657
 SHA512:
-  metadata.gz: 28a1b3621688f111349b37c9996d530855d07081c17ce4525e33426b2ff30f1c714f8871555925dd7c11ec78ff09ad0566295552c54d05d141c28b944fe2f383
-  data.tar.gz: c262d8b152f55680dc7ad02d19733089b59415f4a853cf33d5e8ffcade2851a69d4ada2963a7e05e4af8ca758e08340288213ea5e90da68d68c1b6baaf768108
+  metadata.gz: a5380bdc6bc4c7b4c1e4cb9e2c0d9d4cc4825f87d3517b57c22db7e63fff519071e46e9ad3555d3035819f4e1a64819d26305a1646f18cb32c02977cff925da2
+  data.tar.gz: b3d7c3a5932f560be7ec3b1dc1a88a2319799e2b166e91d8a6d6084e8d6d7eaf262c047c5d7f9ba3e095d44dc857d1ed701605ced120a2253a168d3568cc5687

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v0.4.2 - 2026-09-16
+
+- Added process-local delivery counters and an optional recursion-safe observer for queued, acknowledged, unconfirmed, queue-full, and retry outcomes without exporting event contents.
+- Clarified that a drained queue or successful `flush` does not prove every event was acknowledged; timed-out requests may already have reached the server.
+- Removed exception messages from terminal event-publish warnings to avoid exposing transport details.
+- Bounded async shutdown even when the queue is full; retained the worker until it finishes and report incomplete shutdown honestly.
+
+## v0.4.1 - 2026-09-11
+
+- Constrained JSON to the compatible 2.x line while supported ActiveSupport 8 releases use positional JSON.parse options; verified real Rails request decoding.
+- Restored explicit publication dispatch and immutable-tag recovery after successful current-main CI. Weekly dependency checks cannot publish releases.
+
 ## v0.4.0 - 2026-08-08
 
 - Added stable UUID assignment before synchronous or asynchronous delivery so retries preserve one logical event identity.

data/README.md

@@ -162,6 +162,24 @@ safe against a Logister server that supports the batch endpoint. Older servers a
 detected automatically and receive the same stable events through the single-event
 endpoint. Call `Logister.flush` before a short-lived process exits.
 
+### Delivery outcomes
+
+`flush` waits for queued and in-flight attempts to finish; it does not guarantee
+server acknowledgement. Inspect `Logister.delivery_stats` for process-local
+`queued_events`, `acknowledged_events`, `unconfirmed_events`, `queue_full_events`,
+`retry_attempts`, and `pending_events`. An unconfirmed event may already have
+reached the server when its response timed out. Counts are not durable and reset
+with the client/process; they cover events, not deployment reports.
+
+For local delivery diagnostics, set `config.delivery_observer` to a fast callback
+accepting `{ outcome:, count:, reason: }`. It receives no payload, identifiers,
+credentials, or exception messages. Reporting is suppressed inside the callback
+to prevent feedback loops; callback failure cannot change delivery. Write these
+diagnostics to a local log or counter rather than publishing them through Logister.
+`shutdown` waits at most one second for the worker and returns false if attempts
+are still running. It stops accepting asynchronous events and does not kill an
+in-flight request or block while adding a sentinel to a full queue.
+
 Every HTTP attempt applies `timeout_seconds` to connect, read, and write operations.
 Retryable responses honor `Retry-After` when present, cap any individual wait at
 `max_retry_delay`, and add bounded positive jitter controlled by `retry_jitter`.
@@ -427,3 +445,22 @@ Verify both release surfaces before calling a release complete:
 curl -fsSL https://rubygems.org/api/v2/rubygems/logister-ruby/versions/X.Y.Z.json | jq '{number,ruby_version,sha}'
 gh release view vX.Y.Z
 ```
+
+
+### Coordinated release preparation
+
+For a coordinated ecosystem release, keep the version-changing PR unmerged until
+the final agreed Rails PR has been published and its deployment verified. Recheck
+the upstream contract/workflow pin against that final backend commit before merge.
+Successful source CI, a tag, or a release-impact dispatch alone is not backend readiness.
+After independent review, merging the new version runs CI, creates an immutable tag,
+and explicitly dispatches publication. A tag without a package remains incomplete.
+
+To recover an existing reviewed tag, dispatch the publisher workflow from `main`
+with `-f tag=vX.Y.Z` (Python uses `publish.yml`; other SDKs use `release.yml`). The
+workflow checks out that exact tag, proves it belongs to main, and verifies public
+package identity before creating the GitHub Release. Never move a consumed tag.
+
+Weekly CI audits/tests current dependencies and cannot trigger automatic publication.
+Dependabot groups compatible minor/patch updates; major toolchain migrations keep
+separate PRs. Pin Actions to full commits and retain supported runtime floors.

data/lib/logister/client.rb

@@ -32,9 +32,13 @@ module Logister
       @queue         = SizedQueue.new(@configuration.queue_size)
       @worker        = nil
       @running       = false
+      @stopping      = false
       @pending_mutex = Mutex.new
       @pending_condition = ConditionVariable.new
       @pending_count = 0
+      @delivery_mutex = Mutex.new
+      @delivery_counts = { queued_events: 0, acknowledged_events: 0, unconfirmed_events: 0,
+                           queue_full_events: 0, retry_attempts: 0 }
 
       # Cache values that are static for the lifetime of this client so we
       # don't allocate on every send_request call.
@@ -48,6 +52,7 @@ module Logister
     end
 
     def publish(payload)
+      return false if ReportingScope.suppressed?
       return false unless ready?
 
       payload = with_stable_uuid(payload)
@@ -83,25 +88,40 @@ module Logister
     def shutdown
       return true unless @configuration.async
 
-      @running = false
-      begin
-        @queue.push(nil)
-      rescue StandardError
-        nil
+      worker = @worker_mutex.synchronize do
+        @stopping = true
+        begin
+          @queue.push(nil, true)
+        rescue ThreadError
+          # A full queue will be drained by the worker, which also checks the
+          # stopping flag. Never block the caller waiting to enqueue a sentinel.
+        end
+        @worker
       end
-      @worker&.join(1)
-      @worker = nil
-      true
+      worker&.join(1)
+      !worker&.alive?
+    end
+
+    # Process-local counters, never an assertion of exactly-once server receipt.
+    def delivery_stats
+      @delivery_mutex.synchronize { @delivery_counts.dup }
+        .merge(pending_events: @pending_mutex.synchronize { @pending_count })
     end
 
     private
 
     def enqueue(payload)
-      increment_pending
-      @queue.push(payload, true)
+      @worker_mutex.synchronize do
+        return false if @stopping
+
+        increment_pending
+        @queue.push(payload, true)
+      end
+      record_delivery(:queued_events, 1)
       true
     rescue ThreadError
       complete_pending(1)
+      record_delivery(:queue_full_events, 1, reason: 'queue_full')
       @configuration.logger.warn('logister queue full; dropping event')
       false
     end
@@ -111,6 +131,7 @@ module Logister
       return if @running && @worker&.alive?
 
       @worker_mutex.synchronize do
+        return if @stopping
         return if @running && @worker&.alive?
 
         @running = true
@@ -144,7 +165,7 @@ module Logister
 
         publish_batch_sync(batch)
         complete_pending(batch.length)
-        break if stop_after_batch
+        break if stop_after_batch || (@stopping && @queue.empty?)
       end
     rescue StandardError => e
       @configuration.logger.warn("logister worker crashed: #{e.class} #{e.message}")
@@ -158,14 +179,22 @@ module Logister
       attempts = 0
       begin
         attempts += 1
-        send_request(payload)
+        delivered = send_request(payload)
+        unless delivered
+          record_delivery(:unconfirmed_events, 1, reason: 'no_acknowledgment')
+          return false
+        end
+        record_delivery(:acknowledged_events, 1)
+        true
       rescue StandardError => e
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, 1, reason: failure_reason(e))
+        @configuration.logger.warn("logister publish failed: #{e.class}")
         false
       end
     end
@@ -174,7 +203,13 @@ module Logister
       attempts = 0
       begin
         attempts += 1
-        send_batch_request(payloads)
+        delivered = send_batch_request(payloads)
+        unless delivered
+          record_delivery(:unconfirmed_events, payloads.length, reason: 'no_acknowledgment')
+          return false
+        end
+        record_delivery(:acknowledged_events, payloads.length)
+        true
       rescue UnsupportedBatchEndpoint
         payloads.map { |payload| publish_sync(payload) }.all?
       rescue RequestError => e
@@ -185,19 +220,23 @@ module Logister
           return first_half_delivered && second_half_delivered
         end
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister batch publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
+        @configuration.logger.warn("logister batch publish failed: #{e.class}")
         false
       rescue StandardError => e
         if attempts <= @configuration.max_retries && retryable_error?(e)
+          record_delivery(:retry_attempts, 1, reason: failure_reason(e))
           sleep(retry_delay(e, attempts))
           retry
         end
 
-        @configuration.logger.warn("logister batch publish failed: #{e.class} #{e.message}")
+        record_delivery(:unconfirmed_events, payloads.length, reason: failure_reason(e))
+        @configuration.logger.warn("logister batch publish failed: #{e.class}")
         false
       end
     end
@@ -290,6 +329,26 @@ module Logister
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def failure_reason(error)
+      return "http_#{error.status}" if error.is_a?(RequestError)
+      return 'timeout' if error.is_a?(Timeout::Error)
+
+      'transport_error'
+    end
+
+    def record_delivery(counter, count, reason: nil)
+      @delivery_mutex.synchronize { @delivery_counts[counter] += count }
+      observer = @configuration.delivery_observer
+      return unless observer
+
+      ReportingScope.suppress do
+        observer.call({ outcome: counter.to_s, count: count, reason: reason }.compact.freeze)
+      end
+    rescue StandardError
+      # Counters survive observer failure; never report this through telemetry.
+      nil
+    end
+
     def with_stable_uuid(payload)
       attributes = payload.to_h.dup
       key = attributes.keys.any? { |candidate| candidate.is_a?(String) } ? 'uuid' : :uuid

data/lib/logister/configuration.rb

@@ -10,7 +10,7 @@ module Logister
                   :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate,
                   :feature_flags_resolver, :dependency_resolver, :anonymize_ip,
                   :max_breadcrumbs, :max_dependencies, :capture_request_spans,
-                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms
+                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms, :delivery_observer
     attr_writer :deployment_endpoint, :batch_endpoint
 
     def initialize
@@ -32,6 +32,7 @@ module Logister
       @ignore_environments = []
       @ignore_paths = []
       @before_notify = nil
+      @delivery_observer = nil
 
       @async = true
       @queue_size = 1000

data/lib/logister/reporter.rb

@@ -298,6 +298,10 @@ module Logister
       @client.flush(timeout: timeout)
     end
 
+    def delivery_stats
+      @client.delivery_stats
+    end
+
     def shutdown
       @client.shutdown
     end

data/lib/logister/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Logister
-  VERSION = '0.4.0'
+  VERSION = '0.4.2'
 end

data/lib/logister.rb

@@ -64,6 +64,10 @@ module Logister
       reporter.flush(timeout: timeout)
     end
 
+    def delivery_stats
+      reporter.delivery_stats
+    end
+
     def shutdown
       reporter.shutdown
     end

data/logister-ruby.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_dependency 'activesupport', '>= 8.0.5', '< 9'
+  # ActiveSupport 8 passes JSON.parse options positionally; JSON 3 removed that API.
+  spec.add_dependency 'json', '>= 2', '< 3'
   spec.add_development_dependency 'actionpack', '>= 8.0.5', '< 9'
   spec.add_development_dependency 'rake', '>= 13.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: logister-ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Logister
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -29,6 +29,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '9'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement