@oceanum/oceanumlab 4.7.1 → 4.8.0

package/src/auth/tokens.ts

@@ -25,6 +25,19 @@ export interface IOceanumEnvironment {
    * the site origin is an allowed callback URL.
    */
   readonly signInRedirect: boolean;
+  /**
+   * Whether Oceanum.io is the only file management this host shows, as on
+   * notebook.oceanum.io: the file browser and the File menu's local-file entries go,
+   * and every local save is pushed to the spec store. `'local'` (the default when
+   * absent) keeps JupyterLab's file management alongside the Oceanum commands.
+   */
+  readonly fileManagement?: 'local' | 'oceanum';
+  /**
+   * The spec store id of this deployment's Notebook Demo record, the curated list the
+   * Notebooks tab shows as Examples. Absent where a deployment has none, and never set
+   * by a JupyterLab server's sign-in.
+   */
+  readonly notebookDemo?: string;
 }
 
 /** Service base URLs for an environment, without trailing slashes. */

package/src/index.ts

@@ -20,6 +20,8 @@ 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 { OCEANUM_PANEL_ID } from './share/oceanumOnly';
 
 import { snapshotFromIpynb, snapshotOf } from './notebookContext';
 import { notebookHost } from './notebookHost';
@@ -78,6 +80,9 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
     const aiBackendUrl = auth?.urls?.ai ?? OCEANUM_AI_BACKEND_URL;
     // The `datameshToken` setting for the AI chat; empty until the settings load.
     let datameshTokenSetting = '';
+    // The `showExamples` setting for the Notebooks tab; null until the settings load, so
+    // examples a user has hidden do not show for a moment on every reload.
+    let showExamplesSetting: boolean | null = null;
     // Tells the sidebar the settings above have changed.
     const settingsChanged = new Signal<JupyterFrontEnd, void>(app);
 
@@ -99,6 +104,7 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
       }
       window.injectToken = set.get('injectToken').user as boolean;
       datameshTokenSetting = set.get('datameshToken').composite as string;
+      showExamplesSetting = set.get('showExamples').composite as boolean;
       settingsChanged.emit();
     };
     //Try to get the datamesh token from the envars
@@ -115,6 +121,10 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
         console.error(
           `Something went wrong when reading the Oceanumlab settings.\n${reason}`
         );
+        // Unreadable settings fall back to the default rather than leaving the examples
+        // waiting for a value that will never come.
+        showExamplesSetting = true;
+        settingsChanged.emit();
       });
 
     const getCurrentWidget = (): Widget => {
@@ -149,14 +159,39 @@ export const datamesh_connect_extension: JupyterFrontEndPlugin<void> = {
       settingsChanged,
       commands: app.commands,
       getCurrentWidget,
-      auth
-      // No `openStoredNotebook`: nothing can open a spec store record by id yet.
-      // share-oceanum has `oceanum-share:open`, but it takes no arguments — it opens
-      // its own picker — so there is nothing to hand an id to. Opening arrives with
-      // the drive in OCE-182, where the contents API makes it the ordinary path.
-      // Until then the list reads rather than offering a click that does nothing.
+      auth,
+      openStoredNotebook: id => {
+        app.commands.execute(ShareCommandIDs.open, { id }).catch(error => {
+          console.error('Oceanum: could not open the stored notebook.', error);
+        });
+      },
+      openExample: (id, title) => {
+        app.commands
+          .execute(ShareCommandIDs.openExample, { id, title })
+          .catch(error => {
+            console.error('Oceanum: could not open the example.', error);
+          });
+      },
+      uploadNotebook: () => {
+        app.commands.execute(ShareCommandIDs.upload).catch(error => {
+          console.error('Oceanum: could not upload the notebook.', error);
+        });
+      },
+      showExamples: () => showExamplesSetting,
+      // Saved as a user setting, so the choice outlasts the page; the settings'
+      // `changed` signal brings the new value back to the panel. The registry waits
+      // for the plugin's settings to load, so a click before then is not lost.
+      setShowExamples: show => {
+        settingRegistry.set(PLUGIN_ID, 'showExamples', show).catch(error => {
+          // The switch moves only once the setting is saved, so say why it did not.
+          console.error('Oceanum: could not save the Examples setting.', error);
+          Notification.error('Could not save whether to show the examples.', {
+            autoClose: 5000
+          });
+        });
+      }
     });
-    datameshConnectWidget.id = 'datamesh-connect';
+    datameshConnectWidget.id = OCEANUM_PANEL_ID;
     datameshConnectWidget.title.icon = oceanumIcon;
     datameshConnectWidget.title.caption = 'Datamesh Connect';
 
@@ -399,6 +434,7 @@ export * from './auth/tokens';
 
 export default [
   deviceAuthPlugin,
+  sharePlugin,
   datamesh_connect_extension,
   oceanum_ai_extension
 ];

package/src/share/client.ts

@@ -0,0 +1,291 @@
+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>;
+  /** The spec type the client reads and writes; `notebook` unless given. */
+  specType?: string;
+  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 one spec type of the Oceanum spec store, `notebook` by default. */
+export class SpecStoreClient {
+  constructor(options: ISpecStoreClientOptions) {
+    const specType = options.specType ?? 'notebook';
+    this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/${specType}`;
+    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>({});