@reactpy/client 0.1.0 → 0.2.1

package/src/reactpy-client.ts

@@ -0,0 +1,274 @@
+import { OutgoingMessage, IncomingMessage } from "./messages";
+import { ReactPyModule } from "./reactpy-vdom";
+import logger from "./logger";
+
+/**
+ * A client for communicating with a ReactPy server.
+ */
+export interface ReactPyClient {
+  /**
+   * Connect to the server and start receiving messages.
+   *
+   * Message handlers should be registered before calling this method in order to
+   * garuntee that messages are not missed.
+   */
+  start: () => void;
+  /**
+   * Disconnect from the server and stop receiving messages.
+   */
+  stop: () => void;
+  /**
+   * Register a handler for a message type.
+   */
+  onMessage: <M extends IncomingMessage>(
+    type: M["type"],
+    handler: (message: M) => void,
+  ) => void;
+  /**
+   * Send a message to the server.
+   */
+  sendMessage: (message: OutgoingMessage) => void;
+  /**
+   * Dynamically load a module from the server.
+   */
+  loadModule: (moduleName: string) => Promise<ReactPyModule>;
+}
+
+export type SimpleReactPyClientProps = {
+  serverLocation?: LocationProps;
+  reconnectOptions?: ReconnectProps;
+};
+
+/**
+ * The location of the server.
+ *
+ * This is used to determine the location of the server's API endpoints. All endpoints
+ * are expected to be found at the base URL, with the following paths:
+ *
+ * - `_reactpy/stream/${route}${query}`: The websocket endpoint for the stream.
+ * - `_reactpy/modules`: The directory containing the dynamically loaded modules.
+ * - `_reactpy/assets`: The directory containing the static assets.
+ */
+type LocationProps = {
+  /**
+   * The base URL of the server.
+   *
+   * @default - document.location.origin
+   */
+  url: string;
+  /**
+   * The route to the page being rendered.
+   *
+   * @default - document.location.pathname
+   */
+  route: string;
+  /**
+   * The query string of the page being rendered.
+   *
+   * @default - document.location.search
+   */
+  query: string;
+};
+
+type ReconnectProps = {
+  maxInterval?: number;
+  maxRetries?: number;
+  backoffRate?: number;
+  intervalJitter?: number;
+};
+
+export class SimpleReactPyClient implements ReactPyClient {
+  private resolveShouldOpen: (value: unknown) => void;
+  private resolveShouldClose: (value: unknown) => void;
+  private readonly urls: ServerUrls;
+  private readonly handlers: {
+    [key in IncomingMessage["type"]]: ((message: any) => void)[];
+  };
+  private readonly socket: { current?: WebSocket };
+
+  constructor(props: SimpleReactPyClientProps) {
+    this.handlers = {
+      "connection-open": [],
+      "connection-close": [],
+      "layout-update": [],
+    };
+
+    this.urls = getServerUrls(
+      props.serverLocation || {
+        url: document.location.origin,
+        route: document.location.pathname,
+        query: document.location.search,
+      },
+    );
+
+    this.resolveShouldOpen = () => {
+      throw new Error("Could not start client");
+    };
+    this.resolveShouldClose = () => {
+      throw new Error("Could not stop client");
+    };
+    const shouldOpen = new Promise((r) => (this.resolveShouldOpen = r));
+    const shouldClose = new Promise((r) => (this.resolveShouldClose = r));
+
+    this.socket = startReconnectingWebSocket({
+      shouldOpen,
+      shouldClose,
+      url: this.urls.stream,
+      onOpen: () => this.handleIncoming({ type: "connection-open" }),
+      onMessage: async ({ data }) => this.handleIncoming(JSON.parse(data)),
+      onClose: () => this.handleIncoming({ type: "connection-close" }),
+      ...props.reconnectOptions,
+    });
+  }
+
+  start(): void {
+    logger.log("starting client...");
+    this.resolveShouldOpen(undefined);
+  }
+
+  stop(): void {
+    logger.log("stopping client...");
+    this.resolveShouldClose(undefined);
+  }
+
+  onMessage<M extends IncomingMessage>(
+    type: M["type"],
+    handler: (message: M) => void,
+  ): void {
+    this.handlers[type].push(handler);
+  }
+
+  sendMessage(message: OutgoingMessage): void {
+    this.socket.current?.send(JSON.stringify(message));
+  }
+
+  loadModule(moduleName: string): Promise<ReactPyModule> {
+    return import(`${this.urls.modules}/${moduleName}`);
+  }
+
+  private handleIncoming(message: IncomingMessage): void {
+    if (!message.type) {
+      logger.warn("Received message without type", message);
+      return;
+    }
+
+    const messageHandlers: ((m: any) => void)[] | undefined =
+      this.handlers[message.type];
+    if (!messageHandlers) {
+      logger.warn("Received message without handler", message);
+      return;
+    }
+
+    messageHandlers.forEach((h) => h(message));
+  }
+}
+
+type ServerUrls = {
+  base: URL;
+  stream: string;
+  modules: string;
+  assets: string;
+};
+
+function getServerUrls(props: LocationProps): ServerUrls {
+  const base = new URL(`${props.url || document.location.origin}/_reactpy`);
+  const modules = `${base}/modules`;
+  const assets = `${base}/assets`;
+
+  const streamProtocol = `ws${base.protocol === "https:" ? "s" : ""}`;
+  const streamPath = rtrim(`${base.pathname}/stream${props.route || ""}`, "/");
+  const stream = `${streamProtocol}://${base.host}${streamPath}${props.query}`;
+
+  return { base, modules, assets, stream };
+}
+
+function startReconnectingWebSocket(
+  props: {
+    shouldOpen: Promise<any>;
+    shouldClose: Promise<any>;
+    url: string;
+    onOpen: () => void;
+    onMessage: (message: MessageEvent<any>) => void;
+    onClose: () => void;
+  } & ReconnectProps,
+) {
+  const {
+    maxInterval = 60000,
+    maxRetries = 50,
+    backoffRate = 1.1,
+    intervalJitter = 0.1,
+  } = props;
+
+  const startInterval = 750;
+  let retries = 0;
+  let interval = startInterval;
+  let closed = false;
+  let everConnected = false;
+  const socket: { current?: WebSocket } = {};
+
+  const connect = () => {
+    if (closed) {
+      return;
+    }
+    socket.current = new WebSocket(props.url);
+    socket.current.onopen = () => {
+      everConnected = true;
+      logger.log("client connected");
+      interval = startInterval;
+      retries = 0;
+      props.onOpen();
+    };
+    socket.current.onmessage = props.onMessage;
+    socket.current.onclose = () => {
+      if (!everConnected) {
+        logger.log("failed to connect");
+        return;
+      }
+
+      logger.log("client disconnected");
+      props.onClose();
+
+      if (retries >= maxRetries) {
+        return;
+      }
+
+      const thisInterval = addJitter(interval, intervalJitter);
+      logger.log(
+        `reconnecting in ${(thisInterval / 1000).toPrecision(4)} seconds...`,
+      );
+      setTimeout(connect, thisInterval);
+      interval = nextInterval(interval, backoffRate, maxInterval);
+      retries++;
+    };
+  };
+
+  props.shouldOpen.then(connect);
+  props.shouldClose.then(() => {
+    closed = true;
+    socket.current?.close();
+  });
+
+  return socket;
+}
+
+function nextInterval(
+  currentInterval: number,
+  backoffRate: number,
+  maxInterval: number,
+): number {
+  return Math.min(
+    currentInterval *
+      // increase interval by backoff rate
+      backoffRate,
+    // don't exceed max interval
+    maxInterval,
+  );
+}
+
+function addJitter(interval: number, jitter: number): number {
+  return interval + (Math.random() * jitter * interval * 2 - jitter * interval);
+}
+
+function rtrim(text: string, trim: string): string {
+  return text.replace(new RegExp(`${trim}+$`), "");
+}

package/src/reactpy-vdom.tsx

@@ -0,0 +1,261 @@
+import React, { ComponentType } from "react";
+import { ReactPyClient } from "./reactpy-client";
+import serializeEvent from "event-to-object";
+
+export async function loadImportSource(
+  vdomImportSource: ReactPyVdomImportSource,
+  client: ReactPyClient,
+): Promise<BindImportSource> {
+  let module: ReactPyModule;
+  if (vdomImportSource.sourceType === "URL") {
+    module = await import(vdomImportSource.source);
+  } else {
+    module = await client.loadModule(vdomImportSource.source);
+  }
+  if (typeof module.bind !== "function") {
+    throw new Error(
+      `${vdomImportSource.source} did not export a function 'bind'`,
+    );
+  }
+
+  return (node: HTMLElement) => {
+    const binding = module.bind(node, {
+      sendMessage: client.sendMessage,
+      onMessage: client.onMessage,
+    });
+    if (
+      !(
+        typeof binding.create === "function" &&
+        typeof binding.render === "function" &&
+        typeof binding.unmount === "function"
+      )
+    ) {
+      console.error(`${vdomImportSource.source} returned an impropper binding`);
+      return null;
+    }
+
+    return {
+      render: (model) =>
+        binding.render(
+          createImportSourceElement({
+            client,
+            module,
+            binding,
+            model,
+            currentImportSource: vdomImportSource,
+          }),
+        ),
+      unmount: binding.unmount,
+    };
+  };
+}
+
+function createImportSourceElement(props: {
+  client: ReactPyClient;
+  module: ReactPyModule;
+  binding: ReactPyModuleBinding;
+  model: ReactPyVdom;
+  currentImportSource: ReactPyVdomImportSource;
+}): any {
+  let type: any;
+  if (props.model.importSource) {
+    if (
+      !isImportSourceEqual(props.currentImportSource, props.model.importSource)
+    ) {
+      console.error(
+        "Parent element import source " +
+          stringifyImportSource(props.currentImportSource) +
+          " does not match child's import source " +
+          stringifyImportSource(props.model.importSource),
+      );
+      return null;
+    } else if (!props.module[props.model.tagName]) {
+      console.error(
+        "Module from source " +
+          stringifyImportSource(props.currentImportSource) +
+          ` does not export ${props.model.tagName}`,
+      );
+      return null;
+    } else {
+      type = props.module[props.model.tagName];
+    }
+  } else {
+    type = props.model.tagName;
+  }
+  return props.binding.create(
+    type,
+    createAttributes(props.model, props.client),
+    createChildren(props.model, (child) =>
+      createImportSourceElement({
+        ...props,
+        model: child,
+      }),
+    ),
+  );
+}
+
+function isImportSourceEqual(
+  source1: ReactPyVdomImportSource,
+  source2: ReactPyVdomImportSource,
+) {
+  return (
+    source1.source === source2.source &&
+    source1.sourceType === source2.sourceType
+  );
+}
+
+function stringifyImportSource(importSource: ReactPyVdomImportSource) {
+  return JSON.stringify({
+    source: importSource.source,
+    sourceType: importSource.sourceType,
+  });
+}
+
+export function createChildren<Child>(
+  model: ReactPyVdom,
+  createChild: (child: ReactPyVdom) => Child,
+): (Child | string)[] {
+  if (!model.children) {
+    return [];
+  } else {
+    return model.children.map((child) => {
+      switch (typeof child) {
+        case "object":
+          return createChild(child);
+        case "string":
+          return child;
+      }
+    });
+  }
+}
+
+export function createAttributes(
+  model: ReactPyVdom,
+  client: ReactPyClient,
+): { [key: string]: any } {
+  return Object.fromEntries(
+    Object.entries({
+      // Normal HTML attributes
+      ...model.attributes,
+      // Construct event handlers
+      ...Object.fromEntries(
+        Object.entries(model.eventHandlers || {}).map(([name, handler]) =>
+          createEventHandler(client, name, handler),
+        ),
+      ),
+      // Convert snake_case to camelCase names
+    }).map(normalizeAttribute),
+  );
+}
+
+function createEventHandler(
+  client: ReactPyClient,
+  name: string,
+  { target, preventDefault, stopPropagation }: ReactPyVdomEventHandler,
+): [string, () => void] {
+  return [
+    name,
+    function () {
+      const data = Array.from(arguments).map((value) => {
+        if (!(typeof value === "object" && value.nativeEvent)) {
+          return value;
+        }
+        const event = value as React.SyntheticEvent<any>;
+        if (preventDefault) {
+          event.preventDefault();
+        }
+        if (stopPropagation) {
+          event.stopPropagation();
+        }
+        return serializeEvent(event.nativeEvent);
+      });
+      client.sendMessage({ type: "layout-event", data, target });
+    },
+  ];
+}
+
+function normalizeAttribute([key, value]: [string, any]): [string, any] {
+  let normKey = key;
+  let normValue = value;
+
+  if (key === "style" && typeof value === "object") {
+    normValue = Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [snakeToCamel(k), v]),
+    );
+  } else if (
+    key.startsWith("data_") ||
+    key.startsWith("aria_") ||
+    DASHED_HTML_ATTRS.includes(key)
+  ) {
+    normKey = key.split("_").join("-");
+  } else {
+    normKey = snakeToCamel(key);
+  }
+  return [normKey, normValue];
+}
+
+function snakeToCamel(str: string): string {
+  return str.replace(/([_][a-z])/g, (group) =>
+    group.toUpperCase().replace("_", ""),
+  );
+}
+
+// see list of HTML attributes with dashes in them:
+// https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#attribute_list
+const DASHED_HTML_ATTRS = ["accept_charset", "http_equiv"];
+
+export type ReactPyComponent = ComponentType<{ model: ReactPyVdom }>;
+
+export type ReactPyVdom = {
+  tagName: string;
+  key?: string;
+  attributes?: { [key: string]: string };
+  children?: (ReactPyVdom | string)[];
+  error?: string;
+  eventHandlers?: { [key: string]: ReactPyVdomEventHandler };
+  importSource?: ReactPyVdomImportSource;
+};
+
+export type ReactPyVdomEventHandler = {
+  target: string;
+  preventDefault?: boolean;
+  stopPropagation?: boolean;
+};
+
+export type ReactPyVdomImportSource = {
+  source: string;
+  sourceType?: "URL" | "NAME";
+  fallback?: string | ReactPyVdom;
+  unmountBeforeUpdate?: boolean;
+};
+
+export type ReactPyModule = {
+  bind: (
+    node: HTMLElement,
+    context: ReactPyModuleBindingContext,
+  ) => ReactPyModuleBinding;
+} & { [key: string]: any };
+
+export type ReactPyModuleBindingContext = {
+  sendMessage: ReactPyClient["sendMessage"];
+  onMessage: ReactPyClient["onMessage"];
+};
+
+export type ReactPyModuleBinding = {
+  create: (
+    type: any,
+    props?: any,
+    children?: (any | string | ReactPyVdom)[],
+  ) => any;
+  render: (element: any) => void;
+  unmount: () => void;
+};
+
+export type BindImportSource = (
+  node: HTMLElement,
+) => ImportSourceBinding | null;
+
+export type ImportSourceBinding = {
+  render: (model: ReactPyVdom) => void;
+  unmount: () => void;
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../../tsconfig.package.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "composite": true
+  },
+  "include": ["src"],
+  "references": [
+    {
+      "path": "../../event-to-object"
+    }
+  ]
+}