@jupyterlite/terminal 0.1.6 → 0.2.0-a0

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.IManager> | JupyterFrontEndPlugin<void>)[];
 export default _default;

package/lib/index.js

@@ -1,61 +1,39 @@
 // Copyright (c) Jupyter Development Team.
 // Distributed under the terms of the Modified BSD License.
-import { TerminalManager } from './manager';
-import { ITerminalManager } from './tokens';
+import { ITerminalManager } from '@jupyterlab/services';
+import { IServiceWorkerManager } from '@jupyterlite/server';
+import { isILiteTerminalManager, LiteTerminalManager } from './manager';
 /**
- * The terminals service plugin.
+ * The terminal manager plugin, replacing the JupyterLab terminal manager.
  */
-const terminalsPlugin = {
+const terminalManagerPlugin = {
     id: '@jupyterlite/terminal:plugin',
-    description: 'A terminal for JupyterLite',
+    description: 'A JupyterLite extension providing a custom terminal manager',
     autoStart: true,
     provides: ITerminalManager,
-    activate: async (app) => {
+    activate: (_) => {
         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);
+        return new LiteTerminalManager();
     }
 };
 /**
- * A plugin providing the routes for the terminals service
+ * A plugin that sets the browsingContextId of the terminal manager.
  */
-const terminalsRoutesPlugin = {
-    id: '@jupyterlite/terminal:routes-plugin',
+const browsingContextIdSetter = {
+    id: '@jupyterlite/terminal:browsing-context-id',
     autoStart: true,
+    optional: [IServiceWorkerManager],
     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);
+    activate: (_, terminalManager, serviceWorkerManager) => {
+        if (serviceWorkerManager !== undefined) {
+            if (isILiteTerminalManager(terminalManager)) {
+                const { browsingContextId } = serviceWorkerManager;
+                terminalManager.browsingContextId = browsingContextId;
             }
             else {
-                const msg = `The terminal session "${name}"" does not exist`;
-                console.warn(msg);
+                console.warn('Terminal manager does not support setting browsingContextId');
             }
-            return new Response(null, { status: exists ? 204 : 404 });
-        });
+        }
     }
 };
-export default [terminalsPlugin, terminalsRoutesPlugin];
+export default [terminalManagerPlugin, browsingContextIdSetter];

package/lib/manager.d.ts

@@ -1,32 +1,93 @@
-import { TerminalAPI } from '@jupyterlab/services';
-import { ITerminalManager } from './tokens';
+import { BaseManager, Terminal, TerminalManager } from '@jupyterlab/services';
+import { ISignal } from '@lumino/signaling';
 /**
- * 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.
+ * Interface for Lite terminal manager, supports setting browserContextId.
  */
-export declare class TerminalManager implements ITerminalManager {
+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>;
     /**
-     * Construct a new TerminalManager object.
+     * Create an iterator over the most recent running terminals.
+     *
+     * @returns A new iterator over the running terminals.
      */
-    constructor(wsUrl: string);
+    running(): IterableIterator<Terminal.IModel>;
     /**
-     * Return whether the named terminal exists.
+     * A signal emitted when the running terminals change.
      */
-    has(name: string): boolean;
+    get runningChanged(): ISignal<this, Terminal.IModel[]>;
     /**
-     * List the running terminals.
+     * Shut down a terminal session by name.
      */
-    listRunning(): Promise<TerminalAPI.IModel[]>;
+    shutdown(name: string): Promise<void>;
     /**
-     * Shutdown a terminal by name.
+     * Shut down all terminal sessions.
+     *
+     * @returns A promise that resolves when all of the sessions are shut down.
      */
-    shutdownTerminal(name: string): Promise<void>;
+    shutdownAll(): Promise<void>;
     /**
-     * Start a new kernel.
+     * 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(): Promise<TerminalAPI.IModel>;
+    startNew(options: Terminal.ITerminal.IOptions): Promise<Terminal.ITerminalConnection>;
+    private get _models();
     private _nextAvailableName;
-    private _wsUrl;
-    private _terminals;
+    private _browsingContextId?;
+    private _connectionFailure;
+    private _isReady;
+    private _ready;
+    private _runningChanged;
+    private _terminalConnections;
 }
+export {};

package/lib/manager.js

@@ -1,65 +1,165 @@
-// Copyright (c) Jupyter Development Team.
-// Distributed under the terms of the Modified BSD License.
-import { PageConfig } from '@jupyterlab/coreutils';
-import { Terminal } from './terminal';
+import { BaseManager } from '@jupyterlab/services';
+import { Signal } from '@lumino/signaling';
+import { LiteTerminalConnection } 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.
+ * Type guard for ILiteTerminalManager.
  */
-export class TerminalManager {
+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;
+    }
     /**
-     * Construct a new TerminalManager object.
+     * Whether the terminal service is available.
      */
-    constructor(wsUrl) {
-        this._terminals = new Map();
-        this._wsUrl = wsUrl;
-        console.log('==> TerminalManager.constructor', this._wsUrl);
+    isAvailable() {
+        return true;
     }
     /**
-     * Return whether the named terminal exists.
+     * Test whether the manager is ready.
      */
-    has(name) {
-        return this._terminals.has(name);
+    get isReady() {
+        return this._isReady;
     }
     /**
-     * List the running terminals.
+     * A promise that fulfills when the manager is ready.
      */
-    async listRunning() {
-        const ret = [...this._terminals.values()].map(terminal => ({
-            name: terminal.name
-        }));
-        return ret;
+    get ready() {
+        return this._ready;
     }
     /**
-     * Shutdown a terminal by name.
+     * 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 shutdownTerminal(name) {
-        const terminal = this._terminals.get(name);
+    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) {
-            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 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() {
-        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 };
+    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._terminals.has(name)) {
+            if (!this._terminalConnections.has(name)) {
                 return name;
             }
         }

package/lib/terminal.d.ts

@@ -1,24 +1,88 @@
+import { ServerConnection, Terminal } from '@jupyterlab/services';
 import { ISignal } from '@lumino/signaling';
-import { ITerminal } from './tokens';
-export declare class Terminal implements ITerminal {
-    readonly options: ITerminal.IOptions;
+/**
+ * An implementation of a terminal interface.
+ */
+export declare class LiteTerminalConnection implements Terminal.ITerminalConnection {
     /**
-     * Construct a new Terminal.
+     * 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.
      */
-    constructor(options: ITerminal.IOptions);
-    private _outputCallback;
     dispose(): void;
+    /**
+     * A signal emitted when the session is disposed.
+     */
     get disposed(): ISignal<this, void>;
+    /**
+     * Test whether the session is disposed.
+     */
     get isDisposed(): boolean;
     /**
-     * Get the name of the terminal.
+     * 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;
-    wsConnect(url: string): Promise<void>;
-    private _disposed;
+    /**
+     * 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 _server?;
-    private _socket?;
+    private _disposed;
+    private _name;
+    private _serverSettings;
+    private _connectionStatus;
+    private _connectionStatusChanged;
+    private _messageReceived;
     private _shell;
-    private _running;
+}
+export declare namespace LiteTerminalConnection {
+    interface IOptions extends Terminal.ITerminalConnection.IOptions {
+        /**
+         * The ID of the browsing context where the request originated.
+         */
+        browsingContextId?: string;
+    }
 }