@oceanum/oceanumlab 4.7.1 → 4.8.0

package/lib/share/client.js

@@ -0,0 +1,206 @@
+import { isSpecId } from './notebook';
+const MESSAGES = {
+    '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(kind, status = null) {
+        super(kind === 'server'
+            ? `Oceanum.io returned an error (HTTP ${status}).`
+            : MESSAGES[kind]);
+        this.kind = kind;
+        this.status = status;
+        this.name = 'SpecStoreError';
+    }
+}
+/** Map a failed HTTP status to an error. */
+export function errorForStatus(status) {
+    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);
+    }
+}
+function isSummary(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const v = value;
+    return (isSpecId(v.id) &&
+        typeof v.name === 'string' &&
+        typeof v.modified === 'string');
+}
+function isRecord(value) {
+    return isSummary(value) && 'spec' in value;
+}
+/** Client for one spec type of the Oceanum spec store, `notebook` by default. */
+export class SpecStoreClient {
+    constructor(options) {
+        var _a, _b;
+        const specType = (_a = options.specType) !== null && _a !== void 0 ? _a : 'notebook';
+        this._base = `${options.specsUrl.replace(/\/+$/, '')}/specs/${specType}`;
+        this._getAccessToken = options.getAccessToken;
+        this._fetch = (_b = options.fetch) !== null && _b !== void 0 ? _b : ((input, init) => fetch(input, init));
+    }
+    /** Every notebook the user may read, including public ones. */
+    async list() {
+        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) {
+        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) {
+        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, body) {
+        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, changes) {
+        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, name) {
+        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
+            });
+        }
+    }
+    /** Delete a record (requires admin access to it). */
+    async remove(id) {
+        await this._request('DELETE', this._url(id), { auth: 'required' });
+    }
+    /** Grant a permission on a record (requires admin access to it). */
+    async addPermission(id, grant) {
+        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, grant) {
+        await this._request('DELETE', `${this._url(id)}/permissions`, {
+            auth: 'required',
+            body: {
+                type: grant.type,
+                entity: grant.entity,
+                permission: grant.permission
+            }
+        });
+    }
+    _url(id) {
+        if (!isSpecId(id)) {
+            throw new SpecStoreError('invalid');
+        }
+        return `${this._base}/${id}`;
+    }
+    _record(data) {
+        if (!isRecord(data)) {
+            throw new SpecStoreError('invalid');
+        }
+        return data;
+    }
+    async _request(method, url, options) {
+        const token = await this._getAccessToken();
+        if (token === null && options.auth === 'required') {
+            throw new SpecStoreError('signed-out');
+        }
+        const headers = {};
+        if (token !== null) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        const init = { method, headers };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        let response;
+        try {
+            response = await this._fetch(url, init);
+        }
+        catch (_a) {
+            throw new SpecStoreError('network');
+        }
+        if (!response.ok) {
+            throw errorForStatus(response.status);
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        try {
+            return await response.json();
+        }
+        catch (_b) {
+            throw new SpecStoreError('invalid');
+        }
+    }
+}
+/** Only the fields the server accepts; in particular never send an `id`. */
+function pick(body) {
+    return { name: body.name, description: body.description, spec: body.spec };
+}

package/lib/share/events.d.ts

@@ -0,0 +1,7 @@
+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.
+ */
+export declare const notebooksChanged: Signal<object, void>;

package/lib/share/events.js

@@ -0,0 +1,9 @@
+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({});

package/lib/share/notebook.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Notebook records in the Oceanum spec store: the link a local notebook keeps to its
+ * record, the body that is stored, and the names, paths and addresses around them.
+ *
+ * Ported from oceanum-notebook's share-oceanum package, which notebook.oceanum.io will
+ * drop in favour of this one.
+ */
+import type { INotebookContent } from '@jupyterlab/nbformat';
+/** Notebook metadata key linking a local notebook to its spec store record. */
+export declare const METADATA_KEY = "oceanum";
+/** Folder that notebooks opened from Oceanum.io are written to. */
+export declare const OCEANUM_DIR = "Oceanum";
+/** Query parameter carrying a shared notebook id. */
+export declare const QUERY_PARAM = "oceanum-notebook";
+/**
+ * Largest request body we send. Cloud Run rejects requests over 32 MiB; keep a margin
+ * for headers and the server's own encoding.
+ */
+export declare const MAX_BODY_BYTES: number;
+/** The `oceanum` notebook metadata value. */
+export interface IOceanumLink {
+    spec_id: string;
+    /** Spec store the id belongs to, so a development id is never PUT to production. */
+    specs_url: string;
+    description?: string;
+}
+/** A spec store request body for `POST`/`PUT /specs/notebook`. */
+export interface ISpecBody {
+    name: string;
+    description: string | null;
+    spec: INotebookContent;
+}
+/**
+ * The fields a `PATCH /specs/notebook/{id}` may change. A field left out keeps its
+ * stored value, so a rename need not send the notebook back.
+ *
+ * The store refuses anything else outright rather than ignoring it, and refuses a patch
+ * that carries no field at all, so never send an empty one. `spec` is replaced whole:
+ * there is no way to change one key of a stored notebook.
+ */
+export interface ISpecPatch {
+    name?: string;
+    description?: string | null;
+    spec?: INotebookContent;
+}
+/** A spec store list entry (the list omits `spec`). */
+export interface ISpecSummary {
+    id: string;
+    name: string;
+    description: string | null;
+    /**
+     * When the record was created, or last patched. A `PUT` does not touch it, so for a
+     * record nothing has patched this is still a creation time.
+     */
+    modified: string;
+    /** Null unless the caller created the record: the store hides other creators. */
+    creator: string | null;
+}
+/** A full spec store record. */
+export interface ISpecRecord extends ISpecSummary {
+    spec: unknown;
+}
+export type BuildResult = {
+    ok: true;
+    body: ISpecBody;
+    bytes: number;
+    strippedOutputs: boolean;
+} | {
+    ok: false;
+    bytes: number;
+};
+/** Whether `value` is a UUID, and so safe to put in a spec store URL. */
+export declare function isSpecId(value: unknown): value is string;
+/**
+ * Read the link from an `oceanum` metadata value, or `null` if it is missing, malformed,
+ * or belongs to a different spec store.
+ */
+export declare function readLink(value: unknown, specsUrl: string): IOceanumLink | null;
+/** The notebook name stored on Oceanum.io for a local path. */
+export declare function nameFromPath(path: string): string;
+/**
+ * The notebook with every cell's `trusted` metadata removed.
+ *
+ * JupyterLab trusts a cell whose metadata says `trusted: true` and then renders its HTML
+ * and Markdown unsanitised, running any script in them. A notebook from the spec store
+ * (anyone with write access can edit a record) must arrive untrusted; its outputs
+ * become trusted again when the reader re-runs the cells.
+ */
+export declare function withoutTrust(content: INotebookContent): INotebookContent;
+/**
+ * Build the spec store body for a notebook. The `oceanum` link is not stored in the
+ * record. If the body is over `maxBytes`, code-cell outputs and execution counts are
+ * dropped; if it is still too large, the result is not ok.
+ */
+export declare function buildSpecBody(content: INotebookContent, path: string, specsUrl: string, maxBytes?: number): BuildResult;
+/**
+ * A notebook uploaded from the user's computer, untrusted and linked to nothing: a file
+ * someone else downloaded from a record must not save over that record, and its outputs
+ * must not run scripts on the origin that holds the Oceanum.io session. Throws if the
+ * text is not an nbformat 4 notebook; the message never quotes the file.
+ */
+export declare function notebookFromUpload(text: string): INotebookContent;
+/**
+ * The notebook stored in a record, with its `oceanum` link set. Throws if the record
+ * does not hold an nbformat 4 notebook.
+ */
+export declare function notebookFromRecord(record: ISpecRecord, specsUrl: string): INotebookContent;
+/**
+ * A copy of the notebook stored in a record, linked to nothing: untrusted, and without
+ * any `oceanum` link, so saving it creates a record of the user's own instead of
+ * writing to this one. Throws if the record does not hold an nbformat 4 notebook.
+ */
+export declare function unlinkedNotebookFromRecord(record: ISpecRecord): INotebookContent;
+/** Make a record name safe to use as a single path segment. */
+export declare function sanitizeName(name: string): string;
+/**
+ * A path `Oceanum/<name>.ipynb` that does not collide with `existing` (file names in the
+ * `Oceanum` folder), appending ` (1)`, ` (2)`, ... as needed.
+ */
+export declare function uniqueNotebookPath(name: string, existing: Iterable<string>): string;
+/**
+ * The names in `existing` that `uniqueNotebookPath` could have given a record called
+ * `name`, in the order it would have tried them: `<base>.ipynb`, then `<base> (1).ipynb`,
+ * `<base> (2).ipynb` and so on.
+ *
+ * Opening a record looks through these for the copy a previous session left, so the same
+ * record keeps one local file. Without that the second copy is named `<base> (1)`, and
+ * since a record takes its name from the file on every save, opening a notebook twice
+ * would quietly rename it on Oceanum.
+ */
+export declare function notebookNamesFor(name: string, existing: Iterable<string>): string[];
+/**
+ * Split a listing into the caller's own notebooks and the rest, newest first.
+ *
+ * The store only sends `creator` on records the caller created, so anything else it
+ * returns is shared with them — directly, or because it is public. Addresses are
+ * compared case-insensitively: the store matches entities as case-sensitive globs, so
+ * the two sides can differ in case.
+ */
+export declare function partitionSummaries(items: readonly ISpecSummary[], email: string | null): {
+    mine: ISpecSummary[];
+    shared: ISpecSummary[];
+};
+/** The `kind` of a Notebook Demo record's spec. */
+export declare const NOTEBOOK_DEMO_KIND = "notebook-demo";
+/** One example in a Notebook Demo record: a notebook record and how to list it. */
+export interface INotebookDemoItem {
+    id: string;
+    title: string;
+    summary?: string;
+}
+/** A titled group of examples. */
+export interface INotebookDemoSection {
+    title: string;
+    items: INotebookDemoItem[];
+}
+/**
+ * The sections of a Notebook Demo record's spec, keeping only what can be listed: items
+ * with a record id and a title, in sections with a title and at least one such item.
+ * A spec of another kind or version gives no sections, with a warning.
+ */
+export declare function parseNotebookDemo(spec: unknown): INotebookDemoSection[];
+/** Parse a spec store timestamp, which is UTC but usually has no zone designator. */
+export declare function parseTimestamp(value: string): Date | null;
+/**
+ * Whether `email` can be granted access. Glob characters are refused: the server
+ * matches user entities as globs.
+ */
+export declare function isShareableEmail(email: string): boolean;
+/** Addresses typed into the share dialog, split into the ones we can grant and the rest. */
+export interface IParsedShareEmails {
+    /** Valid, lower-cased and de-duplicated, in the order first written. */
+    emails: string[];
+    /** Everything that is not a shareable address, as written, for reporting back. */
+    invalid: string[];
+}
+/**
+ * Split what the user typed into individual addresses. Commas, semicolons and any
+ * whitespace all separate, so one-per-line and a comma-separated list both work.
+ *
+ * Bare addresses only: a mail client's "To:" line carries display names, and
+ * `"Alice B" <alice@example.com>` splits into tokens that are not addresses. Those
+ * come back in `invalid` so the user is told, rather than being silently dropped.
+ *
+ * Addresses are lower-cased because the spec store matches the user entity as a
+ * case-sensitive glob against the Auth0 email claim, which Auth0 stores lower case.
+ */
+export declare function parseShareEmails(raw: string): IParsedShareEmails;
+/**
+ * How to report share failures.
+ *
+ * `original` means hand the underlying error to the reporter untouched — it holds the
+ * only explanation the user gets, and the reporter reads its type to decide whether to
+ * offer sign-in. `partial` is only for the case the original error cannot describe on
+ * its own: some addresses worked and some did not, so the message has to name them.
+ */
+export type ShareReport = {
+    kind: 'original';
+} | {
+    kind: 'partial';
+    named: string[];
+};
+/**
+ * Decide how to report a set of failed grants.
+ *
+ * `entities` are the failed grants' entities, in order; the public grant's entity is
+ * the empty string, which names nobody.
+ */
+export declare function reportForShareFailures(grantCount: number, entities: readonly string[], needsSignIn: boolean): ShareReport;
+/**
+ * The link that opens a shared notebook in this deployment.
+ *
+ * JupyterLite is static files, so its page is `lab/index.html`; a JupyterLab server
+ * serves the application at `lab` and has no `index.html` to route.
+ */
+export declare function shareLink(baseUrl: string, pageHref: string, id: string): string;