@difizen/libro-kernel 0.0.2-alpha.0

package/src/kernel/restapi.ts

@@ -0,0 +1,183 @@
+import { URL } from '@difizen/libro-common';
+import { inject, singleton } from '@difizen/mana-app';
+
+import type { ISettings } from '../server/index.js';
+import { createResponseError, ServerConnection } from '../server/index.js';
+
+import type { IKernelModel, KernelMeta } from './libro-kernel-protocol.js';
+import { validateModel, validateModels } from './validate.js';
+
+export const KERNEL_SERVICE_URL = 'api/kernels';
+
+@singleton()
+export class KernelRestAPI {
+  @inject(ServerConnection) serverConnection: ServerConnection;
+
+  /**
+   * Get a full kernel model from the server by kernel id string.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response and rejected otherwise.
+   */
+  async getKernelModel(
+    id: string,
+    serverSettings?: Partial<ISettings>,
+  ): Promise<IKernelModel | undefined> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(settings.baseUrl, KERNEL_SERVICE_URL, encodeURIComponent(id));
+
+    const response = await this.serverConnection.makeRequest(url, {}, settings);
+    if (response.status === 404) {
+      return undefined;
+    } else if (response.status !== 200) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+    const data = await response.json();
+    validateModel(data);
+    return data;
+  }
+
+  /**
+   * Start a new kernel.
+   *
+   * @param options - The options used to create the kernel.
+   *
+   * @returns A promise that resolves with a kernel connection object.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response and rejected otherwise.
+   */
+  async startNew(
+    options: IKernelOptions = {},
+    serverSettings?: Partial<ISettings>,
+  ): Promise<IKernelModel> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(settings.baseUrl, KERNEL_SERVICE_URL);
+    const init = {
+      method: 'POST',
+      body: JSON.stringify(options),
+    };
+    const response = await this.serverConnection.makeRequest(url, init, settings);
+    if (response.status !== 201) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+    const data = await response.json();
+    validateModel(data);
+    return data;
+  }
+
+  /**
+   * Fetch the running kernels.
+   *
+   * @param settings - The optional server settings.
+   *
+   * @returns A promise that resolves with the list of running kernels.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response and rejected otherwise.
+   */
+  async listRunning(serverSettings?: Partial<ISettings>): Promise<KernelMeta[]> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(settings.baseUrl, KERNEL_SERVICE_URL);
+    const response = await this.serverConnection.makeRequest(url, {}, settings);
+    if (response.status !== 200) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+    const data = await response.json();
+    validateModels(data);
+    return data;
+  }
+
+  /**
+   * Shut down a kernel.
+   *
+   * @param id - The id of the running kernel.
+   *
+   * @param settings - The server settings for the request.
+   *
+   * @returns A promise that resolves when the kernel is shut down.
+   *
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response and rejected otherwise.
+   */
+  async shutdownKernel(id: string, serverSettings?: Partial<ISettings>): Promise<void> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(settings.baseUrl, KERNEL_SERVICE_URL, encodeURIComponent(id));
+    const init = { method: 'DELETE' };
+    const response = await this.serverConnection.makeRequest(url, init, settings);
+    if (response.status === 404) {
+      const msg = `The kernel "${id}" does not exist on the server`;
+      console.warn(msg);
+    } else if (response.status !== 204) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+  }
+
+  /**
+   * Restart a kernel.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response (and thus after a restart) and rejected otherwise.
+   */
+  async restartKernel(id: string, serverSettings?: Partial<ISettings>): Promise<void> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(
+      settings.baseUrl,
+      KERNEL_SERVICE_URL,
+      encodeURIComponent(id),
+      'restart',
+    );
+    const init = { method: 'POST' };
+
+    const response = await this.serverConnection.makeRequest(url, init, settings);
+    if (response.status !== 200) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+    const data = await response.json();
+    validateModel(data);
+  }
+
+  /**
+   * Interrupt a kernel.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernels) and validates the response model.
+   *
+   * The promise is fulfilled on a valid response and rejected otherwise.
+   */
+  async interruptKernel(
+    id: string,
+    serverSettings?: Partial<ISettings>,
+  ): Promise<void> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = URL.join(
+      settings.baseUrl,
+      KERNEL_SERVICE_URL,
+      encodeURIComponent(id),
+      'interrupt',
+    );
+    const init = { method: 'POST' };
+    const response = await this.serverConnection.makeRequest(url, init, settings);
+    if (response.status !== 204) {
+      const err = await createResponseError(response);
+      throw err;
+    }
+  }
+}
+export type IKernelOptions = Partial<Pick<IKernelModel, 'name'>>;

package/src/kernel/serialize.ts

@@ -0,0 +1,262 @@
+import * as KernelMessage from './messages.js';
+
+namespace Private {
+  /**
+   * Deserialize and return the unpacked message.
+   * Protocol `v1.kernel.websocket.jupyter.org`
+   */
+  export function deserializeV1KernelWebsocketJupyterOrg(
+    binMsg: ArrayBuffer,
+  ): KernelMessage.IMessage {
+    const data = new DataView(binMsg);
+    const offsetNumber = Number(data.getBigUint64(0, true /* littleEndian */));
+    const offsets: number[] = [];
+    for (let i = 0; i < offsetNumber; i++) {
+      // WARNING: we cast our 64-bit unsigned int to a number!
+      // so offsets cannot index up to 2**64 bytes
+      offsets.push(Number(data.getBigUint64(8 * (i + 1), true /* littleEndian */)));
+    }
+    const decoder = new TextDecoder('utf8');
+    const channel = decoder.decode(
+      binMsg.slice(offsets[0], offsets[1]),
+    ) as KernelMessage.Channel;
+    const header = JSON.parse(decoder.decode(binMsg.slice(offsets[1], offsets[2])));
+    const parent_header = JSON.parse(
+      decoder.decode(binMsg.slice(offsets[2], offsets[3])),
+    );
+    const metadata = JSON.parse(decoder.decode(binMsg.slice(offsets[3], offsets[4])));
+    const content = JSON.parse(decoder.decode(binMsg.slice(offsets[4], offsets[5])));
+    const buffers = [];
+    for (let i = 5; i < offsets.length; i++) {
+      if (i === offsets.length - 1) {
+        buffers.push(binMsg.slice(offsets[i]));
+      } else {
+        buffers.push(binMsg.slice(offsets[i], offsets[i + 1]));
+      }
+    }
+    const msg: KernelMessage.IMessage = {
+      channel,
+      header,
+      parent_header,
+      metadata,
+      content,
+      buffers,
+    };
+    return msg;
+  }
+
+  /**
+   * Serialize a kernel message for transport.
+   * Protocol `v1.kernel.websocket.jupyter.org`
+   */
+  export function serializeV1KernelWebsocketJupyterOrg(
+    msg: KernelMessage.IMessage,
+  ): ArrayBuffer {
+    const header = JSON.stringify(msg.header);
+    const parentHeader =
+      msg.parent_header === null ? '{}' : JSON.stringify(msg.parent_header);
+    const metadata = JSON.stringify(msg.metadata);
+    const content = JSON.stringify(msg.content);
+    const buffers: (ArrayBuffer | ArrayBufferView)[] =
+      msg.buffers !== undefined ? msg.buffers : [];
+    const offsetNumber: number = 1 + 4 + buffers.length + 1;
+    const offsets: number[] = [];
+    offsets.push(8 * (1 + offsetNumber));
+    offsets.push(msg.channel.length + offsets[offsets.length - 1]);
+    const encoder = new TextEncoder();
+    const channelEncoded = encoder.encode(msg.channel);
+    const headerEncoded = encoder.encode(header);
+    const parentHeaderEncoded = encoder.encode(parentHeader);
+    const metadataEncoded = encoder.encode(metadata);
+    const contentEncoded = encoder.encode(content);
+    const binMsgNoBuff = new Uint8Array(
+      channelEncoded.length +
+        headerEncoded.length +
+        parentHeaderEncoded.length +
+        metadataEncoded.length +
+        contentEncoded.length,
+    );
+    binMsgNoBuff.set(channelEncoded);
+    binMsgNoBuff.set(headerEncoded, channelEncoded.length);
+    binMsgNoBuff.set(parentHeaderEncoded, channelEncoded.length + headerEncoded.length);
+    binMsgNoBuff.set(
+      metadataEncoded,
+      channelEncoded.length + headerEncoded.length + parentHeaderEncoded.length,
+    );
+    binMsgNoBuff.set(
+      contentEncoded,
+      channelEncoded.length +
+        headerEncoded.length +
+        parentHeaderEncoded.length +
+        metadataEncoded.length,
+    );
+    for (const length of [
+      headerEncoded.length,
+      parentHeaderEncoded.length,
+      metadataEncoded.length,
+      contentEncoded.length,
+    ]) {
+      offsets.push(length + offsets[offsets.length - 1]);
+    }
+    let buffersByteLength = 0;
+    for (const buffer of buffers) {
+      const length = buffer.byteLength;
+      offsets.push(length + offsets[offsets.length - 1]);
+      buffersByteLength += length;
+    }
+    const binMsg = new Uint8Array(
+      8 * (1 + offsetNumber) + binMsgNoBuff.byteLength + buffersByteLength,
+    );
+    const word = new ArrayBuffer(8);
+    const data = new DataView(word);
+    data.setBigUint64(0, BigInt(offsetNumber), true /* littleEndian */);
+    binMsg.set(new Uint8Array(word), 0);
+    for (let i = 0; i < offsets.length; i++) {
+      data.setBigUint64(0, BigInt(offsets[i]), true /* littleEndian */);
+      binMsg.set(new Uint8Array(word), 8 * (i + 1));
+    }
+    binMsg.set(binMsgNoBuff, offsets[0]);
+    for (let i = 0; i < buffers.length; i++) {
+      const buffer = buffers[i];
+      binMsg.set(
+        new Uint8Array(ArrayBuffer.isView(buffer) ? buffer.buffer : buffer),
+        offsets[5 + i],
+      );
+    }
+    return binMsg.buffer;
+  }
+
+  /**
+   * Deserialize and return the unpacked message.
+   * Default protocol
+   *
+   * #### Notes
+   * Handles JSON blob strings and binary messages.
+   */
+  export function deserializeDefault(
+    data: ArrayBuffer | string,
+  ): KernelMessage.IMessage {
+    let value: KernelMessage.IMessage;
+    if (typeof data === 'string') {
+      value = JSON.parse(data);
+    } else {
+      value = deserializeBinary(data);
+    }
+    return value;
+  }
+
+  /**
+   * Serialize a kernel message for transport.
+   * Default protocol
+   *
+   * #### Notes
+   * If there is binary content, an `ArrayBuffer` is returned,
+   * otherwise the message is converted to a JSON string.
+   */
+  export function serializeDefault(msg: KernelMessage.IMessage): string | ArrayBuffer {
+    let value: string | ArrayBuffer;
+    if (msg.buffers?.length) {
+      value = serializeBinary(msg);
+    } else {
+      value = JSON.stringify(msg);
+    }
+    return value;
+  }
+}
+
+/**
+ * Serialize a kernel message for transport.
+ */
+export function serialize(
+  msg: KernelMessage.IMessage,
+  protocol = '',
+): string | ArrayBuffer {
+  switch (protocol) {
+    case KernelMessage.supportedKernelWebSocketProtocols.v1KernelWebsocketJupyterOrg:
+      return Private.serializeV1KernelWebsocketJupyterOrg(msg);
+    default:
+      return Private.serializeDefault(msg);
+  }
+}
+
+/**
+ * Deserialize and return the unpacked message.
+ */
+export function deserialize(data: ArrayBuffer, protocol = ''): KernelMessage.IMessage {
+  switch (protocol) {
+    case KernelMessage.supportedKernelWebSocketProtocols.v1KernelWebsocketJupyterOrg:
+      return Private.deserializeV1KernelWebsocketJupyterOrg(data);
+    default:
+      return Private.deserializeDefault(data);
+  }
+}
+/**
+ * Deserialize a binary message to a Kernel Message.
+ */
+function deserializeBinary(buf: ArrayBuffer): KernelMessage.IMessage {
+  const data = new DataView(buf);
+  // read the header: 1 + nbufs 32b integers
+  const nbufs = data.getUint32(0);
+  const offsets: number[] = [];
+  if (nbufs < 2) {
+    throw new Error('Invalid incoming Kernel Message');
+  }
+  for (let i = 1; i <= nbufs; i++) {
+    offsets.push(data.getUint32(i * 4));
+  }
+  const jsonBytes = new Uint8Array(buf.slice(offsets[0], offsets[1]));
+  const msg = JSON.parse(new TextDecoder('utf8').decode(jsonBytes));
+  // the remaining chunks are stored as DataViews in msg.buffers
+  msg.buffers = [];
+  for (let i = 1; i < nbufs; i++) {
+    const start = offsets[i];
+    const stop = offsets[i + 1] || buf.byteLength;
+    msg.buffers.push(new DataView(buf.slice(start, stop)));
+  }
+  return msg;
+}
+
+/**
+ * Implement the binary serialization protocol.
+ *
+ * Serialize Kernel message to ArrayBuffer.
+ */
+function serializeBinary(msg: KernelMessage.IMessage): ArrayBuffer {
+  const offsets: number[] = [];
+  const buffers: ArrayBuffer[] = [];
+  const encoder = new TextEncoder();
+  let origBuffers: (ArrayBuffer | ArrayBufferView)[] = [];
+  if (msg.buffers !== undefined) {
+    origBuffers = msg.buffers;
+    delete msg.buffers;
+  }
+  const jsonUtf8 = encoder.encode(JSON.stringify(msg));
+  buffers.push(jsonUtf8.buffer);
+  for (let i = 0; i < origBuffers.length; i++) {
+    // msg.buffers elements could be either views or ArrayBuffers
+    // buffers elements are ArrayBuffers
+    const b: any = origBuffers[i];
+    buffers.push(ArrayBuffer.isView(b) ? b.buffer : b);
+  }
+  const nbufs = buffers.length;
+  offsets.push(4 * (nbufs + 1));
+  for (let i = 0; i + 1 < buffers.length; i++) {
+    offsets.push(offsets[offsets.length - 1] + buffers[i].byteLength);
+  }
+  const msgBuf = new Uint8Array(
+    offsets[offsets.length - 1] + buffers[buffers.length - 1].byteLength,
+  );
+  // use DataView.setUint32 for network byte-order
+  const view = new DataView(msgBuf.buffer);
+  // write nbufs to first 4 bytes
+  view.setUint32(0, nbufs);
+  // write offsets to next 4 * nbufs bytes
+  for (let i = 0; i < offsets.length; i++) {
+    view.setUint32(4 * (i + 1), offsets[i]);
+  }
+  // write all the buffers at their respective offsets
+  for (let i = 0; i < buffers.length; i++) {
+    msgBuf.set(new Uint8Array(buffers[i]), offsets[i]);
+  }
+  return msgBuf.buffer;
+}

package/src/kernel/validate.ts

@@ -0,0 +1,101 @@
+import { validateProperty } from '../validate-property.js';
+
+import type { KernelMeta } from './libro-kernel-protocol.js';
+import type * as KernelMessage from './messages.js';
+
+/**
+ * Required fields for `IKernelHeader`.
+ */
+const HEADER_FIELDS = ['username', 'version', 'session', 'msg_id', 'msg_type'];
+
+/**
+ * Required fields and types for contents of various types of `kernel.IMessage`
+ * messages on the iopub channel.
+ */
+const IOPUB_CONTENT_FIELDS: Record<string, any> = {
+  stream: { name: 'string', text: 'string' },
+  display_data: { data: 'object', metadata: 'object' },
+  execute_input: { code: 'string', execution_count: 'number' },
+  execute_result: {
+    execution_count: 'number',
+    data: 'object',
+    metadata: 'object',
+  },
+  error: { ename: 'string', evalue: 'string', traceback: 'object' },
+  status: {
+    execution_state: ['string', ['starting', 'idle', 'busy', 'restarting', 'dead']],
+  },
+  clear_output: { wait: 'boolean' },
+  comm_open: { comm_id: 'string', target_name: 'string', data: 'object' },
+  comm_msg: { comm_id: 'string', data: 'object' },
+  comm_close: { comm_id: 'string' },
+  shutdown_reply: { restart: 'boolean' }, // Emitted by the IPython kernel.
+};
+
+/**
+ * Validate the header of a kernel message.
+ */
+function validateHeader(
+  header: KernelMessage.IHeader,
+): asserts header is KernelMessage.IHeader {
+  for (let i = 0; i < HEADER_FIELDS.length; i++) {
+    validateProperty(header, HEADER_FIELDS[i], 'string');
+  }
+}
+
+/**
+ * Validate a kernel message object.
+ */
+export function validateMessage(
+  msg: KernelMessage.IMessage,
+): asserts msg is KernelMessage.IMessage {
+  validateProperty(msg, 'metadata', 'object');
+  validateProperty(msg, 'content', 'object');
+  validateProperty(msg, 'channel', 'string');
+  validateHeader(msg.header);
+  if (msg.channel === 'iopub') {
+    validateIOPubContent(msg as KernelMessage.IIOPubMessage);
+  }
+}
+
+/**
+ * Validate content an kernel message on the iopub channel.
+ */
+function validateIOPubContent(
+  msg: KernelMessage.IIOPubMessage,
+): asserts msg is KernelMessage.IIOPubMessage {
+  if (msg.channel === 'iopub') {
+    const fields = IOPUB_CONTENT_FIELDS[msg.header.msg_type];
+    // Check for unknown message type.
+    if (fields === undefined) {
+      return;
+    }
+    const names = Object.keys(fields);
+    const content = msg.content;
+    for (let i = 0; i < names.length; i++) {
+      let args = fields[names[i]];
+      if (!Array.isArray(args)) {
+        args = [args];
+      }
+      validateProperty(content, names[i], ...args);
+    }
+  }
+}
+
+/**
+ * Validate a `Kernel.KernelMeta` object.
+ */
+export function validateModel(model: KernelMeta): asserts model is KernelMeta {
+  validateProperty(model, 'name', 'string');
+  validateProperty(model, 'id', 'string');
+}
+
+/**
+ * Validate an array of `KernelMeta` objects.
+ */
+export function validateModels(models: KernelMeta[]): asserts models is KernelMeta[] {
+  if (!Array.isArray(models)) {
+    throw new Error('Invalid kernel list');
+  }
+  models.forEach((d) => validateModel(d));
+}

package/src/kernelspec/index.ts

@@ -0,0 +1,5 @@
+export * from './kernelspec.js';
+export * from './restapi.js';
+
+export * from './manager.js';
+export * from './kernelspec-module.js';

package/src/kernelspec/kernelspec-module.ts

@@ -0,0 +1,9 @@
+import { ManaModule } from '@difizen/mana-app';
+
+import { KernelSpecManager } from './manager.js';
+import { KernelSpecRestAPI } from './restapi.js';
+
+export const LibroKernelSpecModule = ManaModule.create().register(
+  KernelSpecManager,
+  KernelSpecRestAPI,
+);

package/src/kernelspec/kernelspec.ts

@@ -0,0 +1,37 @@
+import type { Event as ManaEvent } from '@difizen/mana-app';
+
+import type { IManager as IBaseManager } from '../basemanager.js';
+
+import type { ISpecModels } from './restapi.js';
+
+/**
+ * Object which manages kernel instances for a given base url.
+ *
+ * #### Notes
+ * The manager is responsible for maintaining the state of kernel specs.
+ */
+export interface IManager extends IBaseManager {
+  /**
+   * A signal emitted when the kernel specs change.
+   */
+  specsChanged: ManaEvent<ISpecModels>;
+
+  /**
+   * The kernel spec models.
+   *
+   * #### Notes
+   * The value will be null until the manager is ready.
+   */
+  readonly specs: ISpecModels | null;
+
+  /**
+   * Force a refresh of the specs from the server.
+   *
+   * @returns A promise that resolves when the specs are fetched.
+   *
+   * #### Notes
+   * This is intended to be called only in response to a user action,
+   * since the manager maintains its internal state.
+   */
+  refreshSpecs: () => Promise<void>;
+}