Implement Delayed Reminders Using Node.js — Message Queue Boundaries for Logistics Workers

A delayed reminder should be stored as a durable obligation with a due time, then released into a queue only when a worker can reasonably attempt it. For a logistics system, that means separating timing from delivery, making the reminder key idempotent, and treating acknowledgement as a statement about durable progress rather than a signal that a handler started running.

The queue is not the clock.

TL;DR: use a durable scheduler or database-backed due-time table as the clock, publish a small reminder command when it becomes due, and acknowledge the queue message only after the delivery attempt has reached its defined durable boundary. Bound concurrency in the Node.js worker, use a retry schedule with a dead-letter destination, and measure lateness separately from handler latency. The useful design choice is not the queue brand; it is where each failure becomes visible and recoverable.

The example here is a logistics reminder: notify a dispatcher that a shipment appointment needs confirmation. A reminder can be late by a few seconds during normal load, but sending it twice can create duplicate calls or conflicting instructions. Those are different risks and deserve different controls.

What must remain true when the clock and queue disagree?

I start with invariants, because delayed delivery is an agreement between at least two clocks: the scheduler's view of time and the consumer's view of work. The queue can preserve a message, but it does not automatically know whether a reminder is still useful, already sent, or replaced by a newer appointment.

For each reminder, keep an immutable event identifier, a stable business key such as shipment_id + appointment_version + reminder_type, a due timestamp, and an attempt count. The delivery operation must accept the event identifier as an idempotency key. If a worker crashes after the external notification succeeds but before the queue acknowledgement, the redelivery should be harmless or should produce a deliberate reconciliation record.

The failure boundaries are equally important:

• Before the due record is committed, there is no reminder obligation.
• After the due record is committed, a scheduler crash must not erase it.
• After publication, a publisher failure must not create an invisible gap between storage and the queue.
• While a worker owns a message, its lease or acknowledgement deadline must cover the work, or the operation must be safe to repeat.
• After the delivery boundary, acknowledgement may remove the queue's responsibility for that attempt; it must not be used to pretend an uncertain external call succeeded.

That last point is where many examples become misleading. An acknowledgement is not a receipt from the recipient. It is a protocol message from the consumer to the broker. The application still needs a record of what it considers sent, attempted, or permanently failed.

Which architecture fits the latency budget?

There are three useful shapes. They are not interchangeable, and I would choose based on lateness tolerance, expected due-record volume, and the cost of keeping idle scheduling machinery available.

Shape	Timing behavior	Main failure boundary	Good fit	Cost or complexity
Durable due-time table plus poller	Usually near the poll interval	Claim and publish can be separated	Appointment reminders where seconds of jitter are acceptable	Requires indexed due scans and an outbox or reconciliation pass
Broker-supported delayed delivery	Depends on broker feature and message lifetime	Delay state and acknowledgement semantics live in the broker	Short, bounded delays with a well-understood broker contract	Long delays, cancellation, and inspection can be awkward
Bucketed scheduler plus ready queue	Precision follows bucket width	Bucket promotion can be retried	Large volumes with predictable minute-level timing	More moving parts and explicit duplicate handling

For a logistics workload, I usually favor the first shape when the due time is part of business state. A dispatcher may reschedule an appointment, and the system needs to query, cancel, or audit that reminder without asking a queue to explain its internal timer. A queue remains valuable as the execution buffer, not as the only database for future intent.

The outbox closes the most uncomfortable gap. In one transaction, write the reminder row and an outbox row. A publisher reads unpublished outbox rows, sends commands to the queue, and records a publication result. That publisher can publish twice after a timeout, so the consumer still needs idempotency. Exactly-once delivery is not a sensible assumption across a database, a broker, and an external notification service.

Use UTC instants for due times and preserve the original timezone or local appointment context separately. A timestamp such as 2026-10-23T09:15:00Z is an instant; 09:15 in a depot's local zone is not. This distinction becomes operationally important when appointments cross regions or daylight-saving transitions.

How should delayed reminders use a message queue in Node.js?

The worker should separate queue intake from work concurrency. A process that pulls 500 messages and then waits for a rate-limited API has not increased throughput; it has increased the amount of work that can become invisible, expire, or be redelivered together. Set a small prefetch or intake limit, then enforce a fixed number of in-flight delivery attempts inside the process.

I initially treated a delayed message as a complete reminder record. The correction is important: the message is a transport envelope, while the reminder row owns cancellation, appointment version, and audit history. That split adds a read, but it makes stale reminders explainable instead of mysteriously absent.

The critical path is short enough to test as a state machine. The following Python-like sketch shows the ordering without tying the design to a queue-specific client API; in Node.js, the same boundaries map to an async consumer, an AbortSignal-aware delivery client, and an explicit acknowledgement call.

from datetime import datetime, timezone

MAX_IN_FLIGHT = 8
RETRY_DELAYS_SECONDS = [30, 300, 1800]

async def handle_reminder(message, store, notifier, queue):
    event_id = message["event_id"]
    if await store.is_terminal(event_id):
        await queue.ack(message)
        return

    if datetime.now(timezone.utc) < message["due_at"]:
        await queue.defer(message, message["due_at"])
        return

    lease = await store.claim_once(event_id, message["attempt"])
    if lease is None:
        await queue.ack(message)
        return

    try:
        result = await notifier.send(
            recipient=message["recipient"],
            body=message["body"],
            idempotency_key=event_id,
        )
        await store.mark_delivered(event_id, result.reference)
        await queue.ack(message)
    except TemporaryFailure as error:
        attempt = message["attempt"] + 1
        if attempt <= len(RETRY_DELAYS_SECONDS):
            await store.record_retry(event_id, attempt, str(error))
            await queue.defer(message, delay=RETRY_DELAYS_SECONDS[attempt - 1])
            await queue.ack(message)
        else:
            await store.mark_dead(event_id, str(error))
            await queue.move_to_dead_letter(message)
            await queue.ack(message)
    except PermanentFailure as error:
        await store.mark_failed(event_id, str(error))
        await queue.move_to_dead_letter(message)
        await queue.ack(message)

The sketch deliberately marks a retry before acknowledging the current delivery. If the process stops after the database update and before acknowledgement, the redelivery sees the attempt state and can either continue the same retry policy or reconcile it. The exact choice depends on whether claim_once represents a short lease or a terminal state; it must never be an unbounded lock.

The limitation is deliberate. A database-backed timer is a poor fit for sub-second scheduling or an enormous stream of tiny, short-lived jobs; in those cases, a broker-native delay or a dedicated time-wheel service may be the better boundary. It remains a good fit when future reminders must be queried, cancelled, and audited.

In a real Node.js process, do not use an unbounded Promise.all over queue deliveries. Keep an in-flight counter, stop intake when it reaches the limit, and release the slot in a finally block. A graceful shutdown should stop new intake, wait for active attempts up to a deadline, and let the broker redeliver messages whose acknowledgement was never sent. A forced process exit is an operational event, not a successful completion.

Rate limiting needs its own measurement. If the downstream service permits eight requests per second, eight concurrent promises do not guarantee eight per second; response time, retries, and bursts at the boundary all matter. A token bucket or leaky-bucket limiter can bound the request rate, while the worker pool bounds memory and cancellation pressure. They solve related but distinct problems.

What happens when a reminder is cancelled or delivered twice?

Cancellation is a state transition, not deletion from a queue. Mark the reminder cancelled in durable storage, and have the consumer check that state immediately before the external side effect. A message already in flight can still race that check, so the notification endpoint needs an idempotency key and, where the business permits it, a version check. If a dispatcher changes the appointment from version 11 to 12, a version-11 reminder should become stale even if it was delayed and redelivered later.

Duplicates are normal under at-least-once delivery. They are not evidence that the queue is broken. The dangerous case is a side effect that succeeds while the worker loses its connection before recording success. A practical design records an attempt identifier before the call, sends the stable event key to the notification service, and reconciles ambiguous attempts from a durable result or provider query. If the endpoint has no idempotency support, the application has to choose between possible duplicate delivery and possible omission; document that choice instead of hiding it behind a retry loop.

A dead-letter destination is useful only when somebody can operate it. Include the event key, original due time, latest error class, attempt number, and a redaction-safe payload reference. Do not put sensitive recipient data into logs merely because a dead-letter message is convenient to inspect. Replaying a dead letter should be an explicit action that preserves the original event identity and increments an operational replay counter.

How do you test lateness instead of only success?

A unit test that sees send() resolve has not tested delayed reminders. Test the transitions around the gaps: commit the due row and stop the publisher; publish twice; stop the worker after the external call; advance the clock across a daylight-saving boundary; cancel a reminder while it is queued; exhaust the downstream rate limit; and let the acknowledgement deadline expire. The expected result should be stated in terms of business state and observable side effects, not only queue depth.

Inject a clock into the scheduler. Use a fake queue in unit tests and a real broker in an integration test that exercises acknowledgement and redelivery semantics. For the scheduler, property tests are especially useful: after any number of retries and crashes, there should be at most one terminal delivery record for a given event key, and a non-cancelled due reminder should remain discoverable until it reaches a terminal state.

Track at least these values:

• scheduling lateness: published_at - due_at;
• queue wait: started_at - published_at;
• handler time: finished_at - started_at;
• retry count and dead-letter count;
• duplicate suppression count;
• downstream throttles and acknowledgement failures.

Those dimensions prevent a common misdiagnosis. If scheduling lateness is low but queue wait is high, adding more scheduler capacity will not help. If queue wait is low but handler time grows under load, the rate-limited worker or its downstream dependency is the bottleneck. If duplicate suppression rises after a deployment, inspect acknowledgement deadlines and shutdown behavior before changing the delay mechanism.

My decision rule is narrow: choose the simplest durable timer that meets the lateness objective, keep future intent queryable, and make every boundary observable. A ready queue is an execution mechanism. It is not a substitute for a reminder ledger, an idempotency policy, or a definition of what delivery means.

References

• RabbitMQ, “Consumer Acknowledgements and Publisher Confirms”: https://www.rabbitmq.com/docs/confirms
• Node.js documentation, “Timers”: https://nodejs.org/api/timers.html
• Node.js documentation, “Events”: https://nodejs.org/api/events.html
• PostgreSQL documentation, “SELECT”: https://www.postgresql.org/docs/current/sql-select.html
• RFC 3339, “Date and Time on the Internet”: https://www.rfc-editor.org/rfc/rfc3339