@jupyter/docprovider 1.0.0-alpha.0

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @packageDocumentation
+ * @module docprovider
+ */
+export * from './ydrive';
+export * from './yprovider';

package/lib/index.js

@@ -0,0 +1,10 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+/**
+ * @packageDocumentation
+ * @module docprovider
+ */
+export * from './ydrive';
+export * from './yprovider';

package/lib/ydrive.d.ts

@@ -0,0 +1,77 @@
+import { Contents, Drive, User } from '@jupyterlab/services';
+/**
+ * A Collaborative implementation for an `IDrive`, talking to the
+ * server using the Jupyter REST API and a WebSocket connection.
+ */
+export declare class YDrive extends Drive {
+    /**
+     * Construct a new drive object.
+     *
+     * @param user - The user manager to add the identity to the awareness of documents.
+     */
+    constructor(user: User.IManager);
+    /**
+     * SharedModel factory for the YDrive.
+     */
+    readonly sharedModelFactory: Contents.ISharedFactory;
+    /**
+     * Delete a file.
+     *
+     * @param localPath - The path to the file.
+     *
+     * @returns A promise which resolves when the file is deleted.
+     *
+     * #### Notes
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents).
+     */
+    delete(localPath: string): Promise<void>;
+    /**
+     * Dispose of the resources held by the manager.
+     */
+    dispose(): void;
+    /**
+     * Get a file or directory.
+     *
+     * @param localPath: The path to the file.
+     *
+     * @param options: The options used to fetch the file.
+     *
+     * @returns A promise which resolves with the file content.
+     *
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    get(localPath: string, options?: Contents.IFetchOptions): Promise<Contents.IModel>;
+    /**
+     * Rename a file or directory.
+     *
+     * @param oldLocalPath - The original file path.
+     *
+     * @param newLocalPath - The new file path.
+     *
+     * @returns A promise which resolves with the new file contents model when
+     *   the file is renamed.
+     *
+     * #### Notes
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    rename(oldLocalPath: string, newLocalPath: string): Promise<Contents.IModel>;
+    /**
+     * Save a file.
+     *
+     * @param localPath - The desired file path.
+     *
+     * @param options - Optional overrides to the model.
+     *
+     * @returns A promise which resolves with the file content model when the
+     *   file is saved.
+     *
+     * #### Notes
+     * Ensure that `model.content` is populated for the file.
+     *
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    save(localPath: string, options?: Partial<Contents.IModel>): Promise<Contents.IModel>;
+    private _onCreate;
+    private _user;
+    private _providers;
+}

package/lib/ydrive.js

@@ -0,0 +1,182 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+import { YFile, YNotebook } from '@jupyter/ydoc';
+import { URLExt } from '@jupyterlab/coreutils';
+import { Drive } from '@jupyterlab/services';
+import { WebSocketProvider } from './yprovider';
+/**
+ * The url for the default drive service.
+ */
+const Y_DOCUMENT_PROVIDER_URL = 'api/yjs';
+/**
+ * A Collaborative implementation for an `IDrive`, talking to the
+ * server using the Jupyter REST API and a WebSocket connection.
+ */
+export class YDrive extends Drive {
+    /**
+     * Construct a new drive object.
+     *
+     * @param user - The user manager to add the identity to the awareness of documents.
+     */
+    constructor(user) {
+        super({ name: 'YDrive' });
+        this._onCreate = (options, sharedModel) => {
+            if (typeof options.format !== 'string') {
+                return;
+            }
+            try {
+                const provider = new WebSocketProvider({
+                    url: URLExt.join(this.serverSettings.wsUrl, Y_DOCUMENT_PROVIDER_URL),
+                    path: options.path,
+                    format: options.format,
+                    contentType: options.contentType,
+                    model: sharedModel,
+                    user: this._user
+                });
+                const key = `${options.contentType}:${options.format}:${options.path}`;
+                this._providers.set(key, provider);
+                sharedModel.disposed.connect(() => {
+                    const provider = this._providers.get(key);
+                    if (provider) {
+                        provider.dispose();
+                        this._providers.delete(key);
+                    }
+                });
+            }
+            catch (error) {
+                // Falling back to the contents API if opening the websocket failed
+                //  This may happen if the shared document is not a YDocument.
+                console.error(`Failed to open websocket connection for ${options.path}.\n:${error}`);
+            }
+        };
+        this._user = user;
+        this._providers = new Map();
+        this.sharedModelFactory = new SharedModelFactory(this._onCreate);
+    }
+    /**
+     * Delete a file.
+     *
+     * @param localPath - The path to the file.
+     *
+     * @returns A promise which resolves when the file is deleted.
+     *
+     * #### Notes
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents).
+     */
+    async delete(localPath) {
+        await super.delete(localPath);
+        // FIXME
+        // We are not removing the path from `sharedPaths` as multiple providers of the same file (with different model) may exist.
+        //this._sharedPaths.delete(localPath);
+    }
+    /**
+     * Dispose of the resources held by the manager.
+     */
+    dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        this._providers.forEach(p => p.dispose());
+        this._providers.clear();
+        super.dispose();
+    }
+    /**
+     * Get a file or directory.
+     *
+     * @param localPath: The path to the file.
+     *
+     * @param options: The options used to fetch the file.
+     *
+     * @returns A promise which resolves with the file content.
+     *
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    async get(localPath, options) {
+        if (options && options.format && options.type) {
+            const key = `${options.type}:${options.format}:${localPath}`;
+            const provider = this._providers.get(key);
+            if (provider) {
+                const model = super.get(localPath, { ...options, content: false });
+                await provider.ready;
+                return model;
+            }
+        }
+        return super.get(localPath, options);
+    }
+    /**
+     * Rename a file or directory.
+     *
+     * @param oldLocalPath - The original file path.
+     *
+     * @param newLocalPath - The new file path.
+     *
+     * @returns A promise which resolves with the new file contents model when
+     *   the file is renamed.
+     *
+     * #### Notes
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    async rename(oldLocalPath, newLocalPath) {
+        return await super.rename(oldLocalPath, newLocalPath);
+    }
+    /**
+     * Save a file.
+     *
+     * @param localPath - The desired file path.
+     *
+     * @param options - Optional overrides to the model.
+     *
+     * @returns A promise which resolves with the file content model when the
+     *   file is saved.
+     *
+     * #### Notes
+     * Ensure that `model.content` is populated for the file.
+     *
+     * Uses the [Jupyter Notebook API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml#!/contents) and validates the response model.
+     */
+    async save(localPath, options = {}) {
+        // Save is done from the backend
+        return this.get(localPath, { ...options, content: false });
+    }
+}
+/**
+ * Yjs sharedModel factory for real-time collaboration.
+ */
+class SharedModelFactory {
+    constructor(_onCreate) {
+        this._onCreate = _onCreate;
+        /**
+         * Whether the IDrive supports real-time collaboration or not.
+         */
+        this.collaborative = true;
+    }
+    /**
+     * Create a new `ISharedDocument` instance.
+     *
+     * It should return `undefined` if the factory is not able to create a `ISharedDocument`.
+     */
+    createNew(options) {
+        if (typeof options.format !== 'string') {
+            console.warn(`Only defined format are supported; got ${options.format}.`);
+            return;
+        }
+        if (!options.collaborative) {
+            return;
+        }
+        let sharedModel;
+        switch (options.contentType) {
+            case 'file':
+                sharedModel = new YFile();
+                break;
+            case 'notebook':
+                sharedModel = new YNotebook();
+                break;
+            //default:
+            // FIXME we should request a registry for the proper sharedModel
+        }
+        if (sharedModel) {
+            this._onCreate(options, sharedModel);
+        }
+        return sharedModel;
+    }
+}

package/lib/yprovider.d.ts

@@ -0,0 +1,82 @@
+import { User } from '@jupyterlab/services';
+import { DocumentChange, YDocument } from '@jupyter/ydoc';
+import { IDisposable } from '@lumino/disposable';
+/**
+ * An interface for a document provider.
+ */
+export interface IDocumentProvider extends IDisposable {
+    /**
+     * Returns a Promise that resolves when the document provider is ready.
+     */
+    readonly ready: Promise<void>;
+}
+/**
+ * A class to provide Yjs synchronization over WebSocket.
+ *
+ * We specify custom messages that the server can interpret. For reference please look in yjs_ws_server.
+ *
+ */
+export declare class WebSocketProvider implements IDocumentProvider {
+    /**
+     * Construct a new WebSocketProvider
+     *
+     * @param options The instantiation options for a WebSocketProvider
+     */
+    constructor(options: WebSocketProvider.IOptions);
+    /**
+     * Test whether the object has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * A promise that resolves when the document provider is ready.
+     */
+    get ready(): Promise<void>;
+    /**
+     * Dispose of the resources held by the object.
+     */
+    dispose(): void;
+    private _onUserChanged;
+    private _awareness;
+    private _contentType;
+    private _format;
+    private _isDisposed;
+    private _path;
+    private _ready;
+    private _serverUrl;
+    private _ydoc;
+    private _yWebsocketProvider;
+}
+/**
+ * A namespace for WebSocketProvider statics.
+ */
+export declare namespace WebSocketProvider {
+    /**
+     * The instantiation options for a WebSocketProvider.
+     */
+    interface IOptions {
+        /**
+         * The server URL
+         */
+        url: string;
+        /**
+         * The document file path
+         */
+        path: string;
+        /**
+         * Content type
+         */
+        contentType: string;
+        /**
+         * The source format
+         */
+        format: string;
+        /**
+         * The shared model
+         */
+        model: YDocument<DocumentChange>;
+        /**
+         * The user data
+         */
+        user: User.IManager;
+    }
+}

package/lib/yprovider.js

@@ -0,0 +1,92 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+import { URLExt } from '@jupyterlab/coreutils';
+import { ServerConnection } from '@jupyterlab/services';
+import { PromiseDelegate } from '@lumino/coreutils';
+import { Signal } from '@lumino/signaling';
+import { WebsocketProvider as YWebsocketProvider } from 'y-websocket';
+/**
+ * Room Id endpoint provided by `jupyter_collaboration`
+ * See https://github.com/jupyterlab/jupyter_collaboration
+ */
+const FILE_PATH_TO_ROOM_ID_URL = 'api/yjs/roomid';
+/**
+ * A class to provide Yjs synchronization over WebSocket.
+ *
+ * We specify custom messages that the server can interpret. For reference please look in yjs_ws_server.
+ *
+ */
+export class WebSocketProvider {
+    /**
+     * Construct a new WebSocketProvider
+     *
+     * @param options The instantiation options for a WebSocketProvider
+     */
+    constructor(options) {
+        this._ready = new PromiseDelegate();
+        this._isDisposed = false;
+        this._path = options.path;
+        this._contentType = options.contentType;
+        this._format = options.format;
+        this._serverUrl = options.url;
+        this._ydoc = options.model.ydoc;
+        this._awareness = options.model.awareness;
+        this._yWebsocketProvider = null;
+        const user = options.user;
+        user.ready
+            .then(() => {
+            this._onUserChanged(user);
+        })
+            .catch(e => console.error(e));
+        user.userChanged.connect(this._onUserChanged, this);
+        const serverSettings = ServerConnection.makeSettings();
+        const url = URLExt.join(serverSettings.baseUrl, FILE_PATH_TO_ROOM_ID_URL, encodeURIComponent(this._path));
+        const data = {
+            method: 'PUT',
+            body: JSON.stringify({ format: this._format, type: this._contentType })
+        };
+        ServerConnection.makeRequest(url, data, serverSettings)
+            .then(response => {
+            if (response.status !== 200 && response.status !== 201) {
+                throw new ServerConnection.ResponseError(response);
+            }
+            return response.text();
+        })
+            .then(roomid => {
+            this._yWebsocketProvider = new YWebsocketProvider(this._serverUrl, roomid, this._ydoc, {
+                awareness: this._awareness
+            });
+        })
+            .then(() => this._ready.resolve())
+            .catch(reason => console.warn(reason));
+    }
+    /**
+     * Test whether the object has been disposed.
+     */
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * A promise that resolves when the document provider is ready.
+     */
+    get ready() {
+        return this._ready.promise;
+    }
+    /**
+     * Dispose of the resources held by the object.
+     */
+    dispose() {
+        var _a;
+        if (this.isDisposed) {
+            return;
+        }
+        this._isDisposed = true;
+        (_a = this._yWebsocketProvider) === null || _a === void 0 ? void 0 : _a.destroy();
+        Signal.clearData(this);
+    }
+    _onUserChanged(user) {
+        this._awareness.setLocalStateField('user', user.identity);
+    }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@jupyter/docprovider",
+  "version": "1.0.0-alpha.0",
+  "description": "JupyterLab - Document Provider",
+  "homepage": "https://github.com/jupyterlab/jupyter_collaboration",
+  "bugs": {
+    "url": "https://github.com/jupyterlab/jupyter_collaboration/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jupyterlab/jupyter_collaboration.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Project Jupyter",
+  "sideEffects": [
+    "style/**/*"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "directories": {
+    "lib": "lib/"
+  },
+  "files": [
+    "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
+    "schema/*.json",
+    "style/**/*.{css,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
+    "style/index.js"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "build:prod": "jlpm run build",
+    "build:test": "tsc --build tsconfig.test.json",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+    "clean:lib": "jlpm run clean:all",
+    "clean:all": "rimraf lib tsconfig.tsbuildinfo node_modules",
+    "install:extension": "jlpm run build",
+    "test": "jest",
+    "test:cov": "jest --collect-coverage",
+    "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand",
+    "test:debug:watch": "node --inspect-brk node_modules/.bin/jest --runInBand --watch",
+    "watch": "tsc -b --watch"
+  },
+  "dependencies": {
+    "@jupyter/ydoc": "^0.3.1",
+    "@jupyterlab/coreutils": "^6.0.0-alpha.18",
+    "@jupyterlab/services": "^7.0.0-alpha.18",
+    "@lumino/coreutils": "^2.0.0-alpha.6",
+    "@lumino/disposable": "^2.0.0-alpha.6",
+    "@lumino/signaling": "^2.0.0-alpha.6",
+    "y-protocols": "^1.0.5",
+    "y-websocket": "^1.3.15",
+    "yjs": "^13.5.40"
+  },
+  "devDependencies": {
+    "@jupyterlab/testing": "^4.0.0-alpha.18",
+    "@types/jest": "^29.2.0",
+    "rimraf": "~3.0.0",
+    "typescript": "~4.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts",
+    "displayName": "@jupyter/docprovider",
+    "tsconfig": "./tsconfig.json"
+  }
+}