npm - @kitware/wslink - Versions diffs - 2.5.0 - Mend

@kitware/wslink 2.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/.prettierrc.js +8 -0
package/CHANGELOG.md +551 -0
package/LICENSE +27 -0
package/README.md +36 -0
package/dist/wslink.mjs +1474 -0
package/dist/wslink.umd.js +1 -0
package/package.json +33 -0
package/src/CompositeClosureHelper/index.js +166 -0
package/src/ProcessLauncher/api.md +87 -0
package/src/ProcessLauncher/index.js +125 -0
package/src/SmartConnect/api.md +40 -0
package/src/SmartConnect/index.d.ts +72 -0
package/src/SmartConnect/index.js +179 -0
package/src/WebsocketConnection/api.md +37 -0
package/src/WebsocketConnection/chunking.js +211 -0
package/src/WebsocketConnection/chunking.ts +296 -0
package/src/WebsocketConnection/index.d.ts +70 -0
package/src/WebsocketConnection/index.js +155 -0
package/src/WebsocketConnection/session.js +284 -0
package/src/index.js +11 -0
package/test/simple.js +185 -0
package/vite.config.js +15 -0

package/dist/wslink.umd.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "@kitware/wslink",
+  "version": "2.5.0",
+  "description": "Rpc and pub/sub between Python and JavaScript over WebSockets",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitware/wslink.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kitware/wslink/issues"
+  },
+  "homepage": "https://github.com/kitware/wslink#readme",
+  "main": "dist/wslink.umd.js",
+  "scripts": {
+    "format": "prettier src --write",
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "author": "Kitware",
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "prettier": "^3.8.1",
+    "vite": "^7.3.1",
+    "vite-plugin-prettier-format": "^1.0.0"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^2.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/CompositeClosureHelper/index.js ADDED Viewed

@@ -0,0 +1,166 @@
+// ----------------------------------------------------------------------------
+// capitalize provided string
+// ----------------------------------------------------------------------------
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+// ----------------------------------------------------------------------------
+// Add isA function and register your class name
+// ----------------------------------------------------------------------------
+function isA(publicAPI, model = {}, name = null) {
+  if (!model.isA) {
+    model.isA = [];
+  }
+  if (name) {
+    model.isA.push(name);
+  }
+  if (!publicAPI.isA) {
+    publicAPI.isA = (className) => model.isA.indexOf(className) !== -1;
+  }
+}
+// ----------------------------------------------------------------------------
+// Basic setter
+// ----------------------------------------------------------------------------
+function set(publicAPI, model = {}, names = []) {
+  names.forEach((name) => {
+    publicAPI[`set${capitalize(name)}`] = (value) => {
+      model[name] = value;
+    };
+  });
+}
+// ----------------------------------------------------------------------------
+// Basic getter
+// ----------------------------------------------------------------------------
+function get(publicAPI, model = {}, names = []) {
+  names.forEach((name) => {
+    publicAPI[`get${capitalize(name)}`] = () => model[name];
+  });
+}
+// ----------------------------------------------------------------------------
+// Add destroy function
+// ----------------------------------------------------------------------------
+function destroy(publicAPI, model = {}) {
+  const previousDestroy = publicAPI.destroy;
+  if (!model.subscriptions) {
+    model.subscriptions = [];
+  }
+  publicAPI.destroy = () => {
+    if (previousDestroy) {
+      previousDestroy();
+    }
+    while (model.subscriptions && model.subscriptions.length) {
+      model.subscriptions.pop().unsubscribe();
+    }
+    Object.keys(model).forEach((field) => {
+      delete model[field];
+    });
+    // Flag the instance being deleted
+    model.deleted = true;
+  };
+}
+// ----------------------------------------------------------------------------
+// Event handling: onXXX(callback), fireXXX(args...)
+// ----------------------------------------------------------------------------
+function event(publicAPI, model, eventName, asynchronous = true) {
+  const callbacks = [];
+  const previousDestroy = publicAPI.destroy;
+  function off(index) {
+    callbacks[index] = null;
+  }
+  function on(index) {
+    function unsubscribe() {
+      off(index);
+    }
+    return Object.freeze({ unsubscribe });
+  }
+  publicAPI[`fire${capitalize(eventName)}`] = (...args) => {
+    if (model.deleted) {
+      console.log("instance deleted - can not call any method");
+      return;
+    }
+    function processCallbacks() {
+      callbacks.forEach((callback) => {
+        if (callback) {
+          try {
+            callback.apply(publicAPI, args);
+          } catch (errObj) {
+            console.log("Error event:", eventName, errObj);
+          }
+        }
+      });
+    }
+    if (asynchronous) {
+      setTimeout(processCallbacks, 0);
+    } else {
+      processCallbacks();
+    }
+  };
+  publicAPI[`on${capitalize(eventName)}`] = (callback) => {
+    if (model.deleted) {
+      console.log("instance deleted - can not call any method");
+      return null;
+    }
+    const index = callbacks.length;
+    callbacks.push(callback);
+    return on(index);
+  };
+  publicAPI.destroy = () => {
+    previousDestroy();
+    callbacks.forEach((el, index) => off(index));
+  };
+}
+// ----------------------------------------------------------------------------
+// Chain function calls
+// ----------------------------------------------------------------------------
+function chain(...fn) {
+  return (...args) => fn.filter((i) => !!i).forEach((i) => i(...args));
+}
+// ----------------------------------------------------------------------------
+// newInstance
+// ----------------------------------------------------------------------------
+function newInstance(extend) {
+  return (initialValues = {}) => {
+    const model = {};
+    const publicAPI = {};
+    extend(publicAPI, model, initialValues);
+    return Object.freeze(publicAPI);
+  };
+}
+export default {
+  chain,
+  destroy,
+  event,
+  get,
+  isA,
+  newInstance,
+  set,
+};

package/src/ProcessLauncher/api.md ADDED Viewed

@@ -0,0 +1,87 @@
+# ProcessLauncher
+The ProcessLauncher can be used to start remote python servers, or other remote
+processes. The ProcessLauncher is used in ParaViewWeb to start a new remote
+server instance to perform interactive 3D post-processing using either a VTK or
+a ParaView backend.
+```javascript
+import ProcessLauncher from "wslink/src/ProcessLauncher";
+processLauncher = ProcessLauncher.newInstance({ endPoint: "/paraview" });
+// Optionally you can provide a launcherRetry: [1000, 2000, 3000, 5000]
+// with the set of time to wait in ms before another retry.
+// Retries will only occurred on a 503 response from the server.
+```
+## ProcessLauncher.newInstance({ endPoint, launcherRetry: [] })
+Create a process launcher that will make requests to a remote server using the
+provided endpoint url.
+## start(config)
+Submit a request for a new remote process.
+The config object gets posted via a POST request to the endpoint provided at
+creation time.
+The current ParaViewWeb server-side **Launcher** expects at least the following
+object.
+```js
+{
+    application: 'NameOfTheProcess',
+}
+```
+But additional key/value pairs can be added depending on the needs of the
+targeted process.
+Once the remote process becomes ready a notification is sent.
+## fetchConnection(sessionId)
+Trigger a request for getting the full connection information based on an
+existing sessionId.
+## stop(connection)
+Trigger a request to terminate a remote process using the connection object that
+was provided at start time.
+## listConnections()
+Return the list of already established connections. (From that instance)
+## onProcessReady(callback) : subscription
+Register a callback for when a remote process becomes available after a start()
+request.
+The callback function will then receive a json object describing how to connect
+to that remote process.
+```js
+{
+    sessionURL: 'ws://myServer/proxy?sessionId=asdfwefasdfwerfqerfse',
+    maybe: 'something else too'
+}
+```
+## onProcessStopped(callback) : subscription
+Register a callback for when a stop request is performed.
+## onFetch(callback) : subscription
+Register a callback for when a fetchConnection request is performed.
+## onError(callback) : subscription
+Register a callback for when an error occurred regardless of the request.
+## destroy()
+Free memory and detach any listeners.

package/src/ProcessLauncher/index.js ADDED Viewed

@@ -0,0 +1,125 @@
+/* global XMLHttpRequest */
+import CompositeClosureHelper from "../CompositeClosureHelper";
+const connections = [];
+function ProcessLauncher(publicAPI, model) {
+  publicAPI.start = (config) => {
+    const xhr = new XMLHttpRequest();
+    const url = model.endPoint;
+    if (!model._retry) {
+      model._retry = config.launcherRetry || [];
+    }
+    xhr.open("POST", url, true);
+    if (config.headers) {
+      model._headers = config.headers;
+      delete config.headers;
+    }
+    if (model._headers) {
+      Object.entries(model._headers).forEach(([key, value]) =>
+        xhr.setRequestHeader(key, value)
+      );
+    }
+    xhr.responseType = "json";
+    const supportsJson = "response" in xhr && xhr.responseType === "json";
+    xhr.onload = (e) => {
+      const response = supportsJson ? xhr.response : JSON.parse(xhr.response);
+      if (xhr.status === 200 && response && !response.error) {
+        // Add connection to our global list
+        connections.push(response);
+        publicAPI.fireProcessReady(response);
+        return;
+      } else if (xhr.status === 503 && model._retry.length > 0) {
+        const timeout = model._retry.shift();
+        setTimeout(publicAPI.start, timeout, config);
+      } else {
+        publicAPI.fireError(xhr);
+      }
+    };
+    xhr.onerror = (e) => {
+      publicAPI.fireError(xhr);
+    };
+    xhr.send(JSON.stringify(config));
+  };
+  publicAPI.fetchConnection = (sessionId) => {
+    var xhr = new XMLHttpRequest(),
+      url = [model.endPoint, sessionId].join("/");
+    xhr.open("GET", url, true);
+    xhr.responseType = "json";
+    const supportsJson = "response" in xhr && xhr.responseType === "json";
+    xhr.onload = (e) => {
+      if (this.status === 200) {
+        publicAPI.fireFetch(
+          supportsJson ? xhr.response : JSON.parse(xhr.response)
+        );
+        return;
+      }
+      publicAPI.fireError(xhr);
+    };
+    xhr.onerror = (e) => {
+      publicAPI.fireError(xhr);
+    };
+    xhr.send();
+  };
+  publicAPI.stop = (connection) => {
+    var xhr = new XMLHttpRequest(),
+      url = [model.endPoint, connection.id].join("/");
+    xhr.open("DELETE", url, true);
+    xhr.responseType = "json";
+    const supportsJson = "response" in xhr && xhr.responseType === "json";
+    xhr.onload = (e) => {
+      if (this.status === 200) {
+        const response = supportsJson ? xhr.response : JSON.parse(xhr.response);
+        // Remove connection from the list
+        // FIXME / TODO
+        publicAPI.fireProcessStopped(response);
+        return;
+      }
+      publicAPI.fireError(xhr);
+    };
+    xhr.onerror = (e) => {
+      publicAPI.fireError(xhr);
+    };
+    xhr.send();
+  };
+  publicAPI.listConnections = () => {
+    return connections;
+  };
+}
+const DEFAULT_VALUES = {
+  endPoint: null,
+};
+export function extend(publicAPI, model, initialValues = {}) {
+  Object.assign(model, DEFAULT_VALUES, initialValues);
+  CompositeClosureHelper.destroy(publicAPI, model);
+  CompositeClosureHelper.event(publicAPI, model, "ProcessReady");
+  CompositeClosureHelper.event(publicAPI, model, "ProcessStopped");
+  CompositeClosureHelper.event(publicAPI, model, "Fetch");
+  CompositeClosureHelper.event(publicAPI, model, "Error");
+  CompositeClosureHelper.isA(publicAPI, model, "ProcessLauncher");
+  ProcessLauncher(publicAPI, model);
+}
+// ----------------------------------------------------------------------------
+export const newInstance = CompositeClosureHelper.newInstance(extend);
+export default { newInstance, extend };

package/src/SmartConnect/api.md ADDED Viewed

@@ -0,0 +1,40 @@
+# SmartConnect
+SmartConnect will try to launch a new remote process based on the configuration
+and if that fails or if a sessionURL is already provided in the configuration it
+will establish a direct WebSocket connection using Autobahn.
+## SmartConnect.newInstance({ config })
+Create an instance that will use the provided configuration to connect itself to
+a server either by requesting a new remote process or by trying to directly
+connecting to it as a fallback.
+## connect()
+Trigger the connection request.
+## onConnectionReady(callback) : subscription
+Register callback for when the connection became ready.
+## onConnectionClose(callback) : subscription
+Register callback for when the connection close. Callback takes two arguments,
+the connection object and a websocket event. If the server closes the connection
+after sending a close frame
+(https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1), the event will
+have the shape {code: number, reason: string}.
+## onConnectionError(callback) : subscription
+Register callback for when the connection request failed. Callback takes two
+arguments, the connection object and a websocket event.
+## getSession() : session
+Return the session associated with the connection.
+## destroy()
+Free resources and remove any listener.

package/src/SmartConnect/index.d.ts ADDED Viewed

@@ -0,0 +1,72 @@
+import WebsocketConnection, { WebsocketSession } from "../WebsocketConnection";
+export declare const DEFAULT_SESSION_MANAGER_URL: string;
+export interface ISmartConnectConfig {
+  // URL to connect to. E.g., "ws://localhost:1234".
+  sessionURL?: string;
+  // Endpoint of the launcher that is responsible to start the server process.
+  // Defaults to  SESSION_MANAGER_URL.
+  sessionManagerURL?: string;
+  // The secret token to be sent during handshake and validated by the server.
+  secret?: string;
+  retry?: number;
+}
+// A function that rewrites the configuration.  It is called on connect.
+type ConfigDecorator = (config: ISmartConnectConfig) => ISmartConnectConfig;
+export interface ISmartConnectInitialValues {
+  config: ISmartConnectConfig;
+  configDecorator?: ConfigDecorator;
+}
+export type Event = any;
+export interface WebsocketCloseEvent {
+  // This object reports the values of the close frame.  Cf. RFC6455 section
+  // 5.5.1. If the connection closes w/o a close frame, the following fields are unset.
+  code?: number; // RFC6455, section 7.4.
+  reason?: string;
+}
+export interface SmartConnect {
+  // Starts connecting to the server.
+  connect(): void;
+  getSession(): WebsocketSession;
+  // Called when the connection is established
+  onConnectionReady(cb: (c: WebsocketConnection) => void): void;
+  // Called when the connection cannot be established.
+  onConnectionError(cb: (c: WebsocketConnection, err: Event) => void): void;
+  // Called when the connection is closed.
+  onConnectionClose(
+    cb: (c: WebsocketConnection, event: WebsocketCloseEvent) => void
+  ): void;
+  // Close the connection and destroy this object.
+  destroy(): void;
+  // Return the config passed to newInstance.
+  getConfig(): ISmartConnectConfig;
+  getConfigDecorator(): ConfigDecorator | null;
+  setConfigDecorator(c: ConfigDecorator): void;
+}
+/**
+ * Creates a new SmartConnect object with the given configuration.
+ */
+export function newInstance(config: ISmartConnectInitialValues): SmartConnect;
+/**
+ * Decorates a given object (publicAPI+model) with SmartConnect characteristics.
+ */
+export function extend(
+  publicAPI: object,
+  model: object,
+  initialValues?: ISmartConnectInitialValues
+): void;
+export declare const SmartConnect: {
+  newInstance: typeof newInstance;
+  extend: typeof extend;
+};
+export default SmartConnect;