@jupyterlite/terminal 0.1.6 → 0.2.0-a0

package/src/manager.ts

@@ -1,82 +1,207 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
+import { BaseManager, Terminal, TerminalManager } from '@jupyterlab/services';
+import { ISignal, Signal } from '@lumino/signaling';
+import { LiteTerminalConnection } from './terminal';
 
-import { PageConfig } from '@jupyterlab/coreutils';
-import { TerminalAPI } from '@jupyterlab/services';
+/**
+ * Interface for Lite terminal manager, supports setting browserContextId.
+ */
+interface ILiteTerminalManager extends Terminal.IManager {
+  browsingContextId: string;
+}
 
-import { Terminal } from './terminal';
-import { ITerminalManager } from './tokens';
+/**
+ * Type guard for ILiteTerminalManager.
+ */
+export function isILiteTerminalManager(
+  obj: Terminal.IManager
+): obj is ILiteTerminalManager {
+  return 'browsingContextId' in obj;
+}
 
 /**
- * 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.
+ * A terminal session manager.
  */
-export class TerminalManager implements ITerminalManager {
+export class LiteTerminalManager
+  extends BaseManager
+  implements ILiteTerminalManager
+{
+  /**
+   * Construct a new terminal manager.
+   */
+  constructor(options: TerminalManager.IOptions = {}) {
+    super(options);
+
+    // Initialize internal data.
+    this._ready = (async () => {
+      this._isReady = true;
+    })();
+  }
+
+  /**
+   * Set identifier for communicating with service worker.
+   */
+  set browsingContextId(browsingContextId: string) {
+    console.log('==> LiteTerminalManager browsingContextId', browsingContextId);
+    this._browsingContextId = browsingContextId;
+  }
+
   /**
-   * Construct a new TerminalManager object.
+   * A signal emitted when there is a connection failure.
    */
-  constructor(wsUrl: string) {
-    this._wsUrl = wsUrl;
-    console.log('==> TerminalManager.constructor', this._wsUrl);
+  get connectionFailure(): ISignal<this, Error> {
+    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: Omit<Terminal.ITerminalConnection.IOptions, 'serverSettings'>
+  ): Terminal.ITerminalConnection {
+    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;
   }
 
   /**
-   * Return whether the named terminal exists.
+   * Whether the terminal service is available.
    */
-  has(name: string): boolean {
-    return this._terminals.has(name);
+  isAvailable(): boolean {
+    return true;
   }
 
   /**
-   * List the running terminals.
+   * Test whether the manager is ready.
    */
-  async listRunning(): Promise<TerminalAPI.IModel[]> {
-    const ret = [...this._terminals.values()].map(terminal => ({
-      name: terminal.name
-    }));
-    return ret;
+  get isReady(): boolean {
+    return this._isReady;
   }
 
   /**
-   * Shutdown a terminal by name.
+   * A promise that fulfills when the manager is ready.
    */
-  async shutdownTerminal(name: string): Promise<void> {
-    const terminal = this._terminals.get(name);
+  get ready(): Promise<void> {
+    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(): Promise<void> {
+    this._runningChanged.emit(this._models);
+  }
+
+  /**
+   * Create an iterator over the most recent running terminals.
+   *
+   * @returns A new iterator over the running terminals.
+   */
+  running(): IterableIterator<Terminal.IModel> {
+    return this._models[Symbol.iterator]();
+  }
+
+  /**
+   * A signal emitted when the running terminals change.
+   */
+  get runningChanged(): ISignal<this, Terminal.IModel[]> {
+    return this._runningChanged;
+  }
+
+  /**
+   * Shut down a terminal session by name.
+   */
+  async shutdown(name: string): Promise<void> {
+    const terminal = this._terminalConnections.get(name);
     if (terminal !== undefined) {
-      console.log('==> TerminalManager.shutdownTerminal', name);
-      this._terminals.delete(name);
+      this._terminalConnections.delete(name);
       terminal.dispose();
+      this.refreshRunning();
     }
   }
 
   /**
-   * Start a new kernel.
+   * Shut down all terminal sessions.
+   *
+   * @returns A promise that resolves when all of the sessions are shut down.
    */
-  async startNew(): Promise<TerminalAPI.IModel> {
-    const name = this._nextAvailableName();
-    console.log('==> TerminalManager.startNew', name);
-    const baseUrl = PageConfig.getBaseUrl();
-    const terminal = new Terminal({ name, baseUrl });
-    this._terminals.set(name, terminal);
+  async shutdownAll(): Promise<void> {
+    await Promise.all(this._models.map(model => this.shutdown(model.name)));
+    this.refreshRunning();
+  }
 
-    terminal.disposed.connect(() => this.shutdownTerminal(name));
+  /**
+   * 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: Terminal.ITerminal.IOptions
+  ): Promise<Terminal.ITerminalConnection> {
+    const name = options.name ?? this._nextAvailableName();
+    const model: Terminal.IModel = { name };
+    const { serverSettings } = this;
 
-    const url = `${this._wsUrl}terminals/websocket/${name}`;
-    await terminal.wsConnect(url);
+    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;
+  }
 
-    return { name };
+  private get _models(): Terminal.IModel[] {
+    return Array.from(this._terminalConnections, ([name, value]) => {
+      return { name };
+    });
   }
 
   private _nextAvailableName(): string {
     for (let i = 1; ; ++i) {
       const name = `${i}`;
-      if (!this._terminals.has(name)) {
+      if (!this._terminalConnections.has(name)) {
         return name;
       }
     }
   }
 
-  private _wsUrl: string;
-  private _terminals: Map<string, Terminal> = new Map();
+  private _browsingContextId?: string;
+  private _connectionFailure = new Signal<this, Error>(this);
+  private _isReady = false;
+  private _ready: Promise<void>;
+  private _runningChanged = new Signal<this, Terminal.IModel[]>(this);
+  private _terminalConnections = new Map<
+    string,
+    Terminal.ITerminalConnection
+  >();
 }

package/src/terminal.ts

@@ -1,131 +1,195 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
-
-import { IShell } from '@jupyterlite/cockle';
-import { JSONPrimitive } from '@lumino/coreutils';
+import { ServerConnection, Terminal } from '@jupyterlab/services';
 import { ISignal, Signal } from '@lumino/signaling';
-
-import {
-  Server as WebSocketServer,
-  Client as WebSocketClient
-} from 'mock-socket';
-
 import { Shell } from './shell';
-import { ITerminal } from './tokens';
+import { IShell } from '@jupyterlite/cockle';
 
-export class Terminal implements ITerminal {
+/**
+ * An implementation of a terminal interface.
+ */
+export class LiteTerminalConnection implements Terminal.ITerminalConnection {
   /**
-   * Construct a new Terminal.
+   * Construct a new terminal session.
    */
-  constructor(readonly options: ITerminal.IOptions) {
+  constructor(options: LiteTerminalConnection.IOptions) {
+    this._name = options.model.name;
+    this._serverSettings = options.serverSettings!;
+    const { baseUrl } = this._serverSettings;
+    const { browsingContextId } = options;
+
     this._shell = new Shell({
       mountpoint: '/drive',
-      driveFsBaseUrl: options.baseUrl,
-      wasmBaseUrl:
-        options.baseUrl + 'extensions/@jupyterlite/terminal/static/wasm/',
-      outputCallback: this._outputCallback.bind(this)
+      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'));
   }
 
-  private _outputCallback(text: string): void {
-    if (this._socket) {
-      const ret = JSON.stringify(['stdout', text]);
-      this._socket.send(ret);
-    }
+  /**
+   * The current connection status of the terminal connection.
+   */
+  get connectionStatus(): Terminal.ConnectionStatus {
+    return this._connectionStatus;
+  }
+
+  /**
+   * A signal emitted when the terminal connection status changes.
+   */
+  get connectionStatusChanged(): ISignal<this, Terminal.ConnectionStatus> {
+    return this._connectionStatusChanged;
   }
 
+  /**
+   * Dispose of the resources held by the session.
+   */
   dispose(): void {
     if (this._isDisposed) {
       return;
     }
 
-    console.log('Terminal.dispose');
     this._isDisposed = true;
-
-    if (this._socket !== undefined) {
-      // Disconnect from frontend.
-      this._socket.send(JSON.stringify(['disconnect']));
-      this._socket.close();
-      this._socket = undefined;
-    }
-
-    if (this._server !== undefined) {
-      this._server.close();
-      this._server = undefined;
-    }
-
     this._shell.dispose();
     this._disposed.emit();
+
+    this._updateConnectionStatus('disconnected');
+
+    Signal.clearData(this);
   }
 
+  /**
+   * A signal emitted when the session is disposed.
+   */
   get disposed(): ISignal<this, void> {
     return this._disposed;
   }
 
+  /**
+   * Test whether the session is disposed.
+   */
   get isDisposed(): boolean {
     return this._isDisposed;
   }
 
   /**
-   * Get the name of the terminal.
+   * A signal emitted when a message is received from the server.
+   */
+  get messageReceived(): ISignal<
+    Terminal.ITerminalConnection,
+    Terminal.IMessage
+  > {
+    return this._messageReceived;
+  }
+
+  /**
+   * Get the model for the terminal session.
+   */
+  get model(): Terminal.IModel {
+    return { name: this._name };
+  }
+
+  /**
+   * Get the name of the terminal session.
    */
   get name(): string {
-    return this.options.name;
+    return this._name;
   }
 
-  async wsConnect(url: string) {
-    console.log('Terminal wsConnect', url);
-    this._server = new WebSocketServer(url);
+  /**
+   * Reconnect to a terminal.
+   *
+   * #### Notes
+   * This may try multiple times to reconnect to a terminal, and will sever
+   * any existing connection.
+   */
+  async reconnect(): Promise<void> {
+    console.log('==> LiteTerminalConnection.reconnect not implemented');
+  }
 
-    this._server.on('connection', async (socket: WebSocketClient) => {
-      console.log('Terminal server connection');
-      if (this._socket !== undefined) {
-        this._socket.send(JSON.stringify(['disconnect']));
-        this._socket.close();
-        this._socket = undefined;
-      }
-      this._socket = socket;
-
-      socket.on('message', async (message: any) => {
-        const data = JSON.parse(message) as JSONPrimitive[];
-        //console.log('==> socket message', data);
-        const message_type = data[0];
-        const content = data.slice(1);
-
-        if (message_type === 'stdin') {
-          await this._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 this._shell.setSize(rows, columns);
-        }
-      });
-
-      socket.on('close', () => {
-        console.log('Terminal socket close');
-      });
-
-      socket.on('error', () => {
-        console.log('Terminal socket error');
-      });
-
-      // Return handshake.
-      const res = JSON.stringify(['setup']);
-      console.log('Terminal returning handshake via socket');
-      socket.send(res);
-
-      if (!this._running) {
-        this._running = true;
-        await this._shell.start();
+  /**
+   * 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 {
+    const { content } = message;
+    if (content === undefined) {
+      return;
+    }
+
+    switch (message.type) {
+      case 'stdin':
+        this._shell.input(content[0] as string); // async
+        break;
+      case 'set_size': {
+        const rows = content[0] as number;
+        const columns = content[1] as number;
+        this._shell.setSize(rows, columns); // async
+        break;
       }
-    });
+    }
+  }
+
+  /**
+   * The server settings for the session.
+   */
+  get serverSettings(): ServerConnection.ISettings {
+    return this._serverSettings;
+  }
+
+  /**
+   * Shut down the terminal session.
+   */
+  async shutdown(): Promise<void> {
+    this.dispose();
+  }
+
+  private _outputCallback(text: string): void {
+    // 'stdout' or 'disconnect' as MessageType.
+    // Cockle is not yet using the 'disconnect'.
+    this._messageReceived.emit({ type: 'stdout', content: [text] });
+  }
+
+  /**
+   * Handle connection status changes.
+   */
+  private _updateConnectionStatus(
+    connectionStatus: Terminal.ConnectionStatus
+  ): void {
+    if (this._connectionStatus === connectionStatus) {
+      return;
+    }
+
+    this._connectionStatus = connectionStatus;
+
+    // Notify others that the connection status changed.
+    this._connectionStatusChanged.emit(connectionStatus);
   }
 
-  private _disposed = new Signal<this, void>(this);
   private _isDisposed = false;
-  private _server?: WebSocketServer;
-  private _socket?: WebSocketClient;
+  private _disposed = new Signal<this, void>(this);
+
+  private _name: string;
+  private _serverSettings: ServerConnection.ISettings;
+  private _connectionStatus: Terminal.ConnectionStatus = 'connecting';
+  private _connectionStatusChanged = new Signal<
+    this,
+    Terminal.ConnectionStatus
+  >(this);
+  private _messageReceived = new Signal<this, Terminal.IMessage>(this);
+
   private _shell: IShell;
-  private _running = false;
+}
+
+export namespace LiteTerminalConnection {
+  export interface IOptions extends Terminal.ITerminalConnection.IOptions {
+    /**
+     * The ID of the browsing context where the request originated.
+     */
+    browsingContextId?: string;
+  }
 }

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,37 @@ 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 { browsingContextId, driveFsBaseUrl, fileSystem, mountpoint } =
+      options;
+    console.log(
+      'Terminal initDriveFS',
+      driveFsBaseUrl,
+      mountpoint,
+      browsingContextId
+    );
+    if (
+      mountpoint !== '' &&
+      driveFsBaseUrl !== undefined &&
+      browsingContextId !== undefined
+    ) {
+      const { FS, ERRNO_CODES, PATH } = fileSystem;
+      const driveFS = new DriveFS({
+        FS,
+        PATH,
+        ERRNO_CODES,
+        baseUrl: driveFsBaseUrl,
+        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/tokens.d.ts

@@ -1,52 +0,0 @@
-import { TerminalAPI } from '@jupyterlab/services';
-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 {
-    /**
-     * 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>;
-}
-/**
- * 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;
-    }
-}

package/lib/tokens.js

@@ -1,7 +0,0 @@
-// 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');