@kestack/web-platform 0.0.0-stage → 0.0.1

package/src/pwa/rpc/client/platform.ts

@@ -0,0 +1,213 @@
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Scope from 'effect/Scope';
+import * as Worker from 'effect/workers/Worker';
+import {
+  WorkerError,
+  WorkerReceiveError,
+  WorkerSpawnError,
+} from 'effect/workers/WorkerError';
+import type { PlatformMessage } from 'effect/workers/WorkerRunner';
+import type { BuildId } from '../../shared/build/index.js';
+import {
+  makeInFlight,
+  matchWorkerEnvelope,
+  RPC_ENVELOPE_KEY,
+  type ClientEnvelope,
+  VersionSkew,
+} from '../handshake/index.js';
+import type { SkewState } from './version-skew.js';
+
+interface Options {
+  readonly buildId: BuildId;
+  /** How often to check a silent worker, and how long to wait for READY. */
+  readonly livenessMs: number;
+  readonly skew: SkewState;
+}
+
+/**
+ * Resolves with the controller to connect to. A controller that just
+ * reported Version Skew is skipped until another takes its place.
+ */
+const awaitController = (
+  container: ServiceWorkerContainer,
+  skip?: ServiceWorker,
+) =>
+  Effect.callback<ServiceWorker>((resume) => {
+    const check = () => {
+      const controller = container.controller;
+      if (controller === null || controller === skip) return false;
+      resume(Effect.succeed(controller));
+      return true;
+    };
+    if (check()) return;
+    const onChange = () => {
+      if (check()) container.removeEventListener('controllerchange', onChange);
+    };
+    container.addEventListener('controllerchange', onChange);
+    return Effect.sync(() =>
+      container.removeEventListener('controllerchange', onChange),
+    );
+  });
+
+/** One connection to one controller: what Effect's worker client sends to. */
+const makePort = (controller: ServiceWorker, buildId: BuildId) => {
+  const connectionId = crypto.randomUUID();
+  const inFlight = makeInFlight();
+  let closed = false;
+  const post = (
+    body:
+      | { readonly type: 'CONNECT' | 'CLOSE' | 'PING' }
+      | {
+          readonly type: 'MESSAGE';
+          readonly message: unknown;
+          readonly open: number;
+        },
+    transfers: ReadonlyArray<unknown> = [],
+  ) => {
+    if (closed) return;
+    const envelope: ClientEnvelope = {
+      [RPC_ENVELOPE_KEY]: 1,
+      buildId,
+      connectionId,
+      ...body,
+    };
+    controller.postMessage(envelope, transfers as Transferable[]);
+  };
+  return {
+    controller,
+    connectionId,
+    inFlight,
+    post,
+    /** Stops all traffic; the connection is dead. */
+    close() {
+      closed = true;
+      inFlight.clear();
+    },
+    postMessage(
+      frame: PlatformMessage<unknown>,
+      transfers?: ReadonlyArray<unknown>,
+    ) {
+      if (frame[0] === 1) return post({ type: 'CLOSE' });
+      const open = inFlight.size;
+      inFlight.request(frame[1]);
+      post({ type: 'MESSAGE', message: frame[1], open }, transfers);
+    },
+  };
+};
+
+const lost = (message: string) =>
+  new WorkerError({ reason: new WorkerReceiveError({ message }) });
+
+/**
+ * Effect's `WorkerPlatform` for a Worker Client: every frame goes through
+ * `navigator.serviceWorker.controller.postMessage`, which wakes a stopped
+ * worker, and replies arrive on `navigator.serviceWorker`. One spawned
+ * "worker" is one connection; it fails, and Effect's worker protocol opens a
+ * new one, when the worker answers VERSION_SKEW or UNKNOWN_CONNECTION, when
+ * the controller changes, or when no READY comes within the liveness interval.
+ */
+export const makeClientPlatform = (options: Options) =>
+  Worker.makePlatform<ServiceWorkerContainer>()({
+    setup: ({ worker: container, scope }) =>
+      Effect.gen(function* () {
+        const controller = yield* awaitController(
+          container,
+          options.skew.controller,
+        );
+        const port = makePort(controller, options.buildId);
+        yield* Scope.addFinalizer(
+          scope,
+          Effect.sync(() => {
+            port.postMessage([1]);
+            port.close();
+          }),
+        );
+        return Object.assign(port, { container });
+      }),
+    listen: ({ port, emit, deferred, scope }) =>
+      Effect.suspend(() => {
+        const { container } = port;
+        let ready = false;
+        const openReady = () => {
+          if (ready) return;
+          ready = true;
+          emit([0]);
+        };
+        // Effect's worker client waits for ready before it watches for
+        // failure, so a connection that fails first still reports ready.
+        const fail = (error: WorkerError) => {
+          port.close();
+          openReady();
+          Deferred.doneUnsafe(deferred, Effect.fail(error));
+        };
+
+        const onMessage = (event: MessageEvent) => {
+          const found = matchWorkerEnvelope(event.data);
+          if (Option.isNone(found)) return;
+          const envelope = found.value;
+          if (envelope.connectionId !== port.connectionId) return;
+          switch (envelope.type) {
+            case 'READY':
+              options.skew.clear();
+              return openReady();
+            case 'MESSAGE':
+              port.inFlight.response(envelope.message);
+              return emit([1, envelope.message]);
+            case 'VERSION_SKEW': {
+              const skew = new VersionSkew({
+                pageBuildId: options.buildId,
+                workerBuildId: envelope.buildId,
+              });
+              options.skew.set(skew, port.controller);
+              return fail(
+                new WorkerError({
+                  reason: new WorkerSpawnError({
+                    message:
+                      'Version Skew: the page and the service worker belong to different Build IDs',
+                    cause: skew,
+                  }),
+                }),
+              );
+            }
+            case 'UNKNOWN_CONNECTION':
+              return fail(
+                lost(
+                  'The Worker Server no longer knows this Worker Client; the service worker was restarted',
+                ),
+              );
+          }
+        };
+        const onControllerChange = () =>
+          fail(lost('The service worker controlling this page changed'));
+
+        const connectTimeout = setTimeout(() => {
+          if (!ready) fail(lost('No Worker Server answered the handshake'));
+        }, options.livenessMs);
+        // A stopped worker cannot tell the page it lost its calls. While calls
+        // are in flight, a PING wakes it; a restarted worker answers
+        // UNKNOWN_CONNECTION.
+        const liveness = setInterval(() => {
+          if (ready && port.inFlight.size > 0) port.post({ type: 'PING' });
+        }, options.livenessMs);
+
+        container.addEventListener('message', onMessage);
+        container.addEventListener('controllerchange', onControllerChange);
+        container.startMessages?.();
+        port.post({ type: 'CONNECT' });
+
+        return Scope.addFinalizer(
+          scope,
+          Effect.sync(() => {
+            clearTimeout(connectTimeout);
+            clearInterval(liveness);
+            container.removeEventListener('message', onMessage);
+            container.removeEventListener(
+              'controllerchange',
+              onControllerChange,
+            );
+          }),
+        );
+      }),
+  });

package/src/pwa/rpc/client/version-skew.ts

@@ -0,0 +1,71 @@
+import * as Effect from 'effect/Effect';
+import type * as RpcClient from 'effect/rpc/RpcClient';
+import type { FromServerEncoded } from 'effect/rpc/RpcMessage';
+import { VersionSkew } from '../handshake/index.js';
+
+/**
+ * The last handshake's Version Skew, if any, and the controller that
+ * reported it. Cleared by the next READY.
+ */
+export const makeSkewState = () => {
+  let current:
+    | { readonly skew: VersionSkew; readonly controller: ServiceWorker }
+    | undefined;
+  return {
+    get skew() {
+      return current?.skew;
+    },
+    get controller() {
+      return current?.controller;
+    },
+    set(skew: VersionSkew, controller: ServiceWorker) {
+      current = { skew, controller };
+    },
+    clear() {
+      current = undefined;
+    },
+  };
+};
+export type SkewState = ReturnType<typeof makeSkewState>;
+
+const skewOf = (message: FromServerEncoded): VersionSkew | undefined => {
+  if (message._tag !== 'ClientProtocolError') return undefined;
+  const cause: unknown = (message.error.reason as { cause?: unknown }).cause;
+  return cause instanceof VersionSkew ? cause : undefined;
+};
+
+/**
+ * Surfaces Version Skew to calls as the typed `VersionSkew` error instead of
+ * an `RpcClientError`. The platform reports skew as a failed connection whose
+ * cause is the `VersionSkew`; this unwraps it. While skew is known, new calls
+ * fail at once instead of waiting for a connection that cannot open.
+ */
+export const withVersionSkew = (
+  protocol: RpcClient.Protocol['Service'],
+  state: SkewState,
+): RpcClient.Protocol['Service'] => {
+  const writers = new Map<
+    number,
+    (message: FromServerEncoded) => Effect.Effect<void>
+  >();
+  const failWith = (skew: VersionSkew): FromServerEncoded =>
+    ({ _tag: 'ClientProtocolError', error: skew }) as never;
+
+  return {
+    ...protocol,
+    run: (clientId, write) => {
+      writers.set(clientId, write);
+      return protocol.run(clientId, (message) => {
+        const skew = skewOf(message);
+        return write(skew ? failWith(skew) : message);
+      });
+    },
+    send: (clientId, request, transferables) => {
+      const skew = state.skew;
+      const write = writers.get(clientId);
+      return skew && write && request._tag === 'Request'
+        ? write(failWith(skew))
+        : protocol.send(clientId, request, transferables);
+    },
+  };
+};

package/src/pwa/rpc/handshake/handshake.ts

@@ -0,0 +1,125 @@
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { BuildId } from '../../shared/build/index.js';
+
+/**
+ * Worker RPC's own envelope, distinct from the command key so each
+ * listener ignores the other's traffic. Every envelope names its sender's
+ * Build ID and the Worker Client connection it belongs to.
+ *
+ * A connection opens with CONNECT, answered by READY or VERSION_SKEW. A
+ * worker that does not know the connection (it was stopped and started
+ * again) adopts it when the message is a new Request and the page has no
+ * other call open (`open: 0`), since nothing was lost; otherwise it answers
+ * UNKNOWN_CONNECTION, and the page opens a new one.
+ */
+export const RPC_ENVELOPE_KEY = '__pwaToolkitRpc';
+const Envelope = {
+  [RPC_ENVELOPE_KEY]: Schema.Literal(1),
+  buildId: BuildId,
+  connectionId: Schema.String,
+} as const;
+
+/** Worker Client → Worker Server, via `navigator.serviceWorker.controller.postMessage`. */
+export const ClientEnvelope = Schema.Union([
+  Schema.Struct({
+    ...Envelope,
+    type: Schema.Literals(['CONNECT', 'CLOSE', 'PING']),
+  }),
+  Schema.Struct({
+    ...Envelope,
+    type: Schema.Literal('MESSAGE'),
+    message: Schema.Unknown,
+    /** Calls the page had open on this connection before this message. */
+    open: Schema.Number,
+  }),
+]);
+export type ClientEnvelope = typeof ClientEnvelope.Type;
+
+/** Worker Server → Worker Client, via the page's `Client.postMessage`. */
+export const WorkerEnvelope = Schema.Union([
+  Schema.Struct({
+    ...Envelope,
+    type: Schema.Literals(['READY', 'VERSION_SKEW', 'UNKNOWN_CONNECTION']),
+  }),
+  Schema.Struct({
+    ...Envelope,
+    type: Schema.Literal('MESSAGE'),
+    message: Schema.Unknown,
+  }),
+]);
+export type WorkerEnvelope = typeof WorkerEnvelope.Type;
+
+/** A page and its worker belong to different Build IDs. Transient, never supported. */
+export class VersionSkew extends Schema.TaggedError<VersionSkew>()(
+  'VersionSkew',
+  { pageBuildId: BuildId, workerBuildId: BuildId },
+) {}
+
+const decodeClient = Schema.decodeUnknownOption(ClientEnvelope);
+const decodeWorker = Schema.decodeUnknownOption(WorkerEnvelope);
+const hasKey = (data: unknown): boolean =>
+  typeof data === 'object' && data !== null && RPC_ENVELOPE_KEY in data;
+
+export const matchClientEnvelope = (
+  data: unknown,
+): Option.Option<ClientEnvelope> =>
+  hasKey(data) ? decodeClient(data) : Option.none();
+
+export const matchWorkerEnvelope = (
+  data: unknown,
+): Option.Option<WorkerEnvelope> =>
+  hasKey(data) ? decodeWorker(data) : Option.none();
+
+/** None when both sides run one Build ID. */
+export const checkVersionSkew = (
+  pageBuildId: BuildId,
+  workerBuildId: BuildId,
+): Option.Option<VersionSkew> =>
+  pageBuildId === workerBuildId
+    ? Option.none()
+    : Option.some(new VersionSkew({ pageBuildId, workerBuildId }));
+
+/** Whether an encoded RPC message opens a new call. */
+export const isRequest = (message: unknown): boolean =>
+  typeof message === 'object' &&
+  message !== null &&
+  (message as { _tag?: unknown })._tag === 'Request';
+
+/**
+ * Counts RPC calls in flight on one side of the wire, from the encoded RPC
+ * messages passing through: a Request opens a call, its Exit or Interrupt
+ * closes it, a Defect closes all. `idle` fires on each return to zero.
+ */
+export const makeInFlight = (idle: () => void = () => {}) => {
+  const open = new Set<unknown>();
+  const close = (id: unknown) => {
+    if (open.delete(id) && open.size === 0) idle();
+  };
+  const tagged = (message: unknown): Record<string, unknown> | undefined =>
+    typeof message === 'object' && message !== null
+      ? (message as Record<string, unknown>)
+      : undefined;
+  return {
+    get size() {
+      return open.size;
+    },
+    /** A message from Worker Client to Worker Server. */
+    request(message: unknown): void {
+      const m = tagged(message);
+      if (m?._tag === 'Request') open.add(String(m.id));
+      else if (m?._tag === 'Interrupt') close(String(m.requestId));
+    },
+    /** A message from Worker Server to Worker Client. */
+    response(message: unknown): void {
+      const m = tagged(message);
+      if (m?._tag === 'Exit') close(String(m.requestId));
+      else if (m?._tag === 'Defect') this.clear();
+    },
+    clear(): void {
+      if (open.size === 0) return;
+      open.clear();
+      idle();
+    },
+  };
+};

package/src/pwa/rpc/handshake/index.ts

@@ -0,0 +1,11 @@
+export {
+  checkVersionSkew,
+  isRequest,
+  makeInFlight,
+  matchClientEnvelope,
+  matchWorkerEnvelope,
+  RPC_ENVELOPE_KEY,
+  ClientEnvelope,
+  VersionSkew,
+  WorkerEnvelope,
+} from './handshake.js';

package/src/pwa/rpc/worker/connections.ts

@@ -0,0 +1,62 @@
+import { makeInFlight } from '../handshake/index.js';
+
+/** The part of a Service Worker API `Client` the Worker Server talks to. */
+export interface PageHandle {
+  readonly id: string;
+  postMessage(message: unknown, transfer: Transferable[]): void;
+}
+
+export interface Connection {
+  readonly portId: number;
+  readonly clientId: string;
+  readonly connectionId: string;
+  page: PageHandle;
+  readonly inFlight: ReturnType<typeof makeInFlight>;
+}
+
+/**
+ * The Worker Client connections this worker instance has seen. Each gets the
+ * numeric port id Effect's runner protocol uses. Held in memory only, so a
+ * restarted worker starts empty.
+ */
+export const makeConnections = (onIdle: () => void) => {
+  let nextPortId = 0;
+  const byKey = new Map<string, Connection>();
+  const byPort = new Map<number, Connection>();
+  const keyOf = (clientId: string, connectionId: string) =>
+    `${clientId}\u0000${connectionId}`;
+
+  return {
+    open(page: PageHandle, connectionId: string): Connection {
+      const existing = byKey.get(keyOf(page.id, connectionId));
+      if (existing) {
+        existing.page = page;
+        return existing;
+      }
+      const connection: Connection = {
+        portId: nextPortId++,
+        clientId: page.id,
+        connectionId,
+        page,
+        inFlight: makeInFlight(onIdle),
+      };
+      byKey.set(keyOf(page.id, connectionId), connection);
+      byPort.set(connection.portId, connection);
+      return connection;
+    },
+    find: (clientId: string, connectionId: string) =>
+      byKey.get(keyOf(clientId, connectionId)),
+    byPort: (portId: number) => byPort.get(portId),
+    all: () => [...byPort.values()],
+    ofClient: (clientId: string) =>
+      [...byPort.values()].filter((c) => c.clientId === clientId),
+    close(connection: Connection): void {
+      byKey.delete(keyOf(connection.clientId, connection.connectionId));
+      byPort.delete(connection.portId);
+      connection.inFlight.clear();
+    },
+    get busy(): boolean {
+      return [...byPort.values()].some((c) => c.inFlight.size > 0);
+    },
+  };
+};

package/src/pwa/rpc/worker/index.ts

@@ -0,0 +1 @@
+export { WorkerServer } from './worker.js';

package/src/pwa/rpc/worker/keep-alive.ts

@@ -0,0 +1,26 @@
+/**
+ * Holds the service worker alive while calls are in flight: every event seen
+ * while busy is extended with one shared promise, settled on `release`.
+ */
+export const makeKeepAlive = () => {
+  let held: { promise: Promise<void>; release: () => void } | undefined;
+  return {
+    extend(event: ExtendableEvent): void {
+      if (held === undefined) {
+        let release!: () => void;
+        const promise = new Promise<void>((resolve) => (release = resolve));
+        held = { promise, release };
+      }
+      try {
+        event.waitUntil(held.promise);
+      } catch {
+        // The event is no longer extendable (InvalidStateError). A later
+        // event of the same calls extends the lifetime instead.
+      }
+    },
+    release(): void {
+      held?.release();
+      held = undefined;
+    },
+  };
+};