@opengeni/sdk 3.3.2 → 3.4.0

package/src/site-sql.ts

@@ -0,0 +1,153 @@
+/**
+ * Site SQL for Site HTML: run the named, parameterized queries the Site's
+ * owner defined on its optional SQLite database. Sites never send SQL. The
+ * request travels over the host's Site HTTP channel like Site Data; the API
+ * checks who may run the query and binds `:viewer` (and the other `viewer_*`
+ * parameters) from the signed-in viewer, never from the page. Returned rows
+ * are untrusted input: render them with textContent, never innerHTML.
+ */
+import { SITE_DATA_PATH_PREFIX } from "./site-data";
+
+export type OpenGeniSiteSqlErrorCode =
+  | "validation"
+  | "not_found"
+  | "forbidden"
+  /** This viewer may not do this on this Site (a role the Site's rules exclude). */
+  | "not_available_for_viewer"
+  | "conflict"
+  | "quota_exceeded"
+  | "rate_limited"
+  | "sql_error"
+  | "unavailable"
+  | "disabled"
+  | "site_sql_unsupported"
+  | "request_failed";
+
+export class OpenGeniSiteSqlError extends Error {
+  constructor(
+    readonly code: OpenGeniSiteSqlErrorCode,
+    message: string,
+    readonly status: number,
+    readonly details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "OpenGeniSiteSqlError";
+  }
+}
+
+/** A parameter value. Booleans bind as 1 and 0. */
+export type OpenGeniSiteSqlValue = string | number | boolean | null;
+
+export type OpenGeniSiteSqlResult<Row extends Record<string, unknown> = Record<string, unknown>> = {
+  columns: string[];
+  /** Rows keyed by column name; blobs come back as `{ $base64: string }`. */
+  rows: Row[];
+  /** True when the query's row or size limit cut the result short. */
+  truncated: boolean;
+  rowsRead: number;
+  rowsWritten: number;
+};
+
+export type OpenGeniSiteSql = {
+  /**
+   * Run the named query `name` with `params` (names without the colon). Do
+   * not pass `viewer` or any `viewer_*` parameter: the host binds them.
+   */
+  run<Row extends Record<string, unknown> = Record<string, unknown>>(
+    name: string,
+    params?: Record<string, OpenGeniSiteSqlValue>,
+  ): Promise<OpenGeniSiteSqlResult<Row>>;
+};
+
+const QUERY_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/u;
+
+const KNOWN_CODES = new Set<string>([
+  "validation",
+  "not_found",
+  "forbidden",
+  "not_available_for_viewer",
+  "conflict",
+  "quota_exceeded",
+  "rate_limited",
+  "sql_error",
+  "unavailable",
+  "disabled",
+]);
+
+type SiteSqlFetch = (path: string, init: RequestInit) => Promise<Response>;
+
+/** Build `site.sql` over a Site HTTP fetch; `ready` says whether the host serves the pinned Site. */
+export function createOpenGeniSiteSql(
+  fetchSite: SiteSqlFetch,
+  ready: () => Promise<boolean>,
+): OpenGeniSiteSql {
+  return {
+    async run<Row extends Record<string, unknown> = Record<string, unknown>>(
+      name: string,
+      params: Record<string, OpenGeniSiteSqlValue> = {},
+    ): Promise<OpenGeniSiteSqlResult<Row>> {
+      if (!QUERY_NAME.test(name))
+        throw new OpenGeniSiteSqlError("validation", "Invalid query name", 0);
+      if (Object.keys(params).some((key) => key === "viewer" || key.startsWith("viewer_")))
+        throw new OpenGeniSiteSqlError(
+          "validation",
+          "viewer parameters are bound by the host, not the Site",
+          0,
+        );
+      if (!(await ready()))
+        throw new OpenGeniSiteSqlError(
+          "site_sql_unsupported",
+          "This Site host does not provide Site SQL",
+          0,
+        );
+      const response = await fetchSite(
+        `${SITE_DATA_PATH_PREFIX}/sql/queries/${encodeURIComponent(name)}`,
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ params }),
+        },
+      );
+      const text = await response.text();
+      let value: unknown = null;
+      try {
+        value = text ? JSON.parse(text) : null;
+      } catch {
+        value = null;
+      }
+      if (response.ok) return value as OpenGeniSiteSqlResult<Row>;
+      throw siteSqlErrorFromResponse(response.status, value);
+    },
+  };
+}
+
+function siteSqlErrorFromResponse(status: number, value: unknown): OpenGeniSiteSqlError {
+  const error =
+    typeof value === "object" && value !== null && "error" in value
+      ? (value as { error: unknown }).error
+      : null;
+  const record =
+    typeof error === "object" && error !== null ? (error as Record<string, unknown>) : {};
+  const details =
+    typeof record.details === "object" && record.details !== null
+      ? (record.details as Record<string, unknown>)
+      : {};
+  const detailCode = typeof details.code === "string" ? details.code : undefined;
+  const code: OpenGeniSiteSqlErrorCode =
+    detailCode && KNOWN_CODES.has(detailCode)
+      ? (detailCode as OpenGeniSiteSqlErrorCode)
+      : status === 404
+        ? "not_found"
+        : status === 403
+          ? "forbidden"
+          : status === 413
+            ? "quota_exceeded"
+            : status === 429
+              ? "rate_limited"
+              : "request_failed";
+  const message =
+    typeof record.message === "string" && record.message
+      ? record.message
+      : `Site SQL request failed with HTTP ${status}`;
+  return new OpenGeniSiteSqlError(code, message, status, details);
+}

package/src/site-tool-bridge.ts

@@ -0,0 +1,401 @@
+import {
+  SITE_FRAME_HEADER,
+  SITE_FRAME_ID_HEADER,
+  SITE_ID_HEADER,
+  SITE_VERSION_HEADER,
+  siteFrameBodyRefusal,
+  siteFrameOperation,
+  siteRequestHeaders,
+} from "@opengeni/contracts/site-session-http";
+import { OpenGeniApiError } from "./errors";
+import { createSharedCatalogLoader } from "./shared-catalog-loader";
+import { siteSessionPath, type SiteHttpRequest } from "./site-http";
+import type { OpenGeniSiteToolCatalog } from "./site";
+import type { OpenGeniWorkspaceTools } from "./tools";
+import type {
+  ToolGatewayCallRequest,
+  ToolGatewayCallResponse,
+  ToolGatewayIdentity,
+  ToolGatewayResolveRequest,
+  ToolGatewayResolvedTool,
+  ToolGatewayInvokeRequest,
+  ToolGatewayInvokeResponse,
+} 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 = {
+  resolve?: (
+    request: ToolGatewayResolveRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayResolvedTool>;
+  invoke?: (
+    request: ToolGatewayInvokeRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayInvokeResponse>;
+  fetch?: (request: SiteHttpRequest, signal: AbortSignal) => Promise<Response>;
+  /** The host serves Site Data for its pinned published Site through `fetch`. */
+  siteData?: boolean;
+  catalog: (options: { signal: AbortSignal }) => Promise<OpenGeniSiteToolCatalog>;
+  call: (
+    request: ToolGatewayCallRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayCallResponse>;
+};
+export type CreateSiteToolBridgeOptions = {
+  workspaceTools: Pick<OpenGeniWorkspaceTools, "$catalog"> &
+    Partial<Pick<OpenGeniWorkspaceTools, "$targetProtocol" | "$resolve" | "$invoke" | "$manifest">>;
+  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.
+ *
+ * `fetch` forwards only the `SITE_OPERATIONS` allowlist (`siteSessionPath`);
+ * every other route is refused before a request is made. Each bridge is one
+ * frame: it mints a frame id, so a frame without a published Site reaches only
+ * the sessions it started. */
+export function createSiteToolBridge(input: CreateSiteToolBridgeOptions): SiteToolBridge {
+  const allowed = input.requestedTools ? new Set(input.requestedTools.map(identityKey)) : null;
+  const frameId = crypto.randomUUID();
+  const targeted =
+    input.workspaceTools.$targetProtocol === 1 &&
+    input.workspaceTools.$resolve &&
+    input.workspaceTools.$invoke &&
+    input.workspaceTools.$manifest;
+  const context = input.artifactId
+    ? { siteArtifactId: input.artifactId, siteVersionId: input.siteVersionId }
+    : {};
+  const manifests = new Map<string, readonly ToolGatewayResolvedTool[]>();
+  const resolve = async (
+    request: ToolGatewayResolveRequest,
+    { signal }: { signal: AbortSignal },
+  ) => {
+    if (
+      allowed &&
+      "identity" in request.target &&
+      !allowed.has(identityKey(request.target.identity))
+    )
+      throw new Error("This tool is not available to the Site");
+    const tool = await input.workspaceTools.$resolve!(request.target, { signal, ...context });
+    if (allowed && !allowed.has(identityKey(tool.entry.identity)))
+      throw new Error("This tool is not available to the Site");
+    return tool;
+  };
+  const invoke = async (request: ToolGatewayInvokeRequest, { signal }: { signal: AbortSignal }) => {
+    if (
+      allowed &&
+      "identity" in request.target &&
+      !allowed.has(identityKey(request.target.identity))
+    )
+      throw new Error("This tool is not available to the Site");
+    return await input.workspaceTools.$invoke!(
+      {
+        target: request.target,
+        operationId: request.operationId,
+        arguments: request.arguments,
+        ...(request.expectedDefinitionDigest === undefined
+          ? {}
+          : { expectedDefinitionDigest: request.expectedDefinitionDigest }),
+        ...context,
+      },
+      { signal },
+    );
+  };
+  // One shared load serves every concurrent Site request (cancelled only when
+  // all of them abort); a stale rejection reloads once for all requests
+  // rejected on that digest.
+  const projectedCatalog = createSharedCatalogLoader<OpenGeniSiteToolCatalog>(
+    async (refresh, signal) => {
+      if (targeted && input.requestedTools) {
+        const manifest = await input.workspaceTools.$manifest!(
+          { identities: [...input.requestedTools], ...context },
+          { signal },
+        );
+        signal.throwIfAborted();
+        if (manifests.size >= 4) manifests.delete(manifests.keys().next().value!);
+        manifests.set(manifest.digest, manifest.tools);
+        return {
+          version: 1,
+          generation: 1,
+          digest: manifest.digest,
+          createdAt: new Date().toISOString(),
+          entries: manifest.tools.map((tool) => tool.entry),
+        };
+      }
+      const current = await input.workspaceTools.$catalog({
+        signal,
+        ...(refresh ? { refresh } : {}),
+      });
+      if (current.workspaceId !== input.workspaceId)
+        throw new Error("Site catalog workspace mismatch");
+      return {
+        version: current.version,
+        generation: current.generation,
+        digest: current.digest,
+        createdAt: current.createdAt,
+        entries: current.entries.filter(
+          (entry) => !allowed || allowed.has(identityKey(entry.identity)),
+        ),
+      };
+    },
+  );
+  const loadCatalog = async ({
+    signal,
+    staleDigest,
+  }: {
+    signal: AbortSignal;
+    staleDigest?: string;
+  }): Promise<OpenGeniSiteToolCatalog> => {
+    signal.throwIfAborted();
+    const catalog =
+      staleDigest === undefined
+        ? await projectedCatalog.load({ signal })
+        : await projectedCatalog.reloadAfterStale(staleDigest, signal);
+    signal.throwIfAborted();
+    return catalog;
+  };
+  return {
+    ...(targeted ? { resolve, invoke } : {}),
+    ...(input.fetchResponse && input.artifactId ? { siteData: true } : {}),
+    ...(input.fetchResponse
+      ? {
+          fetch: async (message: SiteHttpRequest, signal: AbortSignal) => {
+            const path = siteSessionPath(
+              message.path,
+              input.workspaceId,
+              message.method,
+              input.artifactId,
+            );
+            // Site code sends message text, not approvals, answers, resources,
+            // credentials or connection choices. The API refuses them too.
+            const refused = siteFrameBodyFieldRefusal(path, message, input);
+            if (refused) return refused;
+            const headers = siteRequestHeaders(message.headers);
+            // Host-set marker: the API treats every bridged request as a Site frame,
+            // limited to SITE_OPERATIONS and to this frame's own sessions.
+            headers.set(SITE_FRAME_HEADER, "1");
+            headers.set(SITE_FRAME_ID_HEADER, frameId);
+            if (input.artifactId) {
+              headers.set(SITE_ID_HEADER, input.artifactId);
+              headers.set(SITE_VERSION_HEADER, input.siteVersionId);
+            }
+
+            return input.fetchResponse!(path, {
+              method: message.method,
+              signal,
+              headers: Object.fromEntries(headers),
+              ...(message.body === undefined ? {} : { body: message.body }),
+            });
+          },
+        }
+      : {}),
+    catalog: async ({ signal }) => await loadCatalog({ signal }),
+    call: async (request, { signal }) => {
+      if (allowed && !allowed.has(identityKey(request.identity)))
+        throw new Error("This tool is not available to the Site");
+      if (targeted && input.requestedTools) {
+        const tool = manifests
+          .get(request.catalogDigest)
+          ?.find(
+            (candidate) => identityKey(candidate.entry.identity) === identityKey(request.identity),
+          );
+        if (!tool)
+          throw new OpenGeniApiError(
+            409,
+            JSON.stringify({
+              error: { code: "conflict", details: { code: "catalog_stale" }, retryable: true },
+            }),
+          );
+        try {
+          const response = await invoke(
+            {
+              operationId: request.operationId ?? crypto.randomUUID(),
+              target: { identity: request.identity },
+              arguments: request.arguments,
+              expectedDefinitionDigest: tool.definitionDigest,
+            },
+            { signal },
+          );
+          return {
+            operationId: response.operationId,
+            catalogDigest: request.catalogDigest,
+            result: legacySiteToolResult(response.result),
+          };
+        } catch (error) {
+          if (
+            error instanceof OpenGeniApiError &&
+            error.retryable !== false &&
+            !error.outcomeUnknown &&
+            error.details?.code === "tool_definition_stale"
+          ) {
+            projectedCatalog.invalidate(request.catalogDigest);
+            manifests.delete(request.catalogDigest);
+            throw new OpenGeniApiError(
+              409,
+              JSON.stringify({
+                error: {
+                  code: "catalog_stale",
+                  details: { code: "catalog_stale" },
+                  retryable: true,
+                },
+              }),
+            );
+          }
+          throw error;
+        }
+      }
+      let usedDigest: string | undefined;
+      const call = async (staleDigest?: string) => {
+        const catalog = await loadCatalog({
+          signal,
+          ...(staleDigest === undefined ? {} : { staleDigest }),
+        });
+        usedDigest = catalog.digest;
+        if (
+          !catalog.entries.some(
+            (entry) => identityKey(entry.identity) === identityKey(request.identity),
+          )
+        )
+          throw new Error("This requested tool is not enabled in the workspace");
+        const response = await 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 }
+              : {}),
+          },
+        });
+        return { ...response, result: legacySiteToolResult(response.result) };
+      };
+      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 (
+          staleRetryVetoed(error) ||
+          !(input.isCatalogStale ?? isSiteCatalogStaleError)(error) ||
+          usedDigest === undefined
+        )
+          throw error;
+        return await call(usedDigest);
+      }
+    },
+  };
+}
+
+/** Saved Site bundles may treat a provider's error.code as retry authorization.
+ * An executed result is data, never a pre-execution control signal. Only wrap
+ * colliding error results on the legacy call path; keep the original diagnostic
+ * intact and do not project request arguments, tokens, or host credentials. */
+function legacySiteToolResult(
+  result: ToolGatewayCallResponse["result"],
+): ToolGatewayCallResponse["result"] {
+  if (!result?.isError) return result;
+  const structured = result.structuredContent;
+  const error = structured?.error;
+  if (
+    typeof error !== "object" ||
+    error === null ||
+    !("code" in error) ||
+    (error.code !== "catalog_stale" && error.code !== "tool_definition_stale")
+  )
+    return result;
+  return {
+    ...result,
+    structuredContent: {
+      ...structured,
+      error: {
+        code: "site_tool_execution_failed",
+        message:
+          "message" in error && typeof error.message === "string"
+            ? error.message
+            : "Site tool execution failed",
+        retryable: false,
+        outcomeUnknown: "outcomeUnknown" in error && error.outcomeUnknown === true,
+        providerError: error,
+      },
+    },
+  };
+}
+
+export function isSiteCatalogStaleError(error: unknown): boolean {
+  return (
+    !staleRetryVetoed(error) &&
+    error instanceof OpenGeniApiError &&
+    error.status === 409 &&
+    error.details?.code === "catalog_stale"
+  );
+}
+function staleRetryVetoed(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (("outcomeUnknown" in error && error.outcomeUnknown === true) ||
+      ("retryable" in error && error.retryable === false))
+  );
+}
+function identityKey(identity: ToolGatewayIdentity): string {
+  return `${identity.serverId}\u0000${identity.toolName}`;
+}
+
+/** A 403 like the API's for a body field Site code may not send, or null. */
+function siteFrameBodyFieldRefusal(
+  path: string,
+  message: SiteHttpRequest,
+  input: { workspaceId: string; artifactId?: string | undefined },
+): Response | null {
+  if (typeof message.body !== "string" || message.method === "GET") return null;
+  const operation = siteFrameOperation(
+    message.method,
+    path.split("?")[0]!,
+    input.workspaceId,
+    input.artifactId ?? null,
+  );
+  if (!operation) return null;
+  let body: unknown;
+  try {
+    body = JSON.parse(message.body);
+  } catch {
+    return null;
+  }
+  const field = siteFrameBodyRefusal(operation.operation.id, operation.suffix, body);
+  if (!field) return null;
+  return Response.json(
+    {
+      error: {
+        status: 403,
+        code: "forbidden",
+        message:
+          "A Site page can send message text only. Approvals, answers, resources, credentials and connection choices happen in the console.",
+        retryable: false,
+        details: { code: "site_frame_field_forbidden", field },
+      },
+    },
+    { status: 403 },
+  );
+}