fractal-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb85bbae2629a4f35ac315bda48069d46f952a44391422d162e88d05814d6724
+  data.tar.gz: 68f9802f6b2e0db444ce472670269dab8e626d13370adcd47037c362430831ce
+SHA512:
+  metadata.gz: a228762b9ee48fe5e87c4d12b4dcda604a0138b57610c9e7ff5cbdcd0f194b001437fc2e4c51ca18824a3ad98c4f5371d18f1d51b5eb77db4729e664a0bf8229
+  data.tar.gz: b43092221f112e42367e98c4f8cebb200ce6369c4f2a598395aab3abeb0474e411fe95177c822e465d9a63a970a4b882ad71b416b5c7465a294cbd5e7b147593

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to the `fractal-ruby` gem. The version lives in `VERSION`;
+`ci/check_version_sync.sh` keeps `lib/fractal/version.rb`, this file and the lockfiles in step.
+
+## 0.1.0
+
+First version (#495, ADR 0003). Not yet published to rubygems.org (#497); Fractal's own app uses it
+from the path.
+
+- **Errors**, extracted from Fractal's in-repo self-reporter (`lib/self_report/`, #426): a Railtie
+  adds an outermost Rack middleware and a `Rails.error` subscriber; events are built from an
+  allowlist, scrubbed (Rails `filter_parameters`, extra keys, secret ENV values, credential and
+  email patterns, structured Postgres messages), coalesced by the collector's fingerprint (ported,
+  pinned by the shared vectors) and delivered from a background thread with a circuit breaker,
+  fork reset and a 2 s shutdown flush.
+- **Configuration instead of constants**: `Fractal.configure` takes the API key, collector URL,
+  app version, environment, a runtime `enabled` switch, a `user_resolver`, extra filter keys,
+  `message_filters` and a `before_send_error` hook.
+- **401 stops sending** for the rest of the process, for errors and analytics alike; 402 still
+  turns error reporting off.
+- **Request-scoped context**: `Fractal.set_user`, `set_tag`, `add_breadcrumb` and `set_session`,
+  per request and per job, never global.
+- **Analytics** (new): `Fractal.analytics.track` with its own buffer and background flush, a
+  gem-generated `event_id`, the 128-byte `event_type` and 64 KB payload checks before queueing,
+  per-event `player_id`, `session_token` and `client_ip`, and `server_side: true` on the envelope.
+- **Packaging** (#497): MIT licensed, with the `LICENSE` file in the gem. Rails only: plain Rack
+  apps and Sidekiq workers outside Active Job are documented gaps.
+- **Sessions and sign-in**: the default session is a hash of the Rack session id; Warden/Devise
+  sign-in tracks `identify`, linking the logged-out session to the user.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fractal
+
+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,151 @@
+# fractal-ruby
+
+Error tracking and server-side analytics for Rails backends, reporting to
+[Fractal](https://getfractal.dev). The Ruby peer of the JavaScript, Godot and LÖVE SDKs: same
+facade, same wire protocol (`sdks/shared/ANALYTICS_PROTOCOL.md`, `sdks/shared/CRASH_PROTOCOL.md`),
+same conformance check.
+
+Requires Ruby 3.2+ and Rails 7.1+ (ADR 0003). The core (transport, buffers, scrubber, fingerprint,
+`track`) is plain Ruby; the Railtie is the supported entry point for the first release.
+
+> Not published yet (#497). Fractal's own app uses it from the path:
+> `gem "fractal-ruby", path: "sdks/ruby"`.
+
+## Setup
+
+```ruby
+# Gemfile
+gem "fractal-ruby"
+
+# config/initializers/fractal.rb
+Fractal.configure do |c|
+  c.api_key = ENV["FRACTAL_API_KEY"]          # a key created for this backend
+  c.app_version = ENV["GIT_SHA"]              # resolve/reopen compare versions
+  c.user_resolver = ->(controller) { "user-#{controller.current_user.id}" if controller.current_user }
+end
+```
+
+Without an `api_key` the gem does nothing, which is the usual setting for development and test.
+Create a **dedicated key** for the server: until key scopes exist (#490) a key has the same power
+wherever it is used.
+
+## Errors
+
+The Railtie installs an outermost Rack middleware and a `Rails.error` subscriber, so unhandled
+exceptions in requests and Active Job jobs are reported with no further code. Rails' own filter
+(404s and other rescue responses) is respected.
+
+```ruby
+Fractal.errors.capture_error(exception)                 # one you rescued (handled: true)
+Fractal.errors.capture_message("payment provider slow")
+```
+
+What is sent is built from an allowlist (error class, message, frames, controller#action, route,
+request id, job class, queue, executions) and then scrubbed: keys in `filter_parameters` plus
+`extra_filter_keys`, the values of secret-looking ENV variables, credentials in URLs, bearer and
+basic tokens, JWTs, Stripe keys, emails and long hex strings. Postgres errors are reduced to
+`<class> <SQLSTATE> <constraint>`, other Active Record errors to their first line, and errors that
+echo their input (JSON parse errors and the like) have their message withheld. Add your own rules:
+
+```ruby
+c.message_filters << ->(exception, raw) { "Redis timeout" if exception.is_a?(Redis::TimeoutError) }
+c.before_send_error = ->(event) { event["tags"]["region"] = "eu"; event }  # nil drops the event
+```
+
+Repeats of one error are coalesced into one event with an `occurrence_count`, keyed by the
+collector's own fingerprint. Delivery runs on a background thread: at most 100 distinct errors
+buffered, 5 requests per second, a circuit breaker after 5 failures, a fresh buffer after fork
+(Puma, Solid Queue) and a 2-second flush at exit.
+
+## Analytics
+
+```ruby
+Fractal.analytics.track("checkout_completed", { "total_cents" => 1299 })
+```
+
+`track` never sends on the caller's thread: events are buffered (5,000 events or 8 MB, oldest
+dropped first) and flushed every 10 seconds or at 100 events, up to 1,000 per request. Each event
+gets its own `event_id` (UUID). The collector's limits are checked first: an empty or over-128-byte
+`event_type`, a payload that is not a Hash or is over 64 KB serialised, a `player_id` over 256
+bytes, a `timestamp` that is not a `Time`, or an `event_type`, `player_id` or `session_token`
+that is not valid UTF-8, raises `Fractal::Analytics::InvalidEvent` outside production and is
+logged and dropped in production. A `client_ip` never costs the event: one that is not an IPv4 or
+IPv6 address is sent as given (the collector keeps the event and stores it without geo), and one
+that is not valid UTF-8 is left out with a warning.
+
+Delivery is **at least once**: a request whose response is lost is retried and stored twice.
+`event_id` lets you tell duplicates apart; the collector does not deduplicate yet (#513).
+
+### Who and which session
+
+| | Default | Override |
+| --- | --- | --- |
+| Player | the scope's user (`Fractal.set_user`, or Warden), else `user_resolver`, else `"anonymous"` inside a request and `"system"` outside one (jobs, rake, boot) | `track(..., player_id:)`, `anonymous_player_id`, `system_player_id` |
+| Session | a hash of the Rack session id (the raw id is never sent); with no session (jobs, cookie-less APIs), one session per player per UTC day | `track(..., session_token:)`, `Fractal.set_session(token)`, `session_resolver` |
+| End-user address | the request's address (`request.remote_ip`, which honours your trusted proxies) | `track(..., client_ip:)`, `send_client_ip = false` |
+
+With Warden (Devise), the gem sets the user as soon as the app authenticates, and a sign-in
+tracks an `identify` event: it is recorded in the session that was current before sign-in, under
+the user's player id, with `previous_player_id` in the payload. Warden gives the session a new id
+at sign-in, so the logged-out and logged-in halves of a visit are two sessions, linked by that
+event. Only a sign-in stored in the session counts: a stateless strategy (a token or HTTP auth,
+which Warden runs with `store: false` on every request) sets the user but tracks no `identify`.
+Turn it off with `identify_on_login = false`, or call `Fractal.identify(player_id)` yourself when
+you do not use Warden.
+
+The collector geolocates `client_ip` only when the project has IP tracking on, and stores the
+address hashed. Your app owns consent for its users: this gem has no consent switch of its own.
+
+### Request scope
+
+`Fractal.set_user`, `set_tag`, `add_breadcrumb` and `set_session` apply to the current request or
+job only. Tags and breadcrumbs go on errors; the user and session go on both errors and events.
+
+## Configuration reference
+
+See `lib/fractal/configuration.rb`. Highlights: `enabled` may be a callable checked on every call
+(a runtime kill switch), `errors_enabled` / `analytics_enabled` turn one half off (it becomes a
+set of no-ops), and `strict` controls whether invalid events raise.
+
+## Not covered yet
+
+- Sidekiq workers that do not go through Active Job: the `Rails.error` subscriber does not see
+  them. Decided as a documented gap for the first release (#497).
+- Plain Rack apps without Rails. The first release supports Rails only (#497); the core runs
+  without Rails, but nothing installs the middleware or the subscriber for you.
+- Per-event-type sampling.
+
+## Development
+
+```bash
+sdks/ruby/ci/test.sh 3.2 rails_7_1     # the floor lane
+sdks/ruby/ci/test.sh 3.4 rails_8_1     # what Fractal runs
+sdks/ruby/ci/check_version_sync.sh
+sdks/ruby/ci/conformance_capture.sh    # writes tmp/conformance/ruby/
+sdks/ruby/ci/run_e2e.sh                # against a real collector, Postgres and ClickHouse
+```
+
+The fingerprint spec reads `collector/internal/ingest/fingerprint_vectors.json` from the repo,
+so the specs run from a checkout of the Fractal repo.
+
+## Releasing
+
+Merging a `VERSION` bump to `main` is the release: `.github/workflows/ruby_sdk_tag.yml` tags
+`ruby-sdk/vX.Y.Z`, builds the gem with `gem build --strict` and pushes it to rubygems.org. A
+version rubygems.org already has is skipped. Without the `RUBYGEMS_API_KEY` secret the workflow
+tags and skips the push with a warning; re-run it by hand (`workflow_dispatch`) once the secret is
+set. The key needs the "push rubygem" scope, on an account whose MFA level is "UI and gem signin":
+at "UI and API" every push asks for an OTP that CI cannot give.
+
+**Before the first deploy that advertises the gem.** The Settings quick start and the help article
+(`content/help/{en,es}/sdk-integration/ruby.md`) tell customers to add `gem "fractal-ruby"`, and
+the name is not registered on rubygems.org until the first push. Push 0.1.0 by hand from the
+owning account (or set the secret and dispatch the workflow) before running `bin/deploy`: until
+then the install line fails and the name is free for anyone to claim. Shipping the copy ahead of
+the push was an owner decision (2026-10-12), not an oversight.
+
+`spec/fractal/package_spec.rb` builds the gem the same way and checks what is inside it.
+
+## License
+
+MIT. See `LICENSE`.

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/fractal/analytics.rb

@@ -0,0 +1,437 @@
+# frozen_string_literal: true
+
+require "json"
+require "resolv"
+require "securerandom"
+
+module Fractal
+  # Server-side `track`: buffers events in memory and delivers them to POST /v1/batch from its own
+  # background thread. Its buffer is separate from the error reporter's, so a burst of events can
+  # never evict an error report; the circuit breaker and the 401 revocation are shared.
+  #
+  # One request carries many players and sessions: each event names its own player_id,
+  # session_token and client_ip (#511, #512), and the envelope is marked server_side so the
+  # collector never geolocates the server's own address.
+  #
+  # Delivery is at-least-once. A request whose 202 is lost is retried and stored twice; event_id
+  # is set here so duplicates can be told apart (#513).
+  class Analytics
+    MAX_EVENT_TYPE_BYTES = 128
+    MAX_PLAYER_ID_BYTES = 256
+    MAX_PAYLOAD_BYTES = 65_536
+    MAX_BATCH = 1_000            # collector limit per request
+    BACKOFF_BASE = 1
+    BACKOFF_CAP = 60
+
+    InvalidEvent = Class.new(ArgumentError)
+
+    def initialize(config:, transport: Transport.new, breaker: Breaker.new, start_worker: true, clock: nil)
+      @config = config
+      @transport = transport
+      @breaker = breaker
+      @start_worker = start_worker
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @identity = Identity.new(config)
+      reset_state
+    end
+
+    def enabled?
+      @config.analytics_enabled && @config.enabled? && !@breaker.revoked?
+    end
+
+    # Records one event and returns at once; nothing is sent on the caller's thread.
+    #
+    # player_id, session_token and client_ip default to the current scope's (see Identity and
+    # Configuration#session_resolver). An event the collector would reject (empty or over-128-byte
+    # event_type, a non-Hash payload, a payload over 64 KB, a player_id over 256 bytes), that can
+    # never be serialised (an event_type, player_id or session_token that is not valid UTF-8) or
+    # whose timestamp is not a Time raises InvalidEvent in strict mode and is otherwise logged at
+    # error level and dropped. A client_ip never costs the event: one that is not an address is
+    # sent as given (the collector keeps the event and stores it without geo), and one that is not
+    # valid UTF-8 is left out with a warning.
+    def track(event_type, payload = nil, player_id: nil, session_token: nil, client_ip: nil, timestamp: nil)
+      reset_after_fork
+      return false unless enabled?
+
+      payload_json = validate!(event_type, payload)
+      enqueue(build(event_type.to_s, payload_json, player_id: player_id, session_token: session_token,
+                                                   client_ip: client_ip, timestamp: timestamp))
+      true
+    rescue InvalidEvent => e
+      bump(:dropped_invalid)
+      raise if @config.strict?
+
+      log(:error, "event dropped: #{e.message}")
+      false
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      log(:error, "track failed: #{e.class}")
+      false
+    end
+
+    # The logged-out and logged-in halves of a visit are two sessions (the session id changes at
+    # sign-in). This event links them: tracked in the session that was current before sign-in,
+    # under the player that just signed in.
+    def identify(player_id, previous_player_id:)
+      track("identify", { "previous_player_id" => previous_player_id }, player_id: player_id)
+    end
+
+    # Delivers up to one batch. Never raises.
+    def flush(deadline: nil)
+      reset_after_fork
+      unless enabled?
+        discard_buffer
+        return
+      end
+      return if @breaker.open? || now < @retry_at
+
+      loop do
+        break if @breaker.open? || !enabled? || (deadline && now > deadline)
+
+        batch = take_batch
+        break if batch.empty?
+
+        break unless deliver(batch)
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      log(:error, "flush failed: #{e.class}")
+    end
+
+    def shutdown(timeout: @config.shutdown_timeout)
+      return unless @pid == Process.pid
+
+      @stopping = true
+      @mutex.synchronize { @wake.broadcast }
+      @thread&.join(0.5)
+      @retry_at = 0
+      flush(deadline: now + timeout)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      log(:error, "shutdown failed: #{e.class}")
+    end
+
+    def stats
+      @mutex.synchronize { @stats.dup }
+    end
+
+    def pending
+      @mutex.synchronize { @queue.size }
+    end
+
+    private
+
+    def reset_state
+      @pid = Process.pid
+      @mutex = Mutex.new
+      @wake = ConditionVariable.new
+      @queue = []
+      @queue_bytes = 0
+      @seq = 0
+      @stats = Hash.new(0)
+      @thread = nil
+      @stopping = false
+      @attempts = 0
+      @retry_at = 0
+      @flush_requested = false
+    end
+
+    # A forked child inherits the parent's queue; sending it again would duplicate every event.
+    def reset_after_fork
+      reset_state unless @pid == Process.pid
+    end
+
+    def now = @clock.call
+
+    def validate!(event_type, payload)
+      unless event_type.is_a?(String) || event_type.is_a?(Symbol)
+        raise InvalidEvent, "event_type must be a String, got #{event_type.class}"
+      end
+      name = event_type.to_s
+      if name.empty? || name.bytesize > MAX_EVENT_TYPE_BYTES
+        raise InvalidEvent, "event_type must be 1 to #{MAX_EVENT_TYPE_BYTES} bytes, got #{name.bytesize}"
+      end
+      return nil if payload.nil? || (payload.is_a?(Hash) && payload.empty?)
+      raise InvalidEvent, "payload for #{name.inspect} must be a Hash, got #{payload.class}" unless payload.is_a?(Hash)
+
+      json = JSON.generate(payload)
+      if json.bytesize > MAX_PAYLOAD_BYTES
+        raise InvalidEvent, "payload for #{name.inspect} is #{json.bytesize} bytes, over the #{MAX_PAYLOAD_BYTES}-byte limit"
+      end
+      json
+    rescue JSON::JSONError, EncodingError => e # JSONError: also NestingError (circular or over 100 deep)
+      raise InvalidEvent, "payload for #{name.inspect} cannot be serialised as JSON (#{e.class})"
+    end
+
+    def build(event_type, payload_json, player_id:, session_token:, client_ip:, timestamp:)
+      unless timestamp.nil? || timestamp.respond_to?(:getutc)
+        raise InvalidEvent, "timestamp must be a Time, got #{timestamp.class}"
+      end
+
+      scope = Scope.current
+      context = ExecutionContext.current
+      player = player_id.to_s.empty? ? @identity.player_id(scope: scope, controller: context[:controller]) : player_id.to_s
+      event = {
+        "event_id" => SecureRandom.uuid,
+        "event_type" => event_type,
+        "event_timestamp" => (timestamp&.getutc || Time.now.utc).iso8601(3),
+        "player_id" => player,
+        "session_token" => session_token.to_s.empty? ? session_for(scope, player) : session_token.to_s
+      }
+      ip = client_ip.to_s.empty? ? client_ip_for(scope) : client_ip.to_s
+      ip = serialisable_ip(ip) if ip
+      event["client_ip"] = ip if ip
+      reject_invalid_identity!(event)
+      event["payload"] = JSON.parse(payload_json) if payload_json
+      [ event, payload_json ? payload_json.bytesize : 0 ]
+    end
+
+    # These strings come from the caller, the scope or a resolver. One that is not valid UTF-8 can
+    # never be serialised, and the collector rejects an over-long player_id, so each is refused
+    # here like a bad payload, not queued. client_ip never gets here unserialisable (see
+    # serialisable_ip): the collector never rejects an event over it (ANALYTICS_PROTOCOL.md), so
+    # neither does the gem.
+    def reject_invalid_identity!(event)
+      event.each do |field, value|
+        JSON.generate(value)
+      rescue JSON::JSONError, EncodingError
+        raise InvalidEvent, "#{field} is not valid UTF-8 and cannot be serialised as JSON"
+      end
+      return if event["player_id"].bytesize <= MAX_PLAYER_ID_BYTES
+
+      raise InvalidEvent, "player_id must be at most #{MAX_PLAYER_ID_BYTES} bytes, got #{event['player_id'].bytesize}"
+    end
+
+    # An SDK MUST NOT drop an event over its client_ip (ANALYTICS_PROTOCOL.md). One that is not
+    # valid UTF-8 can never be serialised, so the address is what is left out, not the event.
+    def serialisable_ip(ip)
+      JSON.generate(ip)
+      ip
+    rescue JSON::JSONError, EncodingError
+      log(:warn, "client_ip is not valid UTF-8 and was left out; the event is kept without geo")
+      nil
+    end
+
+    # Only decides whether the request's own address is worth sending (see remote_ip). It does not
+    # have to agree with the collector's parser: a miss costs one event its geo, never the event.
+    def address?(ip)
+      return false if ip.include?("%")
+
+      ip.match?(Resolv::IPv4::Regex) || ip.match?(Resolv::IPv6::Regex)
+    end
+
+    # The scope's explicit session, else the configured resolver over the request, else one
+    # session per player per UTC day: a job or a cookie-less API call has no session of its own,
+    # and an empty token would make the collector invent a new session every second.
+    def session_for(scope, player)
+      return scope.session_token.to_s unless scope.session_token.to_s.empty?
+
+      resolved = resolve_session(scope)
+      return resolved unless resolved.to_s.empty?
+
+      "day_#{Time.now.utc.strftime('%Y%m%d')}_#{player}"
+    end
+
+    def resolve_session(scope)
+      return nil unless scope.env && @config.session_resolver
+
+      @config.session_resolver.call(scope.env)&.to_s
+    rescue StandardError => e
+      log(:error, "session_resolver raised #{e.class}; using the daily session")
+      nil
+    end
+
+    def client_ip_for(scope)
+      return scope.client_ip unless scope.client_ip.to_s.empty?
+      return nil unless @config.send_client_ip && scope.env
+
+      scope.client_ip = remote_ip(scope.env)
+    rescue StandardError => e
+      log(:warn, "could not read the client address: #{e.class}")
+      nil
+    end
+
+    # ActionDispatch's remote_ip honours the app's trusted proxies; plain Rack's ip is the fallback.
+    # A request address that is not one (a proxy's "unknown") is left out: the event matters more.
+    def remote_ip(env)
+      ip = if defined?(::ActionDispatch::Request)
+        ::ActionDispatch::Request.new(env).remote_ip
+      elsif defined?(::Rack::Request)
+        ::Rack::Request.new(env).ip
+      else
+        env["REMOTE_ADDR"]
+      end
+      address?(ip.to_s) ? ip.to_s : nil
+    end
+
+    def enqueue((event, bytes))
+      @mutex.synchronize do
+        @seq += 1
+        event["client_seq"] = @seq
+        @queue << [ event, bytes ]
+        @queue_bytes += bytes
+        while @queue.size > @config.analytics_max_queue || @queue_bytes > @config.analytics_max_queue_bytes
+          _, dropped_bytes = @queue.shift
+          @queue_bytes -= dropped_bytes
+          @stats[:dropped_queue_full] += 1
+        end
+        if @queue.size >= @config.analytics_flush_at
+          @flush_requested = true
+          @wake.signal
+        end
+      end
+      start_worker if @start_worker
+    end
+
+    def take_batch
+      @mutex.synchronize do
+        batch = @queue.shift(MAX_BATCH)
+        @queue_bytes -= batch.sum { |_, bytes| bytes }
+        batch
+      end
+    end
+
+    # Puts a batch back at the front for a retry, keeping the queue within its caps by dropping
+    # the oldest events.
+    def restore(batch)
+      @mutex.synchronize do
+        @queue.unshift(*batch)
+        @queue_bytes += batch.sum { |_, bytes| bytes }
+        while @queue.size > @config.analytics_max_queue || @queue_bytes > @config.analytics_max_queue_bytes
+          _, dropped_bytes = @queue.shift
+          @queue_bytes -= dropped_bytes
+          @stats[:dropped_queue_full] += 1
+        end
+      end
+    end
+
+    # Returns true when the batch is settled (delivered or dropped for good), false when it was
+    # put back for a retry.
+    def deliver(batch)
+      body = serialise(batch)
+      return true unless body
+
+      response = @transport.post(@config.endpoint("/v1/batch"), @config.api_key, body)
+      handle_response(response, batch)
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      retry_later(batch, "delivery failed: #{e.class}")
+    end
+
+    # A batch that cannot be serialised now never will be. It is dropped, not retried: a retry
+    # would hold every later event behind it and open the breaker the error reporter shares.
+    def serialise(batch)
+      envelope(batch.map(&:first)).to_json
+    rescue StandardError => e
+      bump(:dropped_invalid, batch.size)
+      log(:error, "batch of #{batch.size} event(s) dropped: cannot be serialised (#{e.class})")
+      nil
+    end
+
+    def handle_response(response, batch)
+      case response.code
+      when 200..299
+        succeeded(batch, response.body)
+        true
+      when 401
+        @breaker.revoke!
+        discard_buffer
+        log(:error, "collector answered 401: the API key is unknown or inactive. Fractal stops sending for the rest of this process")
+        true
+      when 429, 500..599
+        retry_later(batch, "collector answered #{response.code}")
+      else
+        @breaker.failure!
+        bump(:dropped_rejected, batch.size)
+        log(:error, "collector answered #{response.code}; batch of #{batch.size} event(s) dropped")
+        true
+      end
+    end
+
+    def succeeded(batch, body)
+      @breaker.success!
+      @attempts = 0
+      @retry_at = 0
+      json = parse(body)
+      if json.is_a?(Hash) && json["dropped"] == true
+        bump(:dropped_over_cap, batch.size)
+        log(:warn, "collector dropped #{batch.size} event(s): the organization is over its plan's event cap")
+        return
+      end
+      rejected = Rejections.parse(body, batch.size)
+      bump(:sent_events, batch.size - rejected.size)
+      return if rejected.empty?
+
+      bump(:rejected_events, rejected.size)
+      rejected.each do |r|
+        log(:error, "collector rejected event #{batch[r['index']].first['event_type'].inspect}: #{r['reason']}")
+      end
+    end
+
+    # Exponential backoff with jitter, capped, and never giving up on the events: they stay queued
+    # (within the queue caps) for the next attempt.
+    def retry_later(batch, reason)
+      @breaker.failure!
+      bump(:failed_posts)
+      restore(batch)
+      delay = [ BACKOFF_BASE * (2**@attempts), BACKOFF_CAP ].min
+      @attempts += 1
+      @retry_at = now + delay * (1 + (rand * 0.1))
+      log(:warn, "#{reason}; #{batch.size} event(s) kept, retrying in #{delay.round}s")
+      false
+    end
+
+    def parse(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def envelope(events)
+      {
+        sent_at: Time.now.utc.iso8601(3),
+        context: {
+          player_id: @config.system_player_id, session_token: "", platform: "server",
+          app_version: @config.app_version.to_s, environment: @config.environment,
+          sdk_version: Fractal.sdk_version, server_side: true
+        },
+        events: events
+      }
+    end
+
+    def discard_buffer
+      @mutex.synchronize do
+        @queue.clear
+        @queue_bytes = 0
+      end
+    end
+
+    def start_worker
+      return if @thread&.alive?
+
+      @mutex.synchronize do
+        return if @thread&.alive?
+
+        @thread = Thread.new { work }
+        @thread.report_on_exception = false
+      end
+    end
+
+    def work
+      until @stopping
+        # The flag, not just the signal: a signal sent before this thread first waits is lost.
+        @mutex.synchronize do
+          @wake.wait(@mutex, @config.analytics_flush_interval) unless @flush_requested
+          @flush_requested = false
+        end
+        flush unless @stopping
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      log(:error, "analytics worker died: #{e.class}")
+    end
+
+    def bump(stat, by = 1)
+      @mutex.synchronize { @stats[stat] += by }
+    end
+
+    def log(level, message)
+      @config.logger&.public_send(level, "[fractal] #{message}")
+    end
+  end
+end