@difizen/libro-kernel 0.0.2-alpha.0

package/es/kernel/comm.js

@@ -0,0 +1,216 @@
+function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _toPropertyKey(arg) { var key = _toPrimitive(arg, "string"); return _typeof(key) === "symbol" ? key : String(key); }
+function _toPrimitive(input, hint) { if (_typeof(input) !== "object" || input === null) return input; var prim = input[Symbol.toPrimitive]; if (prim !== undefined) { var res = prim.call(input, hint || "default"); if (_typeof(res) !== "object") return res; throw new TypeError("@@toPrimitive must return a primitive value."); } return (hint === "string" ? String : Number)(input); }
+import * as KernelMessage from "./messages.js";
+
+/**
+ * Comm channel handler.
+ */
+export var CommHandler = /*#__PURE__*/function () {
+  /**
+   * Construct a new comm channel.
+   */
+  function CommHandler(target, id, kernel, disposeCb) {
+    _classCallCheck(this, CommHandler);
+    this._target = '';
+    this._id = '';
+    this.disposed = false;
+    this.disposeCb = disposeCb;
+    this._id = id;
+    this._target = target;
+    this._kernel = kernel;
+  }
+  _createClass(CommHandler, [{
+    key: "dispose",
+    value: function dispose() {
+      this.disposeCb();
+      this.disposed = true;
+    }
+
+    /**
+     * The unique id for the comm channel.
+     */
+  }, {
+    key: "commId",
+    get: function get() {
+      return this._id;
+    }
+
+    /**
+     * The target name for the comm channel.
+     */
+  }, {
+    key: "targetName",
+    get: function get() {
+      return this._target;
+    }
+
+    /**
+     * Get the callback for a comm close event.
+     *
+     * #### Notes
+     * This is called when the comm is closed from either the server or client.
+     *
+     * **See also:** [[ICommClose]], [[close]]
+     */
+  }, {
+    key: "onClose",
+    get: function get() {
+      return this._onClose;
+    }
+
+    /**
+     * Set the callback for a comm close event.
+     *
+     * #### Notes
+     * This is called when the comm is closed from either the server or client. If
+     * the function returns a promise, and the kernel was closed from the server,
+     * kernel message processing will pause until the returned promise is
+     * fulfilled.
+     *
+     * **See also:** [[close]]
+     */,
+    set: function set(cb) {
+      this._onClose = cb;
+    }
+
+    /**
+     * Get the callback for a comm message received event.
+     */
+  }, {
+    key: "onMsg",
+    get: function get() {
+      return this._onMsg;
+    }
+
+    /**
+     * Set the callback for a comm message received event.
+     *
+     * #### Notes
+     * This is called when a comm message is received. If the function returns a
+     * promise, kernel message processing will pause until it is fulfilled.
+     */,
+    set: function set(cb) {
+      this._onMsg = cb;
+    }
+
+    /**
+     * Open a comm with optional data and metadata.
+     *
+     * #### Notes
+     * This sends a `comm_open` message to the server.
+     *
+     * **See also:** [[ICommOpen]]
+     */
+  }, {
+    key: "open",
+    value: function open(data, metadata) {
+      var buffers = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+      if (this.disposed || this._kernel.disposed) {
+        throw new Error('Cannot open');
+      }
+      var msg = KernelMessage.createMessage({
+        msgType: 'comm_open',
+        channel: 'shell',
+        username: this._kernel.username,
+        session: this._kernel.clientId,
+        content: {
+          comm_id: this._id,
+          target_name: this._target,
+          data: data !== null && data !== void 0 ? data : {}
+        },
+        metadata: metadata,
+        buffers: buffers
+      });
+      return this._kernel.sendShellMessage(msg, false, true);
+    }
+
+    /**
+     * Send a `comm_msg` message to the kernel.
+     *
+     * #### Notes
+     * This is a no-op if the comm has been closed.
+     *
+     * **See also:** [[ICommMsg]]
+     */
+  }, {
+    key: "send",
+    value: function send(data, metadata) {
+      var buffers = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+      var disposeOnDone = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : true;
+      if (this.disposed || this._kernel.disposed) {
+        throw new Error('Cannot send');
+      }
+      var msg = KernelMessage.createMessage({
+        msgType: 'comm_msg',
+        channel: 'shell',
+        username: this._kernel.username,
+        session: this._kernel.clientId,
+        content: {
+          comm_id: this._id,
+          data: data
+        },
+        metadata: metadata,
+        buffers: buffers
+      });
+      return this._kernel.sendShellMessage(msg, false, disposeOnDone);
+    }
+
+    /**
+     * Close the comm.
+     *
+     * #### Notes
+     * This will send a `comm_close` message to the kernel, and call the
+     * `onClose` callback if set.
+     *
+     * This is a no-op if the comm is already closed.
+     *
+     * **See also:** [[ICommClose]], [[onClose]]
+     */
+  }, {
+    key: "close",
+    value: function close(data, metadata) {
+      var buffers = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+      if (this.disposed || this._kernel.disposed) {
+        throw new Error('Cannot close');
+      }
+      var msg = KernelMessage.createMessage({
+        msgType: 'comm_close',
+        channel: 'shell',
+        username: this._kernel.username,
+        session: this._kernel.clientId,
+        content: {
+          comm_id: this._id,
+          data: data !== null && data !== void 0 ? data : {}
+        },
+        metadata: metadata,
+        buffers: buffers
+      });
+      var future = this._kernel.sendShellMessage(msg, false, true);
+      var onClose = this._onClose;
+      if (onClose) {
+        var ioMsg = KernelMessage.createMessage({
+          msgType: 'comm_close',
+          channel: 'iopub',
+          username: this._kernel.username,
+          session: this._kernel.clientId,
+          content: {
+            comm_id: this._id,
+            data: data !== null && data !== void 0 ? data : {}
+          },
+          metadata: metadata,
+          buffers: buffers
+        });
+        // In the future, we may want to communicate back to the user the possible
+        // promise returned from onClose.
+        void onClose(ioMsg);
+      }
+      this.dispose();
+      return future;
+    }
+  }]);
+  return CommHandler;
+}();

package/es/kernel/future.d.ts

@@ -0,0 +1,178 @@
+import type { Disposable } from '@difizen/mana-app';
+import { Deferred } from '@difizen/mana-app';
+import type { IKernelConnection, IControlFuture, IShellFuture, IFuture } from './libro-kernel-protocol.js';
+import type * as KernelMessage from './messages.js';
+declare namespace Private {
+    /**
+     * A no-op function.
+     */
+    const noOp: () => void;
+    class HookList<T> {
+        /**
+         * Register a hook.
+         *
+         * @param hook - The callback to register.
+         */
+        add(hook: (msg: T) => boolean | PromiseLike<boolean>): void;
+        /**
+         * Remove a hook, if it exists in the hook list.
+         *
+         * @param hook - The callback to remove.
+         */
+        remove(hook: (msg: T) => boolean | PromiseLike<boolean>): void;
+        /**
+         * Process a message through the hooks.
+         *
+         * @returns a promise resolving to false if any hook resolved as false,
+         * otherwise true
+         *
+         * #### Notes
+         * The most recently registered hook is run first. A hook can return a
+         * boolean or a promise to a boolean, in which case processing pauses until
+         * the promise is fulfilled. If a hook return value resolves to false, any
+         * later hooks will not run and the function will return a promise resolving
+         * to false. If a hook throws an error, the error is logged to the console
+         * and the next hook is run. If a hook is registered during the hook
+         * processing, it will not run until the next message. If a hook is removed
+         * during the hook processing, it will be deactivated immediately.
+         */
+        process(msg: T): Promise<boolean>;
+        /**
+         * Schedule a cleanup of the list, removing any hooks that have been nulled out.
+         */
+        protected _scheduleCompact(): void;
+        /**
+         * Compact the list, removing any nulls.
+         */
+        protected _compact(): void;
+        protected _hooks: (((msg: T) => boolean | PromiseLike<boolean>) | null)[];
+        protected _compactScheduled: boolean;
+        protected _processing: Promise<void>;
+    }
+    /**
+     * Bit flags for the kernel future state.
+     */
+    enum KernelFutureFlag {
+        GotReply = 1,
+        GotIdle = 2,
+        IsDone = 4,
+        DisposeOnDone = 8
+    }
+}
+/**
+ * Implementation of a kernel future.
+ *
+ * If a reply is expected, the Future is considered done when both a `reply`
+ * message and an `idle` iopub status message have been received.  Otherwise, it
+ * is considered done when the `idle` status is received.
+ *
+ */
+export declare abstract class KernelFutureHandler<REQUEST extends KernelMessage.IShellControlMessage, REPLY extends KernelMessage.IShellControlMessage> implements Disposable, IFuture<REQUEST, REPLY> {
+    protected disposeCb: () => void;
+    disposed: boolean;
+    /**
+     * Construct a new KernelFutureHandler.
+     */
+    constructor(cb: () => void, msg: REQUEST, expectReply: boolean, disposeOnDone: boolean, kernel: IKernelConnection);
+    /**
+     * Get the original outgoing message.
+     */
+    get msg(): REQUEST;
+    /**
+     * A promise that resolves when the future is done.
+     */
+    get done(): Promise<REPLY>;
+    /**
+     * Get the reply handler.
+     */
+    get onReply(): (msg: REPLY) => void | PromiseLike<void>;
+    /**
+     * Set the reply handler.
+     */
+    set onReply(cb: (msg: REPLY) => void | PromiseLike<void>);
+    /**
+     * Get the iopub handler.
+     */
+    get onIOPub(): (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;
+    /**
+     * Set the iopub handler.
+     */
+    set onIOPub(cb: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>);
+    /**
+     * Get the stdin handler.
+     */
+    get onStdin(): (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;
+    /**
+     * Set the stdin handler.
+     */
+    set onStdin(cb: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>);
+    /**
+     * Register hook for IOPub messages.
+     *
+     * @param hook - The callback invoked for an IOPub message.
+     *
+     * #### Notes
+     * The IOPub hook system allows you to preempt the handlers for IOPub
+     * messages handled by the future.
+     *
+     * The most recently registered hook is run first. A hook can return a
+     * boolean or a promise to a boolean, in which case all kernel message
+     * processing pauses until the promise is fulfilled. If a hook return value
+     * resolves to false, any later hooks will not run and the function will
+     * return a promise resolving to false. If a hook throws an error, the error
+     * is logged to the console and the next hook is run. If a hook is
+     * registered during the hook processing, it will not run until the next
+     * message. If a hook is removed during the hook processing, it will be
+     * deactivated immediately.
+     */
+    registerMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
+    /**
+     * Remove a hook for IOPub messages.
+     *
+     * @param hook - The hook to remove.
+     *
+     * #### Notes
+     * If a hook is removed during the hook processing, it will be deactivated immediately.
+     */
+    removeMessageHook(hook: (msg: KernelMessage.IIOPubMessage) => boolean | PromiseLike<boolean>): void;
+    /**
+     * Send an `input_reply` message.
+     */
+    sendInputReply(content: KernelMessage.IInputReplyMsg['content'], parent_header: KernelMessage.IInputReplyMsg['parent_header']): void;
+    /**
+     * Dispose and unregister the future.
+     */
+    dispose(): void;
+    /**
+     * Handle an incoming kernel message.
+     */
+    handleMsg(msg: KernelMessage.IMessage): Promise<void>;
+    protected _handleReply(msg: REPLY): Promise<void>;
+    protected _handleStdin(msg: KernelMessage.IStdinMessage): Promise<void>;
+    protected _handleIOPub(msg: KernelMessage.IIOPubMessage): Promise<void>;
+    protected _handleDone(): void;
+    /**
+     * Test whether the given future flag is set.
+     */
+    protected _testFlag(flag: Private.KernelFutureFlag): boolean;
+    /**
+     * Set the given future flag.
+     */
+    protected _setFlag(flag: Private.KernelFutureFlag): void;
+    protected _msg: REQUEST;
+    protected _status: number;
+    protected _stdin: (msg: KernelMessage.IStdinMessage) => void | PromiseLike<void>;
+    protected _iopub: (msg: KernelMessage.IIOPubMessage) => void | PromiseLike<void>;
+    protected _reply: (msg: REPLY) => void | PromiseLike<void>;
+    protected _done: Deferred<REPLY>;
+    protected _replyMsg: REPLY;
+    protected _hooks: Private.HookList<KernelMessage.IIOPubMessage<KernelMessage.IOPubMessageType>>;
+    protected _disposeOnDone: boolean;
+    protected _kernel: IKernelConnection;
+}
+export declare class KernelControlFutureHandler<REQUEST extends KernelMessage.IControlMessage = KernelMessage.IControlMessage, REPLY extends KernelMessage.IControlMessage = KernelMessage.IControlMessage> extends KernelFutureHandler<REQUEST, REPLY> implements IControlFuture<REQUEST, REPLY> {
+}
+export declare class KernelShellFutureHandler<REQUEST extends KernelMessage.IShellMessage = KernelMessage.IShellMessage, REPLY extends KernelMessage.IShellMessage = KernelMessage.IShellMessage> extends KernelFutureHandler<REQUEST, REPLY> implements IShellFuture<REQUEST, REPLY> {
+}
+export {};
+//# sourceMappingURL=future.d.ts.map

package/es/kernel/future.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"future.d.ts","sourceRoot":"","sources":["../../src/kernel/future.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,OAAO,EACR,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,KAAK,aAAa,MAAM,eAAe,CAAC;AAIpD,kBAAU,OAAO,CAAC;IAChB;;OAEG;IACI,MAAM,IAAI,QAAO,IAEvB,CAAC;IAeF,MAAa,QAAQ,CAAC,CAAC;QACrB;;;;WAIG;QACH,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;QAK3D;;;;WAIG;QACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,IAAI;QAQ9D;;;;;;;;;;;;;;;WAeG;QACG,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;QA0CvC;;WAEG;QACH,SAAS,CAAC,gBAAgB,IAAI,IAAI;QAkBlC;;WAEG;QACH,SAAS,CAAC,QAAQ,IAAI,IAAI;QAa1B,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAM;QAC/E,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC;QACrC,SAAS,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;KACtC;IAED;;OAEG;IACH,KAAY,gBAAgB;QAC1B,QAAQ,IAAM;QACd,OAAO,IAAM;QACb,MAAM,IAAM;QACZ,aAAa,IAAM;KACpB;CACF;AAED;;;;;;;GAOG;AACH,8BAAsB,mBAAmB,CACrC,OAAO,SAAS,aAAa,CAAC,oBAAoB,EAClD,KAAK,SAAS,aAAa,CAAC,oBAAoB,CAElD,YAAW,UAAU,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC;IAE9C,SAAS,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAChC,QAAQ,UAAS;IACjB;;OAEG;gBAED,EAAE,EAAE,MAAM,IAAI,EACd,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,OAAO,EACpB,aAAa,EAAE,OAAO,EACtB,MAAM,EAAE,iBAAiB;IAW3B;;OAEG;IACH,IAAI,GAAG,IAAI,OAAO,CAEjB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAEzB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAEtD;IAED;;OAEG;IACH,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,EAEvD;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAE5E;IAED;;OAEG;IACH,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,EAE7E;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAE5E;IAED;;OAEG;IACH,IAAI,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,EAE7E;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CACjB,IAAI,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GACzE,IAAI;IAOP;;;;;;;OAOG;IACH,iBAAiB,CACf,IAAI,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,GACzE,IAAI;IAOP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,SAAS,CAAC,EAChD,aAAa,EAAE,aAAa,CAAC,cAAc,CAAC,eAAe,CAAC,GAC3D,IAAI;IAIP;;OAEG;IACH,OAAO,IAAI,IAAI;IAsCf;;OAEG;IACG,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;cAuB3C,YAAY,CAAC,GAAG,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC;cAavC,YAAY,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;cAS7D,YAAY,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7E,SAAS,CAAC,WAAW,IAAI,IAAI;IAW7B;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,gBAAgB,GAAG,OAAO;IAK5D;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,gBAAgB,GAAG,IAAI;IAKxD,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC;IACxB,SAAS,CAAC,OAAO,SAAK;IACtB,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CACjE;IACf,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,aAAa,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CACjE;IACf,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAgB;IAC1E,SAAS,CAAC,KAAK,kBAAyB;IACxC,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC;IAC3B,SAAS,CAAC,MAAM,gFAAuD;IACvE,SAAS,CAAC,cAAc,UAAQ;IAChC,SAAS,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACtC;AAED,qBAAa,0BAA0B,CACnC,OAAO,SAAS,aAAa,CAAC,eAAe,GAAG,aAAa,CAAC,eAAe,EAC7E,KAAK,SAAS,aAAa,CAAC,eAAe,GAAG,aAAa,CAAC,eAAe,CAE7E,SAAQ,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAC1C,YAAW,cAAc,CAAC,OAAO,EAAE,KAAK,CAAC;CAAG;AAE9C,qBAAa,wBAAwB,CACjC,OAAO,SAAS,aAAa,CAAC,aAAa,GAAG,aAAa,CAAC,aAAa,EACzE,KAAK,SAAS,aAAa,CAAC,aAAa,GAAG,aAAa,CAAC,aAAa,CAEzE,SAAQ,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAC1C,YAAW,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC;CAAG"}