@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/examples/live-rpc/src/chat/events.ts

@@ -0,0 +1,74 @@
+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 { CurrentRoom } from "./room.js";
+import { MessageStore } from "./store.js";
+
+const idOf = Schema.decodeUnknownOption(
+  Schema.NumberFromString.pipe(Schema.check(Schema.isInt()))
+);
+
+// A cursor this source gives is `<epoch>:<id>`, the store's epoch and the id of the last message
+// a page holds, so one from before a restart of the memory store is told apart. A page starting
+// a watch gives the id alone, as `readMessages`' `after` is, which is the store's now.
+const positionOf = (epoch: string, cursor: string | null) => {
+  const parts =
+    cursor?.includes(":") === true ? cursor.split(":") : [epoch, cursor];
+
+  return parts.length === 2 && parts[0] === epoch
+    ? idOf(parts[1])
+    : Option.none();
+};
+
+// 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, not at its next read
+// every 5 seconds.
+export const messageEvents = Event.implement(
+  MessagePosted,
+  Effect.gen(function* () {
+    const store = yield* MessageStore;
+
+    return {
+      check: (_input, cursor) =>
+        Effect.gen(function* () {
+          const room = yield* CurrentRoom;
+          const last = yield* store.last(room);
+
+          const after = Option.filter(
+            positionOf(store.epoch, cursor),
+            (id) => id >= 0 && id <= last
+          );
+
+          // No cursor starts after the room's last message. One this room never gave, such as
+          // one from before a restart, is answered `truncated` from there: the page learns its
+          // messages may be another run's, and reads the room again with `readMessages`.
+          if (Option.isNone(after)) {
+            return {
+              cursor: `${store.epoch}:${last}`,
+              events: [],
+              truncated: cursor !== null,
+            };
+          }
+
+          const messages = yield* store.read(room, after.value);
+
+          return {
+            cursor: `${store.epoch}:${messages.at(-1)?.id ?? after.value}`,
+            // A message's id counts within its room and the store's epoch, so the event's id
+            // names all three: a watch drops an id it has seen, and after a restart of the memory
+            // store `lobby:1` is another message.
+            events: messages.map((data) => ({
+              eventId: `${store.epoch}:${room}:${data.id}`,
+              data,
+            })),
+          };
+        }),
+      // A notify for one room wakes that room's pages alone: the key is the room the watch's
+      // header names, read as `check` reads it.
+      key: () => CurrentRoom,
+    };
+  }),
+  { authorize }
+);

package/examples/live-rpc/src/chat/handlers.ts

@@ -1,8 +1,10 @@
-import { Effect } from "effect";
 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 { authorize } from "./authorize.js";
-import { ListRooms, Messages } from "./Chat.js";
+import { ListRooms, MessagePosted, Messages } from "./Chat.js";
 import { CurrentRoom } from "./room.js";
 import { MessageStore } from "./store.js";
 
@@ -13,7 +15,7 @@ export const rooms = Action.implement(
     const store = yield* MessageStore;
 
     return () => Effect.map(store.rooms, (found) => ({ rooms: found }));
-  }),
+  })
 );
 
 // The builder runs once, at startup: it is where a handler gets its startup services. The
@@ -22,6 +24,7 @@ export const messages = Action.implement(
   Messages,
   Effect.gen(function* () {
     const store = yield* MessageStore;
+    const events = yield* Event.Events;
 
     return {
       readMessages: ({ after }) =>
@@ -30,12 +33,17 @@ export const messages = Action.implement(
 
           return { messages: yield* store.read(room, after) };
         }),
+      // The message is in the store, which `MessagePosted`'s check reads: notifying wakes the
+      // pages watching this room to read it now.
       postMessage: ({ text }) =>
         Effect.gen(function* () {
           const room = yield* CurrentRoom;
           const member = yield* CurrentMember;
+          const message = yield* store.post(room, member.id, text);
+
+          yield* events.notify(MessagePosted, { key: room });
 
-          return yield* store.post(room, member.id, text);
+          return message;
         }),
       deleteMessage: ({ id }) =>
         Effect.gen(function* () {
@@ -46,5 +54,5 @@ export const messages = Action.implement(
         }),
     };
   }),
-  { authorize },
+  { authorize }
 );

package/examples/live-rpc/src/chat/room.ts

@@ -1,23 +1,27 @@
 import { Context, Effect, Layer } from "effect";
 import { RpcMiddleware } from "effect/rpc";
+
 import { defaultRoom, roomHeader } from "./Chat.js";
 
 /**
  * The room a message is about. A request-time service: handlers and `authorize` read it per
  * call, and it has no Layer, because no one value of it is right for a whole server.
  */
-export class CurrentRoom extends Context.Service<CurrentRoom, string>()("live-rpc/CurrentRoom") {}
+export class CurrentRoom extends Context.Service<CurrentRoom, string>()(
+  "live-rpc/CurrentRoom"
+) {}
 
 // Native Effect RPC middleware, declared as providing `CurrentRoom`. Listed in
 // `ActionRpc.layer`'s `middleware`, it runs once per message.
-export class ResolveRoom extends RpcMiddleware.Service<ResolveRoom, { provides: CurrentRoom }>()(
-  "live-rpc/ResolveRoom",
-) {}
+export class ResolveRoom extends RpcMiddleware.Service<
+  ResolveRoom,
+  { provides: CurrentRoom }
+>()("live-rpc/ResolveRoom") {}
 
 // The middleware's implementation. It gets the message's headers, which over a WebSocket are
 // the upgrade request's merged with the message's own, and runs the rest of the call with the
 // room they name, or the default room when they name none. It refuses nothing: whether the
 // caller may be in that room is `authorize`'s rule.
 export const resolveRoom = Layer.succeed(ResolveRoom, (call, { headers }) =>
-  Effect.provideService(call, CurrentRoom, headers[roomHeader] ?? defaultRoom),
+  Effect.provideService(call, CurrentRoom, headers[roomHeader] ?? defaultRoom)
 );

package/examples/live-rpc/src/chat/store.ts

@@ -1,5 +1,7 @@
 import { Context, Effect, Layer } from "effect";
-import { type Message, MessageNotFound, NotAuthor } from "./Chat.js";
+
+import { MessageNotFound, NotAuthor } from "./Chat.js";
+import type { Message } from "./Chat.js";
 
 /**
  * Where messages live, by room. That only its author deletes a message is checked here, in the
@@ -8,34 +10,62 @@ import { type Message, MessageNotFound, NotAuthor } from "./Chat.js";
 export class MessageStore extends Context.Service<
   MessageStore,
   {
-    readonly rooms: Effect.Effect<ReadonlyArray<{ name: string; messages: number }>>;
-    readonly read: (room: string, after: number) => Effect.Effect<ReadonlyArray<Message>>;
-    readonly post: (room: string, author: string, text: string) => Effect.Effect<Message>;
+    /** The store's epoch: a message's id is unique within it, and a restarted memory store starts another. */
+    readonly epoch: string;
+    readonly rooms: Effect.Effect<
+      ReadonlyArray<{ name: string; messages: number }>
+    >;
+    readonly read: (
+      room: string,
+      after: number
+    ) => Effect.Effect<readonly Message[]>;
+    /** The id of the room's last message posted, kept or deleted: 0 for an empty room. */
+    readonly last: (room: string) => Effect.Effect<number>;
+    readonly post: (
+      room: string,
+      author: string,
+      text: string
+    ) => Effect.Effect<Message>;
     readonly remove: (
       room: string,
       author: string,
-      id: number,
+      id: number
     ) => Effect.Effect<void, MessageNotFound | NotAuthor>;
   }
 >()("live-rpc/MessageStore") {
-  // DEMO ONLY: memory, lost when the process stops. A real store is another Layer of this
-  // service, chosen by the entrypoint.
+  // DEMO ONLY: memory, lost when the process stops, its ids then counting from 1 again, so each
+  // start is another epoch. A real store is another Layer of this service, chosen by the
+  // entrypoint, whose ids never repeat.
   static readonly layerMemory = Layer.sync(MessageStore, () => {
-    const rooms = new Map<string, { last: number; messages: ReadonlyArray<Message> }>();
+    const epoch = crypto.randomUUID();
+
+    const rooms = new Map<
+      string,
+      { last: number; messages: readonly Message[] }
+    >();
 
     const room = (name: string) => rooms.get(name) ?? { last: 0, messages: [] };
 
     return MessageStore.of({
+      epoch,
       rooms: Effect.sync(() =>
-        Array.from(rooms, ([name, { messages }]) => ({ name, messages: messages.length })),
+        Array.from(rooms, ([name, { messages }]) => ({
+          name,
+          messages: messages.length,
+        }))
       ),
-      read: (name, after) => Effect.sync(() => room(name).messages.filter(({ id }) => id > after)),
+      read: (name, after) =>
+        Effect.sync(() => room(name).messages.filter(({ id }) => id > after)),
+      last: (name) => Effect.sync(() => room(name).last),
       post: (name, author, text) =>
         Effect.sync(() => {
           const { last, messages } = room(name);
           const message = { id: last + 1, author, text };
 
-          rooms.set(name, { last: message.id, messages: [...messages, message] });
+          rooms.set(name, {
+            last: message.id,
+            messages: [...messages, message],
+          });
 
           return message;
         }),
@@ -43,11 +73,18 @@ export class MessageStore extends Context.Service<
         const { last, messages } = room(name);
         const message = messages.find((candidate) => candidate.id === id);
 
-        if (message === undefined) return yield* new MessageNotFound({ id });
+        if (message === undefined) {
+          return yield* new MessageNotFound({ id });
+        }
 
-        if (message.author !== author) return yield* new NotAuthor({ id });
+        if (message.author !== author) {
+          return yield* new NotAuthor({ id });
+        }
 
-        rooms.set(name, { last, messages: messages.filter((kept) => kept !== message) });
+        rooms.set(name, {
+          last,
+          messages: messages.filter((kept) => kept !== message),
+        });
       }),
     });
   });

package/examples/live-rpc/src/client.ts

@@ -1,5 +1,6 @@
 import { NodeRuntime, NodeSocket } from "@effect/platform-node";
-import { Config, Console, Effect, Layer } from "effect";
+import { Config, Console, Effect, Layer, Stream } from "effect";
+
 import { connection, openChat } from "./browser.js";
 
 // Entrypoint: `node --import tsx examples/live-rpc/src/client.ts`, with the server running.
@@ -17,19 +18,35 @@ const visit = Effect.gen(function* () {
 
   yield* Console.log("ada posts:", posted);
   yield* Console.log("grace reads:", yield* grace.read(posted.id - 1));
+  // A watch from the last id grace held before the post: it sends the post, then would send
+  // each one after it, until taken.
+  yield* Console.log(
+    "grace watches:",
+    yield* grace.messages(posted.id - 1).pipe(Stream.take(1), Stream.runCollect)
+  );
   yield* Console.log("grace removes it:", yield* grace.remove(posted.id));
   yield* Console.log("ada removes it:", yield* ada.remove(posted.id));
-  yield* Console.log("grace reads ops:", yield* chat.room("ops", "grace").read(0));
-  yield* Console.log("an expired token reads:", yield* chat.room("lobby", "expired").read(0));
+  yield* Console.log(
+    "grace reads ops:",
+    yield* chat.room("ops", "grace").read(0)
+  );
+  yield* Console.log(
+    "an expired token reads:",
+    yield* chat.room("lobby", "expired").read(0)
+  );
 });
 
 const main = Effect.gen(function* () {
-  const url = yield* Config.String("CHAT_URL").pipe(Config.withDefault("ws://127.0.0.1:3000/rpc"));
+  const url = yield* Config.String("CHAT_URL").pipe(
+    Config.withDefault("ws://127.0.0.1:3000/rpc")
+  );
 
   // One socket for the whole visit, so both members' calls share it.
   yield* visit.pipe(
     Effect.scoped,
-    Effect.provide(connection(url).pipe(Layer.provide(NodeSocket.layerWebSocketConstructor))),
+    Effect.provide(
+      connection(url).pipe(Layer.provide(NodeSocket.layerWebSocketConstructor))
+    )
   );
 });
 

package/examples/live-rpc/src/identity/Identity.ts

@@ -1,9 +1,9 @@
-import { Context } from "effect";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Context } from "effect";
 
 export interface Member {
   readonly id: string;
-  readonly rooms: ReadonlyArray<string>;
+  readonly rooms: readonly string[];
 }
 
 /**
@@ -11,7 +11,7 @@ export interface Member {
  * provides it for each message, and a test calling in process provides it itself.
  */
 export class CurrentMember extends Context.Service<CurrentMember, Member>()(
-  "live-rpc/CurrentMember",
+  "live-rpc/CurrentMember"
 ) {}
 
 // How a remote caller proves it is CurrentMember: a bearer token, the default scheme. Clients

package/examples/live-rpc/src/identity/verifier.ts

@@ -1,20 +1,24 @@
-import { Effect, Redacted } from "effect";
 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);
+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 included. An unknown token is the built-in
 // `Unauthenticated`, which every client decodes.
-const verify = (token: Redacted.Redacted<string>) => {
+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." }));
+    : Effect.fail(
+        new Action.Unauthenticated({ message: "Unknown demo token." })
+      );
 };
 
 // Server only: `Login`'s provider. Over RPC it runs for every message of a protected rpc, not

package/examples/live-rpc/src/page.ts

@@ -1,34 +1,80 @@
-import { Context, Effect, Layer, ManagedRuntime } from "effect";
-import { RpcClient } from "effect/rpc";
+import type * as Event from "@gjermundgaraba/effect-actions/Event";
+import { Context, Effect, Exit, Layer, ManagedRuntime, Stream } from "effect";
+import type { RpcClient } from "effect/rpc";
 import { Socket } from "effect/socket";
+
 import { connection, openChat } from "./browser.js";
+import type { MessagePosted } from "./chat/Chat.js";
 
 // The chat for a page that is not one Effect program: the same client, each call a promise.
 // A `ManagedRuntime` keeps the protocol's layer, and so the socket, between calls. It builds
 // the layer on the first call, which is when the socket opens, and `close` releases it. A
 // failure `openChat` does not handle, such as `InvalidInput`, rejects the promise.
-class Chat extends Context.Service<Chat, Effect.Success<typeof openChat>>()("live-rpc/Chat") {}
+class Chat extends Context.Service<Chat, Effect.Success<typeof openChat>>()(
+  "live-rpc/Chat"
+) {}
 
 export const chatOver = <E>(protocol: Layer.Layer<RpcClient.Protocol, E>) => {
-  const runtime = ManagedRuntime.make(Layer.effect(Chat, openChat).pipe(Layer.provide(protocol)));
+  const runtime = ManagedRuntime.make(
+    Layer.effect(Chat, openChat).pipe(Layer.provide(protocol))
+  );
 
-  const call = <A, E2>(use: (chat: Chat["Service"]) => Effect.Effect<A, E2>) =>
-    runtime.runPromise(Effect.flatMap(Chat, use));
+  const call = async <A, E2>(
+    use: (chat: Chat["Service"]) => Effect.Effect<A, E2>
+  ) => await runtime.runPromise(Effect.flatMap(Chat, use));
 
   return {
-    rooms: () => call((chat) => chat.rooms),
+    rooms: async () => await call((chat) => chat.rooms),
 
     room: (name: string, token: string) => ({
-      read: (after: number) => call((chat) => chat.room(name, token).read(after)),
-      post: (text: string) => call((chat) => chat.room(name, token).post(text)),
-      remove: (id: number) => call((chat) => chat.room(name, token).remove(id)),
+      read: async (after: number) =>
+        await call((chat) => chat.room(name, token).read(after)),
+      post: async (text: string) =>
+        await call((chat) => chat.room(name, token).post(text)),
+      remove: async (id: number) =>
+        await call((chat) => chat.room(name, token).remove(id)),
+      // Calls `receive` with each message posted after `after`, the id of the last message the
+      // page holds, and each gap, as `messages` streams them, until the page calls the function
+      // it returns. `ended` is told why it stopped: a refusal, such as a token that expired by
+      // the time the watch connected again, or anything else, the page's own call included.
+      watch: (
+        after: number,
+        receive: (received: Event.Received<typeof MessagePosted>) => void,
+        ended: (why: "signed-out" | "not-a-member" | "stopped") => void
+      ) =>
+        runtime.runCallback(
+          Effect.flatMap(Chat, (chat) =>
+            Stream.runForEach(
+              chat.room(name, token).messages(after),
+              (received) =>
+                Effect.sync(() => {
+                  receive(received);
+                })
+            )
+          ).pipe(
+            Effect.as("stopped" as const),
+            Effect.catchTags({
+              Unauthenticated: () => Effect.succeed("signed-out" as const),
+              Forbidden: () => Effect.succeed("not-a-member" as const),
+            })
+          ),
+          {
+            onExit: (exit) => {
+              ended(Exit.isSuccess(exit) ? exit.value : "stopped");
+            },
+          }
+        ),
     }),
 
-    close: () => runtime.dispose(),
+    close: async () => {
+      await runtime.dispose();
+    },
   };
 };
 
 // What a page calls: `const chat = connect("wss://chat.example/rpc")`, on the browser's own
 // WebSocket, then `await chat.room("lobby", token).post("Hello")`.
 export const connect = (url: string) =>
-  chatOver(connection(url).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal)));
+  chatOver(
+    connection(url).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal))
+  );

package/examples/live-rpc/src/routes.ts

@@ -1,5 +1,7 @@
-import { Layer } from "effect";
 import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { Layer } from "effect";
+
+import { messageEvents } from "./chat/events.js";
 import { messages, rooms } from "./chat/handlers.js";
 import { ResolveRoom, resolveRoom } from "./chat/room.js";
 import { authenticate } from "./identity/verifier.js";
@@ -8,14 +10,16 @@ import { Rpc } from "./Rpc.js";
 // The binding's rpcs on Effect's own RpcServer, the protected ones behind `Login`'s verifier;
 // `listRooms` needs no token.
 //
-// `ResolveRoom`, listed in `middleware`, provides `CurrentRoom`, which the handlers and
-// `authorize` read. Only something that runs per message can, since each message names its own
-// room: `Layer.succeed(CurrentRoom, "lobby")` provided here would leave the layer still
-// requiring it, in its type.
+// `ResolveRoom`, listed in `middleware`, provides `CurrentRoom`, which the handlers, the event's
+// source and `authorize` read; on a watch it runs as the watch starts, and each time it connects
+// again. Only something that runs per message can, since each message names its own room:
+// `Layer.succeed(CurrentRoom, "lobby")` provided here would leave the layer still requiring it,
+// in its type.
 //
-// It still requires three things, each chosen by whoever serves it. The protocol and its
+// It still requires four things, each chosen by whoever serves it. The protocol and its
 // serialization: server.ts gives it a WebSocket, and a test Effect's HTTP protocol, which
-// answers in memory. And `MessageStore`.
-export const rpc = ActionRpc.layer(Rpc, [rooms, messages], { middleware: [ResolveRoom] }).pipe(
-  Layer.provide([resolveRoom, authenticate]),
-);
+// answers in memory. `MessageStore`, and `Event.Events`, which `postMessage` notifies and the
+// watches wait on: one of each, provided around the whole server.
+export const rpc = ActionRpc.layer(Rpc, [rooms, messages, messageEvents], {
+  middleware: [ResolveRoom],
+}).pipe(Layer.provide([resolveRoom, authenticate]));

package/examples/live-rpc/src/server.ts

@@ -1,8 +1,11 @@
 import { createServer } from "node:http";
+
 import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import * as Event from "@gjermundgaraba/effect-actions/Event";
 import { Config, Effect, Layer } from "effect";
 import { HttpRouter } from "effect/http";
 import { RpcSerialization, RpcServer } from "effect/rpc";
+
 import { MessageStore } from "./chat/store.js";
 import { rpc } from "./routes.js";
 
@@ -15,13 +18,16 @@ import { rpc } from "./routes.js";
 // serialization.
 const socket = rpc.pipe(
   Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
-  Layer.provide(RpcSerialization.layerJson),
+  Layer.provide(RpcSerialization.layerJson)
 );
 
 const server = Layer.unwrap(
   Effect.gen(function* () {
     // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
-    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const host = yield* Config.String("HOST").pipe(
+      Config.withDefault("127.0.0.1")
+    );
+
     const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
 
     return HttpRouter.serve(socket).pipe(
@@ -33,13 +39,17 @@ const server = Layer.unwrap(
           // does not bound it: Node's WebSocket server reads one of up to 100 MiB whole unless
           // told otherwise. A chat message is short, and a larger one closes the socket (1009).
           websocket: { maxPayload: 64 * 1024 },
-        }),
+        })
       ),
       // DEMO ONLY: messages live in this process's memory; a deployment provides a store that
       // lasts.
       Layer.provide(MessageStore.layerMemory),
+      // The pages watching a room are this process's sockets, so what wakes them lives in its
+      // memory too: one for the whole server. Several processes behind a balancer would each
+      // wake only their own pages, the others reading a post at their next read, 5 seconds on.
+      Layer.provide(Event.layerMemory)
     );
-  }),
+  })
 );
 
-Layer.launch(server).pipe(NodeRuntime.runMain);
+Layer.launch(server).pipe(NodeRuntime.runMain());