pug-sh 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 893420d16827c4d7472d599fde6fc5278e354cc559ffcd217b5ff34151c0d5c5
+  data.tar.gz: d9f76d529e9e0fda1fc678a6096cc9922076e84e0a7c53515e5c6ec98eee4eed
+SHA512:
+  metadata.gz: 9194a40e3a2eb238d5dce9f1db3803ca4fd103a0ae366ef27d8dfd266f93fff923fba12afbbce82796af440175a0563bc39495b4e12e007fe32bb7fbb3fb3540
+  data.tar.gz: 4db8dc628a8f10582f53eae2242bd6e35c8e1511669cf643e81b1c095615353fcbbc58ca362e058cbbe72bd81eb4f35b886d34cb88c0c8209688f4764b6a7d7f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pug
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,247 @@
+<p align="center">
+  <img src="https://app.pug.sh/logo.svg" alt="Pug" width="120" height="120" />
+</p>
+
+# pug-sh
+
+Pug server-side SDK for Ruby — event tracking, profile identify, and analytics reads.
+
+It is instance-based and authenticates with a **private** project API key (`prv_…`). Ingestion
+never raises, so a tracking call can't take down your request path.
+
+## Install
+
+```ruby
+# Gemfile
+gem "pug-sh"
+```
+
+Requires Ruby 3.3 or newer.
+
+## Quick start
+
+```ruby
+require "pug"
+
+pug = Pug::Client.new(api_key: ENV.fetch("PUG_API_KEY"))
+
+# Track an event. distinct_id (who the event is for) comes first — a server has no ambient user.
+pug.track("user_42", "order.completed", amount: 49.0, currency: "USD")
+
+# Well-known events get their properties type-checked and validated against the event's schema.
+pug.track("user_42", "feature_used", feature_id: "export")
+
+# Identify a profile (never raises — failures are logged).
+pug.identify("user_42", email: "ada@example.com", plan: "pro")
+
+# Reads raise Pug::Error.
+profile = pug.profiles.get_by_external_id("user_42")
+pug.profiles.list.each { |p| puts p.external_id }
+trend = pug.insights.query(
+  spec: { insight_type: :INSIGHT_TYPE_TRENDS, events: [{ event: { kind: "order.completed" } }] },
+  time_range: { from: Time.now - (30 * 86_400), to: Time.now },
+  granularity: :GRANULARITY_DAY,
+)
+
+# Drain on shutdown so no buffered events are lost.
+pug.close
+```
+
+## Behaviour
+
+- **Ingestion never raises.** `track` and `identify` validate input client-side and log and drop
+  anything invalid. `track` is non-blocking: a background thread sends events in batches, by size
+  (`max_size`) or interval (`max_wait`).
+- **Delivery is best-effort with retry.** A transient send failure keeps events queued and retries
+  `max_wait` after the failure, but no sooner than a second; a permanent one (a fixed set of
+  client-error Connect codes, plus any non-transport error) dead-letters them via `on_error`.
+  `close` drains and reports anything still undelivered through `on_error` and the log.
+  `on_error` covers buffered `track` events only — `identify` failures are logged, and so are
+  events the server drops from a batch it accepts (`BatchCreateResponse.dropped`), at WARN.
+- **Reads are request/response and do raise** `Pug::Error` — they run in your control flow, so
+  you own retry. They are not auto-retried.
+- **Well-known events** have typed, validated properties; any other `kind` is accepted as a
+  custom event with loose properties.
+- **Thread- and fork-safe.** One client can be shared by every thread. A client created before a
+  fork (Puma, Unicorn, Sidekiq) starts empty in each child, with its own sender thread and
+  connections; events buffered in the parent stay with the parent.
+
+## API
+
+### `Pug::Client.new(**options)`
+
+| Option     | Type          | Default                     | Description                                                                                                                       |
+| ---------- | ------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `api_key`  | `String`      | —                           | **Required.** Private project key (`prv_…`).                                                                                      |
+| `endpoint` | `String`      | hosted endpoint             | Pug server origin.                                                                                                                |
+| `batch`    | `Hash`        | see below                   | Ingestion buffer: `max_size` (100, capped at 1000), `max_wait` (5 seconds), `max_queue_size` (10,000).                            |
+| `on_error` | callable      | none                        | Dead-letter hook for undeliverable buffered `track` events, called with `(error, events)`.                                        |
+| `logger`   | `Logger`-like | `Logger.new($stderr)`, WARN | Gets the SDK's warnings and errors: anything with public `warn` and `error`, such as `Rails.logger` (wrap an IO in `Logger.new`). |
+| `timeout`  | `Numeric`     | 10                          | Request timeout, in seconds.                                                                                                      |
+
+```ruby
+Pug::Client.new(
+  api_key: ENV.fetch("PUG_API_KEY"),
+  batch: { max_size: 100, max_wait: 5, max_queue_size: 10_000 },
+  on_error: lambda do |error, events|
+    # dead-letter sink: error is a Pug::QueueOverflowError, a Pug::ClosedError, a Pug::Error
+    # with a permanent Connect code, the transient Pug::Error that failed close's last attempt,
+    # or the exception a bug raised
+  end,
+)
+```
+
+`on_error` runs on the background sender thread; on the thread calling `close`, for what it
+reports undelivered; or, when the queue overflows, on the thread that called `track`. It must be
+thread-safe and return promptly. Called from inside it on the sender or the closing thread, `flush`
+and `close` don't wait for what is waiting on `on_error`: they return `false` at once, except that
+`flush` returns `true` while `close` reports. On the overflow path nothing waits on `on_error`, so
+they behave as anywhere else, blocking the thread that called `track`.
+
+### Ingestion (never raises)
+
+- `pug.track(distinct_id, kind, properties = nil, options = nil)` — enqueue an event. Non-blocking.
+- `pug.identify(external_id, traits = nil, options = nil)` — create or update a profile. Blocks
+  until the server answers.
+- `pug.flush(timeout: nil)` — send the currently buffered events now and wait for that attempt.
+  Returns `false` if `timeout` (seconds) passed first. `true` means the attempt finished, not that
+  every event was delivered: a transient failure keeps them queued for a retry.
+- `pug.close(timeout: nil)` — drain and shut down; call on graceful exit so nothing buffered is lost.
+  Returns `false` if `timeout` passed first. Either way, by the time it returns every event it
+  couldn't send has gone to `on_error` and the log, including a batch still being sent when the
+  timeout ran out, which may yet arrive.
+
+A `timeout` that isn't a number waits without one, with a warning.
+
+`distinct_id` and `external_id` are non-empty Strings, or Integers such as a record's id, sent as
+their decimal string; `session_id`, `anonymous_id` and `device_id` must be Strings. Properties go
+in a Hash, braces optional, and options follow as keywords. Without braces, a key named after an
+option sets that option, so a property with an option's name needs the braces:
+
+```ruby
+pug.track("user_42", "signup", plan: "pro")
+pug.track("user_42", "signup", plan: "pro", timestamp: Time.now - 3600)
+pug.track("user_42", "signup", { plan: "pro", location: "landing" }, location: { country: "DE" })
+```
+
+`track` options: `timestamp` (a `Time`; defaults to now), `session_id` (a UUID overriding the
+client's per-instance session), `location` (the visitor's location — see below).
+`identify` options, which work the same way with traits: `anonymous_id` (must start with `anon-`;
+triggers anon→identified merge), `device_id`. Traits must be JSON-serializable, with nested values
+mapped as for properties below; they travel as a protobuf `Struct`, whose numbers are doubles, so
+an integer past 2^53 is refused.
+
+Custom properties map by Ruby type:
+
+| Ruby value                                       | Sent as                                   |
+| ------------------------------------------------ | ----------------------------------------- |
+| `String`, `Symbol`                               | string                                    |
+| `true`, `false`                                  | bool                                      |
+| `Integer`                                        | int (outside the int64 range: dropped)    |
+| `Float`, `BigDecimal`, `Rational`                | double (NaN and ±Infinity: dropped)       |
+| `Time`, `DateTime`, `Google::Protobuf::Timestamp`| timestamp                                 |
+| `Date`                                           | ISO 8601 date string, e.g. `"2026-10-10"` |
+| `Google::Protobuf::Duration`                     | duration string, e.g. `"1.5s"`            |
+| `Hash`, `Array`                                  | JSON string                               |
+| `nil`                                            | omitted                                   |
+
+Anything else is dropped with a warning. Inside a `Hash` or `Array`, a `Time`, `DateTime` or `Date`
+becomes an ISO 8601 string and a `BigDecimal` or `Rational` a number, while a value JSON has no
+form for, such as a `Set`, drops the whole property with a warning. Strings are capped at 1024
+bytes (truncated with a warning), and invalid UTF-8 is repaired.
+
+### Well-known events
+
+For a well-known kind such as `purchase`, properties are checked against the event's schema.
+Keys may be the field's name (`product_id`) or its JSON name (`productId`); either way the
+property is sent under the JSON name, like every other Pug SDK. A field's type comes from the
+schema rather than the Ruby value, so `amount: 10` is sent as a double. A value of the wrong type,
+or one failing the schema's rules, drops the event with an error; other keys ride along as custom
+properties.
+
+```ruby
+pug.track("user_42", "purchase", product_id: "p1", amount: 49, currency: "USD", coupon: "FALL")
+pug.track("user_42", "video_play", video_id: "v1", position: 92.5) # a Duration field, in seconds
+```
+
+Duration fields take seconds as a number, `{ seconds:, nanos: }`, or a `Google::Protobuf::Duration`.
+
+### Location
+
+Pug only derives geo from CDN headers on browser (public-key) requests. This SDK uses a private
+key, so the server adds no geo of its own — without `location`, an event has no geo at all:
+
+```ruby
+pug.track("user_42", "checkout_completed", { plan: "pro" }, location: { country: "DE", city: "Berlin" })
+```
+
+Fields: `continent`, `country`, `region`, `city`, `postal_code`, `metro_code`, `timezone`,
+`latitude`, `longitude` — strings, except the two coordinates. `country` must be an ISO 3166-1
+alpha-2 code (case and surrounding spaces are normalized); `latitude` and `longitude` are only
+sent as a pair.
+
+A field that is missing, nil or empty is omitted silently. One that looks like a mistake —
+unknown key, wrong type, unknown country, coordinate out of range — is dropped with a warning and
+the rest is still sent. If nothing is usable the event goes out with no geo.
+
+### Reads (raise `Pug::Error`)
+
+These run in your control flow:
+
+- `pug.profiles` — `get(id, include_bots: false)`, `get_by_external_id(external_id, include_bots: false)`,
+  `delete(id)`, `list(request = nil, timeout: nil)` (auto-paginating: yields each profile to a
+  block, or returns an `Enumerator`). The timeout bounds the whole stream, the time your block
+  takes included, so `timeout:` (seconds) can give one long `list` more than the client's.
+- `pug.activity` — `feed`, `event_explorer`, `heatmap`, `profile_sessions`, `profile_stats`,
+  `filter_schema`, `property_values`.
+- `pug.insights` — `query`, `segment_users`, `filter_schema`, `property_values`.
+
+Requests are a Hash or the generated request message, and responses are the generated messages,
+under `Pug::Proto` (`Pug::Proto::Shared::Insights::V1::QueryResponse`, …); call `to_h` on one
+for plain Ruby data.
+
+```ruby
+sessions = pug.activity.profile_sessions(distinct_id: "user_42", page_size: 50)
+sessions.sessions.each { |s| puts s.session_id }
+```
+
+Reads leave out traffic tagged as a bot at ingest unless you ask for it: pass
+`include_bots: true` to `profiles.get` and `get_by_external_id`, set it on the request of
+`profiles.list` or of an `activity` read other than `filter_schema` and `property_values`, or set
+it on the `spec` of `insights.query`. The other requests have no such field.
+
+`Pug::Error#code` is the Connect code as a Symbol (`:not_found`, `:unavailable`, …), or `nil`
+when the failure didn't come from the RPC layer; `cause` is the underlying exception. The SDK
+doesn't follow redirects, so one is `:unimplemented`, like a wrong path: point `endpoint` at the
+final URL.
+
+```ruby
+begin
+  pug.profiles.get("p_123")
+rescue Pug::Error => e
+  raise unless e.code == :not_found
+end
+```
+
+## Rails
+
+```ruby
+# config/initializers/pug.rb
+unless ENV["SECRET_KEY_BASE_DUMMY"]
+  PUG = Pug::Client.new(api_key: Rails.application.credentials.pug_api_key, logger: Rails.logger)
+  at_exit { PUG.close(timeout: 5) }
+end
+```
+
+`Pug::Client.new` raises without an API key, so the guard skips it during the `assets:precompile`
+step of Rails' generated Dockerfile, which boots the app with `SECRET_KEY_BASE_DUMMY=1` and no
+credentials. The client is safe to create before Puma or Unicorn fork their workers.
+
+## Contributing
+
+See [`docs/development.md`](./docs/development.md) for building, testing, and how the generated
+code and the well-known event catalog are maintained.
+
+## License
+
+MIT

data/lib/pug/batcher.rb

@@ -0,0 +1,384 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "log"
+
+module Pug
+  # In-memory batching transport. Events accumulate and are sent by a single background thread
+  # on a size or interval trigger, so batches never overlap and go out in order. A transient
+  # failure re-queues them for a retry after max_wait; a permanent one dead-letters them to
+  # on_error, as does close for anything still undelivered.
+  class Batcher
+    DEFAULTS = { max_size: 100, max_wait: 5.0, max_queue_size: 10_000 }.freeze
+
+    # BatchCreateRequest.events is capped at 1000 by the events proto.
+    MAX_BATCH_EVENTS = 1000
+
+    # The server refuses request bodies over 8 MiB with resource_exhausted, a transient code, so
+    # an oversized batch would be retried forever. Half the cap leaves room for the envelope.
+    MAX_BATCH_BYTES = 4 * 1024 * 1024
+
+    # Retries wait max_wait but at least this long, or a max_wait of 0 would retry a server that
+    # refuses connections in a tight loop.
+    MIN_RETRY_WAIT = 1
+
+    # Retrying can't fix these client errors, nor an error that didn't come from the RPC layer,
+    # which is a bug.
+    PERMANENT_CODES = %i[invalid_argument not_found already_exists permission_denied failed_precondition
+                         unimplemented unauthenticated].freeze
+
+    Item = Struct.new(:event, :bytesize)
+
+    def self.permanent?(error)
+      !error.is_a?(Error) || error.code.nil? || PERMANENT_CODES.include?(error.code)
+    end
+
+    attr_reader :max_size, :max_wait, :max_queue_size
+
+    def initialize(sink, config, on_error, log)
+      @sink = sink
+      @on_error = on_error
+      @log = log
+      configure(config)
+      @lock = Mutex.new
+      @closed = false
+      @closer = nil
+      reset
+    end
+
+    def enqueue(event, bytesize)
+      dropped = nil
+      closed = @lock.synchronize do
+        after_fork
+        next true if @closed
+
+        @buffer << Item.new(event, bytesize)
+        dropped = trim
+        arm
+        @kick = true if @buffer.size >= @max_size && !@backoff
+        start
+        @wake.signal
+        false
+      end
+      return dead_letter(ClosedError.new("client is closed"), [event]) if closed
+
+      report_overflow(dropped)
+    end
+
+    # Resolves once the attempt it requested has finished, or returns false when timeout (in
+    # seconds) runs out first. A transient failure keeps events queued, so an empty queue is not
+    # guaranteed; close drains.
+    def flush(timeout: nil)
+      waiter = Queue.new
+      @lock.synchronize do
+        after_fork
+        return true if @stopping || (@buffer.empty? && !@sending && @requests.empty?)
+        # Called from on_error, which runs on the sender: waiting for it would wait forever.
+        return false if Thread.current.equal?(@thread)
+
+        @requests << waiter
+        start
+        @wake.signal
+      end
+      !waiter.pop(timeout: timeout).nil?
+    end
+
+    # Drains the buffer and stops the sender. Returns false when timeout (in seconds) runs out
+    # first; everything still undelivered then is dead-lettered before it returns, including a
+    # batch whose send goes on in the background and may yet succeed.
+    def close(timeout: nil)
+      deadline = timeout && (monotonic + timeout)
+      first = @lock.synchronize do
+        after_fork
+        next false if @closed
+
+        @closed = true
+        @closer = Thread.current
+        disarm
+        true
+      end
+      unless first
+        # Called from on_error, on the sender or the closing thread: the close underway waits on this call.
+        return false if !@done.closed? && (Thread.current.equal?(@thread) || Thread.current.equal?(@closer))
+
+        @done.pop(timeout: remaining(deadline))
+        return @done.closed? && @drained
+      end
+
+      drained = flush(timeout: remaining(deadline))
+      thread = @lock.synchronize do
+        @stopping = true
+        @wake.signal
+        @thread
+      end
+      stopped = thread.nil? || (!thread.equal?(Thread.current) && !thread.join(remaining(deadline)).nil?)
+      report_undelivered
+      @drained = drained && stopped
+      @done.close
+      @drained
+    end
+
+    # The default would list every buffered event.
+    def inspect = "#<#{self.class.name}>"
+
+    private
+
+    def configure(config)
+      config = (config || {}).transform_keys(&:to_sym)
+      (config.keys - DEFAULTS.keys).each { |key| @log.warn("Ignoring unknown batch option #{key.inspect}") }
+      settings = DEFAULTS.merge(config)
+      @max_size = setting(:max_size, settings[:max_size], 1)
+      if @max_size > MAX_BATCH_EVENTS
+        @log.warn("batch.max_size exceeds the #{MAX_BATCH_EVENTS}-event proto cap, clamping to #{MAX_BATCH_EVENTS}.")
+        @max_size = MAX_BATCH_EVENTS
+      end
+      @max_wait = setting(:max_wait, settings[:max_wait], 0)
+      @retry_wait = [@max_wait, MIN_RETRY_WAIT].max
+      @max_queue_size = setting(:max_queue_size, settings[:max_queue_size], 1)
+    end
+
+    # Counts must be integers; max_wait, in seconds, may be fractional.
+    def setting(name, value, min)
+      if min >= 1 && !value.is_a?(Integer)
+        @log.warn("batch.#{name} must be an integer, using default.")
+        return DEFAULTS[name]
+      end
+      unless value.is_a?(Numeric) && value.real? && value.finite? && value >= min
+        @log.warn("batch.#{name} must be >= #{min}, using default.")
+        return DEFAULTS[name]
+      end
+      value
+    end
+
+    def reset
+      @buffer = []
+      @inflight = nil
+      @requests = []
+      @wake = ConditionVariable.new
+      @done = Queue.new
+      # A child forked from a closed client has nothing to drain, and no closer to wait for.
+      @done.close if @closed
+      @drained = true
+      @deadline = nil
+      @kick = false
+      @backoff = false
+      @sending = false
+      @stopping = false
+      @thread = nil
+      @pid = Process.pid
+    end
+
+    # A forked child inherits the buffer but not the sender thread. The parent still owns and
+    # sends those events, so the child starts empty with a sender of its own.
+    def after_fork
+      reset unless @pid == Process.pid
+    end
+
+    def start
+      return if @thread&.alive?
+
+      @thread = Thread.new { run }
+      @thread.name = "pug-batcher"
+      @thread.report_on_exception = false
+    end
+
+    def run
+      loop do
+        requests = @lock.synchronize { next_job }
+        break if requests.nil?
+
+        begin
+          send_buffer
+        ensure
+          requests.each { |waiter| waiter << true }
+        end
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      # Nothing else would report it: the thread doesn't, and on_error or a logger may raise anything.
+      @log.error("Event sender stopped unexpectedly; it restarts with the next event: #{Log.describe(e)}")
+    ensure
+      # An idle exit has already handed over to whichever thread starts next, so only a sender
+      # that is stopping or crashed answers the pending flushes.
+      @lock.synchronize do
+        if @thread.equal?(Thread.current)
+          @thread = nil unless @stopping
+          @requests.each { |waiter| waiter << true }
+          @requests.clear
+        end
+      end
+    end
+
+    # Called under the lock. Returns the flush requests the next send answers, or nil to stop.
+    def next_job
+      loop do
+        return if @stopping
+
+        unless @requests.empty?
+          requests = @requests
+          @requests = []
+          return requests
+        end
+        if @kick
+          @kick = false
+          # Stale if the send that set it off has since taken those events, or if a backoff began;
+          # once closed, close's flush sends.
+          return [] if @buffer.size >= @max_size && !@backoff && !@closed
+
+          next
+        end
+        if @deadline.nil?
+          # Idle: nothing is buffered without a timer armed, so the thread exits rather than
+          # holding on to the client, and the next event starts a new one.
+          @thread = nil
+          return
+        end
+        wait = @deadline - monotonic
+        return [] unless wait.positive?
+
+        @wake.wait(@lock, wait)
+      end
+    end
+
+    # One attempt at what is buffered now, a chunk at a time. Events stay in the buffer until
+    # their chunk is taken, and the chunk being sent is tracked, so a close that runs out of time
+    # can report every event. Stops at the first transient failure, since the rest would likely
+    # fail the same way.
+    def send_buffer
+      pending = @lock.synchronize do
+        disarm
+        @backoff = false
+        @sending = true
+        @buffer.size
+      end
+      while pending.positive?
+        chunk = @lock.synchronize { take_chunk(pending) unless @stopping }
+        break if chunk.nil?
+
+        pending -= chunk.size
+        break unless %i[sent permanent].include?(settle(chunk, send_chunk(chunk)))
+      end
+    ensure
+      @lock.synchronize { @sending = false }
+    end
+
+    # Called under the lock: the oldest events, at most limit of them, cut at max_size and
+    # MAX_BATCH_BYTES.
+    def take_chunk(limit)
+      cap = [limit, @max_size].min
+      count = 0
+      bytes = 0
+      @buffer.each do |item|
+        break if count == cap || (count.positive? && bytes + item.bytesize > MAX_BATCH_BYTES)
+
+        count += 1
+        bytes += item.bytesize
+      end
+      @inflight = @buffer.shift(count) if count.positive?
+    end
+
+    # Not just StandardError: one that ended the thread would strand the chunk. Any error that
+    # didn't come from the RPC layer is permanent, so the chunk is dead-lettered.
+    def send_chunk(chunk)
+      @sink.call(chunk.map(&:event))
+      nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      e
+    end
+
+    # Returns the outcome of a chunk's send. Open, a transient failure re-queues the chunk for a
+    # retry; closed, it dead-letters it and leaves the rest for close to report.
+    def settle(chunk, error)
+      outcome, dropped = @lock.synchronize do
+        # close ran out of time during the send, and has reported the chunk itself.
+        next [:reported] unless @inflight.equal?(chunk)
+
+        @inflight = nil
+        if error.nil? then [:sent]
+        elsif self.class.permanent?(error) then [:permanent]
+        elsif @closed then [:closed]
+        else [:retry, requeue(chunk)]
+        end
+      end
+      events = chunk.map(&:event)
+      case outcome
+      when :permanent
+        @log.error("Permanent error, #{events.size} event(s) dropped (will NOT retry): #{Log.describe(error)}")
+        dead_letter(error, events)
+      when :closed
+        @log.error("Client closed, #{events.size} event(s) dropped after transient error: #{Log.describe(error)}")
+        dead_letter(error, events)
+      when :retry
+        @log.warn("Transient error sending batch, will retry: #{Log.describe(error)}")
+        report_overflow(dropped)
+      end
+      outcome
+    end
+
+    # Called under the lock. The retry is timed from the failure: a timer an enqueue armed during
+    # the send could already be due.
+    def requeue(chunk)
+      @buffer.unshift(*chunk)
+      @backoff = true
+      disarm
+      arm(@retry_wait)
+      trim
+    end
+
+    # Called under the lock. Drops the oldest events past max_queue_size and returns them.
+    def trim
+      over = @buffer.size - @max_queue_size
+      @buffer.shift(over).map(&:event) if over.positive?
+    end
+
+    def report_overflow(dropped)
+      return unless dropped
+
+      @log.warn("Queue full, dropping #{dropped.size} oldest event(s)")
+      dead_letter(QueueOverflowError.new("queue overflow: dropped oldest event"), dropped)
+    end
+
+    def report_undelivered
+      inflight, unsent = @lock.synchronize do
+        taken = [@inflight, @buffer.slice!(0..)]
+        @inflight = nil
+        taken
+      end
+      if inflight
+        @log.error("Close timed out with #{inflight.size} event(s) still being sent, which may yet arrive")
+        dead_letter(ClosedError.new("close timed out with #{inflight.size} event(s) still being sent"),
+                    inflight.map(&:event))
+      end
+      return if unsent.empty?
+
+      @log.error("Client closed with #{unsent.size} undelivered event(s), dropped")
+      dead_letter(ClosedError.new("client closed with #{unsent.size} undelivered event(s)"), unsent.map(&:event))
+    end
+
+    def arm(wait = @max_wait)
+      @deadline = monotonic + wait if @deadline.nil? && !@closed
+    end
+
+    def disarm
+      @deadline = nil
+    end
+
+    # A raising callback must not abort the sender or a drain: the remaining chunks would be lost
+    # with neither a log nor a callback. NotImplementedError, a common placeholder, is a
+    # ScriptError.
+    def dead_letter(error, events)
+      @on_error&.call(error, events)
+      nil
+    rescue StandardError, ScriptError => e
+      @log.error("on_error callback raised; #{events.size} event(s) may be lost: #{Log.describe(e)}")
+      nil
+    end
+
+    def remaining(deadline)
+      deadline && [deadline - monotonic, 0].max
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end