Clarify Alarm API behavior for recurring/continuous requests in Durable Objects #19658
Description
Existing documentation URL(s)
https://developers.cloudflare.com/durable-objects/examples/alarms-api/
What changes are you suggesting?
The current documentation for the Alarm API in Durable Objects may lead to misunderstanding about its behavior. Specifically, the phrase "wakes the Durable Object once every 10 seconds" suggests that the alarm fires automatically and repeatedly, which is not the case. The alarm only fires if there are continuous requests within the set time frame.
Suggested change:
Replace the current description with a more accurate explanation, such as:
This example implements an alarm() handler that allows batching of requests to a single Durable Object.
When a request is received and no alarm is set, it sets an alarm for 10 seconds in the future. The alarm() handler processes all requests received within that 10-second window.
If no new requests are received, no further alarms will be set until the next request arrives.
Why should the docs be changed?
Prevents misunderstanding of the Alarm API's behavior.
What is the expected outcome?
Developers will have a clear understanding that:
- The alarm is not automatically recurring.
- Alarm firing is dependent on incoming requests.
- There needs to be continuous traffic for the alarm to fire repeatedly.
This clarity will lead to more efficient and correct implementations of batch processing using Durable Objects.
Additional information
The current implementation in the example code correctly demonstrates the behavior, but the accompanying explanation doesn't accurately reflect this behavior. This discrepancy between the code and the explanation is what led to the misunderstanding.
It might be helpful to add a note explicitly stating that the alarm does not automatically recur without new incoming requests, to further emphasize this important aspect of the Alarm API's behavior.