@opengeni/sdk 0.57.0 → 1.0.0

package/src/site-http.ts

@@ -0,0 +1,162 @@
+/** HTTP transport for the ordinary SDK. One response port per request keeps
+ * event streams incremental and cancellation independent of other requests. */
+export const SITE_HTTP = "opengeni.site.http";
+export const SITE_WORKSPACE = "site-host";
+export type SiteHttpRequest = {
+  type: typeof SITE_HTTP;
+  requestId: string;
+  path: string;
+  method: string;
+  headers: [string, string][];
+  body?: string;
+};
+
+import { siteSessionPath } from "@opengeni/contracts/site-session-http";
+export { siteSessionPath } from "@opengeni/contracts/site-session-http";
+
+export function isSiteHttpRequest(value: unknown): value is SiteHttpRequest {
+  if (!value || typeof value !== "object") return false;
+  const v = value as SiteHttpRequest;
+  return (
+    v.type === SITE_HTTP &&
+    typeof v.requestId === "string" &&
+    typeof v.path === "string" &&
+    typeof v.method === "string" &&
+    /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(v.method) &&
+    (v.body === undefined || typeof v.body === "string") &&
+    Array.isArray(v.headers) &&
+    v.headers.every(
+      (h) => Array.isArray(h) && h.length === 2 && h.every((x) => typeof x === "string"),
+    )
+  );
+}
+
+export async function serveSiteHttp(
+  message: SiteHttpRequest,
+  port: MessagePort,
+  fetchResponse: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>,
+  signal: AbortSignal,
+): Promise<void> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let wake: (() => void) | undefined;
+  let pulling = false;
+  const onMessage = (event: MessageEvent) => {
+    if (event.data === "pull") {
+      pulling = true;
+      wake?.();
+    }
+  };
+  const abort = () => {
+    void reader?.cancel(signal.reason).catch(() => {});
+    wake?.();
+  };
+  port.addEventListener("message", onMessage);
+  signal.addEventListener("abort", abort, { once: true });
+  port.start();
+  try {
+    if (signal.aborted) throw signal.reason;
+    const response = await fetchResponse(message, signal);
+    reader = response.body?.getReader();
+    port.postMessage({ status: response.status, headers: [...response.headers], body: !!reader });
+    if (reader)
+      while (!signal.aborted) {
+        if (!pulling)
+          await new Promise<void>((resolve) => {
+            wake = resolve;
+          });
+        wake = undefined;
+        if (signal.aborted) break;
+        pulling = false;
+        const part = await reader.read();
+        if (part.done) {
+          port.postMessage({ done: true });
+          break;
+        }
+        port.postMessage({ chunk: part.value });
+      }
+    if (signal.aborted) throw signal.reason;
+  } catch (error) {
+    port.postMessage({ error: error instanceof Error ? error.message : "Site request failed" });
+  } finally {
+    signal.removeEventListener("abort", abort);
+    port.removeEventListener("message", onMessage);
+    await reader?.cancel().catch(() => {});
+    port.close();
+  }
+}
+
+export async function sitePortFetch(
+  port: MessagePort,
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const request = new Request(input, init);
+  const url = new URL(request.url);
+  const path = `${url.pathname}${url.search}`;
+  siteSessionPath(path, SITE_WORKSPACE, request.method);
+  const channel = new MessageChannel();
+  const requestId = crypto.randomUUID();
+  const body = request.body ? await request.text() : undefined;
+  return await new Promise<Response>((resolve, reject) => {
+    let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+    let finished = false;
+    const cleanup = () => {
+      finished = true;
+      request.signal.removeEventListener("abort", abort);
+      channel.port1.close();
+    };
+    const abort = () => {
+      if (finished) return;
+      port.postMessage({ type: "opengeni.site.cancel", version: 2, requestId });
+      const error = request.signal.reason ?? new DOMException("Cancelled", "AbortError");
+      controller?.error(error);
+      reject(error);
+      cleanup();
+    };
+    channel.port1.onmessage = (event) => {
+      const data = event.data;
+      if (data.error) {
+        const error = new Error(data.error);
+        controller?.error(error);
+        reject(error);
+        cleanup();
+      } else if (data.status) {
+        const stream = data.body
+          ? new ReadableStream<Uint8Array>({
+              start(c) {
+                controller = c;
+              },
+              pull() {
+                channel.port1.postMessage("pull");
+              },
+              cancel() {
+                controller = undefined;
+                abort();
+              },
+            })
+          : null;
+        resolve(new Response(stream, { status: data.status, headers: data.headers }));
+        if (!data.body) cleanup();
+      } else if (data.done) {
+        controller?.close();
+        cleanup();
+      } else if (data.chunk) controller?.enqueue(data.chunk);
+    };
+    if (request.signal.aborted) {
+      abort();
+      return;
+    }
+    request.signal.addEventListener("abort", abort, { once: true });
+    port.postMessage(
+      {
+        type: SITE_HTTP,
+        requestId,
+        path,
+        method: request.method,
+        headers: [...request.headers],
+        ...(body === undefined ? {} : { body }),
+      } satisfies SiteHttpRequest,
+      [channel.port2],
+    );
+  });
+}

package/src/site-tool-bridge.ts

@@ -0,0 +1,146 @@
+import { siteRequestHeaders } from "@opengeni/contracts/site-session-http";
+import { OpenGeniApiError } from "./errors";
+import { siteSessionPath, type SiteHttpRequest } from "./site-http";
+import type { OpenGeniSiteToolCatalog } from "./site";
+import type { OpenGeniWorkspaceTools } from "./tools";
+import type { ToolGatewayCallRequest, ToolGatewayCallResponse, ToolGatewayIdentity } from "./types";
+
+export type SiteToolCallRequest = ToolGatewayCallRequest & {
+  siteArtifactId: string;
+  siteVersionId: string;
+};
+export type SiteToolCaller = (input: {
+  workspaceId: string;
+  request: ToolGatewayCallRequest &
+    Partial<Pick<SiteToolCallRequest, "siteArtifactId" | "siteVersionId">>;
+  signal: AbortSignal;
+}) => Promise<ToolGatewayCallResponse>;
+export type SiteToolBridge = {
+  fetch?: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>;
+  catalog: (options: { signal: AbortSignal }) => Promise<OpenGeniSiteToolCatalog>;
+  call: (
+    request: ToolGatewayCallRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayCallResponse>;
+};
+export type CreateSiteToolBridgeOptions = {
+  workspaceTools: Pick<OpenGeniWorkspaceTools, "$catalog">;
+  workspaceId: string;
+
+  callTool: SiteToolCaller;
+  isCatalogStale?: (error: unknown) => boolean;
+  /** Optional authenticated host transport for the host-bound workspace API.
+   * Omit to expose tools only. Site-provided authorization headers are never forwarded. */
+  fetchResponse?: (path: string, init: RequestInit) => Promise<Response>;
+} & (
+  | { artifactId: string; siteVersionId: string; requestedTools: readonly ToolGatewayIdentity[] }
+  | { artifactId?: never; siteVersionId?: never; requestedTools?: never }
+);
+
+/** Host-side bridge for the opaque Site frame. Supply an authenticated transport;
+ * the server independently checks live viewer access and the exact Site version.
+ * Recreate on actor/version change. Never take these pinned fields from HTML. */
+export function createSiteToolBridge(input: CreateSiteToolBridgeOptions): SiteToolBridge {
+  const allowed = input.requestedTools ? new Set(input.requestedTools.map(identityKey)) : null;
+  let projectedCatalog: OpenGeniSiteToolCatalog | null = null;
+  const loadCatalog = async ({
+    signal,
+    refresh = false,
+  }: {
+    signal: AbortSignal;
+    refresh?: boolean;
+  }): Promise<OpenGeniSiteToolCatalog> => {
+    signal.throwIfAborted();
+    if (projectedCatalog && !refresh) return projectedCatalog;
+    const current = await input.workspaceTools.$catalog({
+      signal,
+      ...(refresh ? { refresh } : {}),
+    });
+    signal.throwIfAborted();
+    if (current.workspaceId !== input.workspaceId)
+      throw new Error("Site catalog workspace mismatch");
+    projectedCatalog = {
+      version: current.version,
+      generation: current.generation,
+      digest: current.digest,
+      createdAt: current.createdAt,
+      entries: current.entries.filter(
+        (entry) => !allowed || allowed.has(identityKey(entry.identity)),
+      ),
+    };
+    return projectedCatalog;
+  };
+  return {
+    ...(input.fetchResponse
+      ? {
+          fetch: async (message: SiteHttpRequest, signal: AbortSignal) => {
+            const path = siteSessionPath(
+              message.path,
+              input.workspaceId,
+              message.method,
+              input.artifactId,
+            );
+            const headers = siteRequestHeaders(message.headers);
+            if (input.artifactId) {
+              headers.set("x-opengeni-site-id", input.artifactId);
+              headers.set("x-opengeni-site-version", input.siteVersionId);
+            }
+
+            return input.fetchResponse!(path, {
+              method: message.method,
+              signal,
+              headers: Object.fromEntries(headers),
+              ...(message.body === undefined ? {} : { body: message.body }),
+            });
+          },
+        }
+      : {}),
+    catalog: loadCatalog,
+    call: async (request, { signal }) => {
+      if (allowed && !allowed.has(identityKey(request.identity)))
+        throw new Error("This tool is not available to the Site");
+      const call = async (refresh = false) => {
+        const catalog = await loadCatalog({ signal, refresh });
+        if (
+          !catalog.entries.some(
+            (entry) => identityKey(entry.identity) === identityKey(request.identity),
+          )
+        )
+          throw new Error("This requested tool is not enabled in the workspace");
+        return input.callTool({
+          workspaceId: input.workspaceId,
+          signal,
+          request: {
+            ...(request.operationId ? { operationId: request.operationId } : {}),
+            catalogDigest: catalog.digest,
+            identity: request.identity,
+            arguments: request.arguments,
+            ...(input.artifactId
+              ? { siteArtifactId: input.artifactId, siteVersionId: input.siteVersionId }
+              : {}),
+          },
+        });
+      };
+      try {
+        return await call();
+      } catch (error) {
+        // Only pre-execution catalog rejection permits one retry. Never retry
+        // transport failures, expired credentials or uncertain tool effects.
+        if (!(input.isCatalogStale ?? isSiteCatalogStaleError)(error)) throw error;
+        projectedCatalog = null;
+        return await call(true);
+      }
+    },
+  };
+}
+
+export function isSiteCatalogStaleError(error: unknown): boolean {
+  return (
+    error instanceof OpenGeniApiError &&
+    error.status === 409 &&
+    error.details?.code === "catalog_stale"
+  );
+}
+function identityKey(identity: ToolGatewayIdentity): string {
+  return `${identity.serverId}\u0000${identity.toolName}`;
+}