DEV Community

YatesHolloway6872
YatesHolloway6872

Posted on

Node.js Setup for Creating a Message Queue and Publishing Game Cleanup Tasks

A game session cleanup job should leave the web request quickly, then make its delivery contract explicit. For expired sessions, I would publish one idempotent message per cleanup unit, let a worker claim it, and delete the message only after the write succeeds. The important choice is not the queue brand. It is what happens when a worker dies after claiming work.

The practical rule is this: use at-least-once delivery, make the handler safe to repeat, and set the visibility window longer than the normal cleanup attempt. A queue is a delivery mechanism, not a transaction around every database and game-service write.

That boundary matters.

Suppose the API receives a request to end a match. It records the match as finished and enqueues cleanup for abandoned room membership, temporary inventory reservations, and the session presence record. The request returns after the durable handoff, not after every cleanup operation. That keeps the request path bounded.

The worker receives a payload like this:

type CleanupMessage = {
  jobId: string;
  sessionId: string;
  reason: "expired" | "match-ended";
  createdAt: string;
};
Enter fullscreen mode Exit fullscreen mode

jobId is the useful field. The worker stores it, or uses a database constraint around it, so a retry cannot remove a newly created session that happens to reuse an identifier. The cleanup operation itself should also be idempotent: deleting an already absent presence row is success, and releasing an already released reservation is success.

That is the difference between “the message was delivered” and “the game reached the desired state.” The queue can provide the first property. The application has to design the second.

How should a Node.js setup create and publish a message queue?

Keep the queue behind a narrow interface. This makes the publisher and worker testable without tying the article to a commercial service or a particular broker protocol.

type QueueMessage<T> = {
  receipt: string;
  body: T;
};

interface TaskQueue<T> {
  publish(message: T): Promise<void>;
  receive(): Promise<QueueMessage<T> | undefined>;
  acknowledge(receipt: string): Promise<void>;
  extendVisibility(receipt: string, seconds: number): Promise<void>;
}

async function enqueueSessionCleanup(
  queue: TaskQueue<CleanupMessage>,
  sessionId: string,
  reason: CleanupMessage["reason"],
): Promise<void> {
  const message: CleanupMessage = {
    jobId: crypto.randomUUID(),
    sessionId,
    reason,
    createdAt: new Date().toISOString(),
  };

  await queue.publish(message);
}

async function runCleanupWorker(
  queue: TaskQueue<CleanupMessage>,
  cleanup: (message: CleanupMessage) => Promise<void>,
): Promise<void> {
  for (;;) {
    const item = await queue.receive();
    if (!item) {
      await new Promise((resolve) => setTimeout(resolve, 250));
      continue;
    }

    try {
      await cleanup(item.body);
      await queue.acknowledge(item.receipt);
    } catch (error) {
      console.error("cleanup failed; leaving message for retry", {
        receipt: item.receipt,
        error,
      });
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

The adapter owns persistence, claiming, visibility timeout, and retry policy. The worker owns business correctness. A failed handler deliberately does not acknowledge the message. A broker can then make it visible again after its visibility timeout. A worker crash follows the same path because the acknowledgement never happens. This split trades a little adapter code for a testable worker and a recovery path that does not depend on a request staying open.

The example uses crypto.randomUUID(), so the module also needs the Node.js import below when the file is compiled as a module:

import crypto from "node:crypto";
Enter fullscreen mode Exit fullscreen mode

In a real process, add a shutdown handler that stops taking new messages and waits for the current cleanup to finish. Do not treat process termination as an acknowledgement.

How long should a message stay invisible?

This is where the delivery guarantee turns into an operational number. If a cleanup normally takes 8 seconds but occasionally waits on a database lock for 20, a 10-second visibility window is too short. Another worker can receive the same message while the first one is still changing state. That is a duplicate execution, not necessarily data loss, but it exposes every non-idempotent side effect.

Start with a measured upper bound, add room for the downstream timeout, and extend visibility during unusually long work. The queue documentation for this pattern describes visibility timeout as the period in which a received message is hidden from other consumers; it does not remove the message. An acknowledgement or delete is still required after successful processing.

There is a second limit: a poisoned message should not retry forever. Track receive attempts in the adapter, move messages beyond the retry budget to a dead-letter destination, and alert on that destination. The alert should include jobId, sessionId, and the last error. A dashboard showing only queue depth will miss a queue that is empty because all the bad work has been quarantined.

What breaks first in production?

The first trap is publishing before the match completion is committed. The queue can contain cleanup for a match state that later rolls back. The opposite trap is committing first and crashing before publish. That leaves a finished match with no cleanup message.

For a solo SaaS, I would use an outbox table when the database transaction and the background task must agree. Write the business change and an outbox row in one transaction. A small publisher reads unsent rows, publishes them, and marks them sent. The publisher can repeat its own work, so the outbox message also needs a stable jobId and a consumer that tolerates duplicates. This costs a table and a polling loop. It buys a clear recovery path.

The other failure is a worker that performs three side effects and fails between the second and third. There is no universal rollback for external systems. Break cleanup into independently retryable operations, record progress where useful, and make each operation converge toward the same final state. “Run once” sounds attractive, but “safe to run again” is the property that survives a crash.

Make retries boring.

What I would change at scale

With a few hundred cleanup messages per hour, one worker process and a durable queue are enough. I would spend the next hour on tests: publish failure, crash after receive, timeout during cleanup, duplicate delivery, and dead-letter recovery. Those tests protect more revenue per hour than a custom scheduler.

At higher volume, separate queues by work profile. Presence cleanup and inventory release have different downstream limits, so one busy category should not consume all worker capacity. Add a concurrency cap per dependency, structured logs keyed by jobId, queue age metrics, retry counts, and an alert on oldest-message age. Autoscaling on depth alone is too blunt when each task has a different runtime.

I would also keep the message small. Put identifiers and the reason in the queue; fetch current state in the worker. Large snapshots become stale while waiting and make retries harder to reason about. The trade-off is an extra read. For cleanup, current state is usually the safer input.

The decision rule is straightforward: if losing a cleanup task is acceptable, an in-process timer may be enough. If the task must survive a web process restart, use durable queue storage. If duplicate cleanup would be dangerous, fix idempotency before increasing worker count. Delivery guarantees are selected in the application boundary, then enforced by the queue adapter and the data model.

Sources

Top comments (0)