@jupyterlite/terminal 0.2.0-a0 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@ A terminal for JupyterLite.
 
 ## Requirements
 
-- JupyterLite >= 0.4.0
+- JupyterLite >= 0.6.0
 
 ## Install
 
@@ -46,18 +46,6 @@ Then build a new JupyterLite site:
 jupyter lite build
 ```
 
-## Deployment
-
-If you would like to deploy a JupyterLite site with the terminal extension, you will need to configure your server to add the `Cross-Origin-Embedder-Policy` and `Cross-Origin-Opener-Policy` headers.
-
-As an example, this repository deploys the JupyterLite terminal to [Vercel](https://vercel.com), using the following files:
-
-- `vercel.json`: configure the COOP / COEP server headers
-- `deploy/requirements-deploy.txt`: dependencies for the JupyterLite deployment
-- `deploy/deploy.sh`: script to deploy to Vercel, using micromamba to have full control on the Python versions and isolate the build in a virtual environment
-
-For more information, have a look at the JupyterLite documentation: https://jupyterlite.readthedocs.io/
-
 ## Contributing
 
 ### Development install
@@ -97,6 +85,18 @@ jupyter lite build --contents contents
 
 And serve it either using:
 
+```bash
+npx static-handler _output/
+```
+
+or:
+
+```bash
+jupyter lite serve
+```
+
+To enable use of SharedArrayBuffer rather than ServiceWorker for `stdin` you will have to configure your server to add the `Cross-Origin-Embedder-Policy` and `Cross-Origin-Opener-Policy` headers. Do this using either:
+
 ```bash
 npx static-handler --cors --coop --coep --corp _output/
 ```
@@ -107,8 +107,6 @@ or:
 jupyter lite serve --LiteBuildConfig.extra_http_headers=Cross-Origin-Embedder-Policy=require-corp --LiteBuildConfig.extra_http_headers=Cross-Origin-Opener-Policy=same-origin
 ```
 
-The extra HTTP headers are require to ensure that `SharedArrayBuffer` is available.
-
 ### Packaging the extension
 
 See [RELEASE](RELEASE.md)

package/lib/client.d.ts

@@ -0,0 +1,28 @@
+import { ServerConnection, Terminal } from '@jupyterlab/services';
+import { IExternalCommand, IStdinReply, IStdinRequest } from '@jupyterlite/cockle';
+import { ILiteTerminalAPIClient } from './tokens';
+export declare class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
+    constructor(options?: {
+        serverSettings?: ServerConnection.ISettings;
+    });
+    /**
+     * Set identifier for communicating with service worker.
+     */
+    set browsingContextId(browsingContextId: string);
+    /**
+     * Function that handles stdin requests received from service worker.
+     */
+    handleStdin(request: IStdinRequest): Promise<IStdinReply>;
+    get isAvailable(): boolean;
+    readonly serverSettings: ServerConnection.ISettings;
+    startNew(options?: Terminal.ITerminal.IOptions): Promise<Terminal.IModel>;
+    listRunning(): Promise<Terminal.IModel[]>;
+    registerExternalCommand(options: IExternalCommand.IOptions): void;
+    shutdown(name: string): Promise<void>;
+    private get _models();
+    private _nextAvailableName;
+    private _browsingContextId?;
+    private _externalCommands;
+    private _shellManager;
+    private _shells;
+}

package/lib/client.js

@@ -0,0 +1,118 @@
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+import { ShellManager } from '@jupyterlite/cockle';
+import { Server as WebSocketServer } from 'mock-socket';
+import { Shell } from './shell';
+export class LiteTerminalAPIClient {
+    constructor(options = {}) {
+        var _a;
+        this._externalCommands = [];
+        this._shells = new Map();
+        this.serverSettings =
+            (_a = options.serverSettings) !== null && _a !== void 0 ? _a : ServerConnection.makeSettings();
+        this._shellManager = new ShellManager();
+    }
+    /**
+     * Set identifier for communicating with service worker.
+     */
+    set browsingContextId(browsingContextId) {
+        console.log('LiteTerminalAPIClient browsingContextId', browsingContextId);
+        this._browsingContextId = browsingContextId;
+    }
+    /**
+     * Function that handles stdin requests received from service worker.
+     */
+    async handleStdin(request) {
+        return await this._shellManager.handleStdin(request);
+    }
+    get isAvailable() {
+        const available = String(PageConfig.getOption('terminalsAvailable'));
+        return available.toLowerCase() === 'true';
+    }
+    async startNew(options) {
+        var _a;
+        // Create shell.
+        const name = (_a = options === null || options === void 0 ? void 0 : options.name) !== null && _a !== void 0 ? _a : this._nextAvailableName();
+        const { baseUrl, wsUrl } = this.serverSettings;
+        const shell = new Shell({
+            mountpoint: '/drive',
+            baseUrl,
+            wasmBaseUrl: URLExt.join(baseUrl, 'extensions/@jupyterlite/terminal/static/wasm/'),
+            browsingContextId: this._browsingContextId,
+            shellId: name,
+            shellManager: this._shellManager,
+            outputCallback: text => {
+                var _a;
+                const msg = JSON.stringify(['stdout', text]);
+                (_a = shell.socket) === null || _a === void 0 ? void 0 : _a.send(msg);
+            }
+        });
+        this._shells.set(name, shell);
+        for (const externalCommand of this._externalCommands) {
+            shell.registerExternalCommand(externalCommand);
+        }
+        // Hook to connect socket to shell.
+        const hook = async (shell, socket) => {
+            shell.socket = socket;
+            socket.on('message', async (message) => {
+                // Message from xtermjs to pass to shell.
+                const data = JSON.parse(message);
+                const message_type = data[0];
+                const content = data.slice(1);
+                await shell.ready;
+                if (message_type === 'stdin') {
+                    await shell.input(content[0]);
+                }
+                else if (message_type === 'set_size') {
+                    const rows = content[0];
+                    const columns = content[1];
+                    await shell.setSize(rows, columns);
+                }
+            });
+            // Return handshake.
+            const res = JSON.stringify(['setup']);
+            console.log('Terminal returning handshake via socket');
+            socket.send(res);
+            shell.start();
+        };
+        const url = URLExt.join(wsUrl, 'terminals', 'websocket', name);
+        const wsServer = new WebSocketServer(url);
+        wsServer.on('connection', (socket) => {
+            hook(shell, socket);
+        });
+        shell.disposed.connect(() => {
+            this.shutdown(name);
+            wsServer.close();
+        });
+        return { name };
+    }
+    async listRunning() {
+        return this._models;
+    }
+    registerExternalCommand(options) {
+        this._externalCommands.push(options);
+    }
+    async shutdown(name) {
+        var _a, _b;
+        const shell = this._shells.get(name);
+        if (shell !== undefined) {
+            (_a = shell.socket) === null || _a === void 0 ? void 0 : _a.send(JSON.stringify(['disconnect']));
+            (_b = shell.socket) === null || _b === void 0 ? void 0 : _b.close();
+            this._shells.delete(name);
+            shell.dispose();
+        }
+    }
+    get _models() {
+        return Array.from(this._shells.keys(), name => {
+            return { name };
+        });
+    }
+    _nextAvailableName() {
+        for (let i = 1;; ++i) {
+            const name = `${i}`;
+            if (!this._shells.has(name)) {
+                return name;
+            }
+        }
+    }
+}

package/lib/index.d.ts

@@ -1,4 +1,4 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 import { ServiceManagerPlugin, Terminal } from '@jupyterlab/services';
-declare const _default: (ServiceManagerPlugin<Terminal.IManager> | JupyterFrontEndPlugin<void>)[];
+declare const _default: (ServiceManagerPlugin<Terminal.ITerminalAPIClient> | ServiceManagerPlugin<Terminal.IManager> | JupyterFrontEndPlugin<void>)[];
 export default _default;

package/lib/index.js

@@ -1,39 +1,67 @@
 // Copyright (c) Jupyter Development Team.
 // Distributed under the terms of the Modified BSD License.
-import { ITerminalManager } from '@jupyterlab/services';
+import { ITerminalManager, ServerConnection, IServerSettings, TerminalManager } from '@jupyterlab/services';
 import { IServiceWorkerManager } from '@jupyterlite/server';
-import { isILiteTerminalManager, LiteTerminalManager } from './manager';
+import { WebSocket } from 'mock-socket';
+import { LiteTerminalAPIClient } from './client';
+import { ILiteTerminalAPIClient } from './tokens';
 /**
- * The terminal manager plugin, replacing the JupyterLab terminal manager.
+ * Plugin containing client for in-browser terminals.
+ */
+const terminalClientPlugin = {
+    id: '@jupyterlite/terminal:client',
+    description: 'The client for Lite terminals',
+    autoStart: true,
+    provides: ILiteTerminalAPIClient,
+    optional: [IServerSettings],
+    activate: (_, serverSettings) => {
+        return new LiteTerminalAPIClient({
+            serverSettings: {
+                ...ServerConnection.makeSettings(),
+                ...serverSettings,
+                WebSocket
+            }
+        });
+    }
+};
+/**
+ * Plugin containing manager for in-browser terminals.
  */
 const terminalManagerPlugin = {
-    id: '@jupyterlite/terminal:plugin',
+    id: '@jupyterlite/terminal:manager',
     description: 'A JupyterLite extension providing a custom terminal manager',
     autoStart: true,
     provides: ITerminalManager,
-    activate: (_) => {
-        console.log('JupyterLite extension @jupyterlite/terminal:plugin is activated!');
-        return new LiteTerminalManager();
+    requires: [ILiteTerminalAPIClient],
+    activate: (_, terminalAPIClient) => {
+        console.log('JupyterLite extension @jupyterlite/terminal:manager activated');
+        return new TerminalManager({
+            terminalAPIClient,
+            serverSettings: terminalAPIClient.serverSettings
+        });
     }
 };
 /**
- * A plugin that sets the browsingContextId of the terminal manager.
+ * Plugin that connects in-browser terminals and service worker.
  */
-const browsingContextIdSetter = {
-    id: '@jupyterlite/terminal:browsing-context-id',
+const terminalServiceWorkerPlugin = {
+    id: '@jupyterlite/terminal:service-worker',
     autoStart: true,
+    requires: [ILiteTerminalAPIClient],
     optional: [IServiceWorkerManager],
-    requires: [ITerminalManager],
-    activate: (_, terminalManager, serviceWorkerManager) => {
+    activate: (_, liteTerminalAPIClient, serviceWorkerManager) => {
         if (serviceWorkerManager !== undefined) {
-            if (isILiteTerminalManager(terminalManager)) {
-                const { browsingContextId } = serviceWorkerManager;
-                terminalManager.browsingContextId = browsingContextId;
-            }
-            else {
-                console.warn('Terminal manager does not support setting browsingContextId');
-            }
+            liteTerminalAPIClient.browsingContextId =
+                serviceWorkerManager.browsingContextId;
+            serviceWorkerManager.registerStdinHandler('terminal', liteTerminalAPIClient.handleStdin.bind(liteTerminalAPIClient));
+        }
+        else {
+            console.warn('Service worker is not available for terminals');
         }
     }
 };
-export default [terminalManagerPlugin, browsingContextIdSetter];
+export default [
+    terminalClientPlugin,
+    terminalManagerPlugin,
+    terminalServiceWorkerPlugin
+];

package/lib/shell.d.ts

@@ -1,4 +1,5 @@
 import { BaseShell, IShell } from '@jupyterlite/cockle';
+import { Client as WebSocketClient } from 'mock-socket';
 /**
  * Shell class that uses web worker that plugs into a DriveFS via the service worker.
  */
@@ -13,4 +14,5 @@ export declare class Shell extends BaseShell {
      * Load the web worker.
      */
     protected initWorker(options: IShell.IOptions): Worker;
+    socket?: WebSocketClient;
 }

package/lib/tokens.d.ts

@@ -0,0 +1,18 @@
+import { Terminal } from '@jupyterlab/services';
+import { IExternalCommand, IStdinReply, IStdinRequest } from '@jupyterlite/cockle';
+import { Token } from '@lumino/coreutils';
+export declare const ILiteTerminalAPIClient: Token<ILiteTerminalAPIClient>;
+export interface ILiteTerminalAPIClient extends Terminal.ITerminalAPIClient {
+    /**
+     * Identifier for communicating with service worker.
+     */
+    browsingContextId: string;
+    /**
+     * Function that handles stdin requests received from service worker.
+     */
+    handleStdin(request: IStdinRequest): Promise<IStdinReply>;
+    /**
+     * Register an external command that will be available in all terminals.
+     */
+    registerExternalCommand(options: IExternalCommand.IOptions): void;
+}

package/lib/tokens.js

@@ -0,0 +1,2 @@
+import { Token } from '@lumino/coreutils';
+export const ILiteTerminalAPIClient = new Token('@jupyterlite/terminal:client');

package/lib/worker.js

@@ -10,17 +10,17 @@ class ShellWorker extends BaseShellWorker {
      * Initialize the DriveFS to mount an external file system, if available.
      */
     initDriveFS(options) {
-        const { browsingContextId, driveFsBaseUrl, fileSystem, mountpoint } = options;
-        console.log('Terminal initDriveFS', driveFsBaseUrl, mountpoint, browsingContextId);
+        const { baseUrl, browsingContextId, fileSystem, mountpoint } = options;
+        console.log('Terminal initDriveFS', baseUrl, mountpoint, browsingContextId);
         if (mountpoint !== '' &&
-            driveFsBaseUrl !== undefined &&
+            baseUrl !== undefined &&
             browsingContextId !== undefined) {
             const { FS, ERRNO_CODES, PATH } = fileSystem;
             const driveFS = new DriveFS({
                 FS,
                 PATH,
                 ERRNO_CODES,
-                baseUrl: driveFsBaseUrl,
+                baseUrl,
                 driveName: '',
                 mountpoint,
                 browsingContextId

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyterlite/terminal",
-    "version": "0.2.0-a0",
+    "version": "0.2.0",
     "description": "A terminal for JupyterLite",
     "keywords": [
         "jupyter",
@@ -59,19 +59,17 @@
         "watch:labextension": "jupyter labextension watch ."
     },
     "dependencies": {
-        "@jupyterlab/coreutils": "^6.4.2",
-        "@jupyterlab/services": "^7.4.2",
-        "@jupyterlab/terminal": "^4.4.2",
-        "@jupyterlab/terminal-extension": "^4.4.2",
-        "@jupyterlite/cockle": "^0.0.19",
-        "@jupyterlite/contents": "0.6.0-beta.0",
-        "@jupyterlite/server": "0.6.0-beta.0",
+        "@jupyterlab/coreutils": "^6.4.3",
+        "@jupyterlab/services": "^7.4.3",
+        "@jupyterlite/cockle": "^0.1.0",
+        "@jupyterlite/contents": "0.6.0",
+        "@jupyterlite/server": "0.6.0",
         "@lumino/coreutils": "^2.2.0",
         "mock-socket": "^9.3.1"
     },
     "devDependencies": {
-        "@jupyterlab/builder": "^4.4.2",
-        "@jupyterlab/testutils": "^4.4.2",
+        "@jupyterlab/builder": "^4.4.3",
+        "@jupyterlab/testutils": "^4.4.3",
         "@types/jest": "^29.2.0",
         "@types/json-schema": "^7.0.11",
         "@types/react": "^18.0.26",
@@ -99,6 +97,9 @@
         "webpack-cli": "^5.1.4",
         "yjs": "^13.5.0"
     },
+    "resolutions": {
+        "parse5": "7.2.1"
+    },
     "sideEffects": [
         "style/*.css",
         "style/index.js"

package/src/client.ts

@@ -0,0 +1,157 @@
+import { PageConfig, URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection, Terminal } from '@jupyterlab/services';
+import {
+  IExternalCommand,
+  IShellManager,
+  IStdinReply,
+  IStdinRequest,
+  ShellManager
+} from '@jupyterlite/cockle';
+import { JSONPrimitive } from '@lumino/coreutils';
+
+import {
+  Server as WebSocketServer,
+  Client as WebSocketClient
+} from 'mock-socket';
+
+import { Shell } from './shell';
+import { ILiteTerminalAPIClient } from './tokens';
+
+export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
+  constructor(options: { serverSettings?: ServerConnection.ISettings } = {}) {
+    this.serverSettings =
+      options.serverSettings ?? ServerConnection.makeSettings();
+    this._shellManager = new ShellManager();
+  }
+
+  /**
+   * Set identifier for communicating with service worker.
+   */
+  set browsingContextId(browsingContextId: string) {
+    console.log('LiteTerminalAPIClient browsingContextId', browsingContextId);
+    this._browsingContextId = browsingContextId;
+  }
+
+  /**
+   * Function that handles stdin requests received from service worker.
+   */
+  async handleStdin(request: IStdinRequest): Promise<IStdinReply> {
+    return await this._shellManager.handleStdin(request);
+  }
+
+  get isAvailable(): boolean {
+    const available = String(PageConfig.getOption('terminalsAvailable'));
+    return available.toLowerCase() === 'true';
+  }
+
+  readonly serverSettings: ServerConnection.ISettings;
+
+  async startNew(
+    options?: Terminal.ITerminal.IOptions
+  ): Promise<Terminal.IModel> {
+    // Create shell.
+    const name = options?.name ?? this._nextAvailableName();
+    const { baseUrl, wsUrl } = this.serverSettings;
+    const shell = new Shell({
+      mountpoint: '/drive',
+      baseUrl,
+      wasmBaseUrl: URLExt.join(
+        baseUrl,
+        'extensions/@jupyterlite/terminal/static/wasm/'
+      ),
+      browsingContextId: this._browsingContextId,
+      shellId: name,
+      shellManager: this._shellManager,
+      outputCallback: text => {
+        const msg = JSON.stringify(['stdout', text]);
+        shell.socket?.send(msg);
+      }
+    });
+    this._shells.set(name, shell);
+
+    for (const externalCommand of this._externalCommands) {
+      shell.registerExternalCommand(externalCommand);
+    }
+
+    // Hook to connect socket to shell.
+    const hook = async (
+      shell: Shell,
+      socket: WebSocketClient
+    ): Promise<void> => {
+      shell.socket = socket;
+
+      socket.on('message', async (message: any) => {
+        // Message from xtermjs to pass to shell.
+        const data = JSON.parse(message) as JSONPrimitive[];
+        const message_type = data[0];
+        const content = data.slice(1);
+        await shell.ready;
+        if (message_type === 'stdin') {
+          await shell.input(content[0] as string);
+        } else if (message_type === 'set_size') {
+          const rows = content[0] as number;
+          const columns = content[1] as number;
+          await shell.setSize(rows, columns);
+        }
+      });
+
+      // Return handshake.
+      const res = JSON.stringify(['setup']);
+      console.log('Terminal returning handshake via socket');
+      socket.send(res);
+
+      shell.start();
+    };
+
+    const url = URLExt.join(wsUrl, 'terminals', 'websocket', name);
+    const wsServer = new WebSocketServer(url);
+    wsServer.on('connection', (socket: WebSocketClient): void => {
+      hook(shell, socket);
+    });
+
+    shell.disposed.connect(() => {
+      this.shutdown(name);
+      wsServer.close();
+    });
+
+    return { name };
+  }
+
+  async listRunning(): Promise<Terminal.IModel[]> {
+    return this._models;
+  }
+
+  registerExternalCommand(options: IExternalCommand.IOptions): void {
+    this._externalCommands.push(options);
+  }
+
+  async shutdown(name: string): Promise<void> {
+    const shell = this._shells.get(name);
+    if (shell !== undefined) {
+      shell.socket?.send(JSON.stringify(['disconnect']));
+      shell.socket?.close();
+      this._shells.delete(name);
+      shell.dispose();
+    }
+  }
+
+  private get _models(): Terminal.IModel[] {
+    return Array.from(this._shells.keys(), name => {
+      return { name };
+    });
+  }
+
+  private _nextAvailableName(): string {
+    for (let i = 1; ; ++i) {
+      const name = `${i}`;
+      if (!this._shells.has(name)) {
+        return name;
+      }
+    }
+  }
+
+  private _browsingContextId?: string;
+  private _externalCommands: IExternalCommand.IOptions[] = [];
+  private _shellManager: IShellManager;
+  private _shells = new Map<string, Shell>();
+}

package/src/index.ts

@@ -8,52 +8,94 @@ import {
 import {
   ITerminalManager,
   ServiceManagerPlugin,
-  Terminal
+  Terminal,
+  ServerConnection,
+  IServerSettings,
+  TerminalManager
 } from '@jupyterlab/services';
 import { IServiceWorkerManager } from '@jupyterlite/server';
 
-import { isILiteTerminalManager, LiteTerminalManager } from './manager';
+import { WebSocket } from 'mock-socket';
+
+import { LiteTerminalAPIClient } from './client';
+import { ILiteTerminalAPIClient } from './tokens';
 
 /**
- * The terminal manager plugin, replacing the JupyterLab terminal manager.
+ * Plugin containing client for in-browser terminals.
+ */
+const terminalClientPlugin: ServiceManagerPlugin<Terminal.ITerminalAPIClient> =
+  {
+    id: '@jupyterlite/terminal:client',
+    description: 'The client for Lite terminals',
+    autoStart: true,
+    provides: ILiteTerminalAPIClient,
+    optional: [IServerSettings],
+    activate: (
+      _: null,
+      serverSettings?: ServerConnection.ISettings
+    ): ILiteTerminalAPIClient => {
+      return new LiteTerminalAPIClient({
+        serverSettings: {
+          ...ServerConnection.makeSettings(),
+          ...serverSettings,
+          WebSocket
+        }
+      });
+    }
+  };
+
+/**
+ * Plugin containing manager for in-browser terminals.
  */
 const terminalManagerPlugin: ServiceManagerPlugin<Terminal.IManager> = {
-  id: '@jupyterlite/terminal:plugin',
+  id: '@jupyterlite/terminal:manager',
   description: 'A JupyterLite extension providing a custom terminal manager',
   autoStart: true,
   provides: ITerminalManager,
-  activate: (_: null): Terminal.IManager => {
+  requires: [ILiteTerminalAPIClient],
+  activate: (
+    _: null,
+    terminalAPIClient: Terminal.ITerminalAPIClient
+  ): Terminal.IManager => {
     console.log(
-      'JupyterLite extension @jupyterlite/terminal:plugin is activated!'
+      'JupyterLite extension @jupyterlite/terminal:manager activated'
     );
-    return new LiteTerminalManager();
+    return new TerminalManager({
+      terminalAPIClient,
+      serverSettings: terminalAPIClient.serverSettings
+    });
   }
 };
 
 /**
- * A plugin that sets the browsingContextId of the terminal manager.
+ * Plugin that connects in-browser terminals and service worker.
  */
-const browsingContextIdSetter: JupyterFrontEndPlugin<void> = {
-  id: '@jupyterlite/terminal:browsing-context-id',
+const terminalServiceWorkerPlugin: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlite/terminal:service-worker',
   autoStart: true,
+  requires: [ILiteTerminalAPIClient],
   optional: [IServiceWorkerManager],
-  requires: [ITerminalManager],
   activate: (
     _: JupyterFrontEnd,
-    terminalManager: Terminal.IManager,
+    liteTerminalAPIClient: ILiteTerminalAPIClient,
     serviceWorkerManager?: IServiceWorkerManager
   ): void => {
     if (serviceWorkerManager !== undefined) {
-      if (isILiteTerminalManager(terminalManager)) {
-        const { browsingContextId } = serviceWorkerManager;
-        terminalManager.browsingContextId = browsingContextId;
-      } else {
-        console.warn(
-          'Terminal manager does not support setting browsingContextId'
-        );
-      }
+      liteTerminalAPIClient.browsingContextId =
+        serviceWorkerManager.browsingContextId;
+
+      serviceWorkerManager.registerStdinHandler(
+        'terminal',
+        liteTerminalAPIClient.handleStdin.bind(liteTerminalAPIClient)
+      );
+    } else {
+      console.warn('Service worker is not available for terminals');
     }
   }
 };
 
-export default [terminalManagerPlugin, browsingContextIdSetter];
+export default [
+  terminalClientPlugin,
+  terminalManagerPlugin,
+  terminalServiceWorkerPlugin
+];