ignotum 0.0.0 → 0.0.2

package/src/client/index.ts

@@ -0,0 +1,90 @@
+import { Result as contractResult } from "@ignotum/contracts/runtime/result";
+import type {
+  ErrorValue,
+  QueryResult as ContractQueryResult,
+  SettledResult,
+} from "@ignotum/contracts/runtime/result";
+
+export const Result = { match: contractResult.match };
+export type Result<Value, Error extends ErrorValue> = SettledResult<Value, Error>;
+export type QueryResult<Value, Error extends ErrorValue> = ContractQueryResult<Value, Error>;
+export type { InternalServerError } from "@ignotum/contracts/runtime/result";
+export { useMutation, useQuery } from "./hooks.js";
+export { Query } from "./query.js";
+export type { QuerySkip } from "./query.js";
+
+export {
+  Component,
+  Fragment,
+  cloneElement,
+  createContext,
+  createElement,
+  createRef,
+  h,
+  isValidElement,
+  toChildArray,
+} from "preact";
+export type {
+  AnyComponent,
+  Attributes,
+  ClassAttributes,
+  ComponentChild,
+  ComponentChildren,
+  ComponentClass,
+  ComponentConstructor,
+  ComponentFactory,
+  ComponentProps,
+  ComponentType,
+  Consumer,
+  Context,
+  ContextType,
+  ErrorInfo,
+  FunctionComponent,
+  FunctionalComponent,
+  JSX,
+  Key,
+  PreactContext,
+  PreactConsumer,
+  PreactDOMAttributes,
+  PreactProvider,
+  Provider,
+  Ref,
+  RefCallback,
+  RefObject,
+  RenderableProps,
+  TargetedAnimationEvent,
+  TargetedClipboardEvent,
+  TargetedCommandEvent,
+  TargetedCompositionEvent,
+  TargetedDragEvent,
+  TargetedEvent,
+  TargetedFocusEvent,
+  TargetedInputEvent,
+  TargetedKeyboardEvent,
+  TargetedMouseEvent,
+  TargetedPictureInPictureEvent,
+  TargetedPointerEvent,
+  TargetedSnapEvent,
+  TargetedSubmitEvent,
+  TargetedToggleEvent,
+  TargetedTouchEvent,
+  TargetedTransitionEvent,
+  TargetedUIEvent,
+  TargetedWheelEvent,
+  VNode,
+} from "preact";
+export {
+  useCallback,
+  useContext,
+  useDebugValue,
+  useEffect,
+  useErrorBoundary,
+  useId,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+} from "preact/hooks";
+export type { Dispatch, Reducer, StateUpdater } from "preact/hooks";

package/src/client/jsx-dev-runtime.ts

@@ -0,0 +1,2 @@
+export { Fragment, jsx, jsxDEV, jsxs } from "preact/jsx-dev-runtime";
+export type { JSX } from "preact/jsx-dev-runtime";

package/src/client/jsx-runtime.ts

@@ -0,0 +1,2 @@
+export { Fragment, jsx, jsxDEV, jsxs } from "preact/jsx-runtime";
+export type { JSX } from "preact/jsx-runtime";

package/src/client/query.ts

@@ -0,0 +1,17 @@
+const QuerySkipTypeId: unique symbol = Symbol.for("ignotum/client/QuerySkip");
+
+export interface QuerySkip {
+  readonly [QuerySkipTypeId]: typeof QuerySkipTypeId;
+}
+
+class QuerySkipToken implements QuerySkip {
+  readonly [QuerySkipTypeId]: typeof QuerySkipTypeId = QuerySkipTypeId;
+}
+
+const skip: QuerySkip = Object.freeze(new QuerySkipToken());
+
+export const Query = { skip };
+
+export const isQuerySkip = <Value extends object | undefined>(
+  value: Value,
+): value is Value & QuerySkip => value === skip;

package/src/client/sync.ts

@@ -0,0 +1,487 @@
+import {
+  Context,
+  Deferred,
+  Duration,
+  Effect,
+  HashMap,
+  Layer,
+  ManagedRuntime,
+  Predicate,
+  Schedule,
+  Schema,
+} from "effect";
+import * as Socket from "effect/unstable/socket/Socket";
+
+import type {
+  ErrorValue,
+  QueryResult,
+  Result as IgnotumResult,
+} from "@ignotum/contracts/runtime/result";
+import { failureFromWire, pending, Result } from "@ignotum/contracts/runtime/result";
+import {
+  ClientMessageJson,
+  RequestId,
+  ServerMessageJson,
+  SubscriptionId,
+  decodeTransportValue,
+  type ClientMessage,
+  type FunctionAddress,
+  type WireResult,
+} from "@ignotum/contracts/runtime/sync";
+import {
+  ClientInfrastructureError,
+  ConnectionUnavailable,
+  InvalidClientMessage,
+  InvalidServerMessage,
+  MutationOutcomeUnknown,
+  ServerProtocolError,
+  clientErrorReporterLayer,
+  reportClientError,
+} from "./errors.js";
+import { syncPath } from "../internal/http-paths.js";
+
+type Listener = () => void;
+type SocketWriter = (chunk: string) => Effect.Effect<void, Socket.SocketError>;
+
+interface QueryEntry {
+  readonly args: Schema.Json;
+  readonly function: FunctionAddress;
+  readonly listeners: Set<Listener>;
+  readonly subscriptionId: SubscriptionId;
+  generation: number;
+  references: number;
+  result: QueryResult<unknown, ErrorValue> | ClientInfrastructureError;
+}
+
+interface QueryObserver {
+  readonly getSnapshot: () => QueryResult<unknown, ErrorValue> | ClientInfrastructureError;
+  readonly release: Effect.Effect<void>;
+  readonly subscribe: (listener: Listener) => () => void;
+}
+
+type QueryLifecycleMessage = Extract<ClientMessage, { readonly type: "Subscribe" | "Unsubscribe" }>;
+
+interface QueryCache {
+  readonly entries: () => Iterable<QueryEntry>;
+  readonly getById: (id: SubscriptionId) => QueryEntry | undefined;
+  readonly setError: (id: SubscriptionId, error: ClientInfrastructureError) => void;
+  readonly setResult: (id: SubscriptionId, result: QueryResult<unknown, ErrorValue>) => void;
+  readonly observe: (
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) => Effect.Effect<QueryObserver>;
+}
+
+const canonicalJson = (value: Schema.Json): string => {
+  if (
+    Predicate.isNull(value) ||
+    Predicate.isString(value) ||
+    Predicate.isNumber(value) ||
+    Predicate.isBoolean(value)
+  ) {
+    return JSON.stringify(value);
+  }
+  if (globalThis.Array.isArray(value)) {
+    return `[${value.map(canonicalJson).join(",")}]`;
+  }
+
+  return `{${Object.entries(value)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+    .join(",")}}`;
+};
+
+const queryKey = (functionAddress: FunctionAddress, args: Schema.Json): string =>
+  `${functionAddress}:${canonicalJson(args)}`;
+
+const subscribeMessage = (entry: QueryEntry): QueryLifecycleMessage => ({
+  type: "Subscribe",
+  id: entry.subscriptionId,
+  function: entry.function,
+  args: entry.args,
+});
+
+const makeQueryCache = (
+  allocateId: () => SubscriptionId,
+  sendLifecycleMessage: (message: QueryLifecycleMessage) => Effect.Effect<void>,
+) => {
+  const queries = new Map<string, QueryEntry>();
+  const queryKeysById = new Map<SubscriptionId, string>();
+
+  const observe = Effect.fn("SyncClient.QueryCache.observe")(function* (
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) {
+    const key = queryKey(functionAddress, args);
+    let entry = queries.get(key);
+
+    if (entry === undefined) {
+      const created: QueryEntry = {
+        args,
+        function: functionAddress,
+        generation: 0,
+        listeners: new Set(),
+        references: 0,
+        result: pending(),
+        subscriptionId: allocateId(),
+      };
+      queries.set(key, created);
+      queryKeysById.set(created.subscriptionId, key);
+      yield* sendLifecycleMessage(subscribeMessage(created));
+      entry = created;
+    }
+
+    const observed = entry;
+    observed.references += 1;
+    observed.generation += 1;
+    let released = false;
+    return {
+      getSnapshot: () => observed.result,
+      subscribe: (listener: Listener) => {
+        observed.listeners.add(listener);
+        return () => observed.listeners.delete(listener);
+      },
+      release: Effect.gen(function* () {
+        if (released) return;
+        released = true;
+        observed.references -= 1;
+        if (observed.references !== 0) return;
+        const generation = ++observed.generation;
+
+        // Preact and HMR may release and reacquire an observer during one render handoff.
+        // Keep the server subscription alive long enough for that handoff to reuse it.
+        yield* Effect.sleep("25 millis");
+        if (
+          observed.references !== 0 ||
+          observed.generation !== generation ||
+          queries.get(key) !== observed
+        ) {
+          return;
+        }
+
+        queries.delete(key);
+        queryKeysById.delete(observed.subscriptionId);
+        yield* sendLifecycleMessage({
+          type: "Unsubscribe",
+          id: observed.subscriptionId,
+        });
+      }),
+    } satisfies QueryObserver;
+  });
+
+  return {
+    entries: () => queries.values(),
+    getById: (id: SubscriptionId) => {
+      const key = queryKeysById.get(id);
+      return key === undefined ? undefined : queries.get(key);
+    },
+    observe,
+    setError: (id, error) => {
+      const key = queryKeysById.get(id);
+      const entry = key === undefined ? undefined : queries.get(key);
+      if (entry === undefined) return;
+      entry.result = error;
+      for (const listener of entry.listeners) {
+        listener();
+      }
+    },
+    setResult: (id, result) => {
+      const key = queryKeysById.get(id);
+      const entry = key === undefined ? undefined : queries.get(key);
+      if (entry === undefined) return;
+      entry.result = result;
+      for (const listener of entry.listeners) {
+        listener();
+      }
+    },
+  } satisfies QueryCache;
+};
+
+const resultFromWire = Effect.fn("SyncClient.resultFromWire")((wire: WireResult) =>
+  Effect.succeed(
+    wire.type === "Success"
+      ? Result.succeed(
+          wire.value === undefined ? undefined : decodeTransportValue(wire.value, wire.dates ?? []),
+        )
+      : failureFromWire(wire.error, wire.dates),
+  ),
+);
+
+export const syncClientInternals = { makeQueryCache, queryIdentity: queryKey, resultFromWire };
+
+const socketUrl = (): string => {
+  const url = new URL(syncPath, globalThis.location.href);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+};
+
+interface SyncClientService {
+  readonly mutate: (
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) => Effect.Effect<IgnotumResult<unknown, ErrorValue>, ClientInfrastructureError>;
+  readonly observe: (
+    functionAddress: FunctionAddress,
+    args: Schema.Json,
+  ) => Effect.Effect<QueryObserver, ClientInfrastructureError>;
+}
+
+interface PendingMutation {
+  readonly deferred: Deferred.Deferred<
+    IgnotumResult<unknown, ErrorValue>,
+    ClientInfrastructureError
+  >;
+  readonly function: FunctionAddress;
+}
+
+export class SyncClient extends Context.Service<SyncClient, SyncClientService>()(
+  "ignotum/client/sync/SyncClient",
+) {
+  static readonly layer = Layer.effect(
+    SyncClient,
+    Effect.gen(function* () {
+      let nextOperationId = 0;
+      let mutations = HashMap.empty<RequestId, PendingMutation>();
+      let writer: SocketWriter | undefined;
+
+      const encode = (message: ClientMessage) =>
+        Schema.encodeEffect(ClientMessageJson)(message).pipe(
+          Effect.mapError((cause) =>
+            InvalidClientMessage.make({
+              cause,
+              message: "Could not encode an Ignotum sync message.",
+            }),
+          ),
+        );
+
+      const sendWith = (write: SocketWriter, message: ClientMessage) =>
+        encode(message).pipe(
+          Effect.flatMap(write),
+          Effect.mapError((cause) =>
+            Schema.is(InvalidClientMessage)(cause)
+              ? cause
+              : ConnectionUnavailable.make({
+                  cause,
+                  message: "The sync connection was lost.",
+                }),
+          ),
+        );
+
+      const send = (message: ClientMessage) =>
+        writer === undefined
+          ? Effect.fail(
+              ConnectionUnavailable.make({ message: "The sync connection is not ready." }),
+            )
+          : sendWith(writer, message);
+
+      const queryCache = makeQueryCache(
+        () => SubscriptionId.make(nextOperationId++),
+        (message) =>
+          writer === undefined
+            ? Effect.void
+            : send(message).pipe(
+                Effect.catchTags({
+                  ConnectionUnavailable: reportClientError,
+                  InvalidClientMessage: reportClientError,
+                }),
+              ),
+      );
+
+      const rejectMutation = (requestId: RequestId, error: ClientInfrastructureError) => {
+        const pendingMutation = HashMap.getUnsafe(mutations, requestId);
+        if (pendingMutation === undefined) {
+          return Effect.void;
+        }
+        mutations = HashMap.remove(mutations, requestId);
+        return reportClientError(error).pipe(
+          Effect.andThen(Deferred.fail(pendingMutation.deferred, error)),
+          Effect.asVoid,
+        );
+      };
+
+      const handleMessage = Effect.fn("SyncClient.handleMessage")(function* (text: string) {
+        const message = yield* Schema.decodeEffect(ServerMessageJson)(text).pipe(
+          Effect.mapError((cause) =>
+            InvalidServerMessage.make({
+              cause,
+              message: "The server returned an invalid sync message.",
+            }),
+          ),
+        );
+
+        switch (message.type) {
+          case "QuerySnapshot": {
+            const entry = queryCache.getById(message.id);
+            if (entry === undefined) return;
+            yield* resultFromWire(message.result).pipe(
+              Effect.tap((result) => Effect.sync(() => queryCache.setResult(message.id, result))),
+            );
+            return;
+          }
+          case "MutationResult": {
+            const pendingMutation = HashMap.getUnsafe(mutations, message.id);
+            if (pendingMutation === undefined) return;
+            mutations = HashMap.remove(mutations, message.id);
+            yield* resultFromWire(message.result).pipe(
+              Effect.flatMap((result) => Deferred.succeed(pendingMutation.deferred, result)),
+            );
+            return;
+          }
+          case "ProtocolError": {
+            const error =
+              message.operation === undefined
+                ? ServerProtocolError.make({
+                    code: message.code,
+                    message: message.message,
+                  })
+                : ServerProtocolError.make({
+                    code: message.code,
+                    message: message.message,
+                    operation: message.operation,
+                  });
+            if (message.operation?.type === "Mutate") {
+              yield* rejectMutation(message.operation.id, error);
+            } else if (message.operation?.type === "Query") {
+              queryCache.setError(message.operation.id, error);
+              yield* reportClientError(error);
+            } else {
+              yield* reportClientError(error);
+            }
+            return;
+          }
+        }
+      });
+
+      const disconnect = Effect.gen(function* () {
+        writer = undefined;
+        const current = mutations;
+        mutations = HashMap.empty();
+        yield* Effect.forEach(HashMap.entries(current), ([id, pendingMutation]) => {
+          const error = MutationOutcomeUnknown.make({
+            function: pendingMutation.function,
+            id,
+            message: "The connection closed before the mutation outcome was known.",
+          });
+          return reportClientError(error).pipe(
+            Effect.andThen(Deferred.fail(pendingMutation.deferred, error)),
+          );
+        });
+      });
+
+      const connect = Effect.scoped(
+        Effect.gen(function* () {
+          const socket = yield* Socket.makeWebSocket(socketUrl(), {
+            closeCodeIsError: () => false,
+          });
+          const write = yield* socket.writer;
+          const onOpen = Effect.gen(function* () {
+            writer = write;
+            yield* Effect.forEach(queryCache.entries(), (entry) =>
+              sendWith(write, subscribeMessage(entry)),
+            );
+          }).pipe(Effect.tapError(reportClientError), Effect.ignore);
+
+          yield* socket.runString(handleMessage, { onOpen });
+        }),
+      ).pipe(
+        Effect.mapError((cause) =>
+          Schema.is(ClientInfrastructureError)(cause)
+            ? cause
+            : ConnectionUnavailable.make({
+                cause,
+                message: "The sync connection was lost.",
+              }),
+        ),
+        Effect.ensuring(disconnect),
+      );
+
+      const reconnectSchedule = Schedule.exponential("250 millis").pipe(
+        Schedule.modifyDelay(({ duration }) =>
+          Effect.succeed(Duration.min(duration, Duration.seconds(5))),
+        ),
+        Schedule.jittered,
+      );
+      yield* connect.pipe(
+        Effect.andThen(
+          Effect.fail(
+            ConnectionUnavailable.make({
+              message: "The sync connection closed; reconnecting.",
+            }),
+          ),
+        ),
+        Effect.tapError(reportClientError),
+        Effect.retry(reconnectSchedule),
+        Effect.forkScoped,
+      );
+
+      const observe: SyncClientService["observe"] = Effect.fn("SyncClient.observe")(
+        function* (functionAddress, args) {
+          return yield* queryCache.observe(functionAddress, args);
+        },
+      );
+
+      const mutate: SyncClientService["mutate"] = Effect.fn("SyncClient.mutate")(
+        function* (functionAddress, args) {
+          const requestId = RequestId.make(nextOperationId++);
+          const deferred = yield* Deferred.make<
+            IgnotumResult<unknown, ErrorValue>,
+            ClientInfrastructureError
+          >();
+          mutations = HashMap.set(mutations, requestId, {
+            deferred,
+            function: functionAddress,
+          });
+          const message: ClientMessage = {
+            type: "Mutate",
+            id: requestId,
+            function: functionAddress,
+            args,
+          };
+          const sendMutation = Effect.gen(function* () {
+            const mutationWriter = writer;
+            if (mutationWriter === undefined) {
+              return yield* ConnectionUnavailable.make({
+                message: "The sync connection is not ready.",
+              });
+            }
+            return yield* sendWith(mutationWriter, message).pipe(
+              Effect.mapError((error) =>
+                Schema.is(InvalidClientMessage)(error)
+                  ? error
+                  : MutationOutcomeUnknown.make({
+                      cause: error,
+                      function: functionAddress,
+                      id: requestId,
+                      message: "The connection failed while sending the mutation.",
+                    }),
+              ),
+            );
+          });
+          yield* sendMutation.pipe(
+            Effect.tapError(reportClientError),
+            Effect.tapError(() =>
+              Effect.sync(() => (mutations = HashMap.remove(mutations, requestId))),
+            ),
+          );
+          return yield* Deferred.await(deferred);
+        },
+      );
+
+      return SyncClient.of({ mutate, observe });
+    }),
+  ).pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal));
+}
+
+export const syncRuntime = ManagedRuntime.make(
+  SyncClient.layer.pipe(Layer.provideMerge(clientErrorReporterLayer)),
+);
+
+// SAFETY: Vite adds this optional property to browser development modules.
+const hot = (
+  import.meta as ImportMeta & {
+    readonly hot?: { readonly dispose: (cleanup: () => void) => void };
+  }
+).hot;
+if (hot !== undefined) {
+  hot.dispose(() => void syncRuntime.dispose());
+}