@frontmcp/utils 1.10.15 → 1.11.0-rc.1

package/browser/stdio-bridge/state-machine.mjs

@@ -0,0 +1,211 @@
+// libs/utils/src/stdio-bridge/state-machine.ts
+import { DEV_BUFFER_FULL, DEV_RELOAD_DEADLINE, DEV_SERVER_UNREACHABLE, makeDevError } from "./errors.mjs";
+function createBridgeStateMachine(options) {
+  const { log, bufferSize, reloadDeadlineMs, respond, forward } = options;
+  let state = "Idle";
+  const buffer = [];
+  const requeued = /* @__PURE__ */ new WeakSet();
+  const inflight = /* @__PURE__ */ new Map();
+  let reloadTimer;
+  let degradedDetail;
+  let readyGen = 0;
+  function transition(next, info) {
+    if (state === next) return;
+    log.info("state-transition", { from: state, to: next, ...info });
+    state = next;
+  }
+  function clearReloadTimer() {
+    if (reloadTimer) {
+      clearTimeout(reloadTimer);
+      reloadTimer = void 0;
+    }
+  }
+  async function flushBufferAsResponses(code, reason, data) {
+    while (buffer.length > 0) {
+      const f = buffer.shift();
+      if (!f) break;
+      const id = f.id ?? null;
+      if (id === null) {
+        log.warn("drop-notification", { method: f.method, reason });
+        continue;
+      }
+      await respond(makeDevError(id, code, { reason, ...data }));
+    }
+  }
+  async function failInflightAsResponses(reason, data) {
+    for (const [id, req] of inflight) {
+      const idVal = typeof id === "number" ? id : id;
+      await respond(makeDevError(idVal, DEV_SERVER_UNREACHABLE, { reason, ...data, method: req.frame.method }));
+    }
+    inflight.clear();
+  }
+  const machine = {
+    get state() {
+      return state;
+    },
+    bufferDepth: () => buffer.length,
+    onBootStart() {
+      transition("Booting");
+    },
+    onChildReady() {
+      clearReloadTimer();
+      degradedDetail = void 0;
+      transition("Ready", { bufferDepth: buffer.length });
+      const drain = [...buffer];
+      buffer.length = 0;
+      const drainGen = readyGen;
+      void (async () => {
+        for (const [index, f] of drain.entries()) {
+          if (readyGen !== drainGen) {
+            await keepUnsent(drain.slice(index));
+            return;
+          }
+          const requestId = typeof f.id === "string" || typeof f.id === "number" ? f.id : null;
+          if (requestId !== null) {
+            inflight.set(requestId, { frame: f, forwardedAt: Date.now() });
+          }
+          try {
+            await forward(f);
+          } catch (err) {
+            log.error("forward-failed", { error: err.message });
+            if (requestId !== null && inflight.delete(requestId)) {
+              await respond(makeDevError(requestId, DEV_SERVER_UNREACHABLE, { reason: "forward_failed" }));
+            }
+          }
+        }
+      })();
+    },
+    onChildExit(reason) {
+      log.warn("child-exit", { reason, state });
+      if (state === "Stopping") return;
+      if (state === "Ready" || state === "Booting") {
+        readyGen++;
+        transition("Reloading", { trigger: "child-exit", reason });
+        void failInflightAsResponses("child_exit", { reason });
+        scheduleReloadDeadline();
+      } else if (state === "Reloading") {
+      }
+    },
+    onUpstreamLost(reason) {
+      if (state !== "Ready" && state !== "Booting") return;
+      readyGen++;
+      transition("Reloading", { trigger: "upstream-lost", reason });
+      scheduleReloadDeadline();
+    },
+    async requeue(frame) {
+      if (frame.id !== void 0 && frame.id !== null) inflight.delete(frame.id);
+      if (state === "Ready") {
+        await machine.enqueue(frame);
+        return;
+      }
+      requeued.add(frame);
+      buffer.unshift(frame);
+      if (state === "Degraded" || state === "Stopping") await keepUnsent([]);
+    },
+    onWatcherEvent(trigger) {
+      if (state === "Stopping" || state === "Degraded") return;
+      log.reloadEvent("start", { trigger });
+      readyGen++;
+      transition("Reloading", { trigger });
+      void failInflightAsResponses("reload", { trigger });
+      scheduleReloadDeadline();
+    },
+    onReloadDeadline(detail) {
+      log.error("reload-deadline-elapsed", { bufferDepth: buffer.length });
+      transition("Degraded", { reason: "reload_deadline" });
+      degradedDetail = detail;
+      void flushBufferAsResponses(DEV_RELOAD_DEADLINE, "deadline", { deadlineMs: reloadDeadlineMs, ...detail });
+    },
+    async enqueue(frame) {
+      const isRequest = frame.id !== void 0 && frame.id !== null;
+      if (state === "Ready") {
+        if (isRequest) {
+          inflight.set(frame.id, { frame, forwardedAt: Date.now() });
+        }
+        try {
+          await forward(frame);
+        } catch (err) {
+          log.error("forward-failed", { error: err.message });
+          if (isRequest && inflight.delete(frame.id)) {
+            await respond(makeDevError(frame.id ?? null, DEV_SERVER_UNREACHABLE, { reason: "forward_failed" }));
+          }
+        }
+        return;
+      }
+      if (state === "Degraded" || state === "Stopping") {
+        if (isRequest) {
+          await respond(
+            makeDevError(frame.id ?? null, DEV_SERVER_UNREACHABLE, {
+              reason: state === "Stopping" ? "stopping" : "degraded",
+              ...state === "Degraded" ? degradedDetail : void 0
+            })
+          );
+        } else {
+          log.warn("drop-notification", {
+            method: frame.method,
+            reason: state === "Stopping" ? "stopping" : "degraded"
+          });
+        }
+        return;
+      }
+      if (buffer.length >= bufferSize) {
+        if (isRequest) {
+          await respond(makeDevError(frame.id ?? null, DEV_BUFFER_FULL, { capacity: bufferSize }));
+        } else {
+          log.warn("drop-notification", { method: frame.method, reason: "buffer_full" });
+        }
+        return;
+      }
+      buffer.push(frame);
+    },
+    async relayUpstream(frame) {
+      if (frame.id !== void 0 && frame.id !== null && (frame.result !== void 0 || frame.error !== void 0)) {
+        inflight.delete(frame.id);
+      }
+      await respond(frame);
+    },
+    async stop() {
+      readyGen++;
+      transition("Stopping");
+      clearReloadTimer();
+      await failInflightAsResponses("stopping");
+      await flushBufferAsResponses(DEV_SERVER_UNREACHABLE, "stopping");
+    }
+  };
+  return machine;
+  async function keepUnsent(frames) {
+    if (state === "Ready") {
+      for (const frame of frames) await machine.enqueue(frame);
+      return;
+    }
+    let at = 0;
+    while (at < buffer.length && requeued.has(buffer[at])) at++;
+    buffer.splice(at, 0, ...frames);
+    if (state === "Stopping") await flushBufferAsResponses(DEV_SERVER_UNREACHABLE, "stopping");
+    if (state === "Degraded") await flushBufferAsResponses(DEV_RELOAD_DEADLINE, "deadline", degradedDetail);
+  }
+  function scheduleReloadDeadline() {
+    clearReloadTimer();
+    reloadTimer = setTimeout(() => {
+      if (state === "Reloading" || state === "Booting") {
+        log.error("reload-deadline-fired");
+        transition("Degraded", { reason: "reload_deadline" });
+        void (async () => {
+          while (buffer.length > 0) {
+            const f = buffer.shift();
+            if (!f) break;
+            const id = f.id ?? null;
+            if (id === null) {
+              log.warn("drop-notification", { method: f.method, reason: "deadline" });
+              continue;
+            }
+            await respond(makeDevError(id, DEV_RELOAD_DEADLINE, { deadlineMs: reloadDeadlineMs }));
+          }
+        })();
+      }
+    }, reloadDeadlineMs).unref();
+  }
+}
+export {
+  createBridgeStateMachine
+};

package/browser/stdio-bridge/stdio-framer.mjs

@@ -0,0 +1,91 @@
+// libs/utils/src/stdio-bridge/stdio-framer.ts
+import { makeDevError } from "./errors.mjs";
+function createStdioFramer(options) {
+  const { input, output, log, onFrame, onClose } = options;
+  let buffer = "";
+  let paused = false;
+  let drainResolvers = [];
+  function flushBuffer() {
+    let nl;
+    while ((nl = buffer.indexOf("\n")) >= 0) {
+      const raw = buffer.slice(0, nl).replace(/\r$/, "");
+      buffer = buffer.slice(nl + 1);
+      if (raw.length === 0) continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        log.warn("parse-error", { raw: raw.slice(0, 200), error: err.message });
+        void write(makeDevError(null, -32700, { reason: "parse_error" }));
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        log.warn("parse-error", { raw: raw.slice(0, 200), reason: "not_object" });
+        void write(makeDevError(null, -32700, { reason: "not_object" }));
+        continue;
+      }
+      void Promise.resolve(onFrame(parsed)).catch((err) => {
+        log.error("on-frame-error", {
+          error: err instanceof Error ? err.message : String(err)
+        });
+      });
+    }
+  }
+  let closed = false;
+  function onInputClosed() {
+    if (closed) return;
+    closed = true;
+    onClose?.();
+  }
+  function onData(chunk) {
+    buffer += typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+    flushBuffer();
+  }
+  function write(frame) {
+    return new Promise((resolve) => {
+      const line = JSON.stringify(frame) + "\n";
+      const ok = output.write(line);
+      if (ok) return resolve();
+      if (!paused) {
+        paused = true;
+        input.pause?.();
+      }
+      drainResolvers.push(resolve);
+    });
+  }
+  function onDrain() {
+    if (paused) {
+      paused = false;
+      input.resume?.();
+    }
+    const resolvers = drainResolvers;
+    drainResolvers = [];
+    for (const r of resolvers) r();
+  }
+  return {
+    start: () => {
+      input.setEncoding?.("utf-8");
+      input.on("data", onData);
+      input.on("end", onInputClosed);
+      input.on("close", onInputClosed);
+      output.on("drain", onDrain);
+    },
+    write,
+    stop: () => {
+      input.off("data", onData);
+      input.off("end", onInputClosed);
+      input.off("close", onInputClosed);
+      output.off("drain", onDrain);
+      if (paused) {
+        paused = false;
+        input.resume?.();
+      }
+      const resolvers = drainResolvers;
+      drainResolvers = [];
+      for (const r of resolvers) r();
+    }
+  };
+}
+export {
+  createStdioFramer
+};

package/browser/stdio-bridge/upstream-client.mjs

@@ -0,0 +1,189 @@
+// libs/utils/src/stdio-bridge/upstream-client.ts
+var SESSION_HEADER = "mcp-session-id";
+var END_SESSION_TIMEOUT_MS = 2e3;
+var reinitCounter = 0;
+function nextReinitId() {
+  reinitCounter += 1;
+  return `frontmcp-dev-bridge:reinitialize:${reinitCounter}`;
+}
+function initializedNotification() {
+  return { jsonrpc: "2.0", method: "notifications/initialized" };
+}
+function resultOf(frame, method) {
+  if (!frame) throw new Error(`no response to the replayed ${method}`);
+  if (frame.error) throw new Error(`replayed ${method} failed: ${frame.error.message}`);
+  return typeof frame.result === "object" && frame.result !== null ? frame.result : void 0;
+}
+function createHttpUpstream(options) {
+  const { log, url, onFrame } = options;
+  const abortControllers = /* @__PURE__ */ new Set();
+  let sessionId;
+  async function post(frame, deliver) {
+    const abortController = new AbortController();
+    abortControllers.add(abortController);
+    const signal = abortController.signal;
+    try {
+      const headers = {
+        ...options.headers,
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream"
+      };
+      if (sessionId && frame.method !== "initialize") headers[SESSION_HEADER] = sessionId;
+      const res = await (options.fetch ?? fetch)(url, {
+        method: "POST",
+        redirect: "error",
+        headers,
+        body: JSON.stringify(frame),
+        signal
+      });
+      if (!res.ok) {
+        log.warn("http-upstream-non-ok", { status: res.status, method: frame.method });
+        throw new Error(`upstream returned ${res.status} for ${frame.method ?? "request"}`);
+      }
+      const issued = res.headers.get(SESSION_HEADER);
+      if (issued && frame.method === "initialize") {
+        sessionId = issued;
+        log.info("http-upstream-session");
+      }
+      const contentType = res.headers.get("content-type") ?? "";
+      if (contentType.includes("text/event-stream")) {
+        const reader = res.body?.getReader();
+        if (!reader) return;
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          let nl;
+          while ((nl = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line.startsWith("data:")) continue;
+            const json = line.slice(5).trim();
+            if (!json) continue;
+            try {
+              const parsed = JSON.parse(json);
+              await deliver(parsed);
+            } catch (err) {
+              log.warn("sse-parse-error", { error: err.message, raw: json.slice(0, 200) });
+            }
+          }
+        }
+      } else if (contentType.includes("application/json")) {
+        const body = await res.json();
+        await deliver(body);
+      }
+    } catch (err) {
+      if (err.name === "AbortError") {
+        log.info("http-upstream-aborted", { method: frame.method });
+      } else {
+        log.error("http-upstream-error", { error: err.message, method: frame.method });
+      }
+      throw err;
+    } finally {
+      abortControllers.delete(abortController);
+    }
+  }
+  return {
+    send: (frame) => post(frame, onFrame),
+    async reinitialize(initialize, initialized) {
+      const id = nextReinitId();
+      let response;
+      await post({ ...initialize, id }, async (frame) => {
+        if (frame.id === id) response = frame;
+        else await onFrame(frame);
+      });
+      const result = resultOf(response, "initialize");
+      if (initialized) await post(initializedNotification(), onFrame);
+      return result;
+    },
+    async endSession() {
+      const ending = sessionId;
+      if (!ending) return;
+      sessionId = void 0;
+      try {
+        const res = await (options.fetch ?? fetch)(url, {
+          method: "DELETE",
+          redirect: "error",
+          headers: { ...options.headers, [SESSION_HEADER]: ending },
+          signal: AbortSignal.timeout(END_SESSION_TIMEOUT_MS)
+        });
+        await res.body?.cancel();
+      } catch (err) {
+        log.warn("http-upstream-end-session-failed", { error: err.message });
+      }
+    },
+    close: async () => {
+      for (const ac of abortControllers) ac.abort();
+      abortControllers.clear();
+    }
+  };
+}
+function createPipeUpstream(options) {
+  const { log, child, onFrame, onDevEvents, reinitializeTimeoutMs = 1e4 } = options;
+  const pending = /* @__PURE__ */ new Map();
+  function handleMessage(msg) {
+    if (!msg || typeof msg !== "object") {
+      log.warn("pipe-upstream-non-object", { type: typeof msg });
+      return;
+    }
+    const control = msg;
+    if (control.__frontmcp === "dev-events" && Array.isArray(control.events)) onDevEvents?.(control.events);
+    if (control.__frontmcp !== void 0) return;
+    const frame = msg;
+    const waiter = typeof frame.id === "string" ? pending.get(frame.id) : void 0;
+    if (waiter) {
+      waiter(frame);
+      return;
+    }
+    void onFrame(frame);
+  }
+  child.on("message", handleMessage);
+  async function send(frame) {
+    if (!child.connected) {
+      log.warn("pipe-upstream-disconnected", { method: frame.method });
+      throw new Error(`pipe upstream disconnected for ${frame.method ?? "request"}`);
+    }
+    await new Promise((resolve, reject) => {
+      child.send(frame, (err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    }).catch((err) => {
+      log.warn("pipe-upstream-send-error", { error: err.message, method: frame.method });
+      throw err;
+    });
+  }
+  return {
+    send,
+    async reinitialize(initialize, initialized) {
+      const id = nextReinitId();
+      let timer;
+      const response = new Promise((resolve, reject) => {
+        pending.set(id, resolve);
+        timer = setTimeout(
+          () => reject(new Error(`no response to the replayed initialize within ${reinitializeTimeoutMs}ms`)),
+          reinitializeTimeoutMs
+        );
+      });
+      try {
+        await send({ ...initialize, id });
+        const result = resultOf(await response, "initialize");
+        if (initialized) await send(initializedNotification());
+        return result;
+      } finally {
+        if (timer) clearTimeout(timer);
+        pending.delete(id);
+      }
+    },
+    close: async () => {
+      child.off("message", handleMessage);
+      pending.clear();
+    }
+  };
+}
+export {
+  createHttpUpstream,
+  createPipeUpstream
+};

package/browser/storage/adapters/base.mjs

@@ -0,0 +1,139 @@
+// libs/utils/src/storage/adapters/base.ts
+import { StorageNotConnectedError, StorageNotSupportedError } from "../errors.mjs";
+import { validateOptionalTTL } from "../utils/ttl.mjs";
+var BaseStorageAdapter = class {
+  /**
+   * Whether the adapter is currently connected.
+   */
+  connected = false;
+  /**
+   * Ensure adapter is connected before operations.
+   * @throws StorageNotConnectedError if not connected
+   */
+  ensureConnected() {
+    if (!this.connected) {
+      throw new StorageNotConnectedError(this.backendName);
+    }
+  }
+  /**
+   * Set with validation.
+   */
+  async set(key, value, options) {
+    this.ensureConnected();
+    this.validateSetOptions(options);
+    return this.doSet(key, value, options);
+  }
+  // ============================================
+  // Batch Operations (default implementations)
+  // ============================================
+  /**
+   * Default mget: sequential gets.
+   * Override for more efficient implementations.
+   */
+  async mget(keys) {
+    this.ensureConnected();
+    return Promise.all(keys.map((k) => this.get(k)));
+  }
+  /**
+   * Default mset: sequential sets.
+   * Override for atomic/pipelined implementations.
+   */
+  async mset(entries) {
+    this.ensureConnected();
+    for (const entry of entries) {
+      this.validateSetOptions(entry.options);
+    }
+    await Promise.all(entries.map((e) => this.doSet(e.key, e.value, e.options)));
+  }
+  /**
+   * Default mdelete: sequential deletes.
+   * Override for more efficient implementations.
+   */
+  async mdelete(keys) {
+    this.ensureConnected();
+    const results = await Promise.all(keys.map((k) => this.delete(k)));
+    return results.filter(Boolean).length;
+  }
+  /**
+   * Default count: keys().length.
+   * Override for more efficient implementations.
+   */
+  async count(pattern = "*") {
+    const matchedKeys = await this.keys(pattern);
+    return matchedKeys.length;
+  }
+  /**
+   * Default: not supported, since a read followed by a delete is not atomic.
+   * Override in adapters whose backend can compare and delete in one step.
+   */
+  async deleteIfEquals(_key, _expectedValue) {
+    throw new StorageNotSupportedError(
+      "deleteIfEquals",
+      this.backendName,
+      "Use the memory, Redis, Upstash, Vercel KV or SQLite adapter for an atomic compare-and-delete."
+    );
+  }
+  /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+  async expireIfEquals(_key, _expectedValue, _ttlSeconds) {
+    throw new StorageNotSupportedError(
+      "expireIfEquals",
+      this.backendName,
+      "Use the memory, Redis, Upstash, Vercel KV or SQLite adapter for an atomic compare-and-expire."
+    );
+  }
+  /** Default: not supported, for the same reason as {@link deleteIfEquals}. */
+  async setIfEquals(_key, _expectedValue, _value) {
+    throw new StorageNotSupportedError(
+      "setIfEquals",
+      this.backendName,
+      "Use the memory, Redis or SQLite adapter for an atomic compare-and-set."
+    );
+  }
+  // ============================================
+  // Pub/Sub (default: not supported)
+  // ============================================
+  /**
+   * Default: pub/sub not supported.
+   * Override in adapters that support it.
+   */
+  supportsPubSub() {
+    return false;
+  }
+  /**
+   * Default: throw not supported error.
+   * Override in adapters that support pub/sub.
+   */
+  async publish(_channel, _message) {
+    throw new StorageNotSupportedError("publish", this.backendName, this.getPubSubSuggestion());
+  }
+  /**
+   * Default: throw not supported error.
+   * Override in adapters that support pub/sub.
+   */
+  async subscribe(_channel, _handler) {
+    throw new StorageNotSupportedError("subscribe", this.backendName, this.getPubSubSuggestion());
+  }
+  /**
+   * Get suggestion message for pub/sub not supported error.
+   * Override in specific adapters.
+   */
+  getPubSubSuggestion() {
+    return "Use Redis or Upstash adapter for pub/sub support.";
+  }
+  // ============================================
+  // Validation Helpers
+  // ============================================
+  /**
+   * Validate set options.
+   */
+  validateSetOptions(options) {
+    if (!options) return;
+    validateOptionalTTL(options.ttlSeconds);
+    if (options.ifNotExists && options.ifExists) {
+      throw new Error("ifNotExists and ifExists are mutually exclusive");
+    }
+  }
+};
+export {
+  BaseStorageAdapter
+};