@knime/hub-features 1.14.29 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @knime/hub-features
 
+## 1.15.0
+
+### Minor Changes
+
+- 34a4517: Add embedding SDK
+
+### Patch Changes
+
+- Updated dependencies [34a4517]
+  - @knime/utils@1.7.0
+  - @knime/components@1.41.4
+
 ## 1.14.29
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knime/hub-features",
-  "version": "1.14.29",
+  "version": "1.15.0",
   "description": "Vue components & composables for shared hub features",
   "homepage": "https://knime.github.io/webapps-common/",
   "license": "GPL 3 and Additional Permissions according to Sec. 7 (SEE the file LICENSE)",
@@ -31,9 +31,9 @@
     "lodash-es": "4.17.21",
     "ofetch": "^1.4.1",
     "typescript": "^5.8.3",
-    "@knime/components": "1.41.3",
+    "@knime/components": "1.41.4",
     "@knime/styles": "1.14.2",
-    "@knime/utils": "1.6.2"
+    "@knime/utils": "1.7.0"
   },
   "peerDependencies": {
     "consola": "3.x",

package/src/embeddingSDK/guest.ts

@@ -0,0 +1,124 @@
+/* eslint-disable @typescript-eslint/no-use-before-define */
+import { promise as PromiseUtils } from "@knime/utils";
+
+import { MESSAGES } from "./messages";
+import {
+  type EmbeddingContext,
+  type GenericEvent,
+  type UserActivityInfo,
+} from "./types";
+
+let __embeddingContext: Readonly<EmbeddingContext>;
+const logger = () => consola.withTag("Embedding SDK::GUEST application");
+
+/**
+ * Manually set the Embedding context. Use with caution as this should be done
+ * automatically out-of-the-box. It's mostly exposed to be helpful for dev setups
+ */
+export const setContext = (value: EmbeddingContext) => {
+  if (__embeddingContext) {
+    logger().warn("Cannot set context, it is already set");
+    return;
+  }
+
+  __embeddingContext = Object.freeze(value);
+};
+
+export const getContext = () => {
+  if (!__embeddingContext) {
+    logger().warn("Embedding:: Context was accessed before it was set.");
+    return undefined;
+  }
+
+  return __embeddingContext;
+};
+
+/**
+ * Only relevant for tests
+ */
+export const clearContext = () => {
+  if (import.meta.env.PROD) {
+    return;
+  }
+
+  // @ts-expect-error should not be called in prod
+  __embeddingContext = undefined;
+};
+
+type EmbeddingContextValidator = (
+  context: EmbeddingContext,
+) => { valid: true; error: null } | { valid: false; error: string };
+const defaultvalidator: EmbeddingContextValidator = () => ({
+  valid: true,
+  error: null,
+});
+
+/**
+ * Wait for host application to send a message containing the embedding context
+ */
+export const waitForContext = (
+  validator: EmbeddingContextValidator = defaultvalidator,
+): Promise<EmbeddingContext> => {
+  const { promise, reject, resolve } =
+    PromiseUtils.createUnwrappedPromise<EmbeddingContext>();
+
+  function teardown() {
+    window.removeEventListener("message", onMessage);
+  }
+
+  function onMessage(event: MessageEvent) {
+    if (event.data.type !== MESSAGES.EMBEDDING_CONTEXT) {
+      return;
+    }
+
+    const { data } = event as MessageEvent<{
+      type: string;
+      payload: EmbeddingContext;
+    }>;
+
+    const validation = validator(data.payload);
+    if (!validation.valid) {
+      logger().fatal("Incorrect embedding context payload", {
+        data,
+        error: validation.error,
+      });
+      reject(new Error(validation.error));
+      teardown();
+      return;
+    }
+
+    logger().info("Received embedding context message", data);
+
+    setContext(data.payload);
+    resolve(data.payload);
+    teardown();
+  }
+
+  window.addEventListener("message", onMessage, false);
+
+  // send message to parent after postmessage listener has been set-up
+  logger().info("Awaiting to receive embedding context");
+  window.parent.postMessage({ type: MESSAGES.AWAITING_EMBEDDING_CONTEXT }, "*");
+
+  return promise;
+};
+
+export const sendEmbeddingFailureMessage = (error: unknown) => {
+  window.parent.postMessage({ type: MESSAGES.EMBEDDING_FAILED, error }, "*");
+};
+
+export const dispatchGenericEventToHost = (event: GenericEvent) => {
+  window.parent.postMessage(
+    { type: MESSAGES.GENERIC_EVENT, payload: event },
+    "*",
+  );
+};
+
+export const notifyActivityChange = (userActivityInfo: UserActivityInfo) => {
+  logger().info("Sending user activity info", { payload: userActivityInfo });
+
+  window.parent.postMessage(
+    { type: MESSAGES.USER_ACTIVITY, payload: userActivityInfo },
+    "*",
+  );
+};

package/src/embeddingSDK/host.ts

@@ -0,0 +1,128 @@
+/* eslint-disable @typescript-eslint/no-use-before-define */
+import { MESSAGES } from "./messages";
+import {
+  type EmbeddingContext,
+  type GenericEvent,
+  type GenericEventHandlers,
+  type UserActivityInfo,
+} from "./types";
+import { messageValidators } from "./util";
+
+const logger = () => consola.withTag("Embedding SDK::HOST embedder");
+
+/**
+ * This function acts as a handshake to make sure the event with the
+ * embedding context is only sent once the embedded application is ready to
+ * receive it and not earlier. It also listens to possible embedding failure
+ * from the child application
+ */
+export const init = (callbacks: {
+  onReady: () => void;
+  onError: (error: Error) => void;
+}) => {
+  function teardown() {
+    window.removeEventListener("message", onMessage);
+  }
+
+  function onMessage(event: MessageEvent) {
+    if (!messageValidators.isInitializationMessage(event)) {
+      return;
+    }
+
+    if (event.data?.type === MESSAGES.AWAITING_EMBEDDING_CONTEXT) {
+      logger().info("Got confirmation to send embedding context");
+      callbacks.onReady();
+      teardown();
+    }
+
+    if (event.data?.type === MESSAGES.EMBEDDING_FAILED) {
+      logger().error("Received embedding failure message", {
+        event: event.data,
+      });
+      callbacks.onError(event.data.error);
+      teardown();
+    }
+  }
+
+  window.addEventListener("message", onMessage);
+  logger().info("Initialization done");
+};
+
+export const sendEmbeddingContext = (
+  iframe: HTMLIFrameElement,
+  targetOrigin: string,
+  context: EmbeddingContext,
+) => {
+  logger().info("Sending embedding context", context);
+
+  iframe.contentWindow?.postMessage(
+    {
+      type: MESSAGES.EMBEDDING_CONTEXT,
+      payload: {
+        // AP uses `url` instead of `wsConnectionUri` in older versions, so it needs
+        // to be present to preserve backwards compatibility
+        url: context.wsConnectionUri,
+        wsConnectionUri: context.wsConnectionUri,
+
+        restApiBaseUrl: context.restApiBaseUrl,
+        userIdleTimeout: context.userIdleTimeout,
+        sessionId: context.sessionId,
+        jobId: context.jobId,
+      } satisfies EmbeddingContext,
+    },
+    targetOrigin,
+  );
+};
+
+/**
+ * Sets up a listener to receive user activity events to detect idleness
+ */
+export const listenToActivityEvents = (callbacks: {
+  onActivity: (event: UserActivityInfo) => void;
+}) => {
+  const onMessage = (event: MessageEvent) => {
+    if (!messageValidators.isUserActivityMessage(event)) {
+      return;
+    }
+
+    logger().info("Received user activity change event", {
+      event: event.data,
+    });
+    callbacks.onActivity(event.data.payload);
+  };
+
+  window.addEventListener("message", onMessage);
+  logger().info("Attaching user activity listener");
+
+  return () => window.removeEventListener("message", onMessage);
+};
+
+/**
+ * Sets up handlers for commands dispatched from the embedded guest application
+ */
+export const setupGenericEventHandlers = <K extends GenericEvent["kind"]>(
+  handlers: GenericEventHandlers,
+) => {
+  const onMessage = (event: MessageEvent) => {
+    if (!messageValidators.isGenericEvent<K>(event)) {
+      return;
+    }
+
+    const genericEvent = event.data.payload;
+    logger().info("Received GenericEvent", { event: event.data });
+
+    const isCallable =
+      Object.prototype.hasOwnProperty.call(handlers, genericEvent.kind) &&
+      typeof handlers[genericEvent.kind] === "function";
+
+    if (isCallable) {
+      logger().trace("Calling provided handler", { event: event.data });
+      handlers[genericEvent.kind]?.(genericEvent);
+    }
+  };
+
+  window.addEventListener("message", onMessage);
+  logger().info("Attaching listener for GenericEvents");
+
+  return () => window.removeEventListener("message", onMessage);
+};

package/src/embeddingSDK/index.ts

@@ -0,0 +1,5 @@
+import * as guest from "./guest";
+import * as host from "./host";
+
+export const embeddingSDK = { host, guest };
+export * from "./types";

package/src/embeddingSDK/messages.ts

@@ -0,0 +1,36 @@
+/**
+ * ----------- IMPORTANT NOTES ---------------
+ * 1. These messages are considered API. So they **must** remain
+ *    backwards compatible
+ * 2. Instead of removal of properties from the embedding context payload,
+ *    we must use deprecation notes that list which AP version last used the
+ *    deprecated property
+ * 3. The message variable name can change, but not it's value. This is because
+ *    these values are used since AP browser embedding was first implemented, so
+ *    they must be retained in order to preserve backwars compatibility
+ */
+
+export const MESSAGES = {
+  /**
+   * Message used to establish a handshake and setup
+   * before waiting for embedding context transfer
+   */
+  AWAITING_EMBEDDING_CONTEXT: "KNIME_UI__AWAITING_CONNECTION_INFO",
+  /**
+   * Message that contains the embedding context information
+   */
+  EMBEDDING_CONTEXT: "KNIME_UI__CONNECTION_INFO",
+  /**
+   * Message used for when embedding failed
+   */
+  EMBEDDING_FAILED: "KNIME_UI__CONNECTION_FAIL",
+  /**
+   * Message to report user activity events
+   */
+  USER_ACTIVITY: "KNIME_UI__USER_ACTIVITY",
+  /**
+   * General purpose event to transfer data between host application and embedded
+   * application.
+   */
+  GENERIC_EVENT: "KNIME_UI__GENERIC_EVENT",
+} as const;

package/src/embeddingSDK/types.ts

@@ -0,0 +1,61 @@
+import type { Toast } from "@knime/components";
+
+export type EmbeddingContext = {
+  /**
+   * URI of the WS used by the embedded application.
+   * (e.g in case of browser AP, this is the WS url provided by the ws-proxy)
+   */
+  wsConnectionUri: string;
+  /**
+   * @deprecated URI of the WS used by the embedded application.
+   * Last used in AP 5.8.0
+   */
+  url?: string;
+  /**
+   * Base URL of the Hub's REST API. This will be used by the embedded application
+   * to make requests to the hub API. It can also be used to fetch resources
+   * dynamically at runtime and get assets needed to render UI extensions
+   * (e.g port views, node views, etc)
+   */
+  restApiBaseUrl: string;
+  /**
+   * Id of the job loaded into the executor that is providing the embedded application
+   */
+  jobId: string;
+  /**
+   * @deprecated only needed due to backwards compatibility because it's used
+   * by older AP versions. Last used in AP 5.4.0
+   */
+  sessionId?: string;
+  /**
+   * Time in MS after which the user is considered idle if no interactions
+   * are being made on the page
+   */
+  userIdleTimeout?: number;
+};
+
+type ShowNotificationEvent = {
+  kind: "showNotification";
+  payload: Toast;
+};
+
+type ClearNotificationEvent = {
+  kind: "clearNotification";
+  payload: { id: string } | { deduplicationKey: string };
+};
+
+export type GenericEvent = ShowNotificationEvent | ClearNotificationEvent;
+
+export type GenericEventByKind<K extends GenericEvent["kind"]> = Extract<
+  GenericEvent,
+  { kind: K }
+>;
+
+export type GenericEventHandlers = {
+  [K in GenericEvent["kind"]]?: (event: GenericEventByKind<K>) => void;
+};
+
+export type UserActivityInfo = {
+  idle: boolean;
+  lastActive: string;
+};

package/src/embeddingSDK/util.ts

@@ -0,0 +1,19 @@
+import { MESSAGES } from "./messages";
+import { type GenericEvent, type GenericEventByKind } from "./types";
+
+export const messageValidators = {
+  isInitializationMessage: (event: MessageEvent) =>
+    [MESSAGES.AWAITING_EMBEDDING_CONTEXT, MESSAGES.EMBEDDING_FAILED].includes(
+      event.data?.type,
+    ),
+
+  isUserActivityMessage: (event: MessageEvent) =>
+    MESSAGES.USER_ACTIVITY === event.data?.type,
+
+  isGenericEvent: <K extends GenericEvent["kind"]>(
+    event: MessageEvent,
+  ): event is MessageEvent<{
+    type: typeof MESSAGES.GENERIC_EVENT;
+    payload: GenericEventByKind<K>;
+  }> => event.data?.type === MESSAGES.GENERIC_EVENT,
+};

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./rfcErrors";
 export * from "./useFileUpload";
 export * from "./useDownloadArtifact";
 export * from "./components/avatars";
+export * from "./embeddingSDK";