@gjermundgaraba/effect-actions-cloudflare 0.0.0-stage → 0.22.0

package/dist/alarm.mjs

@@ -0,0 +1,155 @@
+import { State } from "./state.mjs";
+import { Clock, Context, DateTime, Effect, Exit, Layer, Option, Schema, Semaphore } from "effect";
+// 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
+});
+const keptOf = Schema.decodeUnknownOption(Kept);
+const backoffRetries = 6;
+const hour = 36e5;
+const retryDelay = (failures) => failures > backoffRetries ? hour : 2e3 * 2 ** (failures - 1);
+/**
+* The object's alarm times, one per owner, kept in its storage: the runtime's one alarm is set
+* for the earliest, and `runDue` runs each owner whose time has come. `handlers` and `make` make
+* one per instance, which its `Alarm` and its `alarm` handler share.
+*/
+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) => [{
+			owner: key.slice(21),
+			...kept
+		}]
+	}))));
+	const rearm = Effect.flatMap(times, (kept) => {
+		const earliest = Math.min(...kept.map(({ at }) => at));
+		return Effect.promise(async () => {
+			await (Number.isFinite(earliest) ? storage.setAlarm(earliest) : storage.deleteAlarm());
+		});
+	});
+	const keep = (owner, kept) => Effect.promise(async () => {
+		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)),
+		/**
+		* 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(keyOf(owner))), rearm)),
+		/**
+		* 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 run = owners[owner];
+				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 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, mark } = due;
+				const attempt = failures + 1;
+				const exit = yield* Effect.exit(due.run({
+					retryCount: failures,
+					isRetry: failures > 0,
+					scheduledTime: at
+				}));
+				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.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);
+				}));
+			}).pipe(Effect.ensuring(Effect.sync(() => {
+				running.delete(owner);
+			}))), { discard: true });
+			yield* lock.withPermits(1)(rearm);
+		})
+	};
+};
+/** The owner the application's `alarm` option runs as. */
+const applicationOwner = "application";
+/** The application's alarm over `schedule`, the instance's. */
+const alarmOf = (schedule) => Alarm.of({
+	set: (at) => schedule.setBy(applicationOwner, DateTime.toEpochMillis(at)),
+	clear: schedule.clear(applicationOwner)
+});
+/**
+* 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 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") {
+	/**
+	* The application's alarm, over the schedule of the instance whose `State` it is given.
+	*
+	* **Gotchas**
+	*
+	* - Only `handlers`' and `make`'s `alarm` runs the times it keeps: provide this layer alone only where nothing calls `set`, as to a store under test.
+	* - Each build makes a schedule of its own, which takes no turns with the object's: a `set` through it while the object's alarm runs may be lost, so an object's own code uses the `Alarm` `handlers` and `make` provide.
+	*/
+	static layer = Layer.effect(Alarm)(Effect.map(State, (state) => alarmOf(makeSchedule(state))));
+};
+export { Alarm, alarmOf, alarmPrefix, applicationOwner, makeSchedule };

package/dist/batches.mjs

@@ -0,0 +1,10 @@
+import { Array, Effect } from "effect";
+// src/durable/batches.ts
+/**
+* `keys`, or entries, in the batches one storage call takes: `get`, `put` and `delete` take at
+* most 128 keys each, as Cloudflare's storage API documents, though local workerd takes more.
+*/
+const batches = (keys) => Array.chunksOf(keys, 128);
+/** Deletes `keys` from `storage`, one batch per call. */
+const deleted = (storage, keys) => Effect.forEach(batches(keys), (batch) => Effect.promise(async () => await storage.delete([...batch])), { discard: true });
+export { batches, deleted };

package/dist/calls.d.mts

@@ -0,0 +1,9 @@
+import { Effect, Queue } from "effect";
+import { RpcMessage, RpcSerialization } from "effect/rpc";
+import "@gjermundgaraba/effect-actions/ActionRpc";
+/**
+ * What a call over the stub carries to the object's `effectActionsRpc`: its messages, as values.
+ * A class of its own delegating the method takes it as its parameter,
+ * `effectActionsRpc(request: ActionDurableObject.StubRequest)`.
+ */
+export type StubRequest = readonly RpcMessage.FromClientEncoded[];

package/dist/calls.mjs

@@ -0,0 +1,92 @@
+import { Effect, Predicate, Queue, Schema } from "effect";
+import { RpcMessage, RpcServer } from "effect/rpc";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+// src/durable/calls.ts
+/**
+* The codec of the stub's values: each schema's type to its plain form, `Schema.toCodecIso`, which
+* Workers RPC's structured clone carries as it is, a `Date`, bytes, `undefined` and a `Map` among
+* them, where JSON would encode them again. An `Exit`, a `Cause` and an `Option` encode to their
+* tagged objects, a class instance to its fields.
+*/
+const codecFor = Schema.toCodecIso;
+const encodeDefect = Schema.encodeSync(codecFor(Schema.Defect()));
+/**
+* A unary `RpcServer.Protocol` over the object's stub, passing values, modeled on Effect's HTTP
+* protocol: one call is one client, its requests and their responses, then its end. `serve`
+* answers one call of `effectActionsRpc`, and `served` dies unless a server runs on `protocol`.
+*/
+const makeStubProtocol = Effect.gen(function* () {
+	const context = yield* Effect.context();
+	let running = false;
+	const disconnects = yield* Queue.make();
+	const clients = /* @__PURE__ */ new Map();
+	let nextId = 0;
+	const failPending = (client, defect) => {
+		const requests = [...client.pending.keys()];
+		client.pending.clear();
+		return Queue.offerAll(client.responses, requests.length === 0 ? [defect] : requests.map((id) => RpcMessage.ResponseExitDieEncoded({
+			requestId: RpcMessage.RequestId(id),
+			encodedDefect: defect.defect
+		})));
+	};
+	let serve;
+	const protocol = yield* RpcServer.Protocol.make((write) => {
+		serve = (request) => Effect.gen(function* () {
+			const clientId = nextId;
+			nextId += 1;
+			const client = {
+				responses: yield* Queue.make(),
+				pending: /* @__PURE__ */ new Map()
+			};
+			clients.set(clientId, client);
+			yield* Effect.addFinalizer(() => Effect.sync(() => {
+				clients.delete(clientId);
+				Queue.offerUnsafe(disconnects, clientId);
+			}));
+			yield* Effect.suspend(() => Effect.forEach(request, (message) => {
+				if (Predicate.isTagged(message, "Request")) client.pending.set(message.id, message.tag);
+				return write(clientId, message);
+			}, { discard: true })).pipe(Effect.catchDefect((defect) => failPending(client, RpcMessage.ResponseDefectEncoded(encodeDefect(defect)))));
+			yield* write(clientId, RpcMessage.constEof);
+			return yield* Queue.collect(client.responses);
+		}).pipe(Effect.scoped, Effect.provideContext(context));
+		return Effect.succeed({
+			disconnects,
+			send: (clientId, response) => Effect.suspend(() => {
+				const client = clients.get(clientId);
+				if (client === void 0) return Effect.void;
+				if (Predicate.isTagged(response, "Defect")) return failPending(client, response);
+				if (!Predicate.isTagged(response, "Chunk")) {
+					if (Predicate.isTagged(response, "Exit")) client.pending.delete(response.requestId);
+					return Queue.offer(client.responses, response);
+				}
+				const tag = client.pending.get(response.requestId) ?? "";
+				return failPending(client, RpcMessage.ResponseDefectEncoded(encodeDefect(/* @__PURE__ */ new Error(`The rpc ${tag} streams, and the object's stub is unary: serve streams over layerWebSocket`)))).pipe(Effect.andThen(Queue.end(client.responses)), Effect.andThen(Queue.offer(disconnects, clientId)));
+			}),
+			end: (clientId) => Effect.suspend(() => {
+				const client = clients.get(clientId);
+				return client === void 0 ? Effect.void : Queue.end(client.responses);
+			}),
+			clientIds: Effect.sync(() => new Set(clients.keys())),
+			initialMessage: Effect.succeedNone,
+			supportsAck: false,
+			supportsTransferables: false,
+			supportsSpanPropagation: true,
+			supportsNotifications: false,
+			codecFor
+		});
+	});
+	return {
+		protocol: {
+			...protocol,
+			run: (f) => Effect.suspend(() => {
+				running = true;
+				return protocol.run(f);
+			}),
+			[ActionRpc.unaryProtocol]: true
+		},
+		serve,
+		served: Effect.yieldNow.pipe(Effect.andThen(Effect.suspend(() => running ? Effect.void : Effect.die(/* @__PURE__ */ new Error("No rpc server runs on this object's stub protocol: serve a group over it in make's or handlers' calls, such as RpcServer.layer(group)")))))
+	};
+});
+export { codecFor, makeStubProtocol };

package/dist/events.mjs

@@ -0,0 +1,131 @@
+import { State } from "./state.mjs";
+import { deleted } from "./batches.mjs";
+import { Effect, Function, Layer, Option, Schema, Semaphore } from "effect";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+// src/durable/events.ts
+const Position = Schema.Struct({
+	epoch: Schema.String,
+	last: Schema.Int
+});
+const Stored = Schema.Struct({
+	at: Schema.Finite,
+	key: Schema.optional(Schema.String),
+	eventId: Schema.optional(Schema.String),
+	timestamp: Schema.optional(Schema.DateTimeUtcFromMillis),
+	data: Schema.optional(Schema.Json)
+});
+const positionOf = Schema.decodeUnknownOption(Position);
+const storedOf = Schema.decodeUnknownOption(Stored);
+const encodeStored = Schema.encodeSync(Stored);
+const seqWidth = 16;
+/**
+* A log's storage in the object's, under `effect-actions/log/<event>/`: its position, and each
+* entry by its sequence number, its data encoded as the event's payload JSON.
+*/
+const storageLog = (storage, event) => {
+	const prefix = `effect-actions/log/${event.name}/`;
+	const positionKey = `${prefix}meta`;
+	const entries = `${prefix}entry/`;
+	const entryKey = (seq) => `${entries}${String(seq).padStart(seqWidth, "0")}`;
+	const seqOfKey = (key) => Number(key.slice(entries.length));
+	const codec = Schema.toCodecJson(event.payload);
+	const encode = Schema.encodeUnknownEffect(codec);
+	const decode = Schema.decodeUnknownEffect(codec);
+	const listedOf = (found) => Option.match(found, {
+		onNone: () => Effect.succeed({
+			at: 0,
+			logged: void 0
+		}),
+		onSome: ({ at, key, eventId, timestamp, data }) => Effect.map(data === void 0 ? Effect.succeedNone : Effect.option(decode(data)), (decoded) => ({
+			at,
+			logged: Option.match(decoded, {
+				onNone: Function.constUndefined,
+				onSome: (payload) => ({
+					key,
+					value: {
+						data: payload,
+						eventId,
+						timestamp
+					}
+				})
+			})
+		}))
+	});
+	return {
+		position: Effect.map(Effect.promise(async () => await storage.get(positionKey)), (found) => Option.getOrUndefined(positionOf(found))),
+		put: (position, entry) => Effect.gen(function* () {
+			if (entry === void 0) return yield* Effect.promise(async () => {
+				await storage.put(positionKey, position);
+			});
+			const { at, logged } = entry.stored;
+			const data = yield* encode(logged.value.data).pipe(Effect.catch((error) => Effect.as(Effect.logError(`An occurrence published to the log of event "${event.name}" does not encode as its payload, and is kept as a gap`, error), void 0)));
+			yield* Effect.promise(async () => {
+				await storage.put({
+					[positionKey]: position,
+					[entryKey(entry.seq)]: encodeStored({
+						at,
+						key: logged.key,
+						eventId: logged.value.eventId,
+						timestamp: logged.value.timestamp,
+						data
+					})
+				});
+			});
+		}),
+		list: (from, limit) => Effect.flatMap(Effect.promise(async () => await storage.list({
+			prefix: entries,
+			start: entryKey(from),
+			limit
+		})), (listed) => Effect.forEach(listed, ([key, value]) => Effect.map(listedOf(storedOf(value)), (kept) => [seqOfKey(key), kept]))),
+		delete: (seqs) => deleted(storage, seqs.map(entryKey))
+	};
+};
+const revisionPrefix = "effect-actions/revisions/";
+const epochKey = `${revisionPrefix}epoch`;
+const countPrefix = `${revisionPrefix}count/`;
+const epochOf = Schema.decodeUnknownOption(Schema.String);
+const countOf = Schema.decodeUnknownOption(Schema.Int);
+/**
+* Current sources' revisions in the object's storage, under `effect-actions/revisions/`: an
+* epoch made as the object first builds, and a counter by name.
+*/
+const storageRevisions = (storage) => {
+	const get = (name) => Effect.map(Effect.promise(async () => await storage.get(`${countPrefix}${name}`)), (found) => Option.getOrElse(countOf(found), () => 0));
+	return Effect.gen(function* () {
+		const kept = Option.getOrUndefined(epochOf(yield* Effect.promise(async () => await storage.get(epochKey))));
+		const epoch = kept ?? crypto.randomUUID();
+		if (kept === void 0) yield* Effect.promise(async () => {
+			await storage.put(epochKey, epoch);
+		});
+		const inTurn = Semaphore.withPermit(yield* Semaphore.make(1));
+		return {
+			epoch,
+			get,
+			bump: (names) => Effect.flatMap(Effect.forEach(names, (name) => Effect.map(get(name), (count) => [name, count])), (counts) => Effect.promise(async () => {
+				await storage.put(Object.fromEntries(counts.map(([name, count]) => [`${countPrefix}${name}`, count + 1])));
+			})).pipe(inTurn)
+		};
+	});
+};
+/**
+* The object's `Event.Events`, which `handlers` and `make` provide to the services, calls and
+* routes: each log source's log kept in the object's storage, under `effect-actions/log/`, each
+* current source's revisions beside it, so a cursor outlives an eviction, and a check or current
+* source's subscribers read again when notified, not on its `nextPoll`, a timer that would keep the
+* object from hibernating. Its rules are on `handlers`.
+*/
+const layerEvents = Layer.effect(Event.Events)(Effect.flatMap(State, ({ storage }) => Effect.flatMap(storageRevisions(storage), (revisions) => {
+	const named = /* @__PURE__ */ new Map();
+	return Event.makeEvents({
+		log: (event) => {
+			const prior = named.get(event.name);
+			if (prior !== void 0 && prior !== event) throw new Error(`An object's Event.Events keeps each log source's log in the object's storage by its event's name, and two event types are named "${event.name}" (give each event type a name of its own)`);
+			named.set(event.name, event);
+			return storageLog(storage, event);
+		},
+		polls: false,
+		emits: false,
+		revisions
+	});
+})));
+export { layerEvents };

package/dist/fetcher.d.mts

@@ -0,0 +1,17 @@
+import { Layer } from "effect";
+import { HttpClient } from "effect/http";
+/**
+ * An `HttpClient` whose requests go to `fetcher`, a Durable Object stub or a service binding,
+ * in place of the network: what `ActionHttp.client`, `ActionRpc.client` over
+ * `RpcClient.layerProtocolHttp` and `ActionMcp.client` call an object's routes with, or a
+ * Worker's.
+ *
+ * **Gotchas**
+ *
+ * - A request's URL needs a host, which the fetcher ignores, such as `https://object/api`: a relative URL fails before it is sent.
+ * - Nothing authenticates the request on its way: forward the caller's credential, with the client's `transformClient`, as for any remote surface.
+ * - To pass a page's request on to an object, forward the `Request` itself with the stub's `fetch`: its upgrade goes with it, which this client does not send.
+ *
+ * Guide: `docs/ActionDurableObject.md` in this package.
+ */
+export declare const layerHttpClient: (fetcher: Pick<Fetcher, "fetch">) => Layer.Layer<HttpClient.HttpClient>;

package/dist/fetcher.mjs

@@ -0,0 +1,19 @@
+import { Layer } from "effect";
+import { FetchHttpClient } from "effect/http";
+// src/durable/fetcher.ts
+/**
+* An `HttpClient` whose requests go to `fetcher`, a Durable Object stub or a service binding,
+* in place of the network: what `ActionHttp.client`, `ActionRpc.client` over
+* `RpcClient.layerProtocolHttp` and `ActionMcp.client` call an object's routes with, or a
+* Worker's.
+*
+* **Gotchas**
+*
+* - A request's URL needs a host, which the fetcher ignores, such as `https://object/api`: a relative URL fails before it is sent.
+* - Nothing authenticates the request on its way: forward the caller's credential, with the client's `transformClient`, as for any remote surface.
+* - To pass a page's request on to an object, forward the `Request` itself with the stub's `fetch`: its upgrade goes with it, which this client does not send.
+*
+* Guide: `docs/ActionDurableObject.md` in this package.
+*/
+const layerHttpClient = (fetcher) => FetchHttpClient.layer.pipe(Layer.provide(Layer.succeed(FetchHttpClient.Fetch)(async (input, init) => await fetcher.fetch(input, init))));
+export { layerHttpClient };

package/dist/frames.mjs

@@ -0,0 +1,33 @@
+import { Effect, Schema } from "effect";
+import { RpcSerialization } from "effect/rpc";
+// src/durable/frames.ts
+const socketPrefix = "effect-actions/socket#";
+/** The tag a socket carries for its id, unique among the object's sockets. */
+const socketTag = (id) => `${socketPrefix}${id}`;
+/** The id a socket's tags give it, or 0, which no socket is given, for one no protocol accepted. */
+const socketIdOf = (tags) => {
+	const tag = tags.find((found) => found.startsWith(socketPrefix));
+	return tag === void 0 ? 0 : Number(tag.slice(22));
+};
+/** The tag a socket carries for the `layerWebSocket` path that accepted it. */
+const groupTag = (path) => `effect-actions/rpc:${path}`;
+/** A request's id on the wire, a finite number or a string, which a client tells apart. */
+const RequestId = Schema.Union([Schema.String, Schema.Finite]);
+/** The object's JSON parser, which keeps no state between frames. */
+const parser = RpcSerialization.json.makeUnsafe();
+/** Closes `socket` with `code`, or with none, unless it is already closing. */
+const closeQuietly = (socket, code, reason) => {
+	try {
+		if (code === void 0) socket.close();
+		else socket.close(code, reason);
+	} catch {}
+};
+/** Sends `frame` to the socket `id`, if one holds it and takes it: one the object closed does not. */
+const sendFrame = (state, id, frame) => Effect.sync(() => {
+	const encoded = parser.encode(frame);
+	if (encoded === void 0) return;
+	try {
+		for (const socket of state.getWebSockets(socketTag(id))) socket.send(encoded);
+	} catch {}
+});
+export { RequestId, closeQuietly, groupTag, parser, sendFrame, socketIdOf, socketTag };

package/dist/idempotency.mjs

@@ -0,0 +1,40 @@
+import { deleted } from "./batches.mjs";
+import { Clock, Effect, Layer, Option, Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+// src/durable/idempotency.ts
+/** Where the object's kept answers live, one key per action, caller's principal and idempotency key. */
+const keptPrefix = "effect-actions/idempotency/";
+const hour = 36e5;
+const page = 128;
+const keptOf = Schema.decodeUnknownOption(Action.Idempotency.Kept);
+/**
+* `Action.Idempotency` over the object's storage: each answer kept 24 hours, through
+* hibernation, eviction and deployments, and deleted once its day is past as a later one is kept,
+* at most once an hour, so an object given no further key keeps its last day's answers.
+*/
+const layerIdempotency = (state) => Layer.sync(Action.Idempotency)(() => {
+	let prunedAt = -Infinity;
+	const prune = Effect.gen(function* () {
+		const now = yield* Clock.currentTimeMillis;
+		if (now - prunedAt < hour) return;
+		prunedAt = now;
+		let after;
+		do {
+			const options = {
+				prefix: keptPrefix,
+				limit: page,
+				...after === void 0 ? {} : { startAfter: after }
+			};
+			const listed = [...yield* Effect.promise(async () => await state.storage.list(options))];
+			yield* deleted(state.storage, listed.flatMap(([key, value]) => Option.exists(keptOf(value), ({ at }) => at + Action.Idempotency.keptFor <= now) ? [key] : []));
+			after = listed.length === page ? listed.at(-1)?.[0] : void 0;
+		} while (after !== void 0);
+	});
+	return Action.Idempotency.of({
+		get: (id) => Effect.map(Effect.promise(async () => await state.storage.get(`${keptPrefix}${id}`)), (stored) => Option.getOrUndefined(keptOf(stored))),
+		set: (id, kept) => Effect.andThen(Effect.promise(async () => {
+			await state.storage.put(`${keptPrefix}${id}`, kept);
+		}), prune)
+	});
+});
+export { layerIdempotency };

package/dist/placed.d.mts

@@ -0,0 +1,47 @@
+import { Layer } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+type Contract<H extends ActionHttp.Any> = H["actions"][number] | H["events"][number];
+/**
+ * The key of each contract of `H`, by its name, as `placed` takes them: the name of the object
+ * serving a call or a subscription, read from its input.
+ */
+export type PlacementKeys<H extends ActionHttp.Any> = { readonly [C in Contract<H> as C["name"]]: (input: C["input"]["Type"]) => string; };
+/**
+ * What `placed` returns: the objects whose routes serve `binding`, each the one an input's key
+ * names. Given to `make` or `handlers` as `placed`, it is what the object checks each input by;
+ * given to `reaching` with the namespace, what a Worker serves.
+ */
+export interface Placement<H extends ActionHttp.Any> {
+  readonly binding: H;
+  /** `placed`'s keys: by a contract's name, the name of the object serving its input. */
+  readonly keys: {
+    readonly [name: string]: (input: Action.Any["input"]["Type"]) => string;
+  };
+}
+/** Any placement, as `make` and `handlers` take it. */
+export type AnyPlacement = Placement<ActionHttp.Any>;
+/**
+ * The actions and event types of `binding` served in Durable Objects, each call and subscription
+ * in the object its contract's key in `keys` names for its input, reached by
+ * `getByName(keys[contract.name](input))`. Each object is
+ * given it as `make`'s or `handlers`' `placed`, so that it refuses an input naming another
+ * object, and serves `binding` in an `ActionHttp.layer` of its routes, where each call arrives; a
+ * Worker serves `reaching(placement, () => env.ROOM)` on any surface.
+ *
+ * Guide: `docs/ActionDurableObject-placement.md` in this package.
+ */
+export declare const placed: <const H extends ActionHttp.Any>(binding: H, keys: NoInfer<PlacementKeys<H>>) => Placement<H>;
+/**
+ * The implementations a Worker serves of `placement`, reaching its objects in the namespace
+ * `namespace` answers, `() => env.ROOM`: beside the Worker's own, on any surface, each call and
+ * subscription sent on to the object its input's key names, as `ActionHttp.placed` sends it on.
+ *
+ * **Gotchas**
+ *
+ * - `namespace` is called as each call is sent, never as the module evaluates, so it reads `env` from `cloudflare:workers`, which a module-level value finds unset.
+ * - Its rules, a credential verified by the Worker and again in the object among them, are `ActionHttp.placed`'s.
+ * - An event an object's socket serves through it holds a request to the other object open while it is watched: both stay awake, billed, and neither hibernates. Serve an event in the object whose socket follows it.
+ */
+export declare const reaching: <H extends ActionHttp.Any>(placement: Placement<H>, namespace: () => DurableObjectNamespace) => ActionHttp.Placed<H>;
+export {};

package/dist/placed.mjs

@@ -0,0 +1,53 @@
+import { Effect, Layer } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+// src/durable/placed.ts
+/**
+* The actions and event types of `binding` served in Durable Objects, each call and subscription
+* in the object its contract's key in `keys` names for its input, reached by
+* `getByName(keys[contract.name](input))`. Each object is
+* given it as `make`'s or `handlers`' `placed`, so that it refuses an input naming another
+* object, and serves `binding` in an `ActionHttp.layer` of its routes, where each call arrives; a
+* Worker serves `reaching(placement, () => env.ROOM)` on any surface.
+*
+* Guide: `docs/ActionDurableObject-placement.md` in this package.
+*/
+const placed = (binding, keys) => ({
+	binding,
+	keys
+});
+/**
+* The implementations a Worker serves of `placement`, reaching its objects in the namespace
+* `namespace` answers, `() => env.ROOM`: beside the Worker's own, on any surface, each call and
+* subscription sent on to the object its input's key names, as `ActionHttp.placed` sends it on.
+*
+* **Gotchas**
+*
+* - `namespace` is called as each call is sent, never as the module evaluates, so it reads `env` from `cloudflare:workers`, which a module-level value finds unset.
+* - Its rules, a credential verified by the Worker and again in the object among them, are `ActionHttp.placed`'s.
+* - An event an object's socket serves through it holds a request to the other object open while it is watched: both stay awake, billed, and neither hibernates. Serve an event in the object whose socket follows it.
+*/
+const reaching = (placement, namespace) => {
+	const fetching = Effect.runSync(Effect.provide(Effect.service(HttpClient.HttpClient), FetchHttpClient.layer)).pipe(HttpClient.mapRequest(HttpClientRequest.prependUrl("https://object")));
+	return ActionHttp.placed(placement.binding, (input, contract) => {
+		const key = placement.keys[contract.name];
+		if (key === void 0) throw new Error(`ActionDurableObject.placed: its keys hold none for ${contract.name} (give placed a key for each contract of its binding, by name)`);
+		const stub = namespace().getByName(key(input));
+		return HttpClient.transform(fetching, (sent) => Effect.provideService(sent, FetchHttpClient.Fetch, async (url, init) => await stub.fetch(url, init)));
+	});
+};
+/**
+* The input check of an object named `name`, given `placement`: an input of one of its contracts
+* whose key names another object is refused.
+*/
+const layerInputCheck = (placement, name) => {
+	const contracts = /* @__PURE__ */ new Set([...placement.binding.actions, ...placement.binding.events]);
+	return Layer.succeed(Action.InputCheck)((contract, input) => {
+		const key = contracts.has(contract) ? placement.keys[contract.name] : void 0;
+		if (key === void 0) return Effect.void;
+		const named = key(input);
+		return named === name ? Effect.void : Effect.fail(new Action.Forbidden({ message: `This object is ${String(name)}, and the input of ${contract.name} names ${named}` }));
+	});
+};
+export { layerInputCheck, placed, reaching };