@basthon/kernel-base 0.62.21 → 0.63.0

package/lib/commons.d.ts

@@ -0,0 +1,21 @@
+import { Remote } from "comlink";
+import { ProxyFetch } from "./worker/proxy";
+declare global {
+    interface Window {
+        _remoteProxy: Remote<ProxyFetch>;
+        _assetsURL?: string;
+    }
+}
+/**
+ * An error thrown by not implemented API functions.
+ */
+declare class NotImplementedError extends Error {
+    constructor(funcName: string);
+}
+/**
+ * we mock the fetch function to:
+ *  - redirect queries to local FS
+ *  - bypass the worker's opaque origin
+ */
+declare const mockFetch: (legacy: boolean) => void;
+export { NotImplementedError, mockFetch };

package/lib/commons.js

@@ -0,0 +1,100 @@
+/**
+ * An error thrown by not implemented API functions.
+ */
+class NotImplementedError extends Error {
+    constructor(funcName) {
+        super(`Function ${funcName} not implemented!`);
+        this.name = "NotImplementedError";
+    }
+}
+/* fetch from local FS */
+const fetchFromLocalFS = async (localfsScheme, url) => {
+    const toDataURL = async (content) => {
+        return await new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onloadend = () => {
+                resolve(reader.result);
+            };
+            reader.onerror = reject;
+            reader.readAsDataURL(new Blob([content]));
+        });
+    };
+    const prefix = localfsScheme;
+    const path = url.slice(prefix.length);
+    let content = null;
+    const options = {
+        status: 200,
+        statusText: "OK",
+        headers: new Headers(),
+    };
+    try {
+        //@ts-ignore
+        content = await self.basthon.getFile(path);
+        const dataURL = await toDataURL(content);
+        const mime = dataURL.substring(dataURL.indexOf(":") + 1, dataURL.indexOf(";"));
+        content = content.buffer;
+        options.headers.append("Content-Type", mime);
+        options.headers.append("Content-Length", content.byteLength);
+    }
+    catch (e) {
+        options.status = 404;
+        options.statusText = "Not Found";
+    }
+    return new Response(content, options);
+};
+/**
+ * Get the origin of an url.
+ */
+const origin = (url) => new URL(url).origin;
+/**
+ * Get the parent path of an url.
+ */
+const parent = (url) => {
+    const abs = new URL(url).href;
+    return abs.substring(0, abs.lastIndexOf("/"));
+};
+/**
+ * we mock the fetch function to:
+ *  - redirect queries to local FS
+ *  - bypass the worker's opaque origin
+ */
+const mockFetch = (legacy) => {
+    // already mocked?
+    if (self.fetch.name === "mockedFetch")
+        return;
+    const trueFetch = self.fetch;
+    async function mockedFetch(request, init) {
+        if (!legacy && (self.importScripts == null || self._assetsURL == null))
+            return Response.error();
+        // force all params to init object
+        if (request instanceof Request)
+            init = { ...request, ...init };
+        // ensure credentials are not sent
+        init = { ...init, ...{ credentials: "omit" } };
+        const url = request.url ?? request.toString();
+        const localfsScheme = "filesystem:/";
+        try {
+            // requests towards localfs
+            if (url.startsWith(localfsScheme)) {
+                return await fetchFromLocalFS(localfsScheme, url);
+            }
+            else if (!legacy && origin(url) === origin(self._assetsURL)) {
+                // requests towards same origin
+                // only url under the assets folder are proxyied
+                if (parent(url).startsWith(self._assetsURL)) {
+                    const proxy = self._remoteProxy;
+                    const { body, options } = await proxy.fetch(url, init);
+                    return new Response(body, options);
+                }
+                throw new Error("Ressource is outside the proxy' scope");
+            }
+            return await trueFetch(url, init);
+        }
+        catch (e) {
+            console.error(`security proxy: request to ${url} throw error: ${e.toString()}`);
+            return Response.error();
+        }
+    }
+    self.fetch = mockedFetch;
+};
+export { NotImplementedError, mockFetch };

package/lib/index.d.ts

@@ -1 +1 @@
-export * from './kernel';
+export * from "./kernel";

package/lib/index.js

@@ -1 +1 @@
-export * from './kernel';
+export * from "./kernel";

package/lib/kernel.d.ts

@@ -1,15 +1,26 @@
+import { PromiseDelegate } from "promise-delegate";
+import { VERSION } from "./version";
+export { VERSION };
 /**
  * API that any Basthon kernel should fill to be supported
  * in console/notebook.
  */
 export declare class KernelBase {
     private _rootPath;
+    private _isReady;
     private _ready;
-    private readonly _loaded;
+    private _stopped;
     protected _execution_count: number;
-    protected _pendingInput: boolean;
+    protected _pendingInput?: PromiseDelegate<string>;
     private _listeners;
+    protected _options: any;
+    protected _files: Map<string, ArrayBuffer>;
+    protected _modules: Map<string, ArrayBuffer>;
     constructor(options: any);
+    /**
+     * Is this kernel safe? (loaded from an isolated web worker)
+     */
+    safeKernel(): boolean;
     /**
      * Kernel version number (string).
      */
@@ -28,10 +39,6 @@ export declare class KernelBase {
      * Script (module) file extensions
      */
     moduleExts(): string[];
-    /**
-     * Launch the kernel.
-     */
-    launch(): Promise<void>;
     /**
      * Execution count getter.
      */
@@ -40,7 +47,6 @@ export declare class KernelBase {
      * Async code evaluation that resolves with the result.
      */
     evalAsync(code: string, outCallback: (_: string) => void, errCallback: (_: string) => void, data?: any): Promise<any>;
-    restart(): void;
     putFile(filename: string, content: ArrayBuffer): Promise<void>;
     putModule(filename: string, content: ArrayBuffer): Promise<void>;
     userModules(): string[];
@@ -52,23 +58,48 @@ export declare class KernelBase {
      * Get a user module file content.
      */
     getUserModuleFile(filename: string): Uint8Array;
-    more(source: string): boolean;
-    complete(code: string): [string[], number] | [];
+    more(source: string): Promise<boolean>;
+    complete(code: string): Promise<[string[], number] | []>;
     banner(): string;
     ps1(): string;
     ps2(): string;
     /**
-     * Initialize the kernel.
+     * Launch the kernel (used to wrap a promise around init).
+     */
+    protected _init(): Promise<void>;
+    /**
+     * Initialize the kernel and start it.
      */
     init(): Promise<void>;
+    /**
+     * Start the kernel (used to wrap a promise around start).
+     */
+    protected _start(): Promise<void>;
+    /**
+     * Start the kernel.
+     */
+    start(): Promise<void>;
+    /**
+     * Perform async part of the stoping process.
+     */
+    protected _stop(): Promise<void>;
+    /**
+     * Stop the kernel synchronously (to ensure kernel is stopped after the call).
+     */
+    stop(): void;
+    /**
+     * Restart the kernel (stop and start).
+     * Use await this.ready() to ensure kernel is started
+     */
+    restart(): void;
     /**
      * Is the kernel ready?
      */
-    get ready(): boolean;
+    get isReady(): boolean;
     /**
-     * Promise that resolve when the kernel is loaded.
+     * Promise that resolves when the kernel is ready (started).
      */
-    loaded(): Promise<void>;
+    ready(): Promise<void>;
     /**
      * Root for kernel files. This is always the language directory
      * inside the version number directory inside the kernel directory.
@@ -103,7 +134,11 @@ export declare class KernelBase {
     /**
      * Send eval.input event then wait for the user response and return it.
      */
-    inputAsync(prompt: string | null | undefined, password?: boolean, data?: any): Promise<unknown>;
+    inputAsync(prompt: string | null | undefined, password?: boolean, data?: any): Promise<string>;
+    /**
+     * Close a pending input.
+     */
+    resolvePendingInput(): void;
     /**
      * Simple clone via JSON copy.
      */

package/lib/kernel.js

@@ -1,83 +1,27 @@
 import { PromiseDelegate } from "promise-delegate";
 import { VERSION } from "./version";
-const _localfsScheme = "filesystem:/";
-/* we mock the fetch function to redirect queries to local FS */
-(function () {
-    var _a;
-    const toDataURL = async (content) => {
-        return await new Promise((resolve, reject) => {
-            const reader = new FileReader();
-            reader.onloadend = () => {
-                resolve(reader.result);
-            };
-            reader.onerror = reject;
-            reader.readAsDataURL(new Blob([content]));
-        });
-    };
-    //@ts-ignore
-    window._fetch = (_a = window._fetch) !== null && _a !== void 0 ? _a : window.fetch;
-    window.fetch = async function (request, opts) {
-        var _a;
-        //@ts-ignore
-        const url = (_a = request.url) !== null && _a !== void 0 ? _a : request.toString();
-        const prefix = _localfsScheme;
-        if (url.startsWith(prefix)) {
-            const path = url.slice(prefix.length);
-            let content = null;
-            const options = {
-                status: 200,
-                statusText: "OK",
-                headers: new Headers(),
-            };
-            try {
-                //@ts-ignore
-                content = window.Basthon.getFile(path);
-                const dataURL = await toDataURL(content);
-                const mime = dataURL.substring(dataURL.indexOf(":") + 1, dataURL.indexOf(";"));
-                content = content.buffer;
-                options.headers.append("Content-Type", mime);
-                options.headers.append("Content-Length", content.byteLength);
-            }
-            catch (e) {
-                options.status = 404;
-                options.statusText = "Not Found";
-            }
-            return new Response(content, options);
-        }
-        //@ts-ignore
-        return await window._fetch(request, opts);
-    };
-    const desc = Object.getOwnPropertyDescriptor(HTMLImageElement.prototype, "src");
-    Object.defineProperty(HTMLImageElement.prototype, "src", {
-        ...desc,
-        get: function () {
-            var _a;
-            return (_a = desc === null || desc === void 0 ? void 0 : desc.get) === null || _a === void 0 ? void 0 : _a.call(this);
-        },
-        set: function (e) {
-            var _a;
-            const prefix = _localfsScheme;
-            if (e.startsWith(prefix)) {
-                const path = e.slice(prefix.length);
-                //@ts-ignore
-                const content = window.Basthon.getFile(path).buffer;
-                (async () => { var _a; return (_a = desc === null || desc === void 0 ? void 0 : desc.set) === null || _a === void 0 ? void 0 : _a.call(this, await toDataURL(content)); })();
-            }
-            else {
-                (_a = desc === null || desc === void 0 ? void 0 : desc.set) === null || _a === void 0 ? void 0 : _a.call(this, e);
-            }
-        },
-    });
-})();
-/**
- * An error thrown by not implemented API functions.
- */
-class NotImplementedError extends Error {
-    constructor(funcName) {
-        super(`Function ${funcName} not implemented!`);
-        this.name = "NotImplementedError";
-    }
-}
+import { NotImplementedError } from "./commons";
+// const desc = Object.getOwnPropertyDescriptor(
+//   HTMLImageElement.prototype,
+//   "src"
+// );
+// Object.defineProperty(HTMLImageElement.prototype, "src", {
+//   ...desc,
+//   get: function () {
+//     return desc?.get?.call(this);
+//   },
+//   set: function (e) {
+//     const prefix = _localfsScheme;
+//     if (e.startsWith(prefix)) {
+//       const path = e.slice(prefix.length);
+//       //@ts-ignore
+//       const content = window.Basthon.getFile(path).buffer;
+//       (async () => desc?.set?.call(this, await toDataURL(content)))();
+//     } else {
+//       desc?.set?.call(this, e);
+//     }
+//   },
+// });
 /**
  * Event for Basthon's dispatch/listen.
  */
@@ -87,21 +31,32 @@ class BasthonEvent extends Event {
         this.detail = data;
     }
 }
+export { VERSION };
 /**
  * API that any Basthon kernel should fill to be supported
  * in console/notebook.
  */
 export class KernelBase {
     constructor(options) {
-        this._ready = false;
-        this._loaded = new PromiseDelegate();
+        this._isReady = false;
+        this._ready = new PromiseDelegate();
+        this._stopped = Promise.resolve();
         this._execution_count = 0;
-        this._pendingInput = false;
+        this._pendingInput = undefined;
         // a map to register wrapped listeners to allow later remove
         this._listeners = new Map();
+        this._files = new Map();
+        this._modules = new Map();
+        this._options = this.clone(options);
         // root path where kernel is installed
         this._rootPath = options.rootPath;
     }
+    /**
+     * Is this kernel safe? (loaded from an isolated web worker)
+     */
+    safeKernel() {
+        return false;
+    }
     /**
      * Kernel version number (string).
      */
@@ -128,12 +83,6 @@ export class KernelBase {
     moduleExts() {
         throw new NotImplementedError("moduleExts");
     }
-    /**
-     * Launch the kernel.
-     */
-    async launch() {
-        throw new NotImplementedError("launch");
-    }
     /**
      * Execution count getter.
      */
@@ -146,14 +95,11 @@ export class KernelBase {
     evalAsync(code, outCallback, errCallback, data = null) {
         throw new NotImplementedError("evalAsync");
     }
-    restart() {
-        throw new NotImplementedError("restart");
-    }
     async putFile(filename, content) {
-        throw new NotImplementedError("putFile");
+        this._files.set(filename, content);
     }
     async putModule(filename, content) {
-        throw new NotImplementedError("putModule");
+        this._modules.set(filename, content);
     }
     userModules() {
         return [];
@@ -170,10 +116,10 @@ export class KernelBase {
     getUserModuleFile(filename) {
         throw new NotImplementedError("getUserModuleFile");
     }
-    more(source) {
+    async more(source) {
         throw new NotImplementedError("more");
     }
-    complete(code) {
+    async complete(code) {
         return [];
     }
     banner() {
@@ -186,32 +132,80 @@ export class KernelBase {
         return "... ";
     }
     /**
-     * Initialize the kernel.
+     * Launch the kernel (used to wrap a promise around init).
+     */
+    async _init() { }
+    /**
+     * Initialize the kernel and start it.
      */
     async init() {
+        if (!this.safeKernel())
+            console.warn(`%c⚠ DANGER ⚠: this kernel is not safe!` +
+                " Please consider using a safe kernel.", "color: red; font-size: 20px;");
         try {
-            await this.launch();
+            await this._init();
         }
         catch (error) {
-            this._loaded.reject(error);
+            this._ready.reject(error);
             return;
         }
         // connecting eval to basthon.eval.request event.
         this.addEventListener("eval.request", this.evalFromEvent.bind(this));
-        this._ready = true;
-        this._loaded.resolve();
+        await this.start();
+    }
+    /**
+     * Start the kernel (used to wrap a promise around start).
+     */
+    async _start() { }
+    /**
+     * Start the kernel.
+     */
+    async start() {
+        await this._stopped;
+        this._execution_count = 0;
+        try {
+            await this._start();
+        }
+        catch (error) {
+            this._ready.reject(error);
+            return;
+        }
+        this._files.forEach((v, k) => this.putFile(k, v));
+        this._modules.forEach((v, k) => this.putModule(k, v));
+        this._isReady = true;
+        this._ready.resolve();
+    }
+    /**
+     * Perform async part of the stoping process.
+     */
+    async _stop() { }
+    /**
+     * Stop the kernel synchronously (to ensure kernel is stopped after the call).
+     */
+    stop() {
+        this._isReady = false;
+        this._ready = new PromiseDelegate();
+        this._stopped = this._stop();
+    }
+    /**
+     * Restart the kernel (stop and start).
+     * Use await this.ready() to ensure kernel is started
+     */
+    restart() {
+        this.stop(); // sync
+        this.start(); // async
     }
     /**
      * Is the kernel ready?
      */
-    get ready() {
-        return this._ready;
+    get isReady() {
+        return this._isReady;
     }
     /**
-     * Promise that resolve when the kernel is loaded.
+     * Promise that resolves when the kernel is ready (started).
      */
-    async loaded() {
-        await this._loaded.promise;
+    async ready() {
+        return this._ready.promise;
     }
     /**
      * Root for kernel files. This is always the language directory
@@ -287,7 +281,7 @@ export class KernelBase {
     removeEventListener(eventName, callback) {
         // get the wrapped callback
         const listeners = this._listeners.get(eventName);
-        document.removeEventListener(`basthon.${eventName}`, listeners === null || listeners === void 0 ? void 0 : listeners.get(callback));
+        document.removeEventListener(`basthon.${eventName}`, listeners?.get(callback));
     }
     /**
      * Send eval.input event then wait for the user response and return it.
@@ -295,16 +289,21 @@ export class KernelBase {
     async inputAsync(prompt, password = false, data = undefined) {
         data = this.clone(data);
         data.content = { prompt, password };
-        const promise = new Promise(function (resolve, reject) {
-            data.resolve = resolve;
-            data.reject = reject;
-        });
-        this._pendingInput = true;
+        const pd = new PromiseDelegate();
+        data.resolve = pd.resolve.bind(pd);
+        data.reject = pd.reject.bind(pd);
+        this._pendingInput = pd;
         this.dispatchEvent("eval.input", data);
-        const res = await promise;
-        this._pendingInput = false;
+        const res = await pd.promise;
+        this._pendingInput = undefined;
         return res;
     }
+    /**
+     * Close a pending input.
+     */
+    resolvePendingInput() {
+        this._pendingInput?.resolve("");
+    }
     /**
      * Simple clone via JSON copy.
      */
@@ -317,8 +316,7 @@ export class KernelBase {
      * Detection is based on extension.
      */
     async putRessource(filename, content) {
-        var _a;
-        const ext = (_a = filename.split(".").pop()) !== null && _a !== void 0 ? _a : "";
+        const ext = filename.split(".").pop() ?? "";
         if (this.moduleExts().includes(ext)) {
             return await this.putModule(filename, content);
         }
@@ -330,7 +328,7 @@ export class KernelBase {
      * Is an input pending?
      */
     pendingInput() {
-        return this._pendingInput;
+        return this._pendingInput != null;
     }
     /**
      * Internal. Code evaluation after an eval.request event.

package/lib/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.62.21";
+export declare const VERSION = "0.63.0";

package/lib/version.js

@@ -1 +1 @@
-export const VERSION = "0.62.21";
+export const VERSION = "0.63.0";

package/lib/worker/comlink-proxy.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/worker/comlink-proxy.js

@@ -0,0 +1,4 @@
+import { expose } from "comlink";
+import { ProxyFetch } from "./proxy";
+const proxy = new ProxyFetch();
+expose(proxy);

package/lib/worker/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kernel-main";
+export * from "./kernel-worker";
+export * from "./worker-utils";

package/lib/worker/index.js

@@ -0,0 +1,3 @@
+export * from "./kernel-main";
+export * from "./kernel-worker";
+export * from "./worker-utils";

package/lib/worker/kernel-main.d.ts

@@ -0,0 +1,73 @@
+import { Remote } from "comlink";
+import { KernelWorkerBase } from "./kernel-worker";
+import { KernelBase } from "../kernel";
+export declare class KernelMainBase<Type extends KernelWorkerBase> extends KernelBase {
+    private _worker?;
+    private _remote?;
+    private _legacy;
+    constructor(options: any);
+    /**
+     * Is this a legacy worker? i.e. not runing in a worker.
+     */
+    isLegacy(): boolean;
+    /**
+     * Is this kernel safe? (loaded in an isolated web worker)
+     */
+    safeKernel(): boolean;
+    /**
+     * Get a new worker (should be overloaded).
+     */
+    protected newWorker(): Worker;
+    /**
+     * Import the code for a legacy worker (running in the main thread).
+     */
+    protected importLegacyWorker(): Promise<void>;
+    /**
+     * Create the kernel webworker and setup communication.
+     */
+    protected setupWorker(): Promise<void>;
+    /**
+     * Start the worker.
+     */
+    _start(): Promise<void>;
+    /**
+     * Comlink remote getter.
+     */
+    protected get remote(): Remote<Type> | undefined;
+    /**
+     * Stop the worker.
+     */
+    _stop(): Promise<void>;
+    /**
+     * Process messages from worker (if any).
+     */
+    protected processWorkerMessage(msg: {
+        data: any;
+        type: string;
+        content: any;
+    }): void;
+    evalAsync(code: string, outCallback: (_: string) => void, errCallback: (_: string) => void, data?: any): Promise<any>;
+    /**
+     * Put a file on the local (emulated) filesystem.
+     */
+    putFile(filename: string, content: ArrayBuffer): Promise<void>;
+    /**
+     * Put an importable module on the local (emulated) filesystem
+     * and load dependencies.
+     */
+    putModule(filename: string, content: ArrayBuffer): Promise<void>;
+    /**
+     * Complete a code at the end (usefull for tab completion).
+     *
+     * Returns an array of two elements: the list of completions
+     * and the start index.
+     */
+    complete(code: string): Promise<[string[], number] | []>;
+    /**
+     * Tell wether we should wait for more code or if it can
+     * be run as is.
+     *
+     * Useful to set ps1/ps2 in console prompt.
+     */
+    more(code: string): Promise<boolean>;
+}