@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-frontend/src/runtime/browser/services/PeerSocket.tsx

@@ -0,0 +1,268 @@
+import { AppInstance, DataEnvelope, ServiceClass } from "hkp-frontend/src/types";
+
+import PeerSocketUI from "./PeerSocketUI";
+import ServiceBase from "./ServiceBase";
+import { needsUpdate } from "hkp-frontend/src/ui-components/service/ServiceUI";
+import PeerConnection, { resolveActivePeerHost } from "./PeerConnection";
+
+const serviceName = "Peer Socket";
+const serviceId = "hookup.to/service/peer-socket";
+
+type State = {
+  mode: "Receive only" | "Send only" | "Receive and Send";
+  peerName: string;
+  targetPeer: string;
+  extractIncomingData: boolean;
+  peerPort: number | null;
+  peerPath: string | null;
+  peerHost: string | null;
+  peerSecure: boolean | null;
+  __hkpMount: string | null;
+  /**
+   * Whether this socket may ask its signalling server who else is connected.
+   * A server can refuse on its own (see PeerJsHostDescriptor.discoverable);
+   * this is the same choice made locally, for servers configured by hand where
+   * there is no descriptor to carry it. Off means no such request is ever sent.
+   */
+  peerDiscovery: boolean;
+};
+
+/**
+ * A fresh identity for one end of a socket.
+ *
+ * The two ends carry different prefixes because a socket whose `targetPeer`
+ * equals its own `peerName` addresses itself and connects to nothing — drawing
+ * both from one prefix makes that a matter of luck. The suffix is wide enough
+ * that two people registering against the same signalling server do not land on
+ * an id it would refuse as already taken.
+ */
+const peerIdentity = (prefix: string) =>
+  `${prefix}-${Math.random().toString(36).slice(2, 6)}`;
+
+/** How long to keep waiting for a referenced Peer Server's runtime to publish
+ *  its endpoint before giving up on the connection attempt. */
+const MOUNT_RESOLVE_TIMEOUT_MS = 15000;
+const MOUNT_RETRY_INTERVAL_MS = 250;
+
+class PeerSocket extends ServiceBase<State> {
+  // The live peer connection is owned by the service, not its UI, so it stays
+  // alive whether or not the ServiceUI panel is mounted (crucial on mobile,
+  // where panels mount lazily). The connection is established lazily on the
+  // first configure() — never in the constructor — so instantiating the
+  // service (e.g. in tests) never opens a socket.
+  private connection: PeerConnection;
+  private mountRetryTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    app: AppInstance,
+    board: string,
+    descriptor: ServiceClass,
+    id: string
+  ) {
+    super(app, board, descriptor, id, {
+      mode: "Receive only",
+      peerName: peerIdentity("Host"),
+      targetPeer: peerIdentity("Guest"),
+      extractIncomingData: false,
+      peerPort: null,
+      peerPath: null,
+      peerHost: null,
+      peerSecure: null,
+      __hkpMount: null,
+      peerDiscovery: true,
+    });
+
+    this.connection = new PeerConnection({
+      onData: (envelope) => this.handleIncoming(envelope),
+      onError: (err) => this.pushErrorNotification(err.message),
+    });
+
+    // Override ServiceBase's arrow-function property so toggling bypass also
+    // starts/stops the live connection.
+    this.setBypass = (bypass: boolean) => {
+      this.bypass = !!bypass;
+      this.app.notify(this as any, { bypass: this.bypass });
+      this.syncConnection();
+    };
+  }
+
+  // Forward an inbound envelope to the next service, honouring the mode and the
+  // unpack-received-data setting. Send-only sockets ignore inbound data.
+  private handleIncoming(envelope: DataEnvelope) {
+    if (this.state.mode === "Send only") {
+      return;
+    }
+    const data = this.state.extractIncomingData ? envelope?.data : envelope;
+    this.app.next(this, data);
+  }
+
+  // Bring the live connection in line with the current state + bypass. Cheap to
+  // call repeatedly: PeerConnection.connect() is a no-op when nothing changed.
+  private syncConnection() {
+    this.cancelMountRetry();
+
+    if (this.bypass) {
+      this.connection.close();
+      return;
+    }
+
+    const host = resolveActivePeerHost(this.state, this.app.coordinator);
+    if (host) {
+      this.connection.connect(this.state.peerName, host);
+      return;
+    }
+
+    // Only a mount reference can fail to resolve, and only because the runtime
+    // that owns the Peer Server has not published its endpoint yet — boards
+    // restore their runtimes concurrently, so this service can be configured
+    // first. Poll until it appears rather than leaving the socket dead.
+    this.retryMountResolve(Date.now() + MOUNT_RESOLVE_TIMEOUT_MS);
+  }
+
+  private retryMountResolve(deadline: number) {
+    this.mountRetryTimer = setTimeout(() => {
+      this.mountRetryTimer = null;
+      if (this.bypass) {
+        return;
+      }
+      const host = resolveActivePeerHost(this.state, this.app.coordinator);
+      if (host) {
+        this.connection.connect(this.state.peerName, host);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        this.pushErrorNotification(
+          `Peer Server "${this.state.__hkpMount}" did not publish an endpoint`,
+        );
+        return;
+      }
+      this.retryMountResolve(deadline);
+    }, MOUNT_RETRY_INTERVAL_MS);
+  }
+
+  private cancelMountRetry() {
+    if (this.mountRetryTimer !== null) {
+      clearTimeout(this.mountRetryTimer);
+      this.mountRetryTimer = null;
+    }
+  }
+
+  configure(config: any) {
+    // Backwards-compatible manual injection path: a caller (e.g. a facade) can
+    // still push inbound data through configure({ incoming }).
+    if (config.incoming !== undefined) {
+      const data = this.state.extractIncomingData
+        ? config.incoming.data
+        : config.incoming;
+      this.app.next(this, data);
+    }
+
+    if (needsUpdate(config.peerName, this.state.peerName)) {
+      this.state.peerName = config.peerName;
+      this.app.notify(this, { peerName: this.state.peerName });
+    }
+
+    if (needsUpdate(config.targetPeer, this.state.targetPeer)) {
+      this.state.targetPeer = config.targetPeer;
+      this.app.notify(this, { targetPeer: this.state.targetPeer });
+    }
+
+    if (needsUpdate(config.mode, this.state.mode)) {
+      this.state.mode = config.mode;
+      this.app.notify(this, { mode: this.state.mode });
+    }
+    if (
+      needsUpdate(config.extractIncomingData, this.state.extractIncomingData)
+    ) {
+      this.state.extractIncomingData = config.extractIncomingData;
+      this.app.notify(this, {
+        extractIncomingData: this.state.extractIncomingData,
+      });
+    }
+
+    if (config.peerPort !== undefined) {
+      // coerce string → number (board JSON substitution produces strings)
+      const rawPort = config.peerPort;
+      const port =
+        typeof rawPort === "string"
+          ? rawPort === "" ? null : parseInt(rawPort, 10)
+          : typeof rawPort === "number"
+          ? rawPort
+          : null;
+      if (needsUpdate(port, this.state.peerPort)) {
+        this.state.peerPort = port;
+        this.app.notify(this, { peerPort: this.state.peerPort });
+      }
+    }
+
+    if (config.peerPath !== undefined) {
+      const path = config.peerPath === "" ? null : config.peerPath;
+      if (needsUpdate(path, this.state.peerPath)) {
+        this.state.peerPath = path as string | null;
+        this.app.notify(this, { peerPath: this.state.peerPath });
+      }
+    }
+
+    if (config.peerHost !== undefined) {
+      const host = config.peerHost === "" ? null : config.peerHost;
+      if (needsUpdate(host, this.state.peerHost)) {
+        this.state.peerHost = host as string | null;
+        this.app.notify(this, { peerHost: this.state.peerHost });
+      }
+    }
+
+    if (config.peerSecure !== undefined) {
+      const secure = config.peerSecure === "" ? null : config.peerSecure;
+      if (needsUpdate(secure, this.state.peerSecure)) {
+        this.state.peerSecure = secure as boolean | null;
+        this.app.notify(this, { peerSecure: this.state.peerSecure });
+      }
+    }
+
+    if (config.__hkpMount !== undefined) {
+      const mount = config.__hkpMount === "" ? null : config.__hkpMount;
+      if (needsUpdate(mount, this.state.__hkpMount)) {
+        this.state.__hkpMount = mount as string | null;
+        this.app.notify(this, { __hkpMount: this.state.__hkpMount });
+      }
+    }
+
+    if (config.peerDiscovery !== undefined) {
+      const discovery = !!config.peerDiscovery;
+      if (needsUpdate(discovery, this.state.peerDiscovery)) {
+        this.state.peerDiscovery = discovery;
+        this.app.notify(this, { peerDiscovery: this.state.peerDiscovery });
+      }
+    }
+
+    // Apply any identity/host/bypass change to the live connection.
+    this.syncConnection();
+  }
+
+  process(params: any) {
+    // Receive-only sockets never send upstream data on.
+    if (this.state.mode !== "Receive only") {
+      void this.connection.sendData(this.state.targetPeer, params);
+    }
+    this.app.notify(this, { data: params });
+  }
+
+  destroy() {
+    this.cancelMountRetry();
+    this.connection.close();
+  }
+}
+
+const descriptor = {
+  serviceName,
+  serviceId,
+  create: (
+    app: AppInstance,
+    board: string,
+    descriptor: ServiceClass,
+    id: string
+  ) => new PeerSocket(app, board, descriptor, id),
+  createUI: PeerSocketUI,
+};
+
+export default descriptor;

package/bundle/hkp-frontend/src/runtime/browser/services/PeerSocketReceiverTemplate.json

@@ -0,0 +1,29 @@
+{
+  "runtimes": [
+    {
+      "id": "receiver-runtime",
+      "name": "Peer Receiver",
+      "type": "browser",
+      "state": {
+        "wrapServices": false,
+        "minimized": false
+      }
+    }
+  ],
+  "services": {
+    "receiver-runtime": [
+      {
+        "uuid": "%uuid%",
+        "serviceId": "hookup.to/service/peer-socket",
+        "serviceName": "Peer Socket",
+        "mode": "Receive only",
+        "peerName": "%receiver-name%",
+        "extractIncomingData": false
+      },
+      {
+        "uuid": "%uuid%",
+        "serviceId": "hookup.to/service/monitor"
+      }
+    ]
+  }
+}

package/bundle/hkp-frontend/src/runtime/browser/services/PeerSocketUI.tsx

@@ -0,0 +1,341 @@
+import { useCallback, useState } from "react";
+import { v4 as uuidv4 } from "uuid";
+
+import { ServiceUIProps } from "hkp-frontend/src/types";
+import ServiceUI, {
+  needsUpdate,
+} from "hkp-frontend/src/ui-components/service/ServiceUI";
+import SubmittableInput from "hkp-frontend/src/ui-components/SubmittableInput";
+import ComboInput from "hkp-frontend/src/ui-components/ComboInput";
+
+import RadioGroup from "hkp-frontend/src/ui-components/RadioGroup";
+import Switch from "hkp-frontend/src/ui-components/Switch";
+
+import Button from "hkp-frontend/src/ui-components/Button";
+import { resolveActivePeerHost } from "./PeerConnection";
+
+function parseServerUrl(input: string): {
+  host: string;
+  port: number | null;
+  path: string | null;
+  secure: boolean;
+} {
+  let url = input.trim();
+  if (!url.includes("://")) {
+    url = "ws://" + url;
+  }
+  try {
+    const parsed = new URL(url);
+    const secure = parsed.protocol === "wss:";
+    const host = parsed.hostname;
+    const port = parsed.port ? parseInt(parsed.port, 10) : null;
+    const path =
+      parsed.pathname && parsed.pathname !== "/" ? parsed.pathname : null;
+    return { host, port, path, secure };
+  } catch {
+    return { host: input.trim(), port: null, path: null, secure: false };
+  }
+}
+
+function formatServerUrl(
+  host: string,
+  port: number | null,
+  path: string | null,
+  secure: boolean,
+): string {
+  const scheme = secure ? "wss" : "ws";
+  const defaultPort = secure ? 443 : 80;
+  const portStr = port !== null && port !== defaultPort ? `:${port}` : "";
+  const pathStr = !path || path === "/" ? "" : path;
+  return `${scheme}://${host}${portStr}${pathStr}`;
+}
+
+/**
+ * Outcome of the last peer-list lookup. The list is only fetched when the user
+ * opens the dropdown, so "idle" means nobody has asked yet.
+ */
+type PeerListStatus =
+  | "idle"
+  | "loading"
+  | "ready"
+  | "off"
+  | "prohibited"
+  | "declined"
+  | "error";
+
+const PEER_LIST_HINTS: Record<PeerListStatus, string> = {
+  idle: "Open to look up peers",
+  loading: "Looking up peers…",
+  ready: "No peers found",
+  off: "Peer lookup is switched off",
+  prohibited: "Peer discovery is disabled for this server",
+  declined: "This server does not publish its peer list",
+  error: "Could not reach the peer server",
+};
+
+export default function PeerSocketUI(props: ServiceUIProps) {
+  const [peerName, setPeerName] = useState("");
+  const [targetPeer, setTargetPeer] = useState("");
+  const [currentMode, setCurrentMode] = useState("");
+  const [extractIncomingData, setExtractIncomingData] = useState(false);
+  const [peerPort, setPeerPort] = useState<number | null>(null);
+  const [peerPath, setPeerPath] = useState<string | null>(null);
+  const [peerHost, setPeerHost] = useState<string | null>(null);
+  const [peerSecure, setPeerSecure] = useState<boolean | null>(null);
+  const [mount, setMount] = useState<string | null>(null);
+  const [availablePeers, setAvailablePeers] = useState<string[]>([]);
+  const [peerListStatus, setPeerListStatus] = useState<PeerListStatus>("idle");
+  const [peerDiscovery, setPeerDiscovery] = useState(true);
+
+  // This panel is a pure view: it reflects service state and issues configure()
+  // calls. The live peer connection is owned by the PeerSocket service, so it
+  // keeps running whether or not this panel is mounted.
+  const update = (state: any) => {
+    if (needsUpdate(state.peerName, peerName)) {
+      setPeerName(state.peerName);
+    }
+    if (needsUpdate(state.targetPeer, targetPeer)) {
+      setTargetPeer(state.targetPeer);
+    }
+    if (needsUpdate(state.mode, currentMode)) {
+      setCurrentMode(state.mode);
+    }
+    if (needsUpdate(state.extractIncomingData, extractIncomingData)) {
+      setExtractIncomingData(state.extractIncomingData);
+    }
+    if (needsUpdate(state.peerPort, peerPort)) {
+      setPeerPort(state.peerPort);
+    }
+    if (needsUpdate(state.peerPath, peerPath)) {
+      setPeerPath(state.peerPath);
+    }
+    if (needsUpdate(state.peerHost, peerHost)) {
+      setPeerHost(state.peerHost);
+    }
+    if (needsUpdate(state.peerSecure, peerSecure)) {
+      setPeerSecure(state.peerSecure);
+    }
+    if (needsUpdate(state.__hkpMount, mount)) {
+      setMount(state.__hkpMount);
+    }
+    if (needsUpdate(state.peerDiscovery, peerDiscovery)) {
+      setPeerDiscovery(state.peerDiscovery);
+    }
+  };
+
+  const onInit = (state: any) => update(state);
+  const onNotification = (notification: any) => update(notification);
+
+  const onChangeMode = (newMode: string) => {
+    props.service.configure({ mode: newMode });
+  };
+
+  // Resolve the active server the same way the service does, so the displayed
+  // URL and the fetched peer list match the connection the service holds. Null
+  // means a Peer Server reference whose runtime has not published an endpoint
+  // yet, which is a normal state during board load.
+  const activeHost = resolveActivePeerHost(
+    { peerHost, peerPort, peerPath, peerSecure, __hkpMount: mount },
+    (props.service as any)?.app?.coordinator,
+  );
+
+  const serverDisplayValue = activeHost?.host
+    ? formatServerUrl(
+        activeHost.host,
+        activeHost.port ?? null,
+        activeHost.path,
+        activeHost.secure,
+      )
+    : mount
+      ? `${mount} (waiting for endpoint)`
+      : "";
+
+  const isSendAllowed = currentMode !== "Receive only";
+  const onRandomPeerName = () => setPeerName(uuidv4());
+  const onRandomTargetPeer = () => setTargetPeer(uuidv4());
+  const onSwap = () => {
+    props.service.configure({ peerName: targetPeer, targetPeer: peerName });
+  };
+
+  // Asking a signalling server who is connected to it is a request some
+  // operators would rather not receive, and its outcome is worth reporting
+  // either way — an empty dropdown alone cannot say whether there are no peers,
+  // the server declined, or it was unreachable.
+  const fetchAvailablePeers = useCallback(async () => {
+    if (!activeHost?.host) {
+      return;
+    }
+    if (!peerDiscovery) {
+      // Switched off locally: this is the lever for hand-configured servers,
+      // which have no descriptor to carry an opt-out.
+      setAvailablePeers([]);
+      setPeerListStatus("off");
+      return;
+    }
+    if (!activeHost.discoverable) {
+      // Prohibited for this server: answer from the descriptor without letting
+      // a request leave the client.
+      setAvailablePeers([]);
+      setPeerListStatus("prohibited");
+      return;
+    }
+
+    const protocol = activeHost.secure ? "https" : "http";
+    const defaultPort = activeHost.secure ? 443 : 80;
+    const portStr =
+      activeHost.port && activeHost.port !== defaultPort
+        ? `:${activeHost.port}`
+        : "";
+    const basePath = activeHost.path ?? "/";
+    const peersPath = basePath.endsWith("/")
+      ? `${basePath}peerjs/peers`
+      : `${basePath}/peerjs/peers`;
+    const url = `${protocol}://${activeHost.host}${portStr}${peersPath}`;
+
+    setPeerListStatus("loading");
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        const peers: string[] = await response.json();
+        setAvailablePeers(peers);
+        setPeerListStatus("ready");
+        return;
+      }
+      setAvailablePeers([]);
+      // A refusal is the server's policy, not a fault — worth telling apart
+      // from a server that could not be reached at all.
+      setPeerListStatus(
+        response.status === 401 || response.status === 403
+          ? "declined"
+          : "error",
+      );
+    } catch {
+      setAvailablePeers([]);
+      setPeerListStatus("error");
+    }
+  }, [
+    activeHost?.host,
+    activeHost?.port,
+    activeHost?.path,
+    activeHost?.secure,
+    activeHost?.discoverable,
+    peerDiscovery,
+  ]);
+
+  return (
+    <ServiceUI
+      className="pb-4"
+      {...props}
+      onInit={onInit}
+      onNotification={onNotification}
+      initialSize={{ width: 400, height: undefined }}
+    >
+      <div className="flex flex-col gap-2">
+        <RadioGroup
+          title="Mode"
+          options={["Receive only", "Send only", "Receive and Send"]}
+          value={currentMode}
+          onChange={onChangeMode}
+        />
+        <SubmittableInput
+          fullWidth
+          title="PeerJS Server"
+          value={serverDisplayValue}
+          onSubmit={(value) => {
+            const trimmed = value.trim();
+            // Typing a server here is an explicit override, so it also drops any
+            // Peer Server reference — otherwise the reference would keep winning
+            // and the typed value would appear to be ignored.
+            if (!trimmed) {
+              props.service.configure({
+                peerHost: null,
+                peerPort: null,
+                peerPath: null,
+                peerSecure: null,
+                __hkpMount: null,
+              });
+            } else {
+              const { host, port, path, secure } = parseServerUrl(trimmed);
+              props.service.configure({
+                peerHost: host,
+                peerPort: port,
+                peerPath: path,
+                peerSecure: secure,
+                __hkpMount: null,
+              });
+            }
+          }}
+        />
+        <div className="flex items-stretch gap-1">
+          <div className="flex flex-col gap-2 flex-1">
+            <div className="flex items-end">
+              <SubmittableInput
+                fullWidth
+                title="My Name"
+                value={peerName}
+                onSubmit={(peerName) => props.service.configure({ peerName })}
+              />
+              <Button
+                className="hkp-svc-btn px-1 h-[20px] mb-1"
+                onClick={onRandomPeerName}
+              >
+                Random
+              </Button>
+            </div>
+
+            {isSendAllowed && (
+              <div className="flex items-end">
+                <ComboInput
+                  title="Send to"
+                  value={targetPeer}
+                  options={availablePeers.filter((p) => p !== peerName)}
+                  emptyHint={PEER_LIST_HINTS[peerListStatus]}
+                  onOpen={fetchAvailablePeers}
+                  onSubmit={(targetPeer) =>
+                    props.service.configure({ targetPeer })
+                  }
+                />
+                <Button
+                  className="hkp-svc-btn px-1 h-[20px] mb-1"
+                  onClick={onRandomTargetPeer}
+                >
+                  Random
+                </Button>
+              </div>
+            )}
+          </div>
+
+          {isSendAllowed && (
+            <Button
+              size={null}
+              className="hkp-svc-btn px-1 self-stretch w-6 mb-1"
+              onClick={onSwap}
+            >
+              ⇅
+            </Button>
+          )}
+        </div>
+
+        {currentMode !== "Send only" && (
+          <Switch
+            title="Unpack received data"
+            checked={extractIncomingData}
+            onCheckedChange={(newChecked) =>
+              props.service.configure({ extractIncomingData: newChecked })
+            }
+          />
+        )}
+
+        {isSendAllowed && (
+          <Switch
+            title="Discovery"
+            checked={peerDiscovery}
+            onCheckedChange={(newChecked) =>
+              props.service.configure({ peerDiscovery: newChecked })
+            }
+          />
+        )}
+      </div>
+    </ServiceUI>
+  );
+}