@difizen/libro-kernel 0.0.2-alpha.0

package/src/kernelspec/manager.ts

@@ -0,0 +1,173 @@
+import { deepEqual, Poll } from '@difizen/libro-common';
+import type { Event as ManaEvent } from '@difizen/mana-app';
+import { Emitter, Deferred } from '@difizen/mana-app';
+import { inject, singleton } from '@difizen/mana-app';
+import { prop } from '@difizen/mana-app';
+
+import { BaseManager } from '../basemanager.js';
+import { ServerManager } from '../server/server-manager.js';
+
+import type * as KernelSpec from './kernelspec.js';
+import type { ISpecModels } from './restapi.js';
+import { KernelSpecRestAPI } from './restapi.js';
+
+/**
+ * An implementation of a kernel spec manager.
+ */
+@singleton()
+export class KernelSpecManager extends BaseManager implements KernelSpec.IManager {
+  @inject(ServerManager)
+  protected serverManager: ServerManager;
+  @inject(KernelSpecRestAPI)
+  protected kernelSpecRestAPI: KernelSpecRestAPI;
+
+  /**
+   * Construct a new kernel spec manager.
+   *
+   * @param options - The default options for kernel.
+   */
+  constructor() {
+    super();
+
+    // Initialize internal data.
+    this._ready = Promise.all([this.requestSpecs()])
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      .then((_) => undefined)
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      .catch((_) => undefined)
+      .then(() => {
+        if (this.isDisposed) {
+          return;
+        }
+        this._isReady = true;
+        return;
+      });
+
+    this._pollSpecs = new Poll({
+      auto: false,
+      factory: () => this.requestSpecs(),
+      frequency: {
+        interval: 61 * 1000,
+        backoff: true,
+        max: 300 * 1000,
+      },
+      name: `@jupyterlab/services:KernelSpecManager#specs`,
+      standby: 'when-hidden',
+      // standby: options.standby ?? 'when-hidden',
+    });
+    void this.ready.then(() => {
+      void this._pollSpecs.start();
+      return;
+    });
+  }
+
+  /**
+   * The server settings for the manager.
+   */
+  // readonly serverSettings: ServerConnection.ISettings;
+
+  /**
+   * Test whether the manager is ready.
+   */
+  // get isReady(): boolean {
+  //   return this._isReady;
+  // }
+
+  /**
+   * A promise that fulfills when the manager is ready.
+   */
+  // get ready(): Promise<void> {
+  //   return this._ready;
+  // }
+
+  get specsReady() {
+    return this.specsDeferred.promise;
+  }
+
+  /**
+   * Get the most recently fetched kernel specs.
+   */
+  get specs(): ISpecModels | null {
+    return this._specs;
+  }
+
+  /**
+   * A signal emitted when the specs change.
+   */
+  get specsChanged(): ManaEvent<ISpecModels> {
+    return this.specsChangedEmitter.event;
+  }
+
+  /**
+   * A signal emitted when there is a connection failure.
+   */
+  override get connectionFailure(): ManaEvent<Error> {
+    return this.connectionFailureEmitter.event;
+  }
+
+  /**
+   * Dispose of the resources used by the manager.
+   */
+  override dispose(): void {
+    this._pollSpecs.dispose();
+    super.dispose();
+  }
+
+  /**
+   * 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.
+   */
+  async refreshSpecs(): Promise<void> {
+    await this._pollSpecs.refresh();
+    await this._pollSpecs.tick;
+  }
+
+  /**
+   * Execute a request to the server to poll specs and update state.
+   */
+  protected async requestSpecs(): Promise<void> {
+    const specs = await this.kernelSpecRestAPI.getSpecs(this.serverSettings);
+    if (specs) {
+      this.specsDeferred.resolve(specs);
+    }
+
+    if (this.isDisposed) {
+      return;
+    }
+    if (!this._specs || !deepEqual(specs, this._specs)) {
+      this._specs = specs;
+      this.specsChangedEmitter.fire(specs);
+    }
+  }
+
+  // protected _isReady = false;
+  protected override connectionFailureEmitter = new Emitter<Error>();
+
+  protected _pollSpecs: Poll;
+  // protected _ready: Promise<void>;
+
+  @prop()
+  protected _specs: ISpecModels | null = null;
+  protected specsChangedEmitter = new Emitter<ISpecModels>();
+  protected specsDeferred = new Deferred<ISpecModels>();
+}
+
+/**
+ * The namespace for `KernelManager` class statics.
+ */
+export namespace KernelSpecManager {
+  /**
+   * The options used to initialize a KernelManager.
+   */
+  export interface IOptions extends BaseManager.IOptions {
+    /**
+     * When the manager stops polling the API. Defaults to `when-hidden`.
+     */
+    standby?: Poll.Standby | (() => boolean | Poll.Standby);
+  }
+}

package/src/kernelspec/restapi.ts

@@ -0,0 +1,104 @@
+// import { URL } from '@difizen/libro-common';
+import type { PartialJSONObject } from '@difizen/libro-common';
+import { inject, singleton } from '@difizen/mana-app';
+
+import { createResponseError } from '../server/connection-error.js';
+import type { ISettings } from '../server/server-connection-protocol.js';
+import { ServerConnection } from '../server/server-connection.js';
+
+import { validateSpecModels } from './validate.js';
+
+/**
+ * The url for the kernelspec service.
+ */
+const KERNELSPEC_SERVICE_URL = 'api/kernelspecs';
+@singleton()
+export class KernelSpecRestAPI {
+  @inject(ServerConnection) serverConnection: ServerConnection;
+  /**
+   * Fetch all of the kernel specs.
+   *
+   * @param settings - The optional server settings.
+   * @param useCache - Whether to use the cache. If false, always request.
+   *
+   * @returns A promise that resolves with the kernel specs.
+   *
+   * #### Notes
+   * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernelspecs).
+   */
+  async getSpecs(serverSettings?: Partial<ISettings>): Promise<ISpecModels> {
+    const settings = { ...this.serverConnection.settings, ...serverSettings };
+    const url = settings.baseUrl + KERNELSPEC_SERVICE_URL;
+    // TODO: 当前URL.join 方法是坏的
+    // const url = URL.join(settings.baseUrl, KERNELSPEC_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();
+    return validateSpecModels(data);
+  }
+}
+
+/**
+ * Kernel Spec interface.
+ *
+ * #### Notes
+ * See [Kernel specs](https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernelspecs).
+ */
+export interface ISpecModel extends PartialJSONObject {
+  /**
+   * The name of the kernel spec.
+   */
+  readonly name: string;
+
+  /**
+   * The name of the language of the kernel.
+   */
+  readonly language: string;
+
+  /**
+   * A list of command line arguments used to start the kernel.
+   */
+  readonly argv: string[];
+
+  /**
+   * The kernel’s name as it should be displayed in the UI.
+   */
+  readonly display_name: string;
+
+  /**
+   * A dictionary of environment variables to set for the kernel.
+   */
+  readonly env?: PartialJSONObject;
+
+  /**
+   * A mapping of resource file name to download path.
+   */
+  readonly resources: Record<string, string>;
+
+  /**
+   * A dictionary of additional attributes about this kernel; used by clients to aid in kernel selection.
+   */
+  readonly metadata?: PartialJSONObject;
+}
+
+/**
+ * The available kernelSpec models.
+ *
+ * #### Notes
+ * See the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/kernelspecs).
+ */
+export interface ISpecModels extends PartialJSONObject {
+  /**
+   * The name of the default kernel spec.
+   */
+  default: string;
+
+  /**
+   * A mapping of kernel spec name to spec.
+   */
+  readonly kernelspecs: Record<string, ISpecModel | undefined>;
+}

package/src/kernelspec/validate.ts

@@ -0,0 +1,80 @@
+/* eslint-disable no-prototype-builtins */
+import { validateProperty } from '../validate-property.js';
+
+import type { ISpecModel, ISpecModels } from './restapi.js';
+
+/**
+ * Validate a server kernelspec model to a client side model.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export function validateSpecModel(data: any): ISpecModel {
+  const spec = data.spec;
+  if (!spec) {
+    throw new Error('Invalid kernel spec');
+  }
+  validateProperty(data, 'name', 'string');
+  validateProperty(data, 'resources', 'object');
+  validateProperty(spec, 'language', 'string');
+  validateProperty(spec, 'display_name', 'string');
+  validateProperty(spec, 'argv', 'array');
+
+  let metadata: any = null;
+  if (spec.hasOwnProperty('metadata')) {
+    validateProperty(spec, 'metadata', 'object');
+    metadata = spec.metadata;
+  }
+
+  let env: any = null;
+  if (spec.hasOwnProperty('env')) {
+    validateProperty(spec, 'env', 'object');
+    env = spec.env;
+  }
+  return {
+    name: data.name,
+    resources: data.resources,
+    language: spec.language,
+    display_name: spec.display_name,
+    argv: spec.argv,
+    metadata,
+    env,
+  };
+}
+
+/**
+ * Validate a `Kernel.ISpecModels` object.
+ */
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export function validateSpecModels(data: any): ISpecModels {
+  if (!data.hasOwnProperty('kernelspecs')) {
+    throw new Error('No kernelspecs found');
+  }
+  let keys = Object.keys(data.kernelspecs);
+  const kernelspecs: Record<string, ISpecModel> = Object.create(null);
+  let defaultSpec = data.default;
+
+  for (let i = 0; i < keys.length; i++) {
+    const ks = data.kernelspecs[keys[i]];
+    try {
+      kernelspecs[keys[i]] = validateSpecModel(ks);
+    } catch (err) {
+      // Remove the errant kernel spec.
+      console.warn(`Removing errant kernel spec: ${keys[i]}`);
+    }
+  }
+  keys = Object.keys(kernelspecs);
+  if (!keys.length) {
+    throw new Error('No valid kernelspecs found');
+  }
+  if (
+    !defaultSpec ||
+    typeof defaultSpec !== 'string' ||
+    !(defaultSpec in kernelspecs)
+  ) {
+    defaultSpec = keys[0];
+    console.warn(`Default kernel not found, using '${keys[0]}'`);
+  }
+  return {
+    default: defaultSpec,
+    kernelspecs,
+  };
+}

package/src/libro-kernel-connection-manager.ts

@@ -0,0 +1,73 @@
+import { inject, singleton } from '@difizen/mana-app';
+import { prop } from '@difizen/mana-app';
+
+import type { IContentsModel } from './contents/index.js';
+import { LibroKernelManager } from './kernel/libro-kernel-manager.js';
+import type { IKernelConnection } from './kernel/libro-kernel-protocol.js';
+import { LibroSessionManager } from './session/libro-session-manager.js';
+
+@singleton()
+export class LibroKernelConnectionManager {
+  protected sessionManager: LibroSessionManager;
+  protected kernelManager: LibroKernelManager;
+
+  @prop()
+  private kernelConnectionMap: Map<string, IKernelConnection>;
+
+  constructor(
+    @inject(LibroSessionManager) sessionManager: LibroSessionManager,
+    @inject(LibroKernelManager) kernelManager: LibroKernelManager,
+  ) {
+    this.sessionManager = sessionManager;
+    this.kernelManager = kernelManager;
+    this.kernelConnectionMap = new Map<string, IKernelConnection>();
+  }
+
+  async startNew(fileInfo: IContentsModel): Promise<IKernelConnection | undefined> {
+    const connection = await this.sessionManager.startNew(fileInfo);
+    if (!connection) {
+      throw new Error('start new kernel connection failed');
+    }
+    this.kernelConnectionMap.set(fileInfo.name, connection);
+    return connection;
+  }
+
+  async changeKernel(
+    fileInfo: IContentsModel,
+    reuseKernelInfo: { id?: string; name: string },
+  ) {
+    const connection = await this.sessionManager.changeKernel(
+      fileInfo,
+      reuseKernelInfo,
+    );
+    if (!connection) {
+      throw new Error('change kernel connection failed');
+    }
+    this.kernelConnectionMap.set(fileInfo.name, connection);
+    return connection;
+  }
+
+  async shutdownKC(fileInfo: IContentsModel) {
+    const fileName = fileInfo.name;
+    const kc = this.kernelConnectionMap.get(fileName);
+
+    if (!kc) {
+      throw new Error('interrupt connection failed');
+    }
+
+    await this.sessionManager.shutdownKC(fileInfo, kc);
+    this.kernelConnectionMap.delete(fileName);
+  }
+
+  getAllKernelConnections() {
+    return this.kernelConnectionMap;
+  }
+
+  getKernelConnection(fileInfo: IContentsModel) {
+    const connection = this.kernelConnectionMap.get(fileInfo.name);
+    if (connection && !connection.isDisposed) {
+      return connection;
+    }
+    return;
+  }
+}

package/src/module.ts

@@ -0,0 +1,19 @@
+import { ManaModule } from '@difizen/mana-app';
+
+import { BaseManager } from './basemanager.js';
+import { LibroContentsModule } from './contents/contents-module.js';
+import { LibroKernelModule } from './kernel/kernel-module.js';
+import { LibroKernelSpecModule } from './kernelspec/index.js';
+import { LibroKernelConnectionManager } from './libro-kernel-connection-manager.js';
+import { LibroServerModule } from './server/index.js';
+import { LibroSessionModule } from './session/session-module.js';
+
+export const LibroKernelManageModule = ManaModule.create()
+  .dependOn(
+    LibroSessionModule,
+    LibroKernelModule,
+    LibroServerModule,
+    LibroKernelSpecModule,
+    LibroContentsModule,
+  )
+  .register(BaseManager, LibroKernelConnectionManager);

package/src/page-config.ts

@@ -0,0 +1,106 @@
+import { isObject, URL } from '@difizen/libro-common';
+import { isWeb } from '@difizen/mana-app';
+
+/**
+ * page config data for the Jupyter application.
+ */
+let configData: Record<string, string> | null = null;
+
+export class PageConfig {
+  static defaultWorkspace = 'default';
+  /**
+   * Get a url-encoded item from `body.data` and decode it
+   * We should never have any encoded URLs anywhere else in code
+   * until we are building an actual request.
+   */
+  static getBodyData(key: string): string {
+    if (typeof document === 'undefined' || !document.body) {
+      return '';
+    }
+    const val = document.body.dataset[key];
+    if (typeof val === 'undefined') {
+      return '';
+    }
+    return decodeURIComponent(val);
+  }
+  static getOption(name: string): string {
+    if (configData) {
+      return configData[name] || PageConfig.getBodyData(name);
+    }
+    configData = Object.create(null);
+    // Use script tag if available.
+    if (isWeb) {
+      const el = document.getElementById('jupyter-config-data');
+      if (el) {
+        configData = JSON.parse(el.textContent || '') as Record<string, string>;
+      }
+    }
+
+    if (!isObject(configData)) {
+      configData = Object.create(null);
+    } else {
+      for (const key in configData) {
+        // PageConfig expects strings
+        if (typeof configData[key] !== 'string') {
+          configData[key] = JSON.stringify(configData[key]);
+        }
+      }
+    }
+    return configData![name] || PageConfig.getBodyData(name);
+  }
+
+  /**
+   * Set global configuration data for the Jupyter application.
+   *
+   * @param name - The name of the configuration option.
+   * @param value - The value to set the option to.
+   *
+   * @returns The last config value or an empty string if it doesn't exist.
+   */
+  static setOption(name: string, value: string): string {
+    const last = PageConfig.getOption(name);
+
+    configData![name] = value;
+    return last;
+  }
+
+  /**
+   * Get the base url for a Jupyter application, or the base url of the page.
+   */
+  static getBaseUrl(): string {
+    return URL.normalize(PageConfig.getOption('baseUrl') || '/');
+  }
+
+  /**
+   * Get the base websocket url for a Jupyter application, or an empty string.
+   */
+  static getWsUrl(baseUrl?: string): string {
+    let wsUrl = PageConfig.getOption('wsUrl');
+    if (!wsUrl) {
+      baseUrl = baseUrl ? URL.normalize(baseUrl) : PageConfig.getBaseUrl();
+      if (baseUrl.indexOf('http') !== 0) {
+        return '';
+      }
+      wsUrl = 'ws' + baseUrl.slice(4);
+    }
+    return URL.normalize(wsUrl);
+  }
+
+  /**
+   * Get the authorization token for a Jupyter application.
+   */
+  static getToken(): string {
+    return PageConfig.getOption('token') || PageConfig.getBodyData('jupyterApiToken');
+  }
+
+  /**
+   * Get the Notebook version info [major, minor, patch].
+   */
+  static getNotebookVersion(): [number, number, number] {
+    const notebookVersion = PageConfig.getOption('notebookVersion');
+    if (notebookVersion === '') {
+      return [0, 0, 0];
+    }
+    return JSON.parse(notebookVersion);
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,24 @@
+import type { NotebookModel } from '@difizen/libro-core';
+
+import type { IContentsModel } from './contents/index.js';
+import type { IKernelConnection } from './kernel/index.js';
+
+export const ExecutableNotebookModel = {
+  is: (arg: Record<any, any> | undefined): arg is ExecutableNotebookModel => {
+    return (
+      !!arg &&
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      'filePath' in arg &&
+      typeof (arg as any).filePath === 'string' &&
+      'currentFileContents' in arg &&
+      typeof (arg as any).currentFileContents === 'object'
+    );
+  },
+};
+
+export interface ExecutableNotebookModel extends NotebookModel {
+  filePath: string;
+  currentFileContents: IContentsModel;
+  kernelConnection?: IKernelConnection;
+  kcReady: Promise<IKernelConnection>;
+}

package/src/server/connection-error.ts

@@ -0,0 +1,60 @@
+/**
+ * A wrapped error for a fetch response.
+ */
+export class ResponseError extends Error {
+  /**
+   * The response associated with the error.
+   */
+  response: Response;
+
+  /**
+   * The traceback associated with the error.
+   */
+  traceback: string;
+  /**
+   * Create a new response error.
+   */
+  constructor(
+    response: Response,
+    message = `The response is invalid: ${response.status} ${response.statusText}`,
+    traceback = '',
+  ) {
+    super(message);
+    this.response = response;
+    this.traceback = traceback;
+  }
+}
+
+/**
+ * A wrapped error for a network error.
+ */
+export class NetworkError extends TypeError {
+  /**
+   * Create a new network error.
+   */
+  constructor(original: TypeError) {
+    super(original.message);
+    this.stack = original.stack;
+  }
+}
+
+/**
+ * Create a ResponseError from a response, handling the traceback and message
+ * as appropriate.
+ *
+ * @param response The response object.
+ *
+ * @returns A promise that resolves with a `ResponseError` object.
+ */
+export const createResponseError = async (response: Response) => {
+  try {
+    const data = await response.json();
+    if (data.message) {
+      return new ResponseError(response, data.message);
+    }
+    return new ResponseError(response);
+  } catch (e) {
+    console.warn(e);
+    return new ResponseError(response);
+  }
+};

package/src/server/index.ts

@@ -0,0 +1,5 @@
+export * from './server-connection.js';
+export * from './server-manager.js';
+export * from './server-module.js';
+export * from './server-connection-protocol.js';
+export * from './connection-error.js';