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

package/examples/chat-rooms/src/browser.ts

@@ -0,0 +1,107 @@
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { Effect, Layer, Predicate, Stream } from "effect";
+import { Headers } from "effect/http";
+import { RpcClient, RpcSerialization } from "effect/rpc";
+import { Socket } from "effect/socket";
+
+import { MessagePosted } from "./chat/Chat.js";
+import type { RoomName } from "./chat/Chat.js";
+import { PreviewsChanged } from "./lobby/Lobby.js";
+import {
+  LobbyRpc,
+  protocolVersion,
+  RoomRpc,
+  unsupportedProtocol,
+} from "./Rpc.js";
+
+// Client module: what a web page imports. It holds the binding and nothing of the server.
+
+// Effect's own client protocol, one WebSocket to an object, speaking JSON: the socket's URL is
+// `wss://<host>/rooms/<room>/rpc` for a room and `wss://<host>/lobby/rpc` for the lobby, given the version of the rpcs the page was built
+// with. An object serving another closes the socket at once with `unsupportedProtocol`, which
+// fails every call and stream with a `SocketCloseError` of that code; `reconnectUntil` stops
+// the client there, which Effect's own policy would not, connecting again every five seconds,
+// each attempt waking the object: show "reload". The layer owns the socket, so provide it
+// once, around the page's whole program; a page provides `Socket.layerWebSocketConstructorGlobal`, the browser's own
+// WebSocket. The client pings every five seconds and the object's runtime answers, so a page
+// left open does not wake the object.
+export const connection = (url: string) =>
+  RpcClient.layerProtocolSocket({
+    retryPolicy: ActionRpc.reconnectUntil(unsupportedProtocol),
+  }).pipe(
+    Layer.provide(Socket.layerWebSocket(`${url}?protocol=${protocolVersion}`)),
+    Layer.provide(RpcSerialization.layerJson)
+  );
+
+// A room as a page uses it, over the socket to that room's object: each call names the room, as
+// every call of a room does, and the object refuses one naming another. A browser WebSocket sets
+// no header when it connects, so the token travels on each message; a client that can set headers
+// on the upgrade, such as a Worker or a native app, sends it once there, and the socket keeps it.
+export const openRoom = (room: RoomName, token: string) =>
+  Effect.gen(function* () {
+    const client = yield* ActionRpc.client(RoomRpc);
+    const headers = { authorization: `Bearer ${token}` };
+    const signedIn = RpcClient.withHeaders(headers);
+
+    return {
+      // The room's messages after `after`, the id of the last one the page holds: 0 reads them
+      // all.
+      read: (after: number) =>
+        client.readMessages({ room, after }).pipe(
+          signedIn,
+          Effect.map(({ messages }) => messages)
+        ),
+      // A post the socket lost, as the room's object restarted, fails with an `RpcClientError`,
+      // whether or not it reached the room: sent again with its `request`, made once for the
+      // message, it is posted once.
+      post: (text: string) =>
+        Effect.flatMap(
+          Effect.sync(() => crypto.randomUUID()),
+          (request) =>
+            client.postMessage({ room, text, request }).pipe(
+              signedIn,
+              Effect.retry({
+                while: (error) => Predicate.isTagged(error, "RpcClientError"),
+                times: 2,
+              })
+            )
+        ),
+      // Each message posted to the room after `after`, the id of the last one the page holds: a
+      // page opening the room reads it, then watches from the last id it read, so a post between
+      // the two is not lost. The room's object keeps the watch while it hibernates, and resumes it
+      // when it next wakes, authenticating its token again: a token that expired meanwhile ends
+      // the watch with `Unauthenticated`, so watch again with a fresh one. `watch` connects again
+      // after a drop and resumes from the last message it delivered; a `Gap` says some were
+      // missed, which the page reads with `read`. The headers go with the stream, as `signedIn`
+      // puts them on a call, and so with every request it sends again.
+      messages: (after: number) =>
+        client
+          .watch(MessagePosted, { room }, { cursor: String(after) })
+          .pipe(
+            Stream.updateService(
+              RpcClient.CurrentHeaders,
+              Headers.merge(Headers.fromInput(headers))
+            )
+          ),
+      remove: (id: number) =>
+        client.deleteMessage({ room, id }).pipe(
+          signedIn,
+          Effect.as("removed" as const),
+          Effect.catchTags({
+            MessageNotFound: () => Effect.succeed("removed" as const),
+            NotAuthor: () => Effect.succeed("not-yours" as const),
+          })
+        ),
+    };
+  });
+
+// The lobby as a page follows it, signed in or not: every room's preview, first as it is, then
+// whole again at each change. A watch given no cursor starts with the previews, so the page reads
+// nothing first; after a drop it resumes from the last it received, and hears the previews again
+// only if they changed meanwhile. A `Gap` needs no read either: the next occurrence is whole.
+export const followLobby = Effect.map(ActionRpc.client(LobbyRpc), (client) =>
+  client.watch(PreviewsChanged, {}).pipe(
+    Stream.filter((received) => Predicate.isTagged(received, "Occurrence")),
+    Stream.map(({ data }) => data.previews)
+  )
+);

package/examples/chat-rooms/src/chat/Chat.ts

@@ -0,0 +1,95 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Schema } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+
+// DEMO ONLY: the rooms, fixed. Each name is one Durable Object, which the Worker reaches only
+// for a name listed here, so no caller creates an object of its own. A real application keeps
+// its rooms in a store and checks a name there before it reaches `getByName`.
+export const RoomName = Schema.Literals(["general", "design"]);
+
+export type RoomName = typeof RoomName.Type;
+
+// A message's `id` counts up within its room, so a client asks for what came after the last
+// one it holds. `at` is when it was posted, in milliseconds: messages expire a day later.
+export const Message = Schema.Struct({
+  id: Schema.Int,
+  author: Schema.String,
+  text: Schema.String,
+  at: Schema.Int,
+});
+
+export type Message = typeof Message.Type;
+
+// A declared error is part of the contract: every client decodes it as this class. Its status is
+// for the JSON routes; an rpc carries none.
+export class MessageNotFound extends Schema.TaggedError<
+  MessageNotFound,
+  { readonly brand: unique symbol }
+>()("MessageNotFound", { id: Schema.Int }, { httpApiStatus: 404 }) {}
+
+export class NotAuthor extends Schema.TaggedError<
+  NotAuthor,
+  { readonly brand: unique symbol }
+>()("NotAuthor", { id: Schema.Int }, { httpApiStatus: 403 }) {}
+
+// Every call and watch of a room names it in its input: the Worker sends each on to the room's
+// object, and the object refuses an input naming another room, so a page's socket to one room
+// cannot reach another. Its schema is the room names, so an unknown room is `InvalidInput`
+// before any object is reached.
+const inRoom = { room: RoomName };
+
+const signedIn = { caller: CurrentMember } as const;
+
+// Reads once: a page opening a room reads what is there, then watches `MessagePosted` below from
+// the last id it read.
+export const ReadMessages = Action.make("readMessages", {
+  ...signedIn,
+  description: "Read the room's messages after the given id; 0 reads them all.",
+  input: { ...inRoom, after: Schema.Int },
+  success: { messages: Schema.Array(Message) },
+  readOnly: true,
+});
+
+// `request` is the post's idempotency key: a page makes one at random for each message and
+// sends it again when it retries the post, and the room answers the repeat as it answered the
+// first, posting once. A model reads its description beside the tool, so it does the same.
+export const PostMessage = Action.make("postMessage", {
+  ...signedIn,
+  description: "Post a message to the room. It expires a day later.",
+  input: {
+    ...inRoom,
+    text: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(500)),
+    request: Schema.optional(
+      Schema.String.annotate({
+        description:
+          "A random id for this message, sent again on a retry: it is posted once.",
+      }).check(Schema.isMaxLength(64))
+    ),
+  },
+  success: Message,
+  readOnly: false,
+  idempotencyKey: "request",
+});
+
+export const DeleteMessage = Action.make("deleteMessage", {
+  ...signedIn,
+  description: "Delete one of your own messages from the room.",
+  input: { ...inRoom, id: Schema.Int },
+  error: [MessageNotFound, NotAuthor],
+  readOnly: false,
+});
+
+export const Messages = [ReadMessages, PostMessage, DeleteMessage] as const;
+
+// Each message posted to the room, as it is posted: a page watches it on the socket it keeps
+// open to the room's object. Signed-in, so each watch authenticates and runs `authorize` as it
+// starts, and again each time the object wakes after hibernating, refused for a member outside
+// the room, or one whose token has expired meanwhile.
+export const MessagePosted = Event.make("message.posted", {
+  description: "A message posted to the room.",
+  input: inRoom,
+  payload: Message,
+  caller: CurrentMember,
+});

package/examples/chat-rooms/src/chat/activity.ts

@@ -0,0 +1,16 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+
+/**
+ * Where a room says its latest activity may have changed: the lobby's object, which worker.ts
+ * chooses. `changing` runs a change, then tells, answering as the change did: a post stands
+ * whether the lobby hears of it or not.
+ */
+export class Activity extends Context.Service<
+  Activity,
+  {
+    readonly changing: <A, E, R>(
+      change: Effect.Effect<A, E, R>
+    ) => Effect.Effect<A, E, R>;
+  }
+>()("chat-rooms/Activity") {}

package/examples/chat-rooms/src/chat/authorize.ts

@@ -0,0 +1,22 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { Room } from "./room.js";
+
+// The one rule: a member reads and writes only the rooms they belong to. It is built as
+// handlers are: this Effect runs once per instance and gets the room, a startup service; the
+// function it returns runs before every handler and reads the caller of that call.
+export const authorize = Effect.gen(function* () {
+  const room = yield* Room;
+
+  return Effect.fn("authorize")(function* () {
+    const member = yield* CurrentMember;
+
+    if (!member.rooms.includes(room)) {
+      return yield* new Action.Forbidden({
+        message: `Not a member of ${room}.`,
+      });
+    }
+  });
+});

package/examples/chat-rooms/src/chat/events.ts

@@ -0,0 +1,64 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect, Option, Schema } from "effect";
+
+import { authorize } from "./authorize.js";
+import { MessagePosted } from "./Chat.js";
+import { MessageStore } from "./store.js";
+
+// A cursor is the id of the last message a page holds, as `readMessages`' `after` is.
+const idOf = Schema.decodeUnknownOption(
+  Schema.NumberFromString.pipe(Schema.check(Schema.isInt()))
+);
+
+// An agent polling over MCP asks again after `nextPoll`, 5 seconds by default: a request that
+// often keeps the object from the 10 idle seconds after which the runtime may hibernate it, so it
+// asks every 30 seconds, and an agent that needs a message sooner holds a stream open instead.
+const nextPoll = "30 seconds";
+
+// The room's messages as an event, read from the store that keeps them: a check source.
+// `postMessage` notifies after each post, so a page receives it at once: when an object reads a
+// check source, and what a write that does not notify misses, is on `ActionDurableObject.handlers`.
+export const messageEvents = Event.implement(
+  MessagePosted,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+
+    return {
+      check: (_input, cursor) =>
+        Effect.gen(function* () {
+          const last = yield* store.last;
+
+          const after = Option.filter(
+            idOf(cursor),
+            (id) => id >= 0 && id <= last
+          );
+
+          // No cursor starts after the room's last message. One this room never gave, such as
+          // an id past its last from another copy of its database, is answered `truncated` from
+          // there: the page learns it missed messages, and reads them with `readMessages`. A
+          // message deleted or expired after a cursor is simply not read: the store keeps no
+          // record of either, so no gap marks it.
+          if (Option.isNone(after)) {
+            return {
+              cursor: String(last),
+              events: [],
+              truncated: cursor !== null,
+              nextPoll,
+            };
+          }
+
+          const messages = yield* store.read(after.value);
+
+          return {
+            cursor: String(messages.at(-1)?.id ?? after.value),
+            events: messages.map((data) => ({
+              eventId: String(data.id),
+              data,
+            })),
+            nextPoll,
+          };
+        }),
+    };
+  }),
+  { authorize }
+);

package/examples/chat-rooms/src/chat/handlers.ts

@@ -0,0 +1,38 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { CurrentMember } from "../identity/Identity.js";
+import { Activity } from "./activity.js";
+import { authorize } from "./authorize.js";
+import { MessagePosted, Messages } from "./Chat.js";
+import { MessageStore } from "./store.js";
+
+// The builder runs once per instance, when the object is constructed, and again on the
+// instance the runtime constructs after evicting one: it is where a handler gets its startup
+// services. The caller is read per call, because every message has its own.
+export const messages = Action.implement(
+  Messages,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+    const events = yield* Event.Events;
+    const activity = yield* Activity;
+
+    return {
+      readMessages: ({ after }) =>
+        Effect.map(store.read(after), (read) => ({ messages: read })),
+      // The message is in the store, which `MessagePosted`'s check reads: notifying wakes the
+      // pages watching the room to read it now. The lobby is another object, whose event this
+      // one cannot notify: the room tells it over its stub instead, and the lobby notifies.
+      postMessage: ({ text }) =>
+        Effect.flatMap(CurrentMember, (member) =>
+          store.post(member.id, text)
+        ).pipe(Effect.tap(events.notify(MessagePosted)), activity.changing),
+      deleteMessage: ({ id }) =>
+        activity.changing(
+          Effect.flatMap(CurrentMember, (member) => store.remove(member.id, id))
+        ),
+    };
+  }),
+  { authorize }
+);

package/examples/chat-rooms/src/chat/room.ts

@@ -0,0 +1,12 @@
+import { Context } from "effect";
+
+import type { RoomName } from "./Chat.js";
+
+/**
+ * The room an instance holds. Each room is one Durable Object, reached by its name, so this is
+ * a startup service: one value for the instance's whole life, unlike the caller, which every
+ * message names again.
+ */
+export class Room extends Context.Service<Room, RoomName>()(
+  "chat-rooms/Room"
+) {}

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

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+
+import type { Message, MessageNotFound, NotAuthor } from "./Chat.js";
+
+/**
+ * The room's messages. That only its author deletes a message is checked here, in the data
+ * access, so no surface and no handler can skip it. A message expires a day after it was
+ * posted: `expire` deletes those, and the store sees that it runs.
+ */
+export class MessageStore extends Context.Service<
+  MessageStore,
+  {
+    readonly latest: Effect.Effect<Message | null>;
+    /** The id of the last message ever posted, kept or not, or 0 before the first. */
+    readonly last: Effect.Effect<number>;
+    readonly read: (after: number) => Effect.Effect<readonly Message[]>;
+    readonly post: (author: string, text: string) => Effect.Effect<Message>;
+    readonly remove: (
+      author: string,
+      id: number
+    ) => Effect.Effect<void, MessageNotFound | NotAuthor>;
+    readonly expire: Effect.Effect<void>;
+  }
+>()("chat-rooms/MessageStore") {}

package/examples/chat-rooms/src/env.d.ts

@@ -0,0 +1,12 @@
+// The Worker's bindings and its main module, as `wrangler types` writes them from
+// wrangler.jsonc: regenerate them with it when the configuration changes.
+declare namespace Cloudflare {
+  interface Env {
+    readonly CHAT_ROOM: DurableObjectNamespace<import("./worker.js").ChatRoom>;
+    readonly CHAT_LOBBY: DurableObjectNamespace<import("./worker.js").ChatLobby>;
+  }
+
+  interface GlobalProps {
+    mainModule: typeof import("./worker.js");
+  }
+}

package/examples/chat-rooms/src/identity/Identity.ts

@@ -0,0 +1,21 @@
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Context, Schema } from "effect";
+
+export const Member = Schema.Struct({
+  id: Schema.String,
+  rooms: Schema.Array(Schema.String),
+});
+
+export type Member = typeof Member.Type;
+
+/**
+ * Who sent a message. A protected action declares it, `caller: CurrentMember`; authentication
+ * provides it for each message, from the token the message carries or the one its socket kept.
+ */
+export class CurrentMember extends Context.Service<CurrentMember, Member>()(
+  "chat-rooms/CurrentMember"
+) {}
+
+// How a remote caller proves it is CurrentMember: a bearer token, the default scheme. Clients
+// import this descriptor with the bindings; its verifier, in verifier.ts, stays on the server.
+export const Login = Authentication.make("chat-rooms.Login", CurrentMember);

package/examples/chat-rooms/src/identity/members.ts

@@ -0,0 +1,8 @@
+import type { Member } from "./Identity.js";
+
+// DEMO ONLY: fixed members, each token their name. A real application keeps members in its
+// identity provider and their rooms in a store.
+export const members = {
+  ada: { id: "ada", rooms: ["general", "design"] },
+  grace: { id: "grace", rooms: ["general"] },
+} satisfies Record<string, Member>;

package/examples/chat-rooms/src/identity/verifier.ts

@@ -0,0 +1,24 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Effect, Redacted } from "effect";
+
+import { Login } from "./Identity.js";
+import { members } from "./members.js";
+
+const isToken = (token: string): token is keyof typeof members =>
+  Object.hasOwn(members, token);
+
+// DEMO ONLY: a token is a member's name. A real verifier checks a signed token with your
+// authorization server's library, its audience and expiry included: a socket keeps the token
+// its page connected with, and this runs on every message, so an expired one is refused.
+const verify = (token: Redacted.Redacted) => {
+  const name = Redacted.value(token);
+
+  return isToken(name)
+    ? Effect.succeed(members[name])
+    : Effect.fail(
+        new Action.Unauthenticated({ message: "Unknown demo token." })
+      );
+};
+
+export const authenticate = Authentication.layer(Login, verify);

package/examples/chat-rooms/src/lobby/Calls.ts

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+import { Rpc, RpcGroup } from "effect/rpc";
+
+import { RoomPreview } from "./Lobby.js";
+
+// The lobby's own API, over its stub: a room tells it its latest activity, and the Worker reads
+// the previews. A plain Effect `RpcGroup`, not actions: no page calls it, so it needs no contract
+// checks, no authentication and no JSON route, and nothing authenticates a stub call anyway, as
+// only a binding reaches it. Why a report heard late never overwrites a later one is at
+// `tellLobby`, in lobby-stubs.ts, which sends it.
+export const LobbyCalls = RpcGroup.make(
+  Rpc.make("roomChanged", { payload: RoomPreview }),
+  Rpc.make("previews", { success: Schema.Array(RoomPreview) })
+);

package/examples/chat-rooms/src/lobby/Lobby.ts

@@ -0,0 +1,32 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Schema } from "effect";
+
+import { RoomName } from "../chat/Chat.js";
+
+// When one room was last active, in milliseconds, or null while it holds no message.
+export const RoomPreview = Schema.Struct({
+  room: RoomName,
+  latestAt: Schema.NullOr(Schema.Int),
+});
+
+export type RoomPreview = typeof RoomPreview.Type;
+
+// The Worker's own action, served by the Worker, not by an object: it asks the lobby's object,
+// which keeps every room's preview.
+export const Previews = Action.make("previews", {
+  description:
+    "When each room was last active, in milliseconds, if it holds any message.",
+  success: { previews: Schema.Array(RoomPreview) },
+  readOnly: true,
+  caller: Action.Anyone,
+});
+
+// Every room's preview, sent whole each time one changes: a page watches it on its socket to the
+// lobby's object. Public, as `previews` is, so a page signed out follows it too.
+export const PreviewsChanged = Event.make("previews.changed", {
+  description:
+    "When each room was last active, sent whole: first as it is, then on each change.",
+  payload: Schema.Struct({ previews: Schema.Array(RoomPreview) }),
+  caller: Action.Anyone,
+});

package/examples/chat-rooms/src/lobby/events.ts

@@ -0,0 +1,17 @@
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { PreviewsChanged } from "./Lobby.js";
+import { PreviewStore } from "./store.js";
+
+// Every room's preview as one event, read from the lobby's store: a current source, for a value
+// small enough to send whole. A page watching is sent the previews as they are, then again after
+// each notify, which `roomChanged` makes after each change, so it needs no read before it and is
+// never sent each change it missed, which a whole value makes needless. The object keeps the
+// revision a page's cursor holds, so a page resuming at the latest is sent nothing.
+export const previewEvents = Event.implement(
+  PreviewsChanged,
+  Effect.map(PreviewStore, (store) => ({
+    current: () => Effect.map(store.read, (previews) => ({ previews })),
+  }))
+);

package/examples/chat-rooms/src/lobby/handlers.ts

@@ -0,0 +1,34 @@
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Effect } from "effect";
+
+import { LobbyCalls } from "./Calls.js";
+import { LobbyHost } from "./host.js";
+import { Previews, PreviewsChanged } from "./Lobby.js";
+import { PreviewStore } from "./store.js";
+
+// The Worker's `previews`, as the lobby's object keeps them.
+export const lobby = Action.implement(
+  Previews,
+  Effect.map(
+    LobbyHost,
+    (host) => () => Effect.map(host.previews, (previews) => ({ previews }))
+  )
+);
+
+// The lobby's own API, in its object. A change notifies `PreviewsChanged`, which an object
+// outside this one could not do itself: its event is this object's.
+export const calls = LobbyCalls.toLayer(
+  Effect.gen(function* () {
+    const store = yield* PreviewStore;
+    const events = yield* Event.Events;
+
+    return LobbyCalls.of({
+      roomChanged: ({ room, latestAt }) =>
+        Effect.flatMap(store.record(room, latestAt), (changed) =>
+          changed ? events.notify(PreviewsChanged) : Effect.void
+        ),
+      previews: () => store.read,
+    });
+  })
+);

package/examples/chat-rooms/src/lobby/host.ts

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+
+import type { RoomPreview } from "./Lobby.js";
+
+/** The lobby's object as the Worker reaches it. */
+export class LobbyHost extends Context.Service<
+  LobbyHost,
+  { readonly previews: Effect.Effect<readonly RoomPreview[]> }
+>()("chat-rooms/LobbyHost") {}

package/examples/chat-rooms/src/lobby/store.ts

@@ -0,0 +1,18 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+
+import type { RoomName } from "../chat/Chat.js";
+import type { RoomPreview } from "./Lobby.js";
+
+/** Every room's preview, as the room last told the lobby. */
+export class PreviewStore extends Context.Service<
+  PreviewStore,
+  {
+    readonly read: Effect.Effect<readonly RoomPreview[]>;
+    /** Keeps `room`'s latest activity, succeeding with whether it changed. */
+    readonly record: (
+      room: RoomName,
+      latestAt: number | null
+    ) => Effect.Effect<boolean>;
+  }
+>()("chat-rooms/PreviewStore") {}

package/examples/chat-rooms/src/platform/kv-previews.ts

@@ -0,0 +1,35 @@
+import * as ActionDurableObject from "@gjermundgaraba/effect-actions-cloudflare/ActionDurableObject";
+import { Effect, Layer, Schema } from "effect";
+
+import { RoomName } from "../chat/Chat.js";
+import { RoomPreview } from "../lobby/Lobby.js";
+import { PreviewStore } from "../lobby/store.js";
+
+const decodeLatestAt = Schema.decodeUnknownSync(
+  Schema.UndefinedOr(RoomPreview.fields.latestAt)
+);
+
+// The previews in the lobby's object's synchronous key-value storage: each read and each record
+// is one step no other call runs inside, so a record compares and writes what it read.
+export const layerKvPreviews = Layer.effect(PreviewStore)(
+  Effect.map(ActionDurableObject.State, ({ storage: { kv } }) => {
+    const latestOf = (room: RoomName) =>
+      decodeLatestAt(kv.get(`preview:${room}`)) ?? null;
+
+    return PreviewStore.of({
+      read: Effect.sync(() =>
+        RoomName.literals.map((room) => ({ room, latestAt: latestOf(room) }))
+      ),
+      record: (room, latestAt) =>
+        Effect.sync(() => {
+          if (latestOf(room) === latestAt) {
+            return false;
+          }
+
+          kv.put(`preview:${room}`, latestAt);
+
+          return true;
+        }),
+    });
+  })
+);