@gjermundgaraba/effect-actions-cloudflare 0.21.0 → 0.22.0

package/dist/ActionDurableObject.d.mts

@@ -86,7 +86,7 @@ export interface Options<S = never, SE = never, SR = never, A = never, E = never
    *
    * - A failure is logged and retried 2 seconds later, doubling, six times, as the runtime retries a plain object's alarm, then hourly until a run succeeds, never dropped: the object's `alarm` resolves, so the runtime records no failure.
    * - A run an eviction, a deploy or a crash cuts off runs again at its retry's time, counted in `retryCount` as a failure, so a run may repeat: make what it sends idempotent.
-   * - It runs once per `Alarm.set`: setting a time again replaces it, so a store setting it for its next expiry sets the earliest, and the option sets its next one itself.
+   * - It runs once for every time `Alarm.set` gave before its run, at the earliest: the option sets its next one itself.
    */
   readonly alarm?: ((info: AlarmInvocationInfo) => Effect.Effect<void, AE, AR>) | undefined;
   /**

package/dist/alarm.d.mts

@@ -1,22 +1,31 @@
 import { State } from "./state.mjs";
 import { Context, DateTime, Effect, Layer } from "effect";
 declare const Alarm_base: Context.ServiceClass<Alarm, "effect-actions-cloudflare/ActionDurableObject/Alarm", {
-  /** Runs the object's `alarm` option at `at`, in place of any time set before. */
+  /**
+   * Runs the object's `alarm` option no later than `at`: the earliest time set since it last
+   * ran, or a failed run's retry if earlier, so each deadline sets its own. A failed run's
+   * retry stays unless it was cleared as it ran with no time set afterwards, or a time set as
+   * it ran is earlier.
+   *
+   * **Gotchas**
+   *
+   * - A later time leaves an earlier one in place, so the option runs early: postpone with `clear`, then `set`.
+   */
   readonly set: (at: DateTime.DateTime) => Effect.Effect<void>;
   /** Cancels the time set, if any. */
   readonly clear: Effect.Effect<void>;
 }>;
 /**
- * When the object's `alarm` option runs: `set(at)` schedules it, replacing an earlier time, and
- * `clear` cancels it. A startup service of the object's services, routes, calls and `run`, as
- * `State` is. The object's one runtime alarm is the package's, set for the earliest of the
- * times it keeps, the package's own work among them, so an application never sets it itself.
+ * When the object's `alarm` option runs: `set(at)` has it run no later than `at`, and `clear`
+ * cancels it. A startup service of the object's services, routes, calls and `run`, as `State`
+ * is. The object's one runtime alarm is the package's, set for the earliest of the times it
+ * keeps, the package's own work among them, so an application never sets it itself.
  *
  * **Gotchas**
  *
  * - `State`'s `storage.setAlarm` replaces the package's alarm: the times it keeps then run at that alarm, early or late, or never, and the `alarm` option runs only for a time `Alarm.set` gave, so schedule with `Alarm`.
  * - A firing before every time it keeps, as a repeated one or `runDurableObjectAlarm` in a test, runs none and sets the alarm again: a test runs a time once it has come.
- * - A time already past runs at once; the option runs once per `set`, and sets its next itself.
+ * - A time already past runs at once; the option runs once for every time set before its run, and sets its next itself.
  * - The times live in the object's storage, under `effect-actions/alarm/`, beside the application's data: a store deleting every key deletes them too.
  */
 export declare class Alarm extends Alarm_base {

package/dist/alarm.mjs

@@ -3,10 +3,10 @@ import { Clock, Context, DateTime, Effect, Exit, Layer, Option, Schema, Semaphor
 // src/durable/alarm.ts
 /** Where the object's alarm times are kept, one key per owner. */
 const alarmPrefix = "effect-actions/alarm/";
+const keyOf = (owner) => `${alarmPrefix}${owner}`;
 const Kept = Schema.Struct({
 	at: Schema.Finite,
-	failures: Schema.Int,
-	running: Schema.optional(Schema.Boolean)
+	failures: Schema.Int
 });
 const keptOf = Schema.decodeUnknownOption(Kept);
 const backoffRetries = 6;
@@ -20,6 +20,8 @@ const retryDelay = (failures) => failures > backoffRetries ? hour : 2e3 * 2 ** (
 const makeSchedule = (state) => {
 	const { storage } = state;
 	const lock = Semaphore.makeUnsafe(1);
+	const running = /* @__PURE__ */ new Set();
+	const read = (owner) => Effect.map(Effect.promise(async () => await storage.get(keyOf(owner))), keptOf);
 	const times = Effect.promise(async () => await storage.list({ prefix: alarmPrefix })).pipe(Effect.map((listed) => [...listed].flatMap(([key, value]) => Option.match(keptOf(value), {
 		onNone: () => [],
 		onSome: (kept) => [{
@@ -34,48 +36,61 @@ const makeSchedule = (state) => {
 		});
 	});
 	const keep = (owner, kept) => Effect.promise(async () => {
-		await storage.put(`${alarmPrefix}${owner}`, kept);
+		await storage.put(keyOf(owner), kept);
 	});
 	return {
 		rearm,
 		restore: lock.withPermits(1)(Effect.flatMap(Effect.promise(async () => await storage.getAlarm()), (alarm) => alarm === null ? Effect.flatMap(times, (kept) => kept.length === 0 ? Effect.void : rearm) : Effect.void)),
-		set: (owner, at) => lock.withPermits(1)(Effect.flatMap(Effect.promise(async () => await storage.get(`${alarmPrefix}${owner}`)), (stored) => Option.exists(keptOf(stored), (kept) => kept.at === at && kept.failures === 0 && kept.running !== true) ? Effect.void : Effect.andThen(keep(owner, {
+		/**
+		* Keeps `at` as the owner's time, in place of any: set as the owner's run fails, it gives way
+		* to that run's retry where the retry is earlier.
+		*/
+		set: (owner, at) => lock.withPermits(1)(Effect.flatMap(read(owner), (kept) => Option.exists(kept, (held) => held.at === at && held.failures === 0) ? Effect.void : Effect.andThen(keep(owner, {
+			at,
+			failures: 0
+		}), rearm))),
+		/**
+		* Keeps `at` as the owner's time unless an earlier one is kept, a retry due included: the
+		* mark of the owner's run under way is no time, so a time set from the run is kept.
+		*/
+		setBy: (owner, at) => lock.withPermits(1)(Effect.flatMap(read(owner), (kept) => Option.exists(kept, (held) => held.at <= at && (held.failures === 0 || !running.has(owner))) ? Effect.void : Effect.andThen(keep(owner, {
 			at,
 			failures: 0
 		}), rearm))),
-		clear: (owner) => lock.withPermits(1)(Effect.andThen(Effect.promise(async () => await storage.delete(`${alarmPrefix}${owner}`)), rearm)),
+		clear: (owner) => lock.withPermits(1)(Effect.andThen(Effect.promise(async () => await storage.delete(keyOf(owner))), rearm)),
 		/**
-		* Runs each owner whose time has come as its turn comes, removing its time once its run ends
-		* unless one was set or cleared as it ran: one that fails is logged and retried, 2 seconds
-		* later, doubling, six times, then hourly.
+		* Runs each owner whose time has come as its turn comes, removing its time once its run
+		* succeeds unless one was set or cleared as it ran: one that fails is logged and retried, 2
+		* seconds later, doubling, six times, then hourly, unless cleared as it ran or a time set as
+		* it ran is earlier.
 		*/
 		runDue: (owners) => Effect.gen(function* () {
 			const now = yield* Clock.currentTimeMillis;
 			const kept = yield* times;
 			yield* Effect.forEach(kept.filter(({ at }) => at <= now), ({ owner }) => Effect.gen(function* () {
-				const key = `${alarmPrefix}${owner}`;
 				const run = owners[owner];
-				const stored = Effect.map(Effect.promise(async () => await storage.get(key)), (value) => Option.getOrUndefined(keptOf(value)));
-				const drop = Effect.promise(async () => await storage.delete(key));
+				const stored = Effect.map(read(owner), Option.getOrUndefined);
+				const drop = Effect.promise(async () => await storage.delete(keyOf(owner)));
 				const due = yield* lock.withPermits(1)(Effect.gen(function* () {
 					const current = yield* stored;
 					if (current === void 0 || current.at > now) return;
 					if (run === void 0) return yield* Effect.as(drop, void 0);
-					const startedAt = yield* Clock.currentTimeMillis;
-					yield* keep(owner, {
-						at: startedAt + retryDelay(current.failures + 1),
-						failures: current.failures + 1,
-						running: true
-					}).pipe(Effect.andThen(rearm), Effect.andThen(Effect.promise(async () => {
+					const mark = {
+						at: (yield* Clock.currentTimeMillis) + retryDelay(current.failures + 1),
+						failures: current.failures + 1
+					};
+					yield* keep(owner, mark).pipe(Effect.andThen(rearm), Effect.andThen(Effect.promise(async () => {
 						await storage.sync();
 					})));
+					running.add(owner);
 					return {
 						...current,
+						mark,
 						run
 					};
 				}));
 				if (due === void 0) return;
-				const { at, failures } = due;
+				const { at, failures, mark } = due;
 				const attempt = failures + 1;
 				const exit = yield* Effect.exit(due.run({
 					retryCount: failures,
@@ -84,14 +99,24 @@ const makeSchedule = (state) => {
 				}));
 				if (Exit.isFailure(exit)) yield* Effect.logError(`The alarm of ${owner} failed: retried in ${retryDelay(attempt)} ms`, exit.cause);
 				const endedAt = yield* Clock.currentTimeMillis;
-				yield* lock.withPermits(1)(Effect.flatMap(stored, (current) => {
-					if (current?.running !== true) return Effect.void;
-					return Exit.isSuccess(exit) ? drop : keep(owner, {
+				yield* lock.withPermits(1)(Effect.gen(function* () {
+					running.delete(owner);
+					const current = yield* stored;
+					const isMark = current?.at === mark.at && current.failures === mark.failures;
+					if (Exit.isSuccess(exit)) {
+						if (isMark) yield* drop;
+						return;
+					}
+					if (current === void 0) return;
+					const retry = {
 						at: endedAt + retryDelay(attempt),
 						failures: attempt
-					});
+					};
+					if (isMark || retry.at < current.at) yield* keep(owner, retry);
 				}));
-			}), { discard: true });
+			}).pipe(Effect.ensuring(Effect.sync(() => {
+				running.delete(owner);
+			}))), { discard: true });
 			yield* lock.withPermits(1)(rearm);
 		})
 	};
@@ -100,20 +125,20 @@ const makeSchedule = (state) => {
 const applicationOwner = "application";
 /** The application's alarm over `schedule`, the instance's. */
 const alarmOf = (schedule) => Alarm.of({
-	set: (at) => schedule.set(applicationOwner, DateTime.toEpochMillis(at)),
+	set: (at) => schedule.setBy(applicationOwner, DateTime.toEpochMillis(at)),
 	clear: schedule.clear(applicationOwner)
 });
 /**
-* When the object's `alarm` option runs: `set(at)` schedules it, replacing an earlier time, and
-* `clear` cancels it. A startup service of the object's services, routes, calls and `run`, as
-* `State` is. The object's one runtime alarm is the package's, set for the earliest of the
-* times it keeps, the package's own work among them, so an application never sets it itself.
+* When the object's `alarm` option runs: `set(at)` has it run no later than `at`, and `clear`
+* cancels it. A startup service of the object's services, routes, calls and `run`, as `State`
+* is. The object's one runtime alarm is the package's, set for the earliest of the times it
+* keeps, the package's own work among them, so an application never sets it itself.
 *
 * **Gotchas**
 *
 * - `State`'s `storage.setAlarm` replaces the package's alarm: the times it keeps then run at that alarm, early or late, or never, and the `alarm` option runs only for a time `Alarm.set` gave, so schedule with `Alarm`.
 * - A firing before every time it keeps, as a repeated one or `runDurableObjectAlarm` in a test, runs none and sets the alarm again: a test runs a time once it has come.
-* - A time already past runs at once; the option runs once per `set`, and sets its next itself.
+* - A time already past runs at once; the option runs once for every time set before its run, and sets its next itself.
 * - The times live in the object's storage, under `effect-actions/alarm/`, beside the application's data: a store deleting every key deletes them too.
 */
 var Alarm = class Alarm extends Context.Service()("effect-actions-cloudflare/ActionDurableObject/Alarm") {

package/docs/ActionDurableObject.md

@@ -224,7 +224,7 @@ Give each of a binding's contracts a key of its input, `rooms` in `routes.ts` ab
 
 ## Run an alarm
 
-Give `make` an `alarm`, and set when it runs from a handler or a store with the `Alarm` service: the room's store sets it for the oldest message's expiry and, each run, for the next ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), and `worker.ts` above gives the alarm the store the routes read. How it runs, and how a failure is retried, are on `ActionDurableObject.Options`' `alarm`; why `State`'s `storage.setAlarm` is not the way, on `ActionDurableObject.Alarm`.
+Give `make` an `alarm`, and set when it runs from a handler or a store with the `Alarm` service, which keeps the earliest time it is given: the room's store sets it for each message's expiry as it is posted and, each run, for the oldest left ([chat-rooms/src/platform/sql-store.ts](../examples/chat-rooms/src/platform/sql-store.ts)), and `worker.ts` above gives the alarm the store the routes read. How it runs, and how a failure is retried, are on `ActionDurableObject.Options`' `alarm`; how to postpone it, and why `State`'s `storage.setAlarm` is not the way, on `ActionDurableObject.Alarm`.
 
 ## Call an object from a Worker
 

package/examples/chat-rooms/src/platform/sql-store.ts

@@ -30,17 +30,16 @@ export const layerSql = Layer.effect(MessageStore)(
       "CREATE TABLE IF NOT EXISTS messages (id INTEGER PRIMARY KEY AUTOINCREMENT, author TEXT NOT NULL, text TEXT NOT NULL, at INTEGER NOT NULL)"
     );
 
-    // Every post looks up the oldest message: indexed, it reads one row, where a scan would read
+    // Every expiry looks up the oldest message: indexed, it reads one row, where a scan would read
     // the whole table, and SQLite storage is billed by rows read.
     storage.sql.exec(
       "CREATE INDEX IF NOT EXISTS messages_by_at ON messages (at)"
     );
 
-    // The room's alarm is due no later than the oldest message's expiry: `post` and `expire` set
-    // it for the oldest message, read from the table and set in one step, so posts running at
-    // once each set it for the oldest they see, and the last to set it has seen them all; reading
-    // the alarm first would let two posts both see none and the later one win. Removing the
-    // oldest message leaves its alarm, which then finds nothing due and moves on.
+    // The room's alarm is due no later than the oldest message's expiry: `Alarm.set` keeps the
+    // earliest time it is given, so each post sets its own message's, and `expire`, which runs on
+    // the alarm, sets the next from the oldest message left. Removing the oldest message leaves
+    // its alarm, which then finds nothing due and moves on.
     const alarmForOldest = Effect.suspend(() => {
       const [oldest] = query("SELECT * FROM messages ORDER BY at LIMIT 1");
 
@@ -82,7 +81,7 @@ export const layerSql = Layer.effect(MessageStore)(
             .one()
         );
 
-        yield* alarmForOldest;
+        yield* alarm.set(DateTime.makeUnsafe(message.at + day));
 
         return message;
       }),

package/examples/chat-rooms/test/worker.test.ts

@@ -7,7 +7,7 @@ import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
 import { evictDurableObject, runInDurableObject } from "cloudflare:test";
 import { env, exports } from "cloudflare:workers";
 import type { Schema } from "effect";
-import { Effect, Schedule, Stream } from "effect";
+import { DateTime, Effect, Schedule, Stream } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { TestClock } from "effect/testing";
 
@@ -536,21 +536,28 @@ describe("the Worker and its rooms", () => {
           text: "From yesterday.",
         });
 
+        const recent = yield* json.postMessage({
+          room: "design",
+          text: "From today.",
+        });
+
+        // A day passes for the first message alone: it is backdated, and the alarm set for its
+        // expiry, as its post would have set it a day ago. That time is past, so the runtime runs
+        // it at once: the test waits until it has set the next, for the recent one's.
         yield* Effect.promise(async () => {
-          await runInDurableObject(stub, (_, state) => {
+          await runInDurableObject(stub, async (room, state) => {
             state.storage.sql.exec(
               "UPDATE messages SET at = at - ? WHERE id = ?",
               day,
               old.id
             );
-          });
-        });
 
-        // The next post sets the alarm for the day-old message's expiry, already past, so the
-        // runtime runs it at once: the test waits until it has set the next, for the recent one's.
-        const recent = yield* json.postMessage({
-          room: "design",
-          text: "From today.",
+            await room.run(
+              ActionDurableObject.Alarm.use((alarm) =>
+                alarm.set(DateTime.makeUnsafe(old.at))
+              )
+            );
+          });
         });
 
         yield* eventually(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions-cloudflare",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Serve effect-actions from Cloudflare Durable Objects, with Effect RPC over hibernating WebSockets.",
   "keywords": [
     "cloudflare",
@@ -39,11 +39,11 @@
     "@cloudflare/vitest-plugin": "1.4.7",
     "@cloudflare/workers-types": "5.20261025.1",
     "@effect/vitest": "4.0.6",
-    "@gjermundgaraba/effect-actions": "0.21.0",
+    "@gjermundgaraba/effect-actions": "0.22.0",
     "effect": "4.0.6"
   },
   "peerDependencies": {
-    "@gjermundgaraba/effect-actions": "^0.21.0",
+    "@gjermundgaraba/effect-actions": "^0.22.0",
     "effect": "~4.0.5"
   },
   "scripts": {

package/examples/chat-rooms/node_modules/.vite/vitest/CACHEDIR.TAG

@@ -1,3 +0,0 @@
-Signature: 8a477f597d28d172789f06886806bc55
-# This file is a cache directory tag created by Vitest.
-# For information about cache directory tags see https://bford.info/cachedir/

package/examples/chat-rooms/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +0,0 @@
-{"version":1,"projects":{"":{"files":{"test/worker.test.ts":{"failed":false,"duration":3218,"lastRun":1793050877213},"test/platform/sql-store.test.ts":{"failed":false,"duration":405,"lastRun":1793050877213}}}}}