Warn about the importance of catching exceptions in DO alarm handlers

Since otherwise a series of repeated uncaught exceptions can cause
alarms to stop getting retried. That behavior was documented, but it
isn't obvious that that means you may want to be careful about catching
exceptions and scheduling your own new alarms.

Author: a-robinson

src/content/docs/durable-objects/api/alarms.mdx

@@ -123,6 +123,12 @@ This is due to the fact that, if the Durable Object wakes up after being inactiv
 
   - This method can be `async`.
 
+:::note[Catching exceptions in alarm handlers]
+
+Because alarms are only retried up to 6 times on error, it's recommended to catch any exceptions inside your `alarm()` handler and schedule a new alarm before returning if you want to make sure your alarm handler will be retried indefinitely. Otherwise, a sufficiently long outage in a downstream service that you depend on or a bug in your code that goes unfixed for hours can exhaust the limited number of retries, causing the alarm to not be re-run in the future until the next time you call `setAlarm`.
+
+:::
+
 ## Example
 
 This example shows how to both set alarms with the `setAlarm(timestamp)` method and handle alarms with the `alarm()` handler within your Durable Object.

src/content/docs/durable-objects/best-practices/rules-of-durable-objects.mdx

@@ -1318,7 +1318,7 @@ export class GameMatch extends DurableObject<Env> {
     }
 
     // Called when the alarm fires
-    async alarm() {
+    async alarm(alarmInfo) {
     	const isActive = await this.ctx.storage.get<boolean>("gameActive");
 
     	if (!isActive) {
@@ -1330,7 +1330,17 @@ export class GameMatch extends DurableObject<Env> {
     	await this.ctx.storage.put("gameEnded", Date.now());
 
     	// Calculate final scores, notify players, etc.
-    	await this.calculateFinalScores();
+        try {
+            await this.calculateFinalScores();
+        } catch (err) {
+            // If we're almost out of retries but still have work to do, schedule a new alarm
+            // rather than letting our retries run out to ensure we keep getting invoked.
+            if (alarmInfo.retryCount >= 5) {
+                await this.ctx.storage.setAlarm(Date.now() + 30 * 1000);
+                return;
+            }
+            throw err;
+        }
 
     	// Schedule the next alarm only if there's more work to do
     	// In this case, schedule cleanup in 24 hours