@oceanum/oceanumlab 4.7.0 → 4.7.2

package/src/index.ts

@@ -18,6 +18,10 @@ import { requestAPI } from './handler';
 import { ChatRouter, ChatRouterError, ChatMessage } from './chatRouter';
 import { reporterFor } from './progress';
 import { ConversationPin } from './conversationPin';
+import { deviceAuthPlugin } from './auth/plugin';
+import { IOceanumAuth } from './auth/tokens';
+import { CommandIDs as ShareCommandIDs, sharePlugin } from './share/plugin';
+
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
 import { KernelHandoff } from './kernelHandoff';
@@ -53,20 +57,27 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
     ISettingRegistry,
     IStateDB
   ],
+  // Optional so the panel still loads on a host with no Oceanum environment; the
+  // Notebooks tab then explains why it is empty instead of the panel failing to start.
+  optional: [IOceanumAuth],
   activate: (
     app: JupyterFrontEnd,
     palette: ICommandPalette,
     restorer: ILayoutRestorer,
     status: ILabStatus,
-    settingRegistry: ISettingRegistry
+    settingRegistry: ISettingRegistry,
+    stateDB: IStateDB,
+    auth: IOceanumAuth | null
   ) => {
     console.log('Oceanum datamesh connect extension is loaded');
 
-    // The `datameshUiUrl` setting; the default until the settings load.
-    let datameshUiUrl = DATAMESH_UI_SERVICE;
-    // The `aiBackendUrl` and `datameshToken` settings for the AI chat; the
-    // defaults until the settings load.
-    let aiBackendUrl = OCEANUM_AI_BACKEND_URL;
+    // Where the Datamesh UI and Oceanum AI live is the deployment's business, so it comes
+    // from the sign-in environment (the Jupyter server's configuration, or the notebook
+    // site's) and falls back to production. These were user settings until 4.7.1; a
+    // user-editable service address is somewhere to send the user's credential.
+    const datameshUiUrl = auth?.urls?.datameshUi ?? DATAMESH_UI_SERVICE;
+    const aiBackendUrl = auth?.urls?.ai ?? OCEANUM_AI_BACKEND_URL;
+    // The `datameshToken` setting for the AI chat; empty until the settings load.
     let datameshTokenSetting = '';
     // Tells the sidebar the settings above have changed.
     const settingsChanged = new Signal<JupyterFrontEnd, void>(app);
@@ -88,14 +99,7 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
         }).then(res => console.log(res));
       }
       window.injectToken = set.get('injectToken').user as boolean;
-      aiBackendUrl = set.get('aiBackendUrl').composite as string;
       datameshTokenSetting = set.get('datameshToken').composite as string;
-      // An open Datamesh UI panel follows a change of address.
-      datameshUiUrl = set.get('datameshUiUrl').composite as string;
-      const datameshUI = findDatameshUI();
-      if (datameshUI) {
-        datameshUI.url = datameshUiUrl;
-      }
       settingsChanged.emit();
     };
     //Try to get the datamesh token from the envars
@@ -145,7 +149,13 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
       aiBackendUrl: () => aiBackendUrl,
       settingsChanged,
       commands: app.commands,
-      getCurrentWidget
+      getCurrentWidget,
+      auth,
+      openStoredNotebook: id => {
+        app.commands.execute(ShareCommandIDs.open, { id }).catch(error => {
+          console.error('Oceanum: could not open the stored notebook.', error);
+        });
+      }
     });
     datameshConnectWidget.id = 'datamesh-connect';
     datameshConnectWidget.title.icon = oceanumIcon;
@@ -153,8 +163,30 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
 
     restorer.add(datameshConnectWidget, 'datamesh-connect');
 
+    // The layout restorer restores the widget's place in the shell, not fields on it,
+    // so the chosen tab is kept here. Restoring is best effort: a missing or unreadable
+    // entry just leaves the default.
+    const TAB_STATE_KEY = `${PLUGIN_ID}:tab`;
+    void stateDB
+      .fetch(TAB_STATE_KEY)
+      .then(value => {
+        if (typeof value === 'string') {
+          datameshConnectWidget.selectTab(value);
+        }
+      })
+      .catch((): void => undefined);
+    datameshConnectWidget.tabChanged.connect((_, id) => {
+      void stateDB.save(TAB_STATE_KEY, id);
+    });
+
     // Rank has been chosen somewhat arbitrarily to give priority to the running
     // sessions widget in the sidebar.
+    //
+    // Oceanum Notebook wants this panel first instead, but that is a property of that
+    // distribution rather than of the extension: in a plain JupyterLab the file browser
+    // is the primary navigation surface and displacing it would be a regression. A
+    // distribution moves it with JupyterLab's own shell user-layout settings, keyed on
+    // this widget's id, rather than this extension hard-coding one host's preference.
     app.shell.add(datameshConnectWidget, 'left', { rank: 900 });
 
     app.commands.addCommand('datamesh-ui:open', {
@@ -174,10 +206,12 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
   id: '@oceanum/oceanumlab:ai-chat',
   autoStart: true,
   requires: [INotebookTracker, ISettingRegistry],
+  optional: [IOceanumAuth],
   activate: (
     app: JupyterFrontEnd,
     notebookTracker: INotebookTracker,
-    settingRegistry: ISettingRegistry
+    settingRegistry: ISettingRegistry,
+    auth: IOceanumAuth | null
   ) => {
     console.log('Oceanum AI chat extension is loaded');
 
@@ -197,26 +231,31 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
         // The panel the current request read its selected cell from, if the
         // notebook was open: a code answer may replace that cell only there.
         let readFrom: NotebookPanel | null = null;
-        const router = new ChatRouter(settings, app.commands, async () => {
-          const open = await pin.current();
-          readFrom = open;
-          if (open) {
-            return snapshotOf(open.content);
-          }
-          const path = pin.path();
-          if (!path) {
-            return null;
-          }
-          try {
-            const file = await app.serviceManager.contents.get(path, {
-              content: true
-            });
-            return snapshotFromIpynb(file.content);
-          } catch {
-            // Gone: an answer's cells will go into a new notebook instead.
-            return null;
-          }
-        });
+        const router = new ChatRouter(
+          settings,
+          app.commands,
+          async () => {
+            const open = await pin.current();
+            readFrom = open;
+            if (open) {
+              return snapshotOf(open.content);
+            }
+            const path = pin.path();
+            if (!path) {
+              return null;
+            }
+            try {
+              const file = await app.serviceManager.contents.get(path, {
+                content: true
+              });
+              return snapshotFromIpynb(file.content);
+            } catch {
+              // Gone: an answer's cells will go into a new notebook instead.
+              return null;
+            }
+          },
+          () => auth?.urls?.ai ?? ''
+        );
         // Asked only when an answer has blocks to place: brings the
         // conversation's notebook to the front, opening it again if closed.
         const handoff = new KernelHandoff(
@@ -352,4 +391,16 @@ export const oceanum_ai_extension: JupyterFrontEndPlugin<void> = {
   }
 };
 
-export default [datamesh_connect_extension, oceanum_ai_extension];
+/**
+ * The sign-in contract, exported so another extension can provide or consume it: a Lumino
+ * token is matched by object identity, so everyone has to import this one object, and
+ * JupyterLab shares `@oceanum/oceanumlab` between extensions as a singleton module.
+ */
+export * from './auth/tokens';
+
+export default [
+  deviceAuthPlugin,
+  sharePlugin,
+  datamesh_connect_extension,
+  oceanum_ai_extension
+];

package/src/share/client.ts

@@ -0,0 +1,288 @@
+import {
+  isSpecId,
+  ISpecBody,
+  ISpecPatch,
+  ISpecRecord,
+  ISpecSummary
+} from './notebook';
+
+export type ErrorKind =
+  | 'signed-out'
+  | 'expired'
+  | 'forbidden'
+  | 'not-found'
+  | 'too-large'
+  | 'network'
+  | 'invalid'
+  | 'unsupported'
+  | 'server';
+
+const MESSAGES: Record<Exclude<ErrorKind, 'server'>, string> = {
+  'signed-out': 'Sign in to Oceanum.io to continue.',
+  expired: 'Your Oceanum session has expired, sign in again.',
+  forbidden:
+    'You have no access to this notebook. It may not exist, or was created under another organisation.',
+  'not-found': 'This notebook no longer exists on Oceanum.io.',
+  'too-large': 'The notebook is too large for Oceanum.io (32 MiB limit).',
+  network:
+    'Could not reach Oceanum.io. Check your connection; very large notebooks can also fail this way.',
+  invalid: 'Oceanum.io returned an unexpected response.',
+  unsupported: 'This Oceanum.io service does not offer that operation yet.'
+};
+
+/** A spec store failure with a message that is safe to show to the user. */
+export class SpecStoreError extends Error {
+  constructor(
+    readonly kind: ErrorKind,
+    readonly status: number | null = null
+  ) {
+    super(
+      kind === 'server'
+        ? `Oceanum.io returned an error (HTTP ${status}).`
+        : MESSAGES[kind]
+    );
+    this.name = 'SpecStoreError';
+  }
+}
+
+/** Map a failed HTTP status to an error. */
+export function errorForStatus(status: number): SpecStoreError {
+  switch (status) {
+    // The spec store's authentication middleware answers a bad or expired token with 400.
+    case 400:
+      return new SpecStoreError('expired', status);
+    // Casbin answers 403 both for no access and for a record that does not exist.
+    case 403:
+      return new SpecStoreError('forbidden', status);
+    case 404:
+      return new SpecStoreError('not-found', status);
+    case 405:
+      // The route is there but not this method: a store from before it had PATCH.
+      return new SpecStoreError('unsupported', status);
+    case 413:
+      return new SpecStoreError('too-large', status);
+    default:
+      return new SpecStoreError('server', status);
+  }
+}
+
+export type SharePermission = 'read' | 'write';
+
+/** A permission grant, as accepted by `POST /specs/notebook/{id}/permissions`. */
+export type PermissionGrant =
+  | { type: 'user'; entity: string; permission: SharePermission }
+  | { type: 'public'; entity: ''; permission: 'read' };
+
+/**
+ * What the share dialog asks for: add grants, or remove one (e.g. stop public access).
+ *
+ * Granting carries a list because the dialog shares with several people at once, while
+ * the spec store takes one grant per request. `invalid` carries back anything typed that
+ * is not a shareable address, so the caller can name it rather than failing with
+ * "invalid email".
+ */
+export type ShareChoice =
+  | { action: 'grant'; grants: PermissionGrant[]; invalid: string[] }
+  | { action: 'revoke'; grant: PermissionGrant };
+
+export interface ISpecStoreClientOptions {
+  /** Spec store base URL, e.g. `https://specs.oceanum.io`. */
+  specsUrl: string;
+  /** Returns a current access token or `null`. Called for every request. */
+  getAccessToken: () => Promise<string | null>;
+  fetch?: typeof fetch;
+}
+
+function isSummary(value: unknown): value is ISpecSummary {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as Record<string, unknown>;
+  return (
+    isSpecId(v.id) &&
+    typeof v.name === 'string' &&
+    typeof v.modified === 'string'
+  );
+}
+
+function isRecord(value: unknown): value is ISpecRecord {
+  return isSummary(value) && 'spec' in value;
+}
+
+/** Client for the `notebook` spec type of the Oceanum spec store. */
+export class SpecStoreClient {
+  constructor(options: ISpecStoreClientOptions) {
+    this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/notebook`;
+    this._getAccessToken = options.getAccessToken;
+    this._fetch = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+
+  /** Every notebook the user may read, including public ones. */
+  async list(): Promise<ISpecSummary[]> {
+    const data = await this._request('GET', this._base, { auth: 'required' });
+    if (!Array.isArray(data) || !data.every(isSummary)) {
+      throw new SpecStoreError('invalid');
+    }
+    return data;
+  }
+
+  /** Read a record, anonymously when signed out. */
+  async get(id: string): Promise<ISpecRecord> {
+    return this._record(
+      await this._request('GET', this._url(id), { auth: 'optional' })
+    );
+  }
+
+  /** Create a record. The server mints the id: use the returned record's. */
+  async create(body: ISpecBody): Promise<ISpecRecord> {
+    return this._record(
+      await this._request('POST', this._base, {
+        auth: 'required',
+        body: pick(body)
+      })
+    );
+  }
+
+  /** Replace a record's name, description and notebook. */
+  async update(id: string, body: ISpecBody): Promise<ISpecRecord> {
+    return this._record(
+      await this._request('PUT', this._url(id), {
+        auth: 'required',
+        body: pick(body)
+      })
+    );
+  }
+
+  /**
+   * Change some of a record's fields and leave the rest as they are. Needs the same
+   * write access as `update`, which the store enforces a patch as.
+   */
+  async patch(id: string, changes: ISpecPatch): Promise<ISpecRecord> {
+    if (Object.keys(changes).length === 0) {
+      // The store answers an empty patch with 400; there is nothing to send anyway.
+      throw new SpecStoreError('invalid');
+    }
+    return this._record(
+      await this._request('PATCH', this._url(id), {
+        auth: 'required',
+        body: changes
+      })
+    );
+  }
+
+  /**
+   * Give a record a new name, without sending the notebook back with it.
+   *
+   * Falls back to reading the record and putting it back where the store has no PATCH
+   * (production had none when this was written). That fallback races another writer's
+   * change to the notebook, which is the whole reason to prefer a patch.
+   */
+  async rename(id: string, name: string): Promise<ISpecRecord> {
+    try {
+      return await this.patch(id, { name });
+    } catch (error) {
+      if (!(error instanceof SpecStoreError) || error.kind !== 'unsupported') {
+        throw error;
+      }
+      const record = await this.get(id);
+      return this.update(id, {
+        name,
+        description: record.description,
+        spec: record.spec as ISpecBody['spec']
+      });
+    }
+  }
+
+  /** Delete a record (requires admin access to it). */
+  async remove(id: string): Promise<void> {
+    await this._request('DELETE', this._url(id), { auth: 'required' });
+  }
+
+  /** Grant a permission on a record (requires admin access to it). */
+  async addPermission(id: string, grant: PermissionGrant): Promise<void> {
+    await this._request('POST', `${this._url(id)}/permissions`, {
+      auth: 'required',
+      body: {
+        type: grant.type,
+        entity: grant.entity,
+        permission: grant.permission
+      }
+    });
+  }
+
+  /**
+   * Remove a permission (requires admin access). The server matches the exact grant and
+   * answers 404 when there is no such permission.
+   */
+  async removePermission(id: string, grant: PermissionGrant): Promise<void> {
+    await this._request('DELETE', `${this._url(id)}/permissions`, {
+      auth: 'required',
+      body: {
+        type: grant.type,
+        entity: grant.entity,
+        permission: grant.permission
+      }
+    });
+  }
+
+  private _url(id: string): string {
+    if (!isSpecId(id)) {
+      throw new SpecStoreError('invalid');
+    }
+    return `${this._base}/${id}`;
+  }
+
+  private _record(data: unknown): ISpecRecord {
+    if (!isRecord(data)) {
+      throw new SpecStoreError('invalid');
+    }
+    return data;
+  }
+
+  private async _request(
+    method: string,
+    url: string,
+    options: { auth: 'required' | 'optional'; body?: object }
+  ): Promise<unknown> {
+    const token = await this._getAccessToken();
+    if (token === null && options.auth === 'required') {
+      throw new SpecStoreError('signed-out');
+    }
+    const headers: Record<string, string> = {};
+    if (token !== null) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+    const init: RequestInit = { method, headers };
+    if (options.body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(options.body);
+    }
+
+    let response: Response;
+    try {
+      response = await this._fetch(url, init);
+    } catch {
+      throw new SpecStoreError('network');
+    }
+    if (!response.ok) {
+      throw errorForStatus(response.status);
+    }
+    if (response.status === 204) {
+      return null;
+    }
+    try {
+      return await response.json();
+    } catch {
+      throw new SpecStoreError('invalid');
+    }
+  }
+
+  private readonly _base: string;
+  private readonly _getAccessToken: () => Promise<string | null>;
+  private readonly _fetch: typeof fetch;
+}
+
+/** Only the fields the server accepts; in particular never send an `id`. */
+function pick(body: ISpecBody): ISpecBody {
+  return { name: body.name, description: body.description, spec: body.spec };
+}

package/src/share/events.ts

@@ -0,0 +1,10 @@
+import { Signal } from '@lumino/signaling';
+
+/**
+ * Emits after this extension creates, renames or deletes a notebook record, so the
+ * Notebooks tab can list again. A plain module-level signal: the tab and the commands
+ * live in different plugins, and the change is the only thing they need to share.
+ */
+// The sender is a throwaway object, not null: Lumino keys its receivers by sender in a
+// WeakMap, which refuses null.
+export const notebooksChanged = new Signal<object, void>({});