Best practices to trigger a Firebase Cloud Function just once

Question

I need to trigger a Firebase Cloud Function just once every time a new Firebase Auth user is created. I already wrote a fully working function that sends one email per user using the onCreate trigger. The function sends a welcome email and track some analytics data, so it is not idempotent.

The problem here is that Google arbitrarily calls that function multiple times. This is not a "bug" but an expected behaviour and the dev must handle it.

I want to know what is the best practice to change the "at least once" behaviour to the "exactly once" one.

What happens now:

1. New User "A" signs up.
2. Google fires the "sendWelcomeEmail" for the user A.
3. Google fires the "sendWelcomeEmail" for the user A AGAIN.

What is the best way to run the function just once and abort/skip any other invocation for the same user?

Answer 1

I faced a similar problem and there's no easy solution. I found that for any action that is using an external system it's quite impossible to make such a function idempotent. I'm using TypeScript and Firestore.

For a solution to this problem, you will need to use Firebase transactions. Only using transaction you'll be able to face race conditions which happen when a function is triggered multiple times, usually at the same time.

I found that there are 2 levels of this problem:

1. You don't have an idempotent function, you just need sending email to be idempotent.
2. You have a set of idempotent functions and need to execute some actions that require integration with external systems.

Examples of such integration are:

• sending an email
• connecting to a payment system

---

1. For non-idempotent function (simple case scenario)

async function isFirstRun(user: UserRecord) {
  return await admin.firestore().runTransaction(async transaction => {
    const userReference = admin.firestore().collection('users').doc(user.uid);

    const userData = await transaction.get(userReference) as any
    const emailSent = userData && userData.emailSent
    if (!emailSent) {
      transaction.set(userReference, { emailSent: true }, { merge: true })
      return true;
    } else {
      return false;
    }
  })
}

export const onUserCreated = functions.auth.user().onCreate(async (user, context) => {
  const shouldSendEmail = await isFirstRun(user);
  if (shouldSendEmail) {
    await sendWelcomeEmail(user)
  }
})

P.S. You can also use built-in eventId field to filter out duplicated event fires. See https://cloud.google.com/blog/products/serverless/cloud-functions-pro-tips-building-idempotent-functions. The work required will be comparable – you still have to store already processed actions or events.

---

2. For a set of already idempotent functions (real case scenario)

To make this work with a set of functions that are already idempotent I switched to the queuing system. I push actions to the collection and utilize Firebase Transactions to "lock" execution of the action to only one function at a time.

I'll try to put the minimal example here.

Deploy the action handler function

export const onActionAdded = functions.firestore
  .document('actions/{actionId}')
  .onCreate(async (actionSnapshot) => {
    const actionItem: ActionQueueItem = tryPickingNewAction(actionSnapshot)

    if (actionItem) {
      if (actionItem.type === "SEND_EMAIL") {
        await handleSendEmail(actionItem)
        await actionSnapshot.ref.update({ status: ActionQueueItemStatus.Finished } as ActionQueueItemStatusUpdate)
      } else {
        await handleOtherAction(actionItem)
      }
    }
  });

/** Returns the action if no other Function already started processing it */
function tryPickingNewAction(actionSnapshot: DocumentSnapshot): Promise<ActionQueueItem> {
  return admin.firestore().runTransaction(async transaction => {
    const actionItemSnapshot = await transaction.get(actionSnapshot.ref);
    const freshActionItem = actionItemSnapshot.data() as ActionQueueItem;

    if (freshActionItem.status === ActionQueueItemStatus.Todo) {
      // Take this action
      transaction.update(actionSnapshot.ref, { status: ActionQueueItemStatus.Processing } as ActionQueueItemStatusUpdate)
      return freshActionItem;
    } else {
      console.warn("Trying to process an item that is already being processed by other thread.");
      return null;
    }
  })
}

Push actions to the collection like this

admin.firestore()
    .collection('actions')
    .add({
      created: new Date(),
      status: ActionQueueItemStatus.Todo,
      type: 'SEND_EMAIL',
      data: {...}
    })

TypeScript definitions

export enum ActionQueueItemStatus {
  Todo = "NEW",
  Processing = "PROCESSING",
  Finished = "FINISHED"
}

export interface ActionQueueItem {
  created: Date
  status: ActionQueueItemStatus
  type: 'SEND_EMAIL' | 'OTHER_ACTION'
  data: EmailActionData
}

export interface EmailActionData {
  subject: string,
  content: string,
  userEmail: string,
  userDisplayName: string
}

You may need to adjust this with richer statuses and their changes, but this approach should work for any case and the code provided should a good starting point. This also doesn't include a mechanism to rerun failed actions, but they are easy to find.

If you know a simpler way of doing this - please tell me how :)

Good luck!