@jupyterlite/services 0.1.0 → 0.7.0-rc.1

package/src/session/client.ts

@@ -0,0 +1,252 @@
+import type { Session } from '@jupyterlab/services';
+import { ServerConnection } from '@jupyterlab/services';
+
+import { PathExt } from '@jupyterlab/coreutils';
+
+import type { LiteKernelClient } from '../kernel';
+
+import { ArrayExt } from '@lumino/algorithm';
+
+import { UUID } from '@lumino/coreutils';
+
+import type { ISessionAPIClient } from '@jupyterlab/services/lib/session/session';
+
+type DeepPartial<T> = {
+  [P in keyof T]?: DeepPartial<T[P]>;
+};
+
+/**
+ * A class to handle requests to /api/sessions
+ */
+export class LiteSessionClient implements ISessionAPIClient {
+  /**
+   * Construct a new LiteSessionClient.
+   *
+   * @param options The instantiation options for a LiteSessionClient.
+   */
+  constructor(options: LiteSessionClient.IOptions) {
+    this._kernelClient = options.kernelClient;
+    this._serverSettings = options.serverSettings ?? ServerConnection.makeSettings();
+    // Listen for kernel removals
+    this._kernelClient.changed.connect((_, args) => {
+      switch (args.type) {
+        case 'remove': {
+          const kernelId = args.oldValue?.id;
+          if (!kernelId) {
+            return;
+          }
+          // find the session associated with the kernel
+          const session = this._sessions.find((s) => s.kernel?.id === kernelId);
+          if (!session) {
+            return;
+          }
+          // Track the kernel ID for restart detection
+          this._pendingRestarts.add(kernelId);
+          setTimeout(async () => {
+            // If after a short delay the kernel hasn't been re-added, it was terminated
+            if (this._pendingRestarts.has(kernelId)) {
+              this._pendingRestarts.delete(kernelId);
+              await this.shutdown(session.id);
+            }
+          }, 100);
+          break;
+        }
+        case 'add': {
+          // If this was a restart, remove it from pending
+          const kernelId = args.newValue?.id;
+          if (!kernelId) {
+            return;
+          }
+          this._pendingRestarts.delete(kernelId);
+          break;
+        }
+      }
+    });
+  }
+
+  /**
+   * The server settings for the session client.
+   */
+  get serverSettings(): ServerConnection.ISettings {
+    return this._serverSettings;
+  }
+
+  /**
+   * Get a session by id.
+   *
+   * @param id The id of the session.
+   */
+  async getModel(id: string): Promise<Session.IModel> {
+    const session = this._sessions.find((s) => s.id === id);
+    if (!session) {
+      throw Error(`Session ${id} not found`);
+    }
+    return session;
+  }
+
+  /**
+   * List the running sessions
+   */
+  async listRunning(): Promise<Session.IModel[]> {
+    return this._sessions;
+  }
+
+  /**
+   * Patch an existing session.
+   * This can be used to rename a session.
+   *
+   * - path updates session to track renamed paths
+   * - kernel.name starts a new kernel with a given kernelspec
+   *
+   * @param options The options to patch the session.
+   */
+  async update(options: DeepPartial<Session.IModel>): Promise<Session.IModel> {
+    const { id, path, name, kernel } = options;
+    const index = this._sessions.findIndex((s) => s.id === id);
+    const session = this._sessions[index];
+    if (!session) {
+      throw Error(`Session ${id} not found`);
+    }
+    const patched = {
+      ...session,
+      path: path ?? session.path,
+      name: name ?? session.name,
+    };
+
+    if (kernel) {
+      // Kernel id takes precedence over name.
+      if (kernel.id) {
+        const session = this._sessions.find(
+          (session) => session.kernel?.id === kernel?.id,
+        );
+        if (session) {
+          patched.kernel = session.kernel;
+        }
+      } else if (kernel.name) {
+        const newKernel = await this._kernelClient.startNew({
+          id: UUID.uuid4(),
+          name: kernel.name,
+          location: PathExt.dirname(patched.path),
+        });
+
+        if (newKernel) {
+          patched.kernel = newKernel;
+        }
+
+        // clean up the session on kernel shutdown
+        void this._handleKernelShutdown({
+          kernelId: newKernel.id,
+          sessionId: session.id,
+        });
+      }
+    }
+
+    this._sessions[index] = patched;
+    return patched;
+  }
+
+  /**
+   * Start a new session
+   * TODO: read path and name
+   *
+   * @param options The options to start a new session.
+   */
+  async startNew(options: Session.ISessionOptions): Promise<Session.IModel> {
+    const { path, name } = options;
+    const running = this._sessions.find((s) => s.name === name);
+    if (running) {
+      return running;
+    }
+    const kernelName = options.kernel?.name ?? '';
+    const id = UUID.uuid4();
+    const nameOrPath = options.name ?? options.path;
+    const dirname = PathExt.dirname(options.name) || PathExt.dirname(options.path);
+    const hasDrive = nameOrPath.includes(':');
+    const driveName = hasDrive ? nameOrPath.split(':')[0] : '';
+    // add drive name if missing (top level directory)
+    const location = dirname.includes(driveName) ? dirname : `${driveName}:${dirname}`;
+    const kernel = await this._kernelClient.startNew({
+      id,
+      name: kernelName,
+      location,
+    });
+    const session: Session.IModel = {
+      id,
+      path,
+      name: name ?? path,
+      type: 'notebook',
+      kernel: {
+        id: kernel.id,
+        name: kernel.name,
+      },
+    };
+    this._sessions.push(session);
+
+    // clean up the session on kernel shutdown
+    void this._handleKernelShutdown({ kernelId: id, sessionId: session.id });
+
+    return session;
+  }
+
+  /**
+   * Shut down a session.
+   *
+   * @param id The id of the session to shut down.
+   */
+  async shutdown(id: string): Promise<void> {
+    const session = this._sessions.find((s) => s.id === id);
+    if (!session) {
+      throw Error(`Session ${id} not found`);
+    }
+    const kernelId = session.kernel?.id;
+    if (kernelId) {
+      await this._kernelClient.shutdown(kernelId);
+    }
+    ArrayExt.removeFirstOf(this._sessions, session);
+  }
+
+  /**
+   * Shut down all sessions.
+   */
+  async shutdownAll(): Promise<void> {
+    await Promise.all(this._sessions.map((s) => this.shutdown(s.id)));
+  }
+
+  /**
+   * Handle kernel shutdown
+   */
+  private async _handleKernelShutdown({
+    kernelId,
+    sessionId,
+  }: {
+    kernelId: string;
+    sessionId: string;
+  }): Promise<void> {
+    // No need to handle kernel shutdown here anymore since we're using the changed signal
+  }
+
+  private _kernelClient: LiteKernelClient;
+  private _serverSettings: ServerConnection.ISettings;
+  private _sessions: Session.IModel[] = [];
+  private _pendingRestarts = new Set<string>();
+}
+
+/**
+ * A namespace for LiteSessionClient statics.
+ */
+export namespace LiteSessionClient {
+  /**
+   * The instantiation options for the session client.
+   */
+  export interface IOptions {
+    /**
+     * A reference to the kernels service.
+     */
+    kernelClient: LiteKernelClient;
+
+    /**
+     * Server settings for the session client.
+     */
+    serverSettings?: ServerConnection.ISettings;
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+export * from './client';

package/src/settings/index.ts

@@ -0,0 +1,4 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+export * from './settings';

package/src/settings/settings.ts

@@ -0,0 +1,237 @@
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+
+import type { ServerConnection, Setting } from '@jupyterlab/services';
+import { SettingManager } from '@jupyterlab/services';
+
+import type { ISettingRegistry } from '@jupyterlab/settingregistry';
+
+import { PromiseDelegate } from '@lumino/coreutils';
+
+import * as json5 from 'json5';
+
+import type localforage from 'localforage';
+
+/**
+ * The settings file to request
+ */
+export type SettingsFile = 'all.json' | 'all_federated.json';
+
+/**
+ * The name of the local storage.
+ */
+const DEFAULT_STORAGE_NAME = 'JupyterLite Storage';
+
+/**
+ * A class to manage settings in the browser.
+ */
+export class Settings extends SettingManager implements Setting.IManager {
+  /**
+   * Create a new settings service.
+   */
+  constructor(options: Settings.IOptions) {
+    super({
+      serverSettings: options.serverSettings,
+    });
+    this._localforage = options.localforage;
+    this._storageName = options.storageName || DEFAULT_STORAGE_NAME;
+    this._storageDrivers = options.storageDrivers || null;
+
+    this._ready = new PromiseDelegate();
+    void this.initialize().catch(console.warn);
+  }
+
+  /**
+   * A promise that resolves when the settings storage is fully initialized
+   */
+  get ready(): Promise<void> {
+    return this._ready.promise;
+  }
+
+  /**
+   * A lazy reference to initialized storage
+   */
+  protected get storage(): Promise<LocalForage> {
+    return this.ready.then(() => this._storage as LocalForage);
+  }
+
+  /**
+   * Finish any initialization after server has started and all extensions are applied.
+   */
+  async initialize() {
+    await this.initStorage();
+    this._ready.resolve(void 0);
+  }
+
+  /**
+   * Prepare the storage
+   */
+  protected async initStorage() {
+    this._storage = this.defaultSettingsStorage();
+  }
+
+  /**
+   * Get default options for localForage instances
+   */
+  protected get defaultStorageOptions(): LocalForageOptions {
+    const driver = this._storageDrivers?.length ? this._storageDrivers : null;
+    return {
+      version: 1,
+      name: this._storageName,
+      ...(driver ? { driver } : {}),
+    };
+  }
+
+  /**
+   * Create a settings store.
+   */
+  protected defaultSettingsStorage(): LocalForage {
+    return this._localforage.createInstance({
+      description: 'Offline Storage for Settings',
+      storeName: 'settings',
+      ...this.defaultStorageOptions,
+    });
+  }
+
+  /**
+   * Get settings by plugin id
+   *
+   * @param pluginId the id of the plugin
+   *
+   */
+  async fetch(pluginId: string): Promise<ISettingRegistry.IPlugin> {
+    const all = await this.list();
+    const settings = all.values as ISettingRegistry.IPlugin[];
+    const setting = settings.find((setting: ISettingRegistry.IPlugin) => {
+      return setting.id === pluginId;
+    });
+    if (!setting) {
+      throw new Error(`Setting ${pluginId} not found`);
+    }
+    return setting;
+  }
+
+  /**
+   * Get all the settings
+   */
+  async list(
+    query?: 'ids',
+  ): Promise<{ ids: string[]; values: ISettingRegistry.IPlugin[] }> {
+    const allCore = await this._getAll('all.json');
+    let allFederated: ISettingRegistry.IPlugin[] = [];
+    try {
+      allFederated = await this._getAll('all_federated.json');
+    } catch {
+      // handle the case where there is no federated extension
+    }
+
+    // JupyterLab 4 expects all settings to be returned in one go
+    // so append the settings from federated plugins to the core ones
+    const all = allCore.concat(allFederated);
+
+    // return existing user settings if they exist
+    const storage = await this.storage;
+    const settings = await Promise.all(
+      all.map(async (plugin) => {
+        const { id } = plugin;
+        const raw = ((await storage.getItem(id)) as string) ?? plugin.raw;
+        return {
+          ...Private.override(plugin),
+          raw,
+          settings: json5.parse(raw),
+        };
+      }),
+    );
+
+    // format the settings
+    const ids = settings.map((plugin: ISettingRegistry.IPlugin) => plugin.id) ?? [];
+
+    let values: ISettingRegistry.IPlugin[] = [];
+    if (!query) {
+      values =
+        settings.map((plugin: ISettingRegistry.IPlugin) => {
+          plugin.data = { composite: {}, user: {} };
+          return plugin;
+        }) ?? [];
+    }
+
+    return { ids, values };
+  }
+
+  /**
+   * Save settings for a given plugin id
+   *
+   * @param pluginId The id of the plugin
+   * @param raw The raw settings
+   *
+   */
+  async save(id: string, raw: string): Promise<void> {
+    await (await this.storage).setItem(id, raw);
+  }
+
+  /**
+   * Clear all stored settings
+   *
+   * @returns A promise which resolves when the settings are cleared
+   */
+  async clear(): Promise<void> {
+    await (await this.storage).clear();
+  }
+
+  /**
+   * Get all the settings for core or federated plugins
+   */
+  private async _getAll(file: SettingsFile): Promise<ISettingRegistry.IPlugin[]> {
+    const settingsUrl = PageConfig.getOption('settingsUrl') ?? '/';
+    const all = (await (
+      await fetch(URLExt.join(settingsUrl, file))
+    ).json()) as ISettingRegistry.IPlugin[];
+    return all;
+  }
+
+  private _storageName: string = DEFAULT_STORAGE_NAME;
+  private _storageDrivers: string[] | null = null;
+  private _storage: LocalForage | undefined;
+  private _localforage: typeof localforage;
+  private _ready: PromiseDelegate<void>;
+}
+
+/**
+ * A namespace for settings metadata.
+ */
+export namespace Settings {
+  /**
+   * Initialization options for settings.
+   */
+  export interface IOptions {
+    localforage: typeof localforage;
+    storageName?: string | null;
+    storageDrivers?: string[] | null;
+    serverSettings?: ServerConnection.ISettings;
+  }
+}
+
+/**
+ * A namespace for private data
+ */
+namespace Private {
+  const _overrides: Record<string, ISettingRegistry.IPlugin['schema']['default']> =
+    JSON.parse(PageConfig.getOption('settingsOverrides') || '{}');
+
+  /**
+   * Override the defaults of the schema with ones from PageConfig
+   *
+   * @see https://github.com/jupyterlab/jupyterlab_server/blob/v2.5.2/jupyterlab_server/settings_handler.py#L216-L227
+   */
+  export function override(plugin: ISettingRegistry.IPlugin): ISettingRegistry.IPlugin {
+    if (_overrides[plugin.id]) {
+      if (!plugin.schema.properties) {
+        // probably malformed, or only provides keyboard shortcuts, etc.
+        plugin.schema.properties = {};
+      }
+      for (const [prop, propDefault] of Object.entries(_overrides[plugin.id] || {})) {
+        plugin.schema.properties[prop].default = propDefault;
+      }
+    }
+    return plugin;
+  }
+}

package/style/index.css

@@ -0,0 +1,6 @@
+/*-----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+/* This file is intentionally empty */

package/style/index.js

@@ -0,0 +1,6 @@
+/*-----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+import './index.css';