@jupyterlite/terminal 0.1.6 → 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 { JupyterLiteServerPlugin } from '@jupyterlite/server';
-import { ITerminalManager } from './tokens';
-declare const _default: (JupyterLiteServerPlugin<ITerminalManager> | JupyterLiteServerPlugin<void>)[];
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { ServiceManagerPlugin, Terminal } from '@jupyterlab/services';
+declare const _default: (ServiceManagerPlugin<Terminal.ITerminalAPIClient> | ServiceManagerPlugin<Terminal.IManager> | JupyterFrontEndPlugin<void>)[];
 export default _default;

package/lib/index.js

@@ -1,61 +1,67 @@
 // Copyright (c) Jupyter Development Team.
 // Distributed under the terms of the Modified BSD License.
-import { TerminalManager } from './manager';
-import { ITerminalManager } from './tokens';
+import { ITerminalManager, ServerConnection, IServerSettings, TerminalManager } from '@jupyterlab/services';
+import { IServiceWorkerManager } from '@jupyterlite/server';
+import { WebSocket } from 'mock-socket';
+import { LiteTerminalAPIClient } from './client';
+import { ILiteTerminalAPIClient } from './tokens';
 /**
- * The terminals service plugin.
+ * Plugin containing client for in-browser terminals.
  */
-const terminalsPlugin = {
-    id: '@jupyterlite/terminal:plugin',
-    description: 'A terminal for JupyterLite',
+const terminalClientPlugin = {
+    id: '@jupyterlite/terminal:client',
+    description: 'The client for Lite terminals',
     autoStart: true,
-    provides: ITerminalManager,
-    activate: async (app) => {
-        console.log('JupyterLite extension @jupyterlite/terminal:plugin is activated!');
-        const { serviceManager } = app;
-        const { serverSettings, terminals } = serviceManager;
-        console.log('terminals available:', terminals.isAvailable());
-        console.log('terminals ready:', terminals.isReady); // Not ready
-        console.log('terminals active:', terminals.isActive);
-        // Not sure this is necessary?
-        await terminals.ready;
-        console.log('terminals ready after await:', terminals.isReady); // Ready
-        return new TerminalManager(serverSettings.wsUrl);
+    provides: ILiteTerminalAPIClient,
+    optional: [IServerSettings],
+    activate: (_, serverSettings) => {
+        return new LiteTerminalAPIClient({
+            serverSettings: {
+                ...ServerConnection.makeSettings(),
+                ...serverSettings,
+                WebSocket
+            }
+        });
     }
 };
 /**
- * A plugin providing the routes for the terminals service
+ * Plugin containing manager for in-browser terminals.
  */
-const terminalsRoutesPlugin = {
-    id: '@jupyterlite/terminal:routes-plugin',
+const terminalManagerPlugin = {
+    id: '@jupyterlite/terminal:manager',
+    description: 'A JupyterLite extension providing a custom terminal manager',
     autoStart: true,
-    requires: [ITerminalManager],
-    activate: (app, terminalManager) => {
-        console.log('JupyterLite extension @jupyterlite/terminal:routes-plugin is activated!', terminalManager);
-        // GET /api/terminals - List the running terminals
-        app.router.get('/api/terminals', async (req) => {
-            const res = await terminalManager.listRunning();
-            // Should return last_activity for each too,
-            return new Response(JSON.stringify(res));
-        });
-        // POST /api/terminals - Start a terminal
-        app.router.post('/api/terminals', async (req) => {
-            const res = await terminalManager.startNew();
-            // Should return last_activity too.
-            return new Response(JSON.stringify(res));
-        });
-        // DELETE /api/terminals/{terminal name} - Delete a terminal
-        app.router.delete('/api/terminals/(.+)', async (req, name) => {
-            const exists = terminalManager.has(name);
-            if (exists) {
-                await terminalManager.shutdownTerminal(name);
-            }
-            else {
-                const msg = `The terminal session "${name}"" does not exist`;
-                console.warn(msg);
-            }
-            return new Response(null, { status: exists ? 204 : 404 });
+    provides: ITerminalManager,
+    requires: [ILiteTerminalAPIClient],
+    activate: (_, terminalAPIClient) => {
+        console.log('JupyterLite extension @jupyterlite/terminal:manager activated');
+        return new TerminalManager({
+            terminalAPIClient,
+            serverSettings: terminalAPIClient.serverSettings
         });
     }
 };
-export default [terminalsPlugin, terminalsRoutesPlugin];
+/**
+ * Plugin that connects in-browser terminals and service worker.
+ */
+const terminalServiceWorkerPlugin = {
+    id: '@jupyterlite/terminal:service-worker',
+    autoStart: true,
+    requires: [ILiteTerminalAPIClient],
+    optional: [IServiceWorkerManager],
+    activate: (_, liteTerminalAPIClient, serviceWorkerManager) => {
+        if (serviceWorkerManager !== undefined) {
+            liteTerminalAPIClient.browsingContextId =
+                serviceWorkerManager.browsingContextId;
+            serviceWorkerManager.registerStdinHandler('terminal', liteTerminalAPIClient.handleStdin.bind(liteTerminalAPIClient));
+        }
+        else {
+            console.warn('Service worker is not available for terminals');
+        }
+    }
+};
+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

@@ -1,52 +1,18 @@
-import { TerminalAPI } from '@jupyterlab/services';
+import { Terminal } from '@jupyterlab/services';
+import { IExternalCommand, IStdinReply, IStdinRequest } from '@jupyterlite/cockle';
 import { Token } from '@lumino/coreutils';
-import { IObservableDisposable } from '@lumino/disposable';
-/**
- * The token for the Terminals service.
- */
-export declare const ITerminalManager: Token<ITerminalManager>;
-/**
- * An interface for the TerminalManager service.
- */
-export interface ITerminalManager {
+export declare const ILiteTerminalAPIClient: Token<ILiteTerminalAPIClient>;
+export interface ILiteTerminalAPIClient extends Terminal.ITerminalAPIClient {
     /**
-     * Return whether the named terminal exists.
+     * Identifier for communicating with service worker.
      */
-    has(name: string): boolean;
+    browsingContextId: string;
     /**
-     * List the running terminals.
+     * Function that handles stdin requests received from service worker.
      */
-    listRunning: () => Promise<TerminalAPI.IModel[]>;
+    handleStdin(request: IStdinRequest): Promise<IStdinReply>;
     /**
-     * Shutdown a terminal by name.
+     * Register an external command that will be available in all terminals.
      */
-    shutdownTerminal: (name: string) => Promise<void>;
-    /**
-     * Start a new kernel.
-     */
-    startNew: () => Promise<TerminalAPI.IModel>;
-}
-/**
- * An interface for a server-side terminal running in the browser.
- */
-export interface ITerminal extends IObservableDisposable {
-    /**
-     * The name of the server-side terminal.
-     */
-    readonly name: string;
-}
-/**
- * A namespace for ITerminal statics.
- */
-export declare namespace ITerminal {
-    /**
-     * The instantiation options for an ITerminal.
-     */
-    interface IOptions {
-        /**
-         * The name of the terminal.
-         */
-        name: string;
-        baseUrl: string;
-    }
+    registerExternalCommand(options: IExternalCommand.IOptions): void;
 }

package/lib/tokens.js

@@ -1,7 +1,2 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
 import { Token } from '@lumino/coreutils';
-/**
- * The token for the Terminals service.
- */
-export const ITerminalManager = new Token('@jupyterlite/terminal:ITerminalManager');
+export const ILiteTerminalAPIClient = new Token('@jupyterlite/terminal:client');

package/lib/worker.js

@@ -1,34 +1,36 @@
 import { expose } from 'comlink';
 import { BaseShellWorker } from '@jupyterlite/cockle';
-import { DriveFS, ServiceWorkerContentsAPI } from '@jupyterlite/contents';
-/**
- * Custom DriveFS implementation using the service worker.
- */
-class MyDriveFS extends DriveFS {
-    createAPI(options) {
-        return new ServiceWorkerContentsAPI(options.baseUrl, options.driveName, options.mountpoint, options.FS, options.ERRNO_CODES);
-    }
-}
+import { DriveFS } from '@jupyterlite/contents';
 /**
  * Shell web worker that uses DriveFS via service worker.
  * Note that this is not exported as it is accessed from Shell via the filename.
  */
 class ShellWorker extends BaseShellWorker {
     /**
-     * Initialize the DriveFS to mount an external file system.
+     * Initialize the DriveFS to mount an external file system, if available.
      */
-    initDriveFS(driveFsBaseUrl, mountpoint, fileSystem) {
-        console.log('Terminal initDriveFS', driveFsBaseUrl, mountpoint);
-        const { FS, ERRNO_CODES, PATH } = fileSystem;
-        const driveFS = new MyDriveFS({
-            FS,
-            PATH,
-            ERRNO_CODES,
-            baseUrl: driveFsBaseUrl,
-            driveName: '',
-            mountpoint
-        });
-        FS.mount(driveFS, {}, mountpoint);
+    initDriveFS(options) {
+        const { baseUrl, browsingContextId, fileSystem, mountpoint } = options;
+        console.log('Terminal initDriveFS', baseUrl, mountpoint, browsingContextId);
+        if (mountpoint !== '' &&
+            baseUrl !== undefined &&
+            browsingContextId !== undefined) {
+            const { FS, ERRNO_CODES, PATH } = fileSystem;
+            const driveFS = new DriveFS({
+                FS,
+                PATH,
+                ERRNO_CODES,
+                baseUrl,
+                driveName: '',
+                mountpoint,
+                browsingContextId
+            });
+            FS.mount(driveFS, {}, mountpoint);
+            console.log('Terminal connected to shared drive');
+        }
+        else {
+            console.warn('Terminal not connected to shared drive');
+        }
     }
 }
 const worker = new ShellWorker();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyterlite/terminal",
-    "version": "0.1.6",
+    "version": "0.2.0",
     "description": "A terminal for JupyterLite",
     "keywords": [
         "jupyter",
@@ -59,19 +59,17 @@
         "watch:labextension": "jupyter labextension watch ."
     },
     "dependencies": {
-        "@jupyterlab/coreutils": "^6.3.5",
-        "@jupyterlab/services": "^7.3.5",
-        "@jupyterlab/terminal": "^4.3.5",
-        "@jupyterlab/terminal-extension": "^4.3.5",
-        "@jupyterlite/cockle": "^0.0.16",
-        "@jupyterlite/contents": "^0.5.1",
-        "@jupyterlite/server": "^0.5.1",
+        "@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.3.5",
-        "@jupyterlab/testutils": "^4.3.5",
+        "@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"
@@ -111,9 +112,6 @@
         "extension": true,
         "outputDir": "jupyterlite_terminal/labextension"
     },
-    "jupyterlite": {
-        "liteExtension": true
-    },
     "eslintIgnore": [
         "node_modules",
         "dist",