@jupyterlite/terminal 0.2.0-a0 → 0.2.1

package/src/index.ts

@@ -8,52 +8,97 @@ 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';
+
+/**
+ * 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 terminal manager plugin, replacing the JupyterLab terminal manager.
+ * 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
+];
+
+// Export ILiteTerminalAPIClient so that other extensions can register external commands.
+export { ILiteTerminalAPIClient };

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

@@ -0,0 +1,28 @@
+import { Terminal } from '@jupyterlab/services';
+import {
+  IExternalCommand,
+  IStdinReply,
+  IStdinRequest
+} from '@jupyterlite/cockle';
+import { Token } from '@lumino/coreutils';
+
+export const ILiteTerminalAPIClient = new Token<ILiteTerminalAPIClient>(
+  '@jupyterlite/terminal:client'
+);
+
+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/src/worker.ts

@@ -12,17 +12,11 @@ class ShellWorker extends BaseShellWorker {
    * Initialize the DriveFS to mount an external file system, if available.
    */
   protected override initDriveFS(options: IDriveFSOptions): void {
-    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;
@@ -30,7 +24,7 @@ class ShellWorker extends BaseShellWorker {
         FS,
         PATH,
         ERRNO_CODES,
-        baseUrl: driveFsBaseUrl,
+        baseUrl,
         driveName: '',
         mountpoint,
         browsingContextId

package/lib/manager.d.ts

@@ -1,93 +0,0 @@
-import { BaseManager, Terminal, TerminalManager } from '@jupyterlab/services';
-import { ISignal } from '@lumino/signaling';
-/**
- * Interface for Lite terminal manager, supports setting browserContextId.
- */
-interface ILiteTerminalManager extends Terminal.IManager {
-    browsingContextId: string;
-}
-/**
- * Type guard for ILiteTerminalManager.
- */
-export declare function isILiteTerminalManager(obj: Terminal.IManager): obj is ILiteTerminalManager;
-/**
- * A terminal session manager.
- */
-export declare class LiteTerminalManager extends BaseManager implements ILiteTerminalManager {
-    /**
-     * Construct a new terminal manager.
-     */
-    constructor(options?: TerminalManager.IOptions);
-    /**
-     * Set identifier for communicating with service worker.
-     */
-    set browsingContextId(browsingContextId: string);
-    /**
-     * A signal emitted when there is a connection failure.
-     */
-    get connectionFailure(): ISignal<this, Error>;
-    connectTo(options: Omit<Terminal.ITerminalConnection.IOptions, 'serverSettings'>): Terminal.ITerminalConnection;
-    /**
-     * Whether the terminal service is available.
-     */
-    isAvailable(): boolean;
-    /**
-     * Test whether the manager is ready.
-     */
-    get isReady(): boolean;
-    /**
-     * A promise that fulfills when the manager is ready.
-     */
-    get ready(): Promise<void>;
-    /**
-     * Force a refresh of the running terminals.
-     *
-     * @returns A promise that with the list of running terminals.
-     *
-     * #### Notes
-     * This is intended to be called only in response to a user action,
-     * since the manager maintains its internal state.
-     */
-    refreshRunning(): Promise<void>;
-    /**
-     * Create an iterator over the most recent running terminals.
-     *
-     * @returns A new iterator over the running terminals.
-     */
-    running(): IterableIterator<Terminal.IModel>;
-    /**
-     * A signal emitted when the running terminals change.
-     */
-    get runningChanged(): ISignal<this, Terminal.IModel[]>;
-    /**
-     * Shut down a terminal session by name.
-     */
-    shutdown(name: string): Promise<void>;
-    /**
-     * Shut down all terminal sessions.
-     *
-     * @returns A promise that resolves when all of the sessions are shut down.
-     */
-    shutdownAll(): Promise<void>;
-    /**
-     * Create a new terminal session.
-     *
-     * @param options - The options used to create the terminal.
-     *
-     * @returns A promise that resolves with the terminal connection instance.
-     *
-     * #### Notes
-     * The manager `serverSettings` will be used unless overridden in the
-     * options.
-     */
-    startNew(options: Terminal.ITerminal.IOptions): Promise<Terminal.ITerminalConnection>;
-    private get _models();
-    private _nextAvailableName;
-    private _browsingContextId?;
-    private _connectionFailure;
-    private _isReady;
-    private _ready;
-    private _runningChanged;
-    private _terminalConnections;
-}
-export {};

package/lib/manager.js

@@ -1,167 +0,0 @@
-import { BaseManager } from '@jupyterlab/services';
-import { Signal } from '@lumino/signaling';
-import { LiteTerminalConnection } from './terminal';
-/**
- * Type guard for ILiteTerminalManager.
- */
-export function isILiteTerminalManager(obj) {
-    return 'browsingContextId' in obj;
-}
-/**
- * A terminal session manager.
- */
-export class LiteTerminalManager extends BaseManager {
-    /**
-     * Construct a new terminal manager.
-     */
-    constructor(options = {}) {
-        super(options);
-        this._connectionFailure = new Signal(this);
-        this._isReady = false;
-        this._runningChanged = new Signal(this);
-        this._terminalConnections = new Map();
-        // Initialize internal data.
-        this._ready = (async () => {
-            this._isReady = true;
-        })();
-    }
-    /**
-     * Set identifier for communicating with service worker.
-     */
-    set browsingContextId(browsingContextId) {
-        console.log('==> LiteTerminalManager browsingContextId', browsingContextId);
-        this._browsingContextId = browsingContextId;
-    }
-    /**
-     * A signal emitted when there is a connection failure.
-     */
-    get connectionFailure() {
-        return this._connectionFailure;
-    }
-    /*
-     * Connect to a running terminal.
-     *
-     * @param options - The options used to connect to the terminal.
-     *
-     * @returns The new terminal connection instance.
-     *
-     * #### Notes
-     * The manager `serverSettings` will be used.
-     */
-    connectTo(options) {
-        const { model } = options;
-        const { name } = model;
-        console.log('==> LiteTerminalManager.connectTo', name);
-        const { serverSettings } = this;
-        const terminal = new LiteTerminalConnection({
-            browsingContextId: this._browsingContextId,
-            model,
-            serverSettings
-        });
-        terminal.disposed.connect(() => this.shutdown(name));
-        return terminal;
-    }
-    /**
-     * Whether the terminal service is available.
-     */
-    isAvailable() {
-        return true;
-    }
-    /**
-     * Test whether the manager is ready.
-     */
-    get isReady() {
-        return this._isReady;
-    }
-    /**
-     * A promise that fulfills when the manager is ready.
-     */
-    get ready() {
-        return this._ready;
-    }
-    /**
-     * Force a refresh of the running terminals.
-     *
-     * @returns A promise that with the list of running terminals.
-     *
-     * #### Notes
-     * This is intended to be called only in response to a user action,
-     * since the manager maintains its internal state.
-     */
-    async refreshRunning() {
-        this._runningChanged.emit(this._models);
-    }
-    /**
-     * Create an iterator over the most recent running terminals.
-     *
-     * @returns A new iterator over the running terminals.
-     */
-    running() {
-        return this._models[Symbol.iterator]();
-    }
-    /**
-     * A signal emitted when the running terminals change.
-     */
-    get runningChanged() {
-        return this._runningChanged;
-    }
-    /**
-     * Shut down a terminal session by name.
-     */
-    async shutdown(name) {
-        const terminal = this._terminalConnections.get(name);
-        if (terminal !== undefined) {
-            this._terminalConnections.delete(name);
-            terminal.dispose();
-            this.refreshRunning();
-        }
-    }
-    /**
-     * Shut down all terminal sessions.
-     *
-     * @returns A promise that resolves when all of the sessions are shut down.
-     */
-    async shutdownAll() {
-        await Promise.all(this._models.map(model => this.shutdown(model.name)));
-        this.refreshRunning();
-    }
-    /**
-     * Create a new terminal session.
-     *
-     * @param options - The options used to create the terminal.
-     *
-     * @returns A promise that resolves with the terminal connection instance.
-     *
-     * #### Notes
-     * The manager `serverSettings` will be used unless overridden in the
-     * options.
-     */
-    async startNew(options) {
-        var _a;
-        const name = (_a = options.name) !== null && _a !== void 0 ? _a : this._nextAvailableName();
-        const model = { name };
-        const { serverSettings } = this;
-        const terminal = new LiteTerminalConnection({
-            browsingContextId: this._browsingContextId,
-            model,
-            serverSettings
-        });
-        terminal.disposed.connect(() => this.shutdown(name));
-        this._terminalConnections.set(name, terminal);
-        await this.refreshRunning();
-        return terminal;
-    }
-    get _models() {
-        return Array.from(this._terminalConnections, ([name, value]) => {
-            return { name };
-        });
-    }
-    _nextAvailableName() {
-        for (let i = 1;; ++i) {
-            const name = `${i}`;
-            if (!this._terminalConnections.has(name)) {
-                return name;
-            }
-        }
-    }
-}

package/lib/terminal.d.ts

@@ -1,88 +0,0 @@
-import { ServerConnection, Terminal } from '@jupyterlab/services';
-import { ISignal } from '@lumino/signaling';
-/**
- * An implementation of a terminal interface.
- */
-export declare class LiteTerminalConnection implements Terminal.ITerminalConnection {
-    /**
-     * Construct a new terminal session.
-     */
-    constructor(options: LiteTerminalConnection.IOptions);
-    /**
-     * The current connection status of the terminal connection.
-     */
-    get connectionStatus(): Terminal.ConnectionStatus;
-    /**
-     * A signal emitted when the terminal connection status changes.
-     */
-    get connectionStatusChanged(): ISignal<this, Terminal.ConnectionStatus>;
-    /**
-     * Dispose of the resources held by the session.
-     */
-    dispose(): void;
-    /**
-     * A signal emitted when the session is disposed.
-     */
-    get disposed(): ISignal<this, void>;
-    /**
-     * Test whether the session is disposed.
-     */
-    get isDisposed(): boolean;
-    /**
-     * A signal emitted when a message is received from the server.
-     */
-    get messageReceived(): ISignal<Terminal.ITerminalConnection, Terminal.IMessage>;
-    /**
-     * Get the model for the terminal session.
-     */
-    get model(): Terminal.IModel;
-    /**
-     * Get the name of the terminal session.
-     */
-    get name(): string;
-    /**
-     * Reconnect to a terminal.
-     *
-     * #### Notes
-     * This may try multiple times to reconnect to a terminal, and will sever
-     * any existing connection.
-     */
-    reconnect(): Promise<void>;
-    /**
-     * Send a message to the terminal session.
-     *
-     * #### Notes
-     * If the connection is down, the message will be queued for sending when
-     * the connection comes back up.
-     */
-    send(message: Terminal.IMessage): void;
-    /**
-     * The server settings for the session.
-     */
-    get serverSettings(): ServerConnection.ISettings;
-    /**
-     * Shut down the terminal session.
-     */
-    shutdown(): Promise<void>;
-    private _outputCallback;
-    /**
-     * Handle connection status changes.
-     */
-    private _updateConnectionStatus;
-    private _isDisposed;
-    private _disposed;
-    private _name;
-    private _serverSettings;
-    private _connectionStatus;
-    private _connectionStatusChanged;
-    private _messageReceived;
-    private _shell;
-}
-export declare namespace LiteTerminalConnection {
-    interface IOptions extends Terminal.ITerminalConnection.IOptions {
-        /**
-         * The ID of the browsing context where the request originated.
-         */
-        browsingContextId?: string;
-    }
-}

package/lib/terminal.js

@@ -1,147 +0,0 @@
-import { Signal } from '@lumino/signaling';
-import { Shell } from './shell';
-/**
- * An implementation of a terminal interface.
- */
-export class LiteTerminalConnection {
-    /**
-     * Construct a new terminal session.
-     */
-    constructor(options) {
-        this._isDisposed = false;
-        this._disposed = new Signal(this);
-        this._connectionStatus = 'connecting';
-        this._connectionStatusChanged = new Signal(this);
-        this._messageReceived = new Signal(this);
-        this._name = options.model.name;
-        this._serverSettings = options.serverSettings;
-        const { baseUrl } = this._serverSettings;
-        const { browsingContextId } = options;
-        this._shell = new Shell({
-            mountpoint: '/drive',
-            driveFsBaseUrl: baseUrl,
-            wasmBaseUrl: baseUrl + 'extensions/@jupyterlite/terminal/static/wasm/',
-            outputCallback: this._outputCallback.bind(this),
-            browsingContextId
-        });
-        this._shell.disposed.connect(() => this.dispose());
-        this._shell.start().then(() => this._updateConnectionStatus('connected'));
-    }
-    /**
-     * The current connection status of the terminal connection.
-     */
-    get connectionStatus() {
-        return this._connectionStatus;
-    }
-    /**
-     * A signal emitted when the terminal connection status changes.
-     */
-    get connectionStatusChanged() {
-        return this._connectionStatusChanged;
-    }
-    /**
-     * Dispose of the resources held by the session.
-     */
-    dispose() {
-        if (this._isDisposed) {
-            return;
-        }
-        this._isDisposed = true;
-        this._shell.dispose();
-        this._disposed.emit();
-        this._updateConnectionStatus('disconnected');
-        Signal.clearData(this);
-    }
-    /**
-     * A signal emitted when the session is disposed.
-     */
-    get disposed() {
-        return this._disposed;
-    }
-    /**
-     * Test whether the session is disposed.
-     */
-    get isDisposed() {
-        return this._isDisposed;
-    }
-    /**
-     * A signal emitted when a message is received from the server.
-     */
-    get messageReceived() {
-        return this._messageReceived;
-    }
-    /**
-     * Get the model for the terminal session.
-     */
-    get model() {
-        return { name: this._name };
-    }
-    /**
-     * Get the name of the terminal session.
-     */
-    get name() {
-        return this._name;
-    }
-    /**
-     * Reconnect to a terminal.
-     *
-     * #### Notes
-     * This may try multiple times to reconnect to a terminal, and will sever
-     * any existing connection.
-     */
-    async reconnect() {
-        console.log('==> LiteTerminalConnection.reconnect not implemented');
-    }
-    /**
-     * Send a message to the terminal session.
-     *
-     * #### Notes
-     * If the connection is down, the message will be queued for sending when
-     * the connection comes back up.
-     */
-    send(message) {
-        const { content } = message;
-        if (content === undefined) {
-            return;
-        }
-        switch (message.type) {
-            case 'stdin':
-                this._shell.input(content[0]); // async
-                break;
-            case 'set_size': {
-                const rows = content[0];
-                const columns = content[1];
-                this._shell.setSize(rows, columns); // async
-                break;
-            }
-        }
-    }
-    /**
-     * The server settings for the session.
-     */
-    get serverSettings() {
-        return this._serverSettings;
-    }
-    /**
-     * Shut down the terminal session.
-     */
-    async shutdown() {
-        this.dispose();
-    }
-    _outputCallback(text) {
-        // 'stdout' or 'disconnect' as MessageType.
-        // Cockle is not yet using the 'disconnect'.
-        this._messageReceived.emit({ type: 'stdout', content: [text] });
-    }
-    /**
-     * Handle connection status changes.
-     */
-    _updateConnectionStatus(connectionStatus) {
-        if (this._connectionStatus === connectionStatus) {
-            return;
-        }
-        this._connectionStatus = connectionStatus;
-        // Notify others that the connection status changed.
-        this._connectionStatusChanged.emit(connectionStatus);
-    }
-}