Class: TrackRelay::DeliveryJob

Inherits:
ActiveJob::Base
  • Object
show all
Defined in:
lib/track_relay/delivery_job.rb

Overview

ActiveJob-backed async delivery for non-synchronous subscribers.

The job receives ‘[subscriber_class_name, payload_hash]` (because ActiveJob arguments must be GlobalID-serializable, not raw subscriber instances or EventPayload objects). On `perform` it reconstructs the EventPayload via EventPayload.from_h and dispatches to a fresh subscriber instance.

**Async loudness mirrors the sync Dispatcher contract:** when ‘safe_deliver` returns a StandardError AND Configuration#swallow_subscriber_errors is `false`, the job re-raises after `safe_deliver` has already logged. This lets ActiveJob’s normal error path (retry / discard / failed-job queue) surface the failure. Under the ‘:test` adapter this propagates synchronously through `perform_now`/`perform_later`.

The job receives a serialized hash, not Current state —ActiveJob’s Executor clears CurrentAttributes before ‘perform`, so any context the subscriber needs must already be on `payload.context` (snapshotted at track time by the Instrumenter).

## GA4 retry / discard policy (Plan 02-04)

‘retry_on TrackRelay::DeliveryRetriableError` covers transient GA4 failures (HTTP 5xx, network timeouts, ECONNREFUSED, SocketError). The wait algorithm `:polynomially_longer` produces ~3s, ~18s, ~83s, ~258s with 15% default jitter — appropriate for GA4 since the Measurement Protocol has no strict ordering requirement, sends are idempotent enough for analytics, and GA4’s 72-hour event-backdating window means late retries still arrive correctly.

‘discard_on TrackRelay::DeliveryDiscardableError` covers HTTP 4xx (defensive — Scout §2 confirms GA4 returns 2xx in practice even on malformed payloads, but mapping 4xx to discard is correct in case Google ever changes that contract).

### Why ‘DEFAULT_GA4_DELIVERY_ATTEMPTS` is a class-local constant

‘retry_on` runs at class-body load time, before any `TrackRelay.configure` block in a host’s initializer has had a chance to mutate config. Reading ‘TrackRelay.config. ga4_delivery_attempts` here would either crash (singleton not yet built) or capture a stale default that the host’s initializer is about to overwrite. Pinning the value to a class-local constant sidesteps the load-order hazard entirely. A future minor (Phase 4) can introduce runtime configurability via ‘self.inherited` / `after_initialize` machinery without breaking this contract.

Constant Summary collapse

DEFAULT_GA4_DELIVERY_ATTEMPTS =

GA4 retry attempt cap (Plan 02-04). Class-local constant — see the rationale in the class docstring above. Future Phase 4 work may introduce ‘config.ga4_delivery_attempts` once a safe late-binding path exists; until then, `5` is the contract.

5

Instance Method Summary collapse

Instance Method Details

#perform(subscriber_class_name, payload_hash) ⇒ void

This method returns an undefined value.

Parameters:

  • subscriber_class_name (String) —

    fully-qualified subscriber class name (e.g. ‘“TrackRelay::Subscribers::Logger”`)

  • payload_hash (Hash) —

    result of EventPayload#to_h, possibly round-tripped through JSON (string keys)



73
74
75
76
77
78
79
80
81
82
 
# File 'lib/track_relay/delivery_job.rb', line 73

def perform(subscriber_class_name, payload_hash)
  subscriber = subscriber_class_name.constantize.new
  payload = EventPayload.from_h(payload_hash)
  result = subscriber.safe_deliver(payload)

  # `safe_deliver` already logged via Rails.logger.error. If the
  # host opts out of swallowing, re-raise so ActiveJob's normal
  # error path surfaces the failure.
  raise result if result.is_a?(StandardError) && !TrackRelay.config.swallow_subscriber_errors
end