@smithers-orchestrator/gateway-client 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/gateway-client",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Browser-first client SDK for the Smithers Gateway RPC and event stream APIs",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,7 @@
     "src/"
   ],
   "dependencies": {
-    "@smithers-orchestrator/gateway": "0.18.0"
+    "@smithers-orchestrator/gateway": "0.19.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/SmithersGatewayClient.ts

@@ -15,6 +15,13 @@ type StreamRunEventPayload = {
   payload?: unknown;
 };
 
+type StreamDevToolsEventPayload = {
+  streamId?: string;
+  runId?: string;
+  event?: unknown;
+  error?: unknown;
+};
+
 declare global {
   var __SMITHERS_GATEWAY_UI__: GatewayUiBootConfig | undefined;
 }
@@ -26,25 +33,34 @@ function defaultBaseUrl() {
   return "http://127.0.0.1:7331";
 }
 
+function isUnixWebSocketUrl(baseUrl: string) {
+  return /^ws\+unix:/i.test(baseUrl);
+}
+
 function normalizeBaseUrl(baseUrl: string) {
+  if (isUnixWebSocketUrl(baseUrl)) {
+    return baseUrl;
+  }
   return baseUrl.replace(/\/+$/, "");
 }
 
 function toWebSocketUrl(baseUrl: string, wsPath = "/") {
+  if (isUnixWebSocketUrl(baseUrl)) {
+    const url = new URL(baseUrl);
+    const socketPath = url.pathname.split(":", 1)[0];
+    const path = wsPath.startsWith("/") ? wsPath : `/${wsPath}`;
+    url.pathname = `${socketPath}:${path}`;
+    url.search = "";
+    return url.toString();
+  }
   const url = new URL(wsPath, baseUrl);
   url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
   return url.toString();
 }
 
-function randomId(method: string) {
-  const cryptoApi = globalThis.crypto;
-  const suffix = typeof cryptoApi?.randomUUID === "function"
-    ? cryptoApi.randomUUID()
-    : Math.random().toString(36).slice(2);
-  return `${method}-${suffix}`;
-}
+const unavailableFetch = (() => Promise.reject(new Error("fetch is not available in this environment."))) as unknown as typeof fetch;
 
-function headersFromOptions(options: SmithersGatewayClientOptions) {
+function headersFromOptions(options: Pick<SmithersGatewayClientOptions, "headers" | "token">) {
   const headers = new Headers(options.headers);
   headers.set("content-type", "application/json");
   if (options.token) {
@@ -53,6 +69,44 @@ function headersFromOptions(options: SmithersGatewayClientOptions) {
   return headers;
 }
 
+function gatewayHttpError(method: string, status: number, message = `Gateway HTTP ${status}`) {
+  return new GatewayRpcError({
+    method,
+    status,
+    code: "HTTP_ERROR",
+    message,
+  });
+}
+
+function invalidGatewayResponse(method: string, status: number | undefined, details?: unknown) {
+  return new GatewayRpcError({
+    method,
+    status,
+    code: "INVALID_GATEWAY_RESPONSE",
+    message: "Gateway returned an invalid RPC response frame.",
+    details,
+  });
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isGatewayResponseFrame(value: unknown): value is GatewayResponseFrame {
+  if (!isObject(value)) {
+    return false;
+  }
+  if (value.type !== "res" || typeof value.id !== "string" || typeof value.ok !== "boolean") {
+    return false;
+  }
+  if (value.ok === true) {
+    return "payload" in value;
+  }
+  return isObject(value.error) &&
+    typeof value.error.code === "string" &&
+    typeof value.error.message === "string";
+}
+
 function rpcError(frame: Extract<GatewayResponseFrame, { ok: false }>, method: string, status?: number) {
   return new GatewayRpcError({
     method,
@@ -69,7 +123,7 @@ export class SmithersGatewayClient {
   readonly baseUrl: string;
   readonly token?: string;
   readonly fetchImpl: typeof fetch;
-  readonly WebSocketImpl: typeof WebSocket;
+  readonly WebSocketImpl: typeof WebSocket | undefined;
   readonly headers: HeadersInit | undefined;
   readonly client: Required<NonNullable<SmithersGatewayClientOptions["client"]>>;
   readonly boot: GatewayUiBootConfig | undefined;
@@ -79,7 +133,11 @@ export class SmithersGatewayClient {
     this.baseUrl = normalizeBaseUrl(options.baseUrl ?? defaultBaseUrl());
     this.token = options.token;
     this.headers = options.headers;
-    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.fetchImpl = options.fetch ?? (
+      typeof globalThis.fetch === "function"
+        ? globalThis.fetch.bind(globalThis)
+        : unavailableFetch
+    );
     this.WebSocketImpl = options.WebSocket ?? globalThis.WebSocket;
     this.client = {
       id: options.client?.id ?? "smithers-gateway-client",
@@ -103,14 +161,20 @@ export class SmithersGatewayClient {
       body: JSON.stringify(params ?? {}),
       signal: options.signal,
     });
-    const frame = (await response.json()) as GatewayResponseFrame;
-    if (!response.ok && !("ok" in frame)) {
-      throw new GatewayRpcError({
-        method,
-        status: response.status,
-        code: "HTTP_ERROR",
-        message: `Gateway HTTP ${response.status}`,
-      });
+    let frame: unknown;
+    try {
+      frame = await response.json();
+    } catch {
+      if (response.ok) {
+        throw invalidGatewayResponse(method, response.status);
+      }
+      throw gatewayHttpError(method, response.status);
+    }
+    if (!isGatewayResponseFrame(frame)) {
+      if (!response.ok) {
+        throw gatewayHttpError(method, response.status);
+      }
+      throw invalidGatewayResponse(method, response.status, frame);
     }
     if (!frame.ok) {
       throw rpcError(frame, method, response.status);
@@ -122,6 +186,9 @@ export class SmithersGatewayClient {
     if (!this.WebSocketImpl) {
       throw new Error("WebSocket is not available in this environment.");
     }
+    if (options.signal?.aborted) {
+      throw new Error("Gateway WebSocket open aborted.");
+    }
     const ws = new this.WebSocketImpl(toWebSocketUrl(this.baseUrl, this.boot?.wsPath));
     await new Promise<void>((resolve, reject) => {
       const onOpen = () => {
@@ -132,26 +199,33 @@ export class SmithersGatewayClient {
         cleanup();
         reject(new Error("Gateway WebSocket failed to open."));
       };
+      const onAbort = () => {
+        cleanup();
+        ws.close();
+        reject(new Error("Gateway WebSocket open aborted."));
+      };
       const cleanup = () => {
         ws.removeEventListener("open", onOpen);
         ws.removeEventListener("error", onError);
+        options.signal?.removeEventListener("abort", onAbort);
       };
       ws.addEventListener("open", onOpen);
       ws.addEventListener("error", onError);
-      options.signal?.addEventListener("abort", () => {
-        cleanup();
-        ws.close();
-        reject(new Error("Gateway WebSocket open aborted."));
-      }, { once: true });
+      options.signal?.addEventListener("abort", onAbort, { once: true });
     });
     const connection = new SmithersGatewayConnection(ws);
-    await connection.requestRaw("connect", {
-      minProtocol: 1,
-      maxProtocol: 1,
-      client: this.client,
-      ...(this.token ? { auth: { token: this.token } } : {}),
-      ...(options.subscribe ? { subscribe: options.subscribe } : {}),
-    });
+    try {
+      await connection.requestRaw("connect", {
+        minProtocol: 1,
+        maxProtocol: 1,
+        client: this.client,
+        ...(this.token ? { auth: { token: this.token } } : {}),
+        ...(options.subscribe ? { subscribe: options.subscribe } : {}),
+      });
+    } catch (error) {
+      connection.close();
+      throw error;
+    }
     return connection;
   }
 
@@ -181,6 +255,32 @@ export class SmithersGatewayClient {
     }
   }
 
+  async *streamDevTools(
+    params: GatewayRpcParams<"streamDevTools">,
+    options: { signal?: AbortSignal } = {},
+  ): AsyncGenerator<GatewayEventFrame<StreamDevToolsEventPayload>> {
+    const connection = await this.connect({ subscribe: [params.runId], signal: options.signal });
+    try {
+      const subscribed = await connection.request("streamDevTools", params);
+      if (!isObject(subscribed) || typeof subscribed.streamId !== "string") {
+        throw invalidGatewayResponse("streamDevTools", undefined, subscribed);
+      }
+      for await (const frame of connection.events(options.signal)) {
+        if (
+          (frame.event === "devtools.event" || frame.event === "devtools.error") &&
+          typeof frame.payload === "object" &&
+          frame.payload !== null &&
+          "streamId" in frame.payload &&
+          frame.payload.streamId === subscribed.streamId
+        ) {
+          yield frame as GatewayEventFrame<StreamDevToolsEventPayload>;
+        }
+      }
+    } finally {
+      connection.close();
+    }
+  }
+
   launchRun(params: GatewayRpcParams<"launchRun">) {
     return this.rpc("launchRun", params);
   }
@@ -193,6 +293,14 @@ export class SmithersGatewayClient {
     return this.rpc("cancelRun", params);
   }
 
+  hijackRun(params: GatewayRpcParams<"hijackRun">) {
+    return this.rpc("hijackRun", params);
+  }
+
+  rewindRun(params: GatewayRpcParams<"rewindRun">) {
+    return this.rpc("rewindRun", params);
+  }
+
   submitApproval(params: GatewayRpcParams<"submitApproval">) {
     return this.rpc("submitApproval", params);
   }
@@ -224,4 +332,20 @@ export class SmithersGatewayClient {
   getNodeDiff(params: GatewayRpcParams<"getNodeDiff">) {
     return this.rpc("getNodeDiff", params);
   }
+
+  cronList(params: GatewayRpcParams<"cronList"> = {}) {
+    return this.rpc("cronList", params);
+  }
+
+  cronCreate(params: GatewayRpcParams<"cronCreate">) {
+    return this.rpc("cronCreate", params);
+  }
+
+  cronDelete(params: GatewayRpcParams<"cronDelete">) {
+    return this.rpc("cronDelete", params);
+  }
+
+  cronRun(params: GatewayRpcParams<"cronRun">) {
+    return this.rpc("cronRun", params);
+  }
 }

package/src/SmithersGatewayConnection.ts

@@ -34,6 +34,42 @@ function frameError(frame: Extract<GatewayResponseFrame, { ok: false }>, method:
   });
 }
 
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function invalidFrameError(details?: unknown) {
+  return new GatewayRpcError({
+    method: "websocket",
+    code: "INVALID_GATEWAY_RESPONSE",
+    message: "Gateway returned an invalid WebSocket frame.",
+    details,
+  });
+}
+
+function isGatewayResponseFrame(value: unknown): value is GatewayResponseFrame {
+  if (!isObject(value)) {
+    return false;
+  }
+  if (value.type !== "res" || typeof value.id !== "string" || typeof value.ok !== "boolean") {
+    return false;
+  }
+  if (value.ok === true) {
+    return "payload" in value;
+  }
+  return isObject(value.error) &&
+    typeof value.error.code === "string" &&
+    typeof value.error.message === "string";
+}
+
+function isGatewayEventFrame(value: unknown): value is GatewayEventFrame {
+  return isObject(value) &&
+    value.type === "event" &&
+    typeof value.event === "string" &&
+    typeof value.seq === "number" &&
+    typeof value.stateVersion === "number";
+}
+
 export class SmithersGatewayConnection {
   readonly ws: WebSocket;
   readonly pending = new Map<string, PendingRequest>();
@@ -50,12 +86,12 @@ export class SmithersGatewayConnection {
       this.push({ kind: "error", error: new Error("Gateway WebSocket error") });
     });
     ws.addEventListener("close", () => {
+      const alreadyClosed = this.closed;
       this.closed = true;
-      for (const pending of this.pending.values()) {
-        pending.reject(new Error("Gateway WebSocket closed"));
+      this.rejectPending(new Error("Gateway WebSocket closed"));
+      if (!alreadyClosed) {
+        this.push({ kind: "close" });
       }
-      this.pending.clear();
-      this.push({ kind: "close" });
     });
   }
 
@@ -63,6 +99,9 @@ export class SmithersGatewayConnection {
     method: Method,
     params: GatewayRpcParams<Method>,
   ): Promise<GatewayRpcPayload<Method>> {
+    if (this.closed) {
+      return Promise.reject(new Error("Gateway WebSocket is closed"));
+    }
     const id = randomId(method);
     const frame = { type: "req", id, method, params };
     return new Promise((resolve, reject) => {
@@ -71,21 +110,38 @@ export class SmithersGatewayConnection {
         resolve: (payload) => resolve(payload as GatewayRpcPayload<Method>),
         reject,
       });
-      this.ws.send(JSON.stringify(frame));
+      try {
+        this.ws.send(JSON.stringify(frame));
+      } catch (cause) {
+        this.pending.delete(id);
+        reject(cause instanceof Error ? cause : new Error(String(cause)));
+      }
     });
   }
 
   requestRaw(method: string, params?: unknown): Promise<unknown> {
+    if (this.closed) {
+      return Promise.reject(new Error("Gateway WebSocket is closed"));
+    }
     const id = randomId(method);
     const frame = { type: "req", id, method, params };
     return new Promise((resolve, reject) => {
       this.pending.set(id, { method, resolve, reject });
-      this.ws.send(JSON.stringify(frame));
+      try {
+        this.ws.send(JSON.stringify(frame));
+      } catch (cause) {
+        this.pending.delete(id);
+        reject(cause instanceof Error ? cause : new Error(String(cause)));
+      }
     });
   }
 
   async *events(signal?: AbortSignal): AsyncGenerator<GatewayEventFrame> {
     const abort = () => this.close();
+    if (signal?.aborted) {
+      this.close();
+      return;
+    }
     signal?.addEventListener("abort", abort, { once: true });
     try {
       while (!this.closed || this.queue.length > 0) {
@@ -108,13 +164,21 @@ export class SmithersGatewayConnection {
       return;
     }
     this.closed = true;
+    this.rejectPending(new Error("Gateway WebSocket closed"));
+    this.push({ kind: "close" });
     this.ws.close();
   }
 
   private handleMessage(raw: unknown) {
     const text = typeof raw === "string" ? raw : String(raw);
-    const frame = JSON.parse(text) as GatewayResponseFrame | GatewayEventFrame;
-    if (frame.type === "res") {
+    let frame: unknown;
+    try {
+      frame = JSON.parse(text);
+    } catch {
+      this.push({ kind: "error", error: invalidFrameError(text) });
+      return;
+    }
+    if (isGatewayResponseFrame(frame)) {
       const pending = this.pending.get(frame.id);
       if (!pending) {
         return;
@@ -127,9 +191,19 @@ export class SmithersGatewayConnection {
       pending.reject(frameError(frame, pending.method));
       return;
     }
-    if (frame.type === "event") {
+    if (isObject(frame) && frame.type === "res" && typeof frame.id === "string") {
+      const pending = this.pending.get(frame.id);
+      if (pending) {
+        this.pending.delete(frame.id);
+        pending.reject(invalidFrameError(frame));
+      }
+      return;
+    }
+    if (isGatewayEventFrame(frame)) {
       this.push({ kind: "event", frame });
+      return;
     }
+    this.push({ kind: "error", error: invalidFrameError(frame) });
   }
 
   private push(event: QueuedEvent) {
@@ -151,4 +225,11 @@ export class SmithersGatewayConnection {
     }
     return this.queue.shift();
   }
+
+  private rejectPending(error: Error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
 }