@difizen/libro-terminal 0.1.0

package/src/connection.ts

@@ -0,0 +1,347 @@
+import type { JSONPrimitive } from '@difizen/libro-common';
+import { URL } from '@difizen/libro-common';
+import type { ISettings } from '@difizen/libro-kernel';
+import type { Disposable, Disposed, Event } from '@difizen/mana-app';
+import { transient } from '@difizen/mana-app';
+import { Deferred } from '@difizen/mana-app';
+import { Emitter } from '@difizen/mana-app';
+import { inject } from '@difizen/mana-app';
+
+import { TerminalOption } from './protocol.js';
+import type {
+  TerminalMessage,
+  TerminalModel,
+  TerminalConnectionStatus,
+  TerminalMessageType,
+} from './protocol.js';
+import { TerminalRestAPI } from './restapi.js';
+
+@transient()
+export class TerminalConnection implements Disposable, Disposed {
+  protected _onDisposed = new Emitter<void>();
+  protected _messageReceived = new Emitter<TerminalMessage>();
+  protected _connectionStatus: TerminalConnectionStatus = 'connecting';
+  protected _connectionStatusChanged = new Emitter<TerminalConnectionStatus>();
+  protected _name: string;
+  protected _reconnectTimeout?: NodeJS.Timeout = undefined;
+  protected _ws?: WebSocket = undefined;
+  protected _noOp = () => {
+    /* no-op */
+  };
+  protected _reconnectLimit = 7;
+  protected _reconnectAttempt = 0;
+  protected _pendingMessages: TerminalMessage[] = [];
+  @inject(TerminalRestAPI) terminalRestAPI: TerminalRestAPI;
+
+  disposed = false;
+
+  /**
+   * Construct a new terminal session.
+   */
+  constructor(@inject(TerminalOption) options: TerminalOption & { name: string }) {
+    this._name = options.name;
+    this._createSocket();
+  }
+
+  /**
+   * A signal emitted when a message is received from the server.
+   */
+  get messageReceived(): Event<TerminalMessage> {
+    return this._messageReceived.event;
+  }
+
+  get onDisposed(): Event<void> {
+    return this._onDisposed.event;
+  }
+
+  /**
+   * Get the name of the terminal session.
+   */
+  get name(): string {
+    return this._name;
+  }
+
+  /**
+   * Get the model for the terminal session.
+   */
+  get model(): TerminalModel {
+    return { name: this._name };
+  }
+
+  /**
+   * The server settings for the session.
+   */
+  readonly serverSettings: ISettings;
+
+  /**
+   * Dispose of the resources held by the session.
+   */
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this.disposed = true;
+    this._updateConnectionStatus('disconnected');
+    this._clearSocket();
+  }
+
+  /**
+   * 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: TerminalMessage): void {
+    this._sendMessage(message);
+  }
+
+  /**
+   * Send a message on the websocket, or possibly queue for later sending.
+   *
+   * @param queue - whether to queue the message if it cannot be sent
+   */
+  _sendMessage(message: TerminalMessage, queue = true): void {
+    if (this.disposed || !message.content) {
+      return;
+    }
+    if (this.connectionStatus === 'connected' && this._ws) {
+      const msg = [message.type, ...message.content];
+      this._ws.send(JSON.stringify(msg));
+    } else if (queue) {
+      this._pendingMessages.push(message);
+    } else {
+      throw new Error(`Could not send message: ${JSON.stringify(message)}`);
+    }
+  }
+
+  /**
+   * Send pending messages to the kernel.
+   */
+  protected _sendPending(): void {
+    // We check to make sure we are still connected each time. For
+    // example, if a websocket buffer overflows, it may close, so we should
+    // stop sending messages.
+    while (this.connectionStatus === 'connected' && this._pendingMessages.length > 0) {
+      this._sendMessage(this._pendingMessages[0], false);
+
+      // We shift the message off the queue after the message is sent so that
+      // if there is an exception, the message is still pending.
+      this._pendingMessages.shift();
+    }
+  }
+
+  toDisposeOnReconnect: Disposable | undefined;
+  /**
+   * Reconnect to a terminal.
+   */
+  reconnect(): Promise<void> {
+    this._errorIfDisposed();
+    const result = new Deferred<void>();
+
+    // Set up a listener for the connection status changing, which accepts or
+    // rejects after the retries are done.
+    const fulfill = (status: TerminalConnectionStatus) => {
+      if (status === 'connected') {
+        result.resolve();
+        this.toDisposeOnReconnect?.dispose();
+      } else if (status === 'disconnected') {
+        result.reject(new Error('Terminal connection disconnected'));
+        this.toDisposeOnReconnect?.dispose();
+      }
+    };
+    this.toDisposeOnReconnect = this.connectionStatusChanged(fulfill);
+
+    // Reset the reconnect limit so we start the connection attempts fresh
+    this._reconnectAttempt = 0;
+
+    // Start the reconnection process, which will also clear any existing
+    // connection.
+    this._reconnect();
+
+    // Return the promise that should resolve on connection or reject if the
+    // retries don't work.
+    return result.promise;
+  }
+
+  /**
+   * Attempt a connection if we have not exhausted connection attempts.
+   */
+  _reconnect(): void {
+    this._errorIfDisposed();
+
+    // Clear any existing reconnection attempt
+    clearTimeout(this._reconnectTimeout);
+
+    // Update the connection status and schedule a possible reconnection.
+    if (this._reconnectAttempt < this._reconnectLimit) {
+      this._updateConnectionStatus('connecting');
+
+      // The first reconnect attempt should happen immediately, and subsequent
+      // attempts should pick a random number in a growing range so that we
+      // don't overload the server with synchronized reconnection attempts
+      // across multiple kernels.
+      const timeout = getRandomIntInclusive(
+        0,
+        1e3 * (Math.pow(2, this._reconnectAttempt) - 1),
+      );
+      console.error(
+        `Connection lost, reconnecting in ${Math.floor(timeout / 1000)} seconds.`,
+      );
+      this._reconnectTimeout = setTimeout(this._createSocket, timeout);
+      this._reconnectAttempt += 1;
+    } else {
+      this._updateConnectionStatus('disconnected');
+    }
+
+    // Clear the websocket event handlers and the socket itself.
+    this._clearSocket();
+  }
+
+  /**
+   * Forcefully clear the socket state.
+   *
+   * #### Notes
+   * This will clear all socket state without calling any handlers and will
+   * not update the connection status. If you call this method, you are
+   * responsible for updating the connection status as needed and recreating
+   * the socket if you plan to reconnect.
+   */
+  protected _clearSocket(): void {
+    if (this._ws) {
+      // Clear the websocket event handlers and the socket itself.
+      this._ws.onopen = this._noOp;
+      this._ws.onclose = this._noOp;
+      this._ws.onerror = this._noOp;
+      this._ws.onmessage = this._noOp;
+      this._ws.close();
+      this._ws = undefined;
+    }
+  }
+
+  /**
+   * Shut down the terminal session.
+   */
+  async shutdown(): Promise<void> {
+    await this.terminalRestAPI.shutdown(this.name, this.serverSettings);
+    this.dispose();
+  }
+
+  /**
+   * Create the terminal websocket connection and add socket status handlers.
+   *
+   * #### Notes
+   * You are responsible for updating the connection status as appropriate.
+   */
+  protected _createSocket = () => {
+    this._errorIfDisposed();
+
+    // Make sure the socket is clear
+    this._clearSocket();
+
+    // Update the connection status to reflect opening a new connection.
+    this._updateConnectionStatus('connecting');
+
+    const name = this._name;
+    const settings = this.serverSettings;
+
+    let url = URL.join(
+      settings.wsUrl,
+      'terminals',
+      'websocket',
+      encodeURIComponent(name),
+    );
+
+    // If token authentication is in use.
+    const token = settings.token;
+    if (settings.appendToken && token !== '') {
+      url = url + `?token=${encodeURIComponent(token)}`;
+    }
+
+    this._ws = new settings.WebSocket(url);
+
+    this._ws.onmessage = this._onWSMessage;
+    this._ws.onclose = this._onWSClose;
+    this._ws.onerror = this._onWSClose as (
+      this: WebSocket,
+      ev: globalThis.Event,
+    ) => any;
+  };
+
+  // Websocket messages events are defined as variables to bind `this`
+  protected _onWSMessage = (event: MessageEvent) => {
+    if (this.disposed) {
+      return;
+    }
+    const data = JSON.parse(event.data) as JSONPrimitive[];
+
+    // Handle a disconnect message.
+    if (data[0] === 'disconnect') {
+      this.dispose();
+    }
+
+    if (this._connectionStatus === 'connecting') {
+      if (data[0] === 'setup') {
+        this._updateConnectionStatus('connected');
+      }
+      return;
+    }
+
+    this._messageReceived.fire({
+      type: data[0] as TerminalMessageType,
+      content: data.slice(1),
+    });
+  };
+
+  protected _onWSClose = (event: CloseEvent) => {
+    console.warn(`Terminal websocket closed: ${event.code}`);
+    if (!this.disposed) {
+      this._reconnect();
+    }
+  };
+
+  /**
+   * Handle connection status changes.
+   */
+  protected _updateConnectionStatus(connectionStatus: TerminalConnectionStatus): void {
+    if (this._connectionStatus === connectionStatus) {
+      return;
+    }
+
+    this._connectionStatus = connectionStatus;
+
+    // If we are not 'connecting', stop any reconnection attempts.
+    if (connectionStatus !== 'connecting') {
+      this._reconnectAttempt = 0;
+      clearTimeout(this._reconnectTimeout);
+    }
+
+    // Send the pending messages if we just connected.
+    if (connectionStatus === 'connected') {
+      this._sendPending();
+    }
+
+    // Notify others that the connection status changed.
+    this._connectionStatusChanged.fire(connectionStatus);
+  }
+
+  protected _errorIfDisposed() {
+    if (this.disposed) {
+      throw new Error('Terminal connection is disposed');
+    }
+  }
+
+  get connectionStatusChanged(): Event<TerminalConnectionStatus> {
+    return this._connectionStatusChanged.event;
+  }
+
+  get connectionStatus(): TerminalConnectionStatus {
+    return this._connectionStatus;
+  }
+}
+
+export function getRandomIntInclusive(min: number, max: number): number {
+  min = Math.ceil(min);
+  max = Math.floor(max);
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}

package/src/index.spec.ts

@@ -0,0 +1,8 @@
+import {} from './index.js';
+import 'reflect-metadata';
+
+describe('libro-widget', () => {
+  it('#import', () => {
+    //
+  });
+});

package/src/index.ts

@@ -0,0 +1 @@
+export * from './module.js';

package/src/manager.ts

@@ -0,0 +1,280 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Poll } from '@difizen/libro-common';
+import type { ISettings } from '@difizen/libro-kernel';
+import { NetworkError } from '@difizen/libro-kernel';
+import type { Disposable, Disposed, Event } from '@difizen/mana-app';
+import { singleton } from '@difizen/mana-app';
+import { Emitter, inject } from '@difizen/mana-app';
+
+import type { TerminalConnection } from './connection.js';
+import type { TerminalModel, TerminalOption } from './protocol.js';
+import { TerminalConnectionFactory } from './protocol.js';
+import { TerminalRestAPI } from './restapi.js';
+
+@singleton()
+export class TerminalManager implements Disposable, Disposed {
+  disposed = false;
+  protected _isReady = false;
+  protected _pollModels: Poll;
+  protected _terminalConnections = new Set<TerminalConnection>();
+  protected _ready: Promise<void>;
+  protected _runningChanged = new Emitter<TerminalModel[]>();
+  protected _connectionFailure = new Emitter<Error>();
+  // As an optimization, we unwrap the models to just store the names.
+  protected _names: string[] = [];
+  protected get _models(): TerminalModel[] {
+    return this._names.map((name) => {
+      return { name };
+    });
+  }
+
+  @inject(TerminalRestAPI) terminalRestAPI: TerminalRestAPI;
+  @inject(TerminalConnectionFactory)
+  terminalConnectionFactory: TerminalConnectionFactory;
+  /**
+   * Construct a new terminal manager.
+   */
+  constructor() {
+    // Start polling with exponential backoff.
+    this._pollModels = new Poll({
+      auto: false,
+      factory: () => this.requestRunning(),
+      frequency: {
+        interval: 10 * 1000,
+        backoff: true,
+        max: 300 * 1000,
+      },
+      name: `@jupyterlab/services:TerminalManager#models`,
+      standby: 'when-hidden',
+    });
+
+    // Initialize internal data.
+    this._ready = (async () => {
+      await this._pollModels.start();
+      await this._pollModels.tick;
+      this._isReady = true;
+    })();
+  }
+
+  /**
+   * The server settings of the manager.
+   */
+  readonly serverSettings: ISettings;
+
+  /**
+   * Test whether the manager is ready.
+   */
+  get isReady(): boolean {
+    return this._isReady;
+  }
+
+  /**
+   * A promise that fulfills when the manager is ready.
+   */
+  get ready(): Promise<void> {
+    return this._ready;
+  }
+
+  /**
+   * A signal emitted when the running terminals change.
+   */
+  get runningChanged(): Event<TerminalModel[]> {
+    return this._runningChanged.event;
+  }
+
+  /**
+   * A signal emitted when there is a connection failure.
+   */
+  get connectionFailure(): Event<Error> {
+    return this._connectionFailure.event;
+  }
+
+  /**
+   * Dispose of the resources used by the manager.
+   */
+  dispose(): void {
+    if (this.disposed) {
+      return;
+    }
+    this._names.length = 0;
+    this._terminalConnections.forEach((x) => x.dispose());
+    this._pollModels.dispose();
+    this.disposed = true;
+  }
+
+  /*
+   * 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: { name: string }): TerminalConnection {
+    const terminalConnection = this.terminalConnectionFactory(options);
+    this._onStarted(terminalConnection);
+    if (!this._names.includes(options.name)) {
+      // We trust the user to connect to an existing session, but we verify
+      // asynchronously.
+      void this.refreshRunning().catch(() => {
+        /* no-op */
+      });
+    }
+    return terminalConnection;
+  }
+
+  /**
+   * Create an iterator over the most recent running terminals.
+   *
+   * @returns A new iterator over the running terminals.
+   */
+  running(): IterableIterator<TerminalModel> {
+    return this._models[Symbol.iterator]();
+  }
+
+  /**
+   * 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> {
+    await this._pollModels.refresh();
+    await this._pollModels.tick;
+  }
+
+  /**
+   * 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: TerminalOption): Promise<TerminalConnection> {
+    const model = await this.terminalRestAPI.startNew(options, this.serverSettings);
+    await this.refreshRunning();
+    return this.connectTo({ ...options, name: model.name });
+  }
+
+  /**
+   * Shut down a terminal session by name.
+   */
+  async shutdown(name: string): Promise<void> {
+    await this.terminalRestAPI.shutdown(name, this.serverSettings);
+    await this.refreshRunning();
+  }
+
+  /**
+   * Shut down all terminal sessions.
+   *
+   * @returns A promise that resolves when all of the sessions are shut down.
+   */
+  async shutdownAll(): Promise<void> {
+    // Update the list of models to make sure our list is current.
+    await this.refreshRunning();
+
+    // Shut down all models.
+    await Promise.all(
+      this._names.map((name) =>
+        this.terminalRestAPI.shutdown(name, this.serverSettings),
+      ),
+    );
+
+    // Update the list of models to clear out our state.
+    await this.refreshRunning();
+  }
+
+  /**
+   * Execute a request to the server to poll running terminals and update state.
+   */
+  protected async requestRunning(): Promise<void> {
+    let models: TerminalModel[];
+    try {
+      models = await this.terminalRestAPI.listRunning(this.serverSettings);
+    } catch (err) {
+      // Handle network errors, as well as cases where we are on a
+      // JupyterHub and the server is not running. JupyterHub returns a
+      // 503 (<2.0) or 424 (>2.0) in that case.
+      if (
+        err instanceof NetworkError ||
+        (err as any).response?.status === 503 ||
+        (err as any).response?.status === 424
+      ) {
+        this._connectionFailure.fire(err as any);
+      }
+      throw err;
+    }
+
+    if (this.disposed) {
+      return;
+    }
+
+    const names = models.map(({ name }) => name).sort();
+    if (names === this._names) {
+      // Identical models list, so just return
+      return;
+    }
+
+    this._names = names;
+    this._terminalConnections.forEach((tc) => {
+      if (!names.includes(tc.name)) {
+        tc.dispose();
+      }
+    });
+    this._runningChanged.fire(this._models);
+  }
+
+  /**
+   * Handle a session starting.
+   */
+  protected _onStarted(terminalConnection: TerminalConnection): void {
+    this._terminalConnections.add(terminalConnection);
+    terminalConnection.onDisposed(() => {
+      this._onDisposed(terminalConnection);
+    });
+  }
+
+  /**
+   * Handle a session terminating.
+   */
+  protected _onDisposed(terminalConnection: TerminalConnection): void {
+    this._terminalConnections.delete(terminalConnection);
+    // Update the running models to make sure we reflect the server state
+    void this.refreshRunning().catch(() => {
+      /* no-op */
+    });
+  }
+
+  getOrCreate = async (options: TerminalOption) => {
+    const { name, cwd } = options;
+    let connection;
+    if (name) {
+      const models = await this.terminalRestAPI.listRunning();
+      if (models.map((d) => d.name).includes(name)) {
+        // we are restoring a terminal widget and the corresponding terminal exists
+        // let's connect to it
+        connection = this.connectTo({ name });
+      } else {
+        // we are restoring a terminal widget but the corresponding terminal was closed
+        // let's start a new terminal with the original name
+        connection = await this.startNew({ name, cwd });
+      }
+    } else {
+      // we are creating a new terminal widget with a new terminal
+      // let the server choose the terminal name
+      connection = await this.startNew({ cwd });
+    }
+    return connection;
+  };
+}

package/src/module.ts

@@ -0,0 +1,29 @@
+import { ManaModule } from '@difizen/mana-app';
+
+import { TerminalConfiguration } from './configuration.js';
+import { TerminalConnection } from './connection.js';
+import { TerminalManager } from './manager.js';
+import { TerminalOption } from './protocol.js';
+import { TerminalConnectionFactory } from './protocol.js';
+import { TerminalRestAPI } from './restapi.js';
+import { TerminalThemeService } from './theme-service.js';
+import { LibroTerminalView } from './view.js';
+
+export const TerminalModule = ManaModule.create().register(
+  TerminalConnection,
+  TerminalManager,
+  TerminalRestAPI,
+  {
+    token: TerminalConnectionFactory,
+    useFactory: (ctx) => {
+      return (options: TerminalOption) => {
+        const child = ctx.container.createChild();
+        child.register({ token: TerminalOption, useValue: options });
+        return child.get(TerminalConnection);
+      };
+    },
+  },
+  TerminalConfiguration,
+  TerminalThemeService,
+  LibroTerminalView,
+);