Warn about the importance of catching exceptions in DO alarm handlers

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