Class: ShipmentsTrackingWorker

Inherits:
Object
  • Object
show all
Includes:
Sidekiq::Job
Defined in:
app/workers/shipments_tracking_worker.rb

Overview

Sidekiq worker: shipments tracking.

Reconciliation cron, every 6 hours. Two passes, both covering gaps the
webhook flow leaves behind:

  1. NEVER SUBSCRIBED — tracking_registered_at IS NULL: these never
    subscribed to ShipEngine's push events (carrier didn't map to an SE
    code, the registration call was rejected with BusinessRulesError, or
    the tracking number pre-dates the registration worker).

  2. WENT SILENT — subscribed, still not delivered, but no scan has
    arrived in SILENT_AFTER. A ShipEngine subscription can stop
    pushing mid-transit with no error and no notice on our side, and
    because pass 1 deliberately skips everything already registered,
    nothing re-polled these: we sat waiting for a push that never came
    while the parcel quietly delivered. Observed 2026-07-27 — 7 of the
    13 parcels on the warehouse Problematic Deliveries tab had been
    delivered for up to two days and ShipEngine's API knew it.

  3. FINISHED — subscribed, and the parcel has reached a state where no
    further webhook can tell us anything useful. Released via
    POST /v1/tracking/stop. We subscribed every parcel and never released
    one, so subscriptions accumulated without bound: 14,831 registered
    all-time on 2026-07-30 against ~1,350 parcels actually inside the
    30-day tracking window.

Pass 2 re-polls through Shipping::TrackingResync, which feeds the
response through the webhook processor, so scans land in
shipment_events and the roll-up columns update through the same code
path a real webhook takes.

Constant Summary collapse

SILENT_AFTER =

How long a subscribed shipment may go without a scan before we stop
trusting the subscription and re-poll. Measured against prod on
2026-07-27: a 1-day threshold selects 134 parcels vs 125 at 2 days —
the backlog is dominated by long-dead subscriptions, not fresh ones,
so the tighter window catches a delivered parcel a full day sooner
for ~9 extra ShipEngine calls a day.

1.day
MAX_RESYNC_PER_RUN =

Blast-radius / quota cap for the re-poll pass: each shipment is one
billed ShipEngine tracking call, and this runs every 6 hours. The
backlog is worked oldest-silent first; the remainder waits for the
next run. Sized against the 2026-07-27 prod backlog of ~98 silent
parcels, which shrinks as parcels heal — a re-poll that returns a
delivered scan drops that parcel out of the set for good.

250
DELIVERED_SETTLE_AFTER =

How long a DELIVERED parcel must stay silent before we release its
subscription. Not zero: scans do keep arriving after a delivered scan,
and a few of them matter commercially — measured over 60 days of prod,
33 of 2,575 delivered parcels (1.3%) saw later scans, including a
refusal at +19.5h, another at +38.2h and a return-to-sender at +90.6h.
Cumulatively 58 of those 75 post-delivery scans land within 24h, 62
within 48h, 65 within 72h. 72h keeps the refusal window open while
still releasing the subscription days before the parcel ages out.

72.hours
ABANDON_UNDELIVERED_AFTER =

How long an UNDELIVERED parcel keeps its subscription before we give up
on push updates. This is abandonment, not completion: past this point a
staff member works the parcel by hand from the warehouse tab — the
carrier's own tracking link, or Dismiss. Deliberately shorter than
ProblematicDeliverySweep::LOOKBACK_WINDOW (30d) so the parcel stays
VISIBLE on that tab for another two weeks after we stop paying
ShipEngine to watch it.

14.days
MAX_STOPS_PER_RUN =

Blast-radius / quota cap for the stop pass — each release is one billed
ShipEngine call. The first run has a backlog (963 eligible inside the
30-day window on 2026-07-30); it drains over a few runs at this cap and
then settles to roughly 37/day, the rate parcels reach a settled
delivered scan.

250

Instance Method Summary collapse

Instance Method Details

#perform ⇒ Object

Runs the job.

Returns:

  • (Object) —

    the result



81
82
83
84
85
 
# File 'app/workers/shipments_tracking_worker.rb', line 81

def perform
  track_never_subscribed
  resync_silent_subscriptions
  stop_finished_subscriptions
end