Dev.to WebDev ๐Ÿ›  Dev ๐Ÿ‘ 0 ๐Ÿ“– 5 min read

Build a Crash-Safe Scheduled Publisher with Leases and Reconciliation

Build a Crash-Safe Scheduled Publisher with Leases and Reconciliation A scheduler that runs once is easy. A scheduler that can run twice, overlap with itself, lose a network response, and still avoid duplicate public p

Build a Crash-Safe Scheduled Publisher with Leases and Reconciliation

A scheduler that runs once is easy. A scheduler that can run twice, overlap with itself, lose a network response, and still avoid duplicate public posts needs a more deliberate design.

This guide builds a small Node.js publishing worker around three ideas: stable delivery identities, expiring leases, and remote reconciliation. The examples use generic adapters so that the same control flow can be applied to any publishing API that can list or retrieve posts. They are intentionally focused on delivery safety rather than text generation.

Start with a durable delivery identity

Do not use a workflow run number as the identity of a post. Retries receive new run numbers, so the same intended publication would appear new.

Instead, derive a stable key from the reviewed content item and its destination:

import {createHash} from "node:crypto";

function deliveryKey({contentId, platform, accountId}) {
  return createHash("sha256")
    .update(`${contentId}\0${platform}\0${accountId}`)
    .digest("hex");
}

Store a unique record for that key. A useful record has a state, lease owner, lease expiry, external ID, public URL and last error. The database must enforce the unique key; checking in application code is not enough when two workers start together.

Claim one item with an expiring lease

A worker should claim an approved delivery atomically. In SQL, that can be an update whose condition proves the item is still available:

UPDATE deliveries
SET state = 'claimed',
    lease_owner = :worker_id,
    lease_until = :lease_until
WHERE delivery_key = :delivery_key
  AND state = 'approved';

Continue only when exactly one row changed. A second worker attempting the same claim receives zero changed rows and skips it.

The lease prevents a crashed process from blocking the item forever. However, lease expiry is not permission to publish again. The crashed worker may have completed the remote write before dying. An expired claim must enter reconciliation first.

Record stages, not one success flag

Model the important states explicitly:

  • approved: editorially reviewed and eligible.
  • claimed: owned temporarily by one worker.
  • publishing: the remote request may have been sent.
  • published: confirmed by an external ID.
  • uncertain: the request outcome is unknown.
  • rejected: the remote service definitively refused it.

This distinction changes retry behaviour. A validation error before the request can return to an editorial or repair queue. A timeout after bytes were sent becomes uncertain and must not trigger an immediate second POST.

Separate the remote adapter from orchestration

Give every platform adapter the same narrow contract:

class PublisherAdapter {
  async create(delivery) {}
  async getByExternalId(externalId) {}
  async findByDeliveryKey(deliveryKey, options) {}
}

The create method should return the platform's real identifier and, when available, its public URL. The lookup must be scoped to the intended account. If it scans history, it must paginate until it either finds a match or reaches a documented boundary.

A result such as {complete: false} is important. Authentication failure, a truncated page sequence, or a rate limit means the worker did not prove absence.

Reconcile before any retry

The recovery path should prefer the strongest available evidence:

async function reconcile(delivery, adapter, store) {
  if (delivery.externalId) {
    const post = await adapter.getByExternalId(delivery.externalId);
    if (post) return store.confirmPublished(delivery.id, post);
  }

  const scan = await adapter.findByDeliveryKey(delivery.deliveryKey, {
    maxAgeHours: 48,
    paginate: true
  });

  if (!scan.complete) {
    return store.markUncertain(delivery.id, "remote history incomplete");
  }

  if (scan.match) {
    return store.confirmPublished(delivery.id, scan.match);
  }

  return store.returnForReviewedRetry(delivery.id);
}

The method deliberately does not publish. It establishes whether the first attempt already produced a remote object. Only a confirmed complete search with no match makes the delivery eligible for a reviewed retry.

If the platform supports idempotency keys for create operations, use the stable delivery key according to that API's documented scope and expiry. Do not assume that adding a custom HTTP header provides idempotency.

Make scheduled runs safe to overlap

GitHub Actions can reduce overlap with a concurrency group:

concurrency:
  group: scheduled-publisher
  cancel-in-progress: false

That is useful but insufficient as the only guard. A manually dispatched run, another repository, or an interrupted runner may bypass the assumption. The durable claim remains the authority.

Schedules can also be delayed. Select work from explicit eligibility rules, not from an exact minute comparison. If the business rule allows one item per day, use a destination-local date key and check confirmed remote history before writing. Do not publish several missed slots merely because the scheduler woke up late.

Preserve evidence in the right order

After a successful create response, save the external ID before performing optional work such as analytics tagging or a dashboard refresh. If the database update fails, write non-secret recovery evidence to durable logs.

Never invent a public URL from an assumed pattern. Some APIs return only an ID; in that case, query the resource or account feed. Report the ID as confirmed and the public URL as pending verification.

A workflow exit code describes job health. A publication receipt requires a remote ID. Keep those two facts separate in summaries.

Test failures at every boundary

A useful test adapter counts write calls and can simulate failure after the remote object is created:

const adapter = new FakeAdapter({
  createThenThrow: new Error("socket closed")
});

await runOnce();
await recoverExpiredClaims();
expect(adapter.createCalls).toBe(1);
expect(store.delivery.state).toBe("published");

Also test two concurrent claims, an expired lease with no remote match, an incomplete paginated scan, a definitive rejection, and a successful write followed by failed local persistence. Assert the number of remote writes, not merely the worker's final exit status.

Operational checklist

Before enabling a schedule:

  1. Confirm that only editorially approved content can be selected.
  2. Enforce a unique delivery key in durable storage.
  3. Verify that two concurrent workers produce at most one remote write.
  4. Confirm that dry run performs no claim or create request.
  5. Test a create-then-timeout response and reconcile it without duplication.
  6. Verify paginated history for the correct destination account.
  7. Require a real external ID before reporting a publication.
  8. Keep tokens out of logs and give them only the permissions required.

A reliable publisher is not one that never fails. It is one that can explain what happened, preserve uncertainty, and recover without turning an infrastructure failure into a duplicate public post.

Shop Daniel Mason

๐Ÿ“ฐ Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes โ€” full credit and traffic to the original publisher.