@jupyterlite/terminal 0.1.6 → 0.2.0

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

@@ -2,84 +2,100 @@
 // Distributed under the terms of the Modified BSD License.
 
 import {
-  JupyterLiteServer,
-  JupyterLiteServerPlugin,
-  Router
-} from '@jupyterlite/server';
+  JupyterFrontEnd,
+  JupyterFrontEndPlugin
+} from '@jupyterlab/application';
+import {
+  ITerminalManager,
+  ServiceManagerPlugin,
+  Terminal,
+  ServerConnection,
+  IServerSettings,
+  TerminalManager
+} from '@jupyterlab/services';
+import { IServiceWorkerManager } from '@jupyterlite/server';
+
+import { WebSocket } from 'mock-socket';
+
+import { LiteTerminalAPIClient } from './client';
+import { ILiteTerminalAPIClient } from './tokens';
 
-import { TerminalManager } from './manager';
-import { ITerminalManager } from './tokens';
+/**
+ * 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
+        }
+      });
+    }
+  };
 
 /**
- * The terminals service plugin.
+ * Plugin containing manager for in-browser terminals.
  */
-const terminalsPlugin: JupyterLiteServerPlugin<ITerminalManager> = {
-  id: '@jupyterlite/terminal:plugin',
-  description: 'A terminal for JupyterLite',
+const terminalManagerPlugin: ServiceManagerPlugin<Terminal.IManager> = {
+  id: '@jupyterlite/terminal:manager',
+  description: 'A JupyterLite extension providing a custom terminal manager',
   autoStart: true,
   provides: ITerminalManager,
-  activate: async (app: JupyterLiteServer) => {
+  requires: [ILiteTerminalAPIClient],
+  activate: (
+    _: null,
+    terminalAPIClient: Terminal.ITerminalAPIClient
+  ): Terminal.IManager => {
     console.log(
-      'JupyterLite extension @jupyterlite/terminal:plugin is activated!'
+      'JupyterLite extension @jupyterlite/terminal:manager 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);
+    return new TerminalManager({
+      terminalAPIClient,
+      serverSettings: terminalAPIClient.serverSettings
+    });
   }
 };
 
 /**
- * A plugin providing the routes for the terminals service
+ * Plugin that connects in-browser terminals and service worker.
  */
-const terminalsRoutesPlugin: JupyterLiteServerPlugin<void> = {
-  id: '@jupyterlite/terminal:routes-plugin',
+const terminalServiceWorkerPlugin: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlite/terminal:service-worker',
   autoStart: true,
-  requires: [ITerminalManager],
-  activate: (app: JupyterLiteServer, terminalManager: ITerminalManager) => {
-    console.log(
-      'JupyterLite extension @jupyterlite/terminal:routes-plugin is activated!',
-      terminalManager
-    );
+  requires: [ILiteTerminalAPIClient],
+  optional: [IServiceWorkerManager],
+  activate: (
+    _: JupyterFrontEnd,
+    liteTerminalAPIClient: ILiteTerminalAPIClient,
+    serviceWorkerManager?: IServiceWorkerManager
+  ): void => {
+    if (serviceWorkerManager !== undefined) {
+      liteTerminalAPIClient.browsingContextId =
+        serviceWorkerManager.browsingContextId;
 
-    // GET /api/terminals - List the running terminals
-    app.router.get('/api/terminals', async (req: Router.IRequest) => {
-      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: Router.IRequest) => {
-      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: Router.IRequest, name: string) => {
-        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 });
-      }
-    );
+      serviceWorkerManager.registerStdinHandler(
+        'terminal',
+        liteTerminalAPIClient.handleStdin.bind(liteTerminalAPIClient)
+      );
+    } else {
+      console.warn('Service worker is not available for terminals');
+    }
   }
 };
 
-export default [terminalsPlugin, terminalsRoutesPlugin];
+export default [
+  terminalClientPlugin,
+  terminalManagerPlugin,
+  terminalServiceWorkerPlugin
+];

package/src/shell.ts

@@ -1,5 +1,7 @@
 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.
  */
@@ -22,4 +24,6 @@ export class Shell extends BaseShell {
       type: 'module'
     });
   }
+
+  socket?: WebSocketClient;
 }

package/src/tokens.ts

@@ -1,66 +1,28 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
-
-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 const ITerminalManager = new Token<ITerminalManager>(
-  '@jupyterlite/terminal:ITerminalManager'
+export const ILiteTerminalAPIClient = new Token<ILiteTerminalAPIClient>(
+  '@jupyterlite/terminal:client'
 );
 
-/**
- * An interface for the TerminalManager service.
- */
-export interface ITerminalManager {
-  /**
-   * Return whether the named terminal exists.
-   */
-  has(name: string): boolean;
-
-  /**
-   * List the running terminals.
-   */
-  listRunning: () => Promise<TerminalAPI.IModel[]>;
-
+export interface ILiteTerminalAPIClient extends Terminal.ITerminalAPIClient {
   /**
-   * Shutdown a terminal by name.
+   * Identifier for communicating with service worker.
    */
-  shutdownTerminal: (name: string) => Promise<void>;
+  browsingContextId: string;
 
   /**
-   * Start a new kernel.
+   * Function that handles stdin requests received from service worker.
    */
-  startNew: () => Promise<TerminalAPI.IModel>;
-}
+  handleStdin(request: IStdinRequest): Promise<IStdinReply>;
 
-/**
- * An interface for a server-side terminal running in the browser.
- */
-export interface ITerminal extends IObservableDisposable {
   /**
-   * The name of the server-side terminal.
+   * Register an external command that will be available in all terminals.
    */
-  readonly name: string;
-}
-
-/**
- * A namespace for ITerminal statics.
- */
-export namespace ITerminal {
-  /**
-   * The instantiation options for an ITerminal.
-   */
-  export interface IOptions {
-    /**
-     * The name of the terminal.
-     */
-    name: string;
-
-    baseUrl: string;
-  }
+  registerExternalCommand(options: IExternalCommand.IOptions): void;
 }

package/src/worker.ts

@@ -1,26 +1,7 @@
 import { expose } from 'comlink';
 
-import { BaseShellWorker, IFileSystem } from '@jupyterlite/cockle';
-import {
-  ContentsAPI,
-  DriveFS,
-  ServiceWorkerContentsAPI
-} from '@jupyterlite/contents';
-
-/**
- * Custom DriveFS implementation using the service worker.
- */
-class MyDriveFS extends DriveFS {
-  createAPI(options: DriveFS.IOptions): ContentsAPI {
-    return new ServiceWorkerContentsAPI(
-      options.baseUrl,
-      options.driveName,
-      options.mountpoint,
-      options.FS,
-      options.ERRNO_CODES
-    );
-  }
-}
+import { BaseShellWorker, IDriveFSOptions } from '@jupyterlite/cockle';
+import { DriveFS } from '@jupyterlite/contents';
 
 /**
  * Shell web worker that uses DriveFS via service worker.
@@ -28,24 +9,31 @@ class MyDriveFS extends DriveFS {
  */
 class ShellWorker extends BaseShellWorker {
   /**
-   * Initialize the DriveFS to mount an external file system.
+   * Initialize the DriveFS to mount an external file system, if available.
    */
-  protected override initDriveFS(
-    driveFsBaseUrl: string,
-    mountpoint: string,
-    fileSystem: IFileSystem
-  ): void {
-    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);
+  protected override initDriveFS(options: IDriveFSOptions): void {
+    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');
+    }
   }
 }
 

package/lib/manager.d.ts

@@ -1,32 +0,0 @@
-import { TerminalAPI } from '@jupyterlab/services';
-import { ITerminalManager } from './tokens';
-/**
- * A class to handle requests to /api/terminals.
- * Although this looks similar to a JupyterLab TerminalManager, it is really a class that
- * implements the terminal REST API.
- */
-export declare class TerminalManager implements ITerminalManager {
-    /**
-     * Construct a new TerminalManager object.
-     */
-    constructor(wsUrl: string);
-    /**
-     * Return whether the named terminal exists.
-     */
-    has(name: string): boolean;
-    /**
-     * List the running terminals.
-     */
-    listRunning(): Promise<TerminalAPI.IModel[]>;
-    /**
-     * Shutdown a terminal by name.
-     */
-    shutdownTerminal(name: string): Promise<void>;
-    /**
-     * Start a new kernel.
-     */
-    startNew(): Promise<TerminalAPI.IModel>;
-    private _nextAvailableName;
-    private _wsUrl;
-    private _terminals;
-}

package/lib/manager.js

@@ -1,67 +0,0 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
-import { PageConfig } from '@jupyterlab/coreutils';
-import { Terminal } from './terminal';
-/**
- * A class to handle requests to /api/terminals.
- * Although this looks similar to a JupyterLab TerminalManager, it is really a class that
- * implements the terminal REST API.
- */
-export class TerminalManager {
-    /**
-     * Construct a new TerminalManager object.
-     */
-    constructor(wsUrl) {
-        this._terminals = new Map();
-        this._wsUrl = wsUrl;
-        console.log('==> TerminalManager.constructor', this._wsUrl);
-    }
-    /**
-     * Return whether the named terminal exists.
-     */
-    has(name) {
-        return this._terminals.has(name);
-    }
-    /**
-     * List the running terminals.
-     */
-    async listRunning() {
-        const ret = [...this._terminals.values()].map(terminal => ({
-            name: terminal.name
-        }));
-        return ret;
-    }
-    /**
-     * Shutdown a terminal by name.
-     */
-    async shutdownTerminal(name) {
-        const terminal = this._terminals.get(name);
-        if (terminal !== undefined) {
-            console.log('==> TerminalManager.shutdownTerminal', name);
-            this._terminals.delete(name);
-            terminal.dispose();
-        }
-    }
-    /**
-     * Start a new kernel.
-     */
-    async startNew() {
-        const name = this._nextAvailableName();
-        console.log('==> TerminalManager.startNew', name);
-        const baseUrl = PageConfig.getBaseUrl();
-        const terminal = new Terminal({ name, baseUrl });
-        this._terminals.set(name, terminal);
-        terminal.disposed.connect(() => this.shutdownTerminal(name));
-        const url = `${this._wsUrl}terminals/websocket/${name}`;
-        await terminal.wsConnect(url);
-        return { name };
-    }
-    _nextAvailableName() {
-        for (let i = 1;; ++i) {
-            const name = `${i}`;
-            if (!this._terminals.has(name)) {
-                return name;
-            }
-        }
-    }
-}

package/lib/terminal.d.ts

@@ -1,24 +0,0 @@
-import { ISignal } from '@lumino/signaling';
-import { ITerminal } from './tokens';
-export declare class Terminal implements ITerminal {
-    readonly options: ITerminal.IOptions;
-    /**
-     * Construct a new Terminal.
-     */
-    constructor(options: ITerminal.IOptions);
-    private _outputCallback;
-    dispose(): void;
-    get disposed(): ISignal<this, void>;
-    get isDisposed(): boolean;
-    /**
-     * Get the name of the terminal.
-     */
-    get name(): string;
-    wsConnect(url: string): Promise<void>;
-    private _disposed;
-    private _isDisposed;
-    private _server?;
-    private _socket?;
-    private _shell;
-    private _running;
-}