[iennae]

Description

Adds cloudscheduler_deduplicate_job_requests, a Cloud Run function that does a Cloud Scheduler job's work once per scheduled run, even when Cloud Scheduler delivers the same run more than once. This rewrites #14702 by @camiekim, who is credited as co-author, and keeps that PR's region tag so the in-progress "Deduplicate job requests" docs page doesn't need to change.

How it works

• Run identity: The job name plus X-CloudScheduler-ScheduleTime, hashed into a Firestore document ID. The schedule time stays the same across retries, so the header is used exactly as received.
• Transactional claim with a lease:
  • A completed run is skipped and returns 200.
  • A run whose claim is still active returns 409, so retries continue in case that attempt fails.
  • A run whose claim has expired, for example after an attempt crashed, can be claimed again.
• Failure handling: If the work raises an exception, the function deletes the claim and re-raises, so Cloud Scheduler retries the run.
• Cleanup: Records include an expire_at field for a Firestore TTL policy.

Changes from #14702

• Adds a lease, so a crashed attempt no longer blocks retries until TTL cleanup, which can take more than 24 hours. The check runs in a transaction, which avoids the race condition raised in that PR's review.
• Moves the sample to its own directory, cloud_scheduler/deduplicate_job_requests/, as a functions-framework function with its own requirements (google-cloud-firestore 2.34.1), instead of adding Flask and Firestore to snippets/.
• Hashes the run key instead of validating the job name and normalizing timestamps.
• Uses shorter comments. Target-specific details belong on the docs page.

Scope. In testing, HTTP targets received X-CloudScheduler-JobName (the job ID) and X-CloudScheduler-ScheduleTime. The API reference documents the same headers for App Engine targets, so this sample covers both. Pub/Sub messages from Cloud Scheduler carry no run identifier, and Google API targets such as Workflows have no user handler, so those targets are better covered on the docs page. A forced run sends the next scheduled time, so header-based deduplication then skips that scheduled run. A comment in the sample notes this.

Tests (in tests/)

• Unit tests with an in-memory fake Firestore cover these cases, and run without credentials:
  • first delivery
  • duplicate after completion
  • active lease
  • expired lease
  • failed work
  • separate runs
  • missing headers
• Integration tests run the handler against a real Firestore database in Native mode. They're skipped unless RUN_INTEGRATION_TESTS=true; set FIRESTORE_DATABASE to use a named database.

Checklist

Testing

• I have tested this change on a live environment and verified it works as intended. Unit and integration tests pass on Python 3.13, including against a live Firestore database.

Compliance & Style

• I have followed the Sample Guidelines.
• The README is updated with all relevant information (if applicable). Not applicable.
• If this PR adds a new sample directory: I updated the CODEOWNERS file. Not applicable: the new directory is inside cloud_scheduler, which the default owners cover.

---

Post-Approval Actions

• Please merge this PR for me once it is approved

[snippet-bot]

Here is the summary of changes.

You are about to add 1 region tag.

• cloud_scheduler/deduplicate_job_requests/main.py:15, tag cloudscheduler_deduplicate_job_requests

---

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

• Refresh this comment

[gemini-code-assist]

Code Review

This pull request introduces a Cloud Function to deduplicate Cloud Scheduler job requests using Firestore for distributed locking and lease management. The review feedback highlights a potential race condition where a slow worker whose lease has expired could inadvertently overwrite or delete a lease claimed by a subsequent retry. To address this, the reviewer suggests using the lease expiration timestamp as a fencing token and performing both the completion and release operations transactionally, providing concrete code suggestions for the implementation and corresponding test updates.

[XrossFox]

The code LGTM, but i left a comment.