@perspective-dev/client 4.0.0

package/src/ts/wasm/browser.ts

@@ -0,0 +1,123 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import type * as psp from "../../../dist/wasm/perspective-js.d.ts";
+
+import * as psp_websocket from "../websocket.ts";
+
+function invert_promise<T>(): [
+    (t: T) => void,
+    Promise<T>,
+    (e: string) => void,
+] {
+    let sender, reject;
+    let receiver: Promise<T> = new Promise((x, y) => {
+        sender = x;
+        reject = y;
+    });
+
+    return [
+        sender as unknown as (t: T) => void,
+        receiver,
+        reject as unknown as (e: string) => void,
+    ];
+}
+
+async function _init(ws: MessagePort | Worker, wasm: WebAssembly.Module) {
+    const [sender, receiver] = invert_promise();
+    ws.addEventListener("message", function listener(resp) {
+        ws.removeEventListener("message", listener);
+        sender(null);
+    });
+
+    ws.onmessage = function listener(resp) {
+        ws.onmessage = function () {};
+        sender(null);
+    };
+
+    ws.onmessageerror = console.error;
+    ws.postMessage(
+        { cmd: "init", args: [wasm] },
+        { transfer: wasm instanceof WebAssembly.Module ? [] : [wasm] },
+    );
+
+    await receiver;
+}
+
+/**
+ * Create a new client connected exclusively to a new Web Worker instance of
+ * the Perspective engine.
+ * @param module
+ * @returns
+ */
+export async function worker(
+    module: Promise<typeof psp>,
+    server_wasm: Promise<WebAssembly.Module>,
+    perspective_wasm_worker: Promise<SharedWorker | ServiceWorker | Worker>,
+) {
+    let [wasm, webworker]: [
+        WebAssembly.Module,
+        SharedWorker | ServiceWorker | Worker | MessagePort,
+    ] = await Promise.all([server_wasm, perspective_wasm_worker]);
+
+    const { Client } = await module;
+    let port: MessagePort;
+    if (
+        typeof SharedWorker !== "undefined" &&
+        webworker instanceof SharedWorker
+    ) {
+        port = webworker.port;
+    } else {
+        webworker = webworker as ServiceWorker | Worker | MessagePort;
+        const messageChannel = new MessageChannel();
+        webworker.postMessage(null, [messageChannel.port2]);
+        port = messageChannel.port1;
+    }
+
+    const client = new Client(
+        async (proto: Uint8Array) => {
+            const f = proto.slice().buffer;
+            port.postMessage(f, { transfer: [f] });
+        },
+        async () => {
+            console.debug("Closing WebWorker");
+            port.close();
+            if (webworker instanceof Worker) {
+                webworker.terminate();
+            }
+        },
+    );
+
+    await _init(port, wasm);
+    port.addEventListener("message", (json: MessageEvent<Uint8Array>) => {
+        client.handle_response(json.data);
+    });
+
+    return client;
+}
+
+/**
+ * Create a new client connected via WebSocket to a server implemnting the
+ * Perspective Protocol.
+ * @param module
+ * @param url
+ * @returns
+ */
+export async function websocket(
+    module: Promise<typeof psp>,
+    url: string | URL,
+) {
+    const { Client } = await module;
+    return await psp_websocket.websocket(WebSocket, Client, url);
+}
+
+export default { websocket, worker };

package/src/ts/wasm/decompress.ts

@@ -0,0 +1,64 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+// @ts-ignore
+import { extract } from "pro_self_extracting_wasm";
+
+if (typeof WebAssembly === "undefined") {
+    throw new Error("WebAssembly not supported.");
+}
+
+interface Module extends WebAssembly.Exports {
+    size(): number;
+    offset(): number;
+    memory: WebAssembly.Memory;
+}
+
+// Perform a silly dance to deal with the different ways webpack and esbuild
+// load binary, as this may either be an `ArrayBuffer` or `URL` depending
+// on whether `inline` option was specified to `perspective-esbuild-plugin`.
+async function compile(
+    buffer: ArrayBuffer | Response | WebAssembly.Module | WebAssembly.Exports,
+): Promise<Module> {
+    if (buffer instanceof Response) {
+        return (await WebAssembly.instantiateStreaming(buffer)).instance
+            .exports as Module;
+    } else if (buffer instanceof WebAssembly.Module) {
+        return (await WebAssembly.instantiate(buffer)).exports as Module;
+    } else if (buffer instanceof WebAssembly.Instance) {
+        return buffer.exports as Module;
+    } else if (buffer instanceof ArrayBuffer) {
+        return (await WebAssembly.instantiate(buffer as BufferSource)).instance
+            .exports as Module;
+    } else {
+        return buffer as Module;
+    }
+}
+
+export async function load_wasm_stage_0(
+    wasm:
+        | ArrayBuffer
+        | Response
+        | WebAssembly.Module
+        | (() => Promise<ArrayBuffer>),
+): Promise<Uint8Array> {
+    if (wasm instanceof Function) {
+        wasm = await wasm();
+    }
+
+    try {
+        return await extract(wasm as ArrayBuffer);
+    } catch (e) {
+        console.warn("Stage 0 wasm loading failed, skipping");
+        return new Uint8Array(wasm as ArrayBuffer);
+    }
+}

package/src/ts/wasm/emscripten_api.ts

@@ -0,0 +1,63 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import * as perspective_server from "./perspective-server.poly.ts";
+export type * from "../../../dist/wasm/perspective-js.js";
+import type * as perspective_server_t from "@perspective-dev/server/dist/wasm/perspective-server.js";
+
+export type PspPtr = BigInt | number;
+export type EmscriptenServer = bigint | number;
+
+export async function compile_perspective(
+    wasmBinary: ArrayBuffer,
+): Promise<perspective_server_t.MainModule> {
+    const module = await perspective_server.default({
+        locateFile(x: any) {
+            return x;
+        },
+        instantiateWasm: async (
+            imports: any,
+            receive: (_: WebAssembly.Instance) => void,
+        ) => {
+            imports["env"] = {
+                ...imports["env"],
+                psp_stack_trace() {
+                    const str = Error().stack || "";
+                    const textEncoder = new TextEncoder();
+                    const bytes = textEncoder.encode(str);
+                    const ptr = module._psp_alloc(
+                        module._psp_is_memory64()
+                            ? (BigInt(bytes.byteLength + 1) as any as number)
+                            : bytes.byteLength + 1,
+                    );
+
+                    module.HEAPU8.set(bytes, Number(ptr));
+                    module.HEAPU8[Number(ptr) + bytes.byteLength] = 0;
+                    return ptr;
+                },
+                psp_heap_size() {
+                    if (module._psp_is_memory64()) {
+                        return BigInt(module.HEAPU8.buffer.byteLength);
+                    } else {
+                        return module.HEAPU8.buffer.byteLength;
+                    }
+                },
+            };
+
+            const webasm = await WebAssembly.instantiate(wasmBinary, imports);
+            receive(webasm.instance);
+            return webasm.instance.exports;
+        },
+    });
+
+    return module;
+}

package/src/ts/wasm/engine.ts

@@ -0,0 +1,271 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import type { MainModule } from "@perspective-dev/server/dist/wasm/perspective-server.js";
+import type { EmscriptenServer, PspPtr } from "./emscripten_api.ts";
+
+export type ApiResponse = {
+    client_id: number;
+    data: Uint8Array;
+};
+
+export interface PerspectiveServerOptions {
+    on_poll_request?: (x: PerspectiveServer) => Promise<void>;
+}
+
+export class PerspectivePollThread {
+    private poll_handle?: Promise<void>;
+    private server: PerspectiveServer;
+    constructor(server: PerspectiveServer) {
+        this.server = server;
+    }
+
+    private set_poll_handle() {
+        this.poll_handle = new Promise((resolve, reject) =>
+            setTimeout(() =>
+                this.server
+                    .poll()
+                    .then(resolve)
+                    .catch(reject)
+                    .finally(() => {
+                        this.poll_handle = undefined;
+                    }),
+            ),
+        );
+
+        return this.poll_handle;
+    }
+
+    async on_poll_request() {
+        if (!this.poll_handle) {
+            await this.set_poll_handle();
+        } else {
+            await this.poll_handle.then(() => {
+                if (!this.poll_handle) {
+                    return this.set_poll_handle();
+                }
+            });
+        }
+    }
+}
+
+export class PerspectiveServer {
+    clients: Map<number, (buffer: Uint8Array) => Promise<void>>;
+    server: EmscriptenServer;
+    module: MainModule;
+    on_poll_request?: (x: PerspectiveServer) => Promise<void>;
+    constructor(module: MainModule, options?: PerspectiveServerOptions) {
+        this.clients = new Map();
+        this.module = module;
+        this.on_poll_request = options?.on_poll_request;
+        this.server = module._psp_new_server(
+            !!options?.on_poll_request ? 1 : 0,
+        ) as EmscriptenServer;
+    }
+
+    /**
+     * Helper function to create server emitter/receiver pairs
+     */
+    make_session(
+        callback: (buffer: Uint8Array) => Promise<void>,
+    ): PerspectiveSession {
+        const client_id = this.module._psp_new_session(this.server as any);
+        this.clients.set(client_id, callback);
+        return new PerspectiveSession(
+            this.module,
+            this.server,
+            client_id,
+            this.clients,
+            this.on_poll_request && (() => this.on_poll_request!(this)),
+        );
+    }
+
+    async poll() {
+        const polled = this.module._psp_poll(this.server as any);
+        await decode_api_responses(
+            this.module,
+            polled,
+            async (msg: ApiResponse) => {
+                await this.clients.get(msg.client_id)!(msg.data);
+            },
+        );
+    }
+
+    delete() {
+        this.module._psp_delete_server(this.server as any);
+    }
+}
+
+export class PerspectiveSession {
+    constructor(
+        private mod: MainModule,
+        private server: EmscriptenServer,
+        private client_id: number,
+        private client_map: Map<number, (buffer: Uint8Array) => Promise<void>>,
+        private on_poll_request?: () => Promise<void>,
+    ) {}
+
+    async handle_request(view: Uint8Array) {
+        const ptr = await convert_typed_array_to_pointer(
+            this.mod,
+            view,
+            async (viewPtr) => {
+                return this.mod._psp_handle_request(
+                    this.server as any,
+                    this.client_id,
+                    viewPtr as any,
+                    this.mod._psp_is_memory64()
+                        ? (BigInt(view.byteLength) as any as number)
+                        : (view.byteLength as any),
+                );
+            },
+        );
+
+        await decode_api_responses(this.mod, ptr, async (msg: ApiResponse) => {
+            await this.client_map.get(msg.client_id)!(msg.data);
+        });
+
+        if (this.on_poll_request) {
+            await this.on_poll_request();
+        } else {
+            await this.poll();
+        }
+    }
+
+    private async poll() {
+        const polled = this.mod._psp_poll(this.server as any);
+        await decode_api_responses(
+            this.mod,
+            polled,
+            async (msg: ApiResponse) => {
+                if (msg.client_id === 0) {
+                    await this.client_map.get(this.client_id)!(msg.data);
+                } else {
+                    await this.client_map.get(msg.client_id)!(msg.data);
+                }
+            },
+        );
+    }
+
+    close() {
+        this.mod._psp_close_session(this.server as any, this.client_id);
+    }
+}
+
+async function convert_typed_array_to_pointer(
+    core: MainModule,
+    array: Uint8Array,
+    callback: (_: PspPtr) => Promise<PspPtr>,
+): Promise<PspPtr> {
+    const ptr = core._psp_alloc(
+        core._psp_is_memory64()
+            ? (BigInt(array.byteLength) as any as number)
+            : (array.byteLength as any),
+    );
+
+    core.HEAPU8.set(array, Number(ptr));
+    const msg = await callback(ptr);
+    core._psp_free(ptr);
+    return msg;
+}
+
+/**
+ * Convert a pointer to WASM memory into an `ApiResponse[]`, via a custom
+ * encoding.
+ *
+ * @param core The emscripten API
+ * @param ptr A pointer to a fixed-sized struct representing a set of
+ * `proto::Resp` payloads, encoded as a length-prefixed array of
+ * (char* data, u32_t len, u32_t client_id) tuples:
+ *
+ * ```text
+ *   N   data    length   client_id   data    length   client_id
+ * +-------------------------------------------------------------+
+ * | 2 | 0xabc | 9      | 0         | 0xdef | 12     | 0         |
+ * +-------------------------------------------------------------+
+ *       |                           |
+ *       |  +-------------+          |  +----------------+
+ *       +--| "Test Data" |          +--| "Hello, World" |
+ *          +-------------+             +----------------+
+ * ```
+ *
+ * @param callback A callback to which is passed the responses. THe responses
+ * must be fully processed or copied before the callback returns, as it
+ * references memory on the wasm stack.
+ */
+async function decode_api_responses(
+    core: MainModule,
+    ptr: PspPtr,
+    callback: (_: ApiResponse) => Promise<void>,
+) {
+    const is_64 = core._psp_is_memory64();
+    const response = new DataView(
+        core.HEAPU8.buffer,
+        Number(ptr),
+        is_64 ? 12 : 8,
+    );
+
+    const num_msgs = response.getUint32(0, true);
+    const msgs_ptr = is_64
+        ? response.getBigInt64(4, true)
+        : response.getUint32(4, true);
+
+    const messages = new DataView(
+        core.HEAPU8.buffer,
+        Number(msgs_ptr),
+        num_msgs * (is_64 ? 16 : 12),
+    );
+
+    try {
+        for (let i = 0; i < num_msgs; i++) {
+            const [data_ptr, data_len, client_id] = is_64
+                ? [
+                      messages.getBigInt64(i * 16, true),
+                      messages.getInt32(i * 16 + 8, true),
+                      messages.getInt32(i * 16 + 12, true),
+                  ]
+                : [
+                      messages.getInt32(i * 12, true),
+                      messages.getInt32(i * 12 + 4, true),
+                      messages.getInt32(i * 12 + 8, true),
+                  ];
+
+            const data = new Uint8Array(
+                core.HEAPU8.buffer,
+                Number(data_ptr),
+                data_len,
+            );
+
+            const resp = { client_id, data };
+            await callback(resp);
+        }
+    } finally {
+        for (let i = 0; i < num_msgs; i++) {
+            const data_ptr = is_64
+                ? messages.getBigInt64(i * 16, true)
+                : messages.getInt32(i * 12, true);
+
+            core._psp_free(data_ptr as any);
+        }
+
+        core._psp_free(
+            is_64
+                ? (BigInt(messages.byteOffset) as any as number)
+                : (messages.byteOffset as any),
+        );
+        core._psp_free(
+            is_64
+                ? (BigInt(response.byteOffset) as any as number)
+                : (response.byteOffset as any),
+        );
+    }
+}