The Outbox and Idempotency

// BROKEN: two systems, no shared transaction. Both orderings have a hole.
await db.order.update({ where: { id }, data: { status: 'PLACED' } });
await broker.publish('order.placed', { orderId: id }); // may never happen

// OUTBOX: the message is a row in the same transaction as the state change,
// so either both are durable or neither is.
await db.$transaction(async (tx) => {
  await tx.order.update({ where: { id }, data: { status: 'PLACED' } });
  await tx.outbox.create({
    data: {
      id: messageId,           // stable, so a redelivery is detectable
      type: 'order.placed',
      payload: { orderId: id },
      createdAt: new Date(),
    },
  });
});

// A separate relay reads unpublished outbox rows, publishes them, and marks
// them sent. If it crashes after publishing but before marking, the message
// is delivered twice — which is exactly why consumers must be idempotent.

export async function handleOrderPlaced(message: Message): Promise<void> {
  await db.$transaction(async (tx) => {
    try {
      // The unique constraint is the actual guard. An if-then check would
      // race: two concurrent deliveries can both read "not processed".
      await tx.processedMessage.create({
        data: { messageId: message.id, consumer: 'billing', at: new Date() },
      });
    } catch (error) {
      if (isUniqueViolation(error)) return; // already handled; safe to drop
      throw error;
    }

    await tx.invoice.create({ data: invoiceFrom(message.payload) });
  });
}

// Note what makes this correct: the marker and the effect are written in the
// same transaction. Marking first and acting afterwards loses the work when
// the process dies in between.