All jobs

Turn On Safe Retries for Event-Driven Firebase Cloud Functions

Yes. An agent enables retries on your 2nd gen event functions, makes each handler idempotent with an event age cut-off, adds tests and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent clones the functions code and reads each handler for what happens if it runs twice. In a repository like firebase/functions-samples, the 2nd gen Node samples pin firebase-functions 7.4 and firebase-admin 14.5 on Node 24, and not one event-driven handler sets retry; the only retry configuration in the tree is the retryConfig on the task queue function in taskqueues-backup-images. quickstarts/uppercase-firestore/functions/index.js reacts to onDocumentCreated("/messages/{documentId}") with event.data.ref.set({uppercase}, {merge: true}), which is safe to repeat. quickstarts/thumbnails/functions/index.js reacts to onObjectFinalized, downloads the image, resizes it with sharp and saves thumb_<name> next to it, also safe to repeat but it returns early when contentType is not an image. fcm-notifications/functions/index.js reacts to onValueWritten on /followers/{followedUid}/{followerUid} and sends a push notification to every token, which a second run would send again. alerts-to-discord/functions/index.js posts to a Discord webhook and already catches its own errors, so a retry would never fire.

It then turns retries on only where a repeat is harmless, and makes the others harmless first. The Firestore and Storage handlers get retry: true in their options object, next to the existing cpu: 2 on the thumbnail function, and each gains a guard at the top that reads the CloudEvent's time, compares it to now and returns after logging when the event is older than a limit the agent sets per function, because a 2nd gen function with retries enabled is retried for up to 24 hours and a thumbnail for an object deleted hours ago should not keep failing. The notification handler is made idempotent before it is allowed to retry: the agent writes a marker keyed on the event id under the followed user's node in a transaction and skips the send when the marker exists, so a retried event never produces a second push. The Discord handler is left as it is, with a note that its catch-all means retries would not change its behaviour.

Each change is explained where the next reader will look: a comment above each retry: true naming the failure it is meant to cover, such as a Storage download that returns a transient error, and a short section in each sample's README on the event age limit and how to change it. The agent does not touch HTTP, callable or scheduled functions, which have no retry option, and says so.

It proves the behaviour with the test setup the repository already uses. test-functions-jest/functions wraps a function with firebase-functions-test and spies on logger, so the agent adds tests in the same shape beside the changed handlers: a wrapped makeuppercase called twice with the same event writes the same document twice without error, a wrapped generateThumbnail with an event time past the limit logs and returns before touching Storage, and the notification handler with a pre-existing marker sends nothing. It runs each sample's npm run lint with the Google ESLint config that --max-warnings=0 enforces and the new Jest tests; a deploy is left to the reviewer, because the sandbox has no Firebase project credentials.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Enable retries safely on the 2nd gen event-driven Cloud Functions in this repository. Read every functions index file and its package.json first, and classify each event handler as safe to repeat, unsafe to repeat, or already swallowing its own errors. For safe handlers add retry: true to the options object and a guard that logs and returns when the event's time is older than a limit you choose per function. For unsafe handlers add an idempotency marker keyed on the event id, written transactionally, before enabling retries. Leave HTTP, callable and scheduled functions alone and say why. Add Jest tests with firebase-functions-test that call each changed handler twice with the same event and once with a stale event, run lint and the tests, and open a pull request with the handler table and the command output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes the Firestore, Storage and Realtime Database handlers, adds a Jest test file and the firebase-functions-test dev dependency beside each, and extends the sample READMEs. The description has a table of every event handler: safe, unsafe or self-handling, whether retry is now on, the event age limit, and the marker path for the handler that needed one.

The run's record keeps each npm run lint pass under the zero-warning rule and the Jest output showing the double-delivery and stale-event cases, so a reviewer reads the assertions rather than a promise that the handlers are idempotent.

Before merging, a reviewer checks the event age limits against how long a real outage might last, confirms the marker path in the Realtime Database is covered by the security rules, and deploys to a staging project where a deliberately thrown error shows the retry arriving.

Run it on every Linear issue labelled functions

An automation in the functions repository's Project with a linear trigger on linear.issue.labeled and the label functions starts one run per labelled issue, with the issue added after the prompt. An issue that names one handler and the failure it keeps hitting narrows the run to that handler, while an issue with no detail gets the whole classification.

The automation's max_runs_per_hour cap keeps a burst of labelled issues from starting more runs than the team can review, and each run reads the handlers afresh rather than reusing another run's table.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Retries are one option flag and a lot of judgement: which handler can run twice, which one sends a notification twice, and how long a retry loop should be allowed to run for an event that will never succeed. The agent reads every handler in its own sandbox, decides per function, and writes the test that calls the handler twice before a person reviews it.

On Rush the lint and test output sit in the run's record next to the pull request, and a follow-up to the same run can change an age limit or add a handler without starting over. One request covers every functions codebase a team deploys, each with its own table.

Frequently asked questions

Why not just set retry: true on every event function?

Because a retried function runs again from the start, and a handler that sends a notification or charges a card would do it twice. Retries are only safe once the handler is idempotent, so the agent makes that change first and turns retries on second.

Why the event age guard?

A 2nd gen function with retries on is retried for up to 24 hours. Without a cut-off, an event that can never succeed, such as a thumbnail for an object that was deleted, fails for a day. The guard reads the event's time and stops cleanly after the limit you set.

Does this apply to HTTP or callable functions?

No. Retries are for event-driven functions on Firestore, Realtime Database, Storage, Pub/Sub and similar triggers. An HTTP caller already decides whether to retry, so the agent leaves onRequest and onCall functions untouched and says so in the pull request.

What signals a failure so a retry happens?

A rejected promise or an unhandled thrown error. A handler that catches everything and logs, like the Discord alert sample, never fails from the platform's point of view, so enabling retries on it changes nothing. The agent points that out instead of changing its error handling.

More Firebase Cloud Functions jobs

The same job on other stacks

Keep reading