@scoova/mgl 1.0.0

package/src/util/abort_error.ts

@@ -0,0 +1,21 @@
+/**
+ * An error message to use when an operation is aborted
+ */
+export const ABORT_ERROR = 'AbortError';
+
+/**
+ * Check if an error is an abort error
+ * @param error - An error object
+ * @returns - true if the error is an abort error
+ */
+export function isAbortError(error: Error): boolean {
+    return error.message === ABORT_ERROR;
+}
+
+/**
+ * Use this when you need to create an abort error.
+ * @returns An error object with the message "AbortError"
+ */
+export function createAbortError(): Error {
+    return new Error(ABORT_ERROR);
+}

package/src/util/actor.test.ts

@@ -0,0 +1,218 @@
+import {Actor, ActorTarget} from './actor';
+import {WorkerGlobalScopeInterface, workerFactory} from './web_worker';
+import {setGlobalWorker} from '../../test/unit/lib/web_worker_mock';
+import {sleep} from './test/util';
+import {ABORT_ERROR, createAbortError} from './abort_error';
+import {MessageType} from './actor_messages';
+
+class MockWorker {
+    self: any;
+    actor: Actor;
+    constructor(self) {
+        this.self = self;
+        this.actor = new Actor(self);
+    }
+}
+
+describe('Actor', () => {
+    let originalWorker;
+    beforeAll(() => {
+        originalWorker = global.Worker;
+        setGlobalWorker(MockWorker);
+    });
+    afterAll(() => {
+        global.Worker = originalWorker;
+    });
+
+    test('forwards responses to correct handler', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, async (_mapId, params) => {
+            await sleep(0);
+            return params.clusterId;
+        });
+
+        const m1 = new Actor(worker, '1');
+        const m2 = new Actor(worker, '2');
+
+        const p1 = m1.sendAsync({type: MessageType.getClusterExpansionZoom, data: {type: 'geojson', source: '', clusterId: 1729}});
+        const p2 = m2.sendAsync({type: MessageType.getClusterExpansionZoom, data: {type: 'geojson', source: '', clusterId: 4104}});
+
+        await Promise.all([p1, p2]);
+        await expect(p1).resolves.toBe(1729);
+        await expect(p2).resolves.toBe(4104);
+    });
+
+    test('cancel a request does not reject or resolve a promise', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, async (_mapId, params) => {
+            await sleep(200);
+            return params.clusterId;
+        });
+
+        const m1 = new Actor(worker, '1');
+
+        let received = false;
+        const abortController = new AbortController();
+        const p1 = m1.sendAsync({type: MessageType.getClusterExpansionZoom, data: {type: 'geojson', source: '', clusterId: 1729}}, abortController)
+            .then(() => { received = true; })
+            .catch(() => { received = true; });
+
+        abortController.abort();
+
+        const p2 = new Promise((resolve) => (setTimeout(resolve, 500)));
+
+        await Promise.any([p1, p2]);
+        expect(received).toBeFalsy();
+    });
+
+    test('aborting a request will successfully abort it', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        let gotAbortSignal = false;
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, (_mapId, _params, handlerAbortController) => {
+            return new Promise((resolve, reject) => {
+                handlerAbortController.signal.addEventListener('abort', () => {
+                    gotAbortSignal = true;
+                    reject(createAbortError());
+                });
+                setTimeout(resolve, 200);
+            });
+        });
+
+        const m1 = new Actor(worker, '1');
+
+        let received = false;
+        const abortController = new AbortController();
+        m1.sendAsync({type: MessageType.getClusterExpansionZoom, data: {type: 'geojson', source: '', clusterId: 1729}}, abortController)
+            .then(() => { received = true; })
+            .catch(() => { received = true; });
+
+        abortController.abort();
+
+        await sleep(500);
+
+        expect(received).toBeFalsy();
+        expect(gotAbortSignal).toBeTruthy();
+    });
+
+    test('cancel a request that must be queued will not call the method at all', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        const spy = jest.fn().mockReturnValue(Promise.resolve({}));
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, spy);
+
+        let received = false;
+        const abortController = new AbortController();
+        const p1 = actor.sendAsync({type: MessageType.getClusterExpansionZoom, data: {type: 'geojson', source: '', clusterId: 1729}, mustQueue: true}, abortController)
+            .then(() => { received = true; })
+            .catch(() => { received = true; });
+
+        abortController.abort();
+
+        const p2 = new Promise((resolve) => (setTimeout(resolve, 500)));
+
+        await Promise.any([p1, p2]);
+        expect(received).toBeFalsy();
+        expect(spy).not.toHaveBeenCalled();
+    });
+
+    test('#remove unbinds event listener', () => new Promise<void>(done => {
+        const actor = new Actor({
+            addEventListener(type, callback, useCapture) {
+                this._addEventListenerArgs = [type, callback, useCapture];
+            },
+            removeEventListener(type, callback, useCapture) {
+                expect([type, callback, useCapture]).toEqual(this._addEventListenerArgs);
+                done();
+            }
+        } as ActorTarget, null);
+        actor.remove();
+    }));
+
+    test('send a message that is rejected', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        worker.worker.actor.registerMessageHandler(MessageType.abortTile, () => Promise.reject(createAbortError()));
+
+        await expect(async () => actor.sendAsync({type: MessageType.abortTile, data: {} as any})).rejects.toThrow(ABORT_ERROR);
+    });
+
+    test('send a message that must be queued, it should still arrive', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, () => Promise.resolve(42));
+
+        const response = await actor.sendAsync({type: MessageType.getClusterExpansionZoom, data: {} as any, mustQueue: true});
+
+        expect(response).toBe(42);
+    });
+
+    test('send a message is not registered should throw', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, () => Promise.resolve(42));
+
+        await expect(async () => actor.sendAsync({type: MessageType.abortTile, data: {} as any})).rejects.toThrow(/Could not find a registered handler for.*/);
+    });
+
+    test('should not process a message with the wrong map id', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        worker.worker.actor.mapId = '2';
+
+        const spy = jest.fn().mockReturnValue(Promise.resolve({}));
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, spy);
+
+        actor.sendAsync({type: MessageType.getClusterExpansionZoom, data: {} as any, targetMapId: '1'});
+
+        await sleep(100);
+
+        expect(spy).not.toHaveBeenCalled();
+    });
+
+    test('should not process a message with the wrong origin', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        const spy = jest.fn().mockReturnValue(Promise.resolve({}));
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, spy);
+
+        actor.target.postMessage({type: 'getClusterExpansionZoom', data: {} as any, origin: 'https://example.com'});
+
+        await sleep(100);
+
+        expect(spy).not.toHaveBeenCalled();
+    });
+
+    test('should process a message when origin is "file://"', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        const spy = jest.fn().mockReturnValue(Promise.resolve({}));
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, spy);
+
+        actor.target.postMessage({type: MessageType.getClusterExpansionZoom, data: {} as any, origin: 'file://'});
+
+        await sleep(0);
+
+        expect(spy).toHaveBeenCalled();
+    });
+
+    test('should process a message when origin is "resource://android"', async () => {
+        const worker = workerFactory() as any as WorkerGlobalScopeInterface & ActorTarget;
+        const actor = new Actor(worker, '1');
+
+        const spy = jest.fn().mockReturnValue(Promise.resolve({}));
+        worker.worker.actor.registerMessageHandler(MessageType.getClusterExpansionZoom, spy);
+
+        actor.target.postMessage({type: MessageType.getClusterExpansionZoom, data: {} as any, origin: 'resource://android'});
+
+        await sleep(0);
+
+        expect(spy).toHaveBeenCalled();
+    });
+});

package/src/util/actor.ts

@@ -0,0 +1,241 @@
+import {Subscription, isWorker, subscribe} from './util';
+import {serialize, deserialize, Serialized} from './web_worker_transfer';
+import {ThrottledInvoker} from './throttled_invoker';
+
+import {
+    MessageType,
+    type ActorMessage,
+    type RequestResponseMessageMap} from './actor_messages';
+
+/**
+ * An interface to be sent to the actor in order for it to allow communication between the worker and the main thread
+ */
+export interface ActorTarget {
+    addEventListener: typeof window.addEventListener;
+    removeEventListener: typeof window.removeEventListener;
+    postMessage: typeof window.postMessage;
+    terminate?: () => void;
+}
+
+/**
+ * This is used to define the parameters of the message that is sent to the worker and back
+ */
+type MessageData = {
+    id: string;
+    type: MessageType | '<cancel>' | '<response>';
+    origin: string;
+    data?: Serialized;
+    targetMapId?: string | number | null;
+    mustQueue?: boolean;
+    error?: Serialized | null;
+    sourceMapId: string | number | null;
+}
+
+type ResolveReject = {
+    resolve: (value?: RequestResponseMessageMap[MessageType][1]) => void;
+    reject: (reason?: Error) => void;
+}
+
+/**
+ * This interface allowing to substitute only the sendAsync method of the Actor class.
+ */
+export interface IActor {
+    sendAsync<T extends MessageType>(message: ActorMessage<T>, abortController?: AbortController): Promise<RequestResponseMessageMap[T][1]>;
+}
+
+export type MessageHandler<T extends MessageType> = (mapId: string | number, params: RequestResponseMessageMap[T][0], abortController?: AbortController) => Promise<RequestResponseMessageMap[T][1]>
+
+/**
+ * An implementation of the [Actor design pattern](https://en.wikipedia.org/wiki/Actor_model)
+ * that maintains the relationship between asynchronous tasks and the objects
+ * that spin them off - in this case, tasks like parsing parts of styles,
+ * owned by the styles
+ */
+export class Actor implements IActor {
+    target: ActorTarget;
+    mapId: string | number | null;
+    resolveRejects: { [x: string]: ResolveReject};
+    name: string;
+    tasks: { [x: string]: MessageData };
+    taskQueue: Array<string>;
+    abortControllers: { [x: number | string]: AbortController };
+    invoker: ThrottledInvoker;
+    globalScope: ActorTarget;
+    messageHandlers: { [x in MessageType]?: MessageHandler<MessageType>};
+    subscription: Subscription;
+
+    /**
+     * @param target - The target
+     * @param mapId - A unique identifier for the Map instance using this Actor.
+     */
+    constructor(target: ActorTarget, mapId?: string | number) {
+        this.target = target;
+        this.mapId = mapId;
+        this.resolveRejects = {};
+        this.tasks = {};
+        this.taskQueue = [];
+        this.abortControllers = {};
+        this.messageHandlers = {};
+        this.invoker = new ThrottledInvoker(() => this.process());
+        this.subscription = subscribe(this.target, 'message', (message) => this.receive(message), false);
+        this.globalScope = isWorker(self) ? target : window;
+    }
+
+    registerMessageHandler<T extends MessageType>(type: T, handler: MessageHandler<T>) {
+        this.messageHandlers[type] = handler;
+    }
+
+    /**
+     * Sends a message from a main-thread map to a Worker or from a Worker back to
+     * a main-thread map instance.
+     * @param message - the message to send
+     * @param abortController - an optional AbortController to abort the request
+     * @returns a promise that will be resolved with the response data
+     */
+    sendAsync<T extends MessageType>(message: ActorMessage<T>, abortController?: AbortController): Promise<RequestResponseMessageMap[T][1]> {
+        return new Promise((resolve, reject) => {
+            // We're using a string ID instead of numbers because they are being used as object keys
+            // anyway, and thus stringified implicitly. We use random IDs because an actor may receive
+            // message from multiple other actors which could run in different execution context. A
+            // linearly increasing ID could produce collisions.
+            const id = Math.round((Math.random() * 1e18)).toString(36).substring(0, 10);
+            this.resolveRejects[id] = {
+                resolve,
+                reject
+            };
+            if (abortController) {
+                abortController.signal.addEventListener('abort', () => {
+                    delete this.resolveRejects[id];
+                    const cancelMessage: MessageData = {
+                        id,
+                        type: '<cancel>',
+                        origin: location.origin,
+                        targetMapId: message.targetMapId,
+                        sourceMapId: this.mapId
+                    };
+                    this.target.postMessage(cancelMessage);
+                    // In case of abort the current behavior is to keep the promise pending.
+                }, {once: true});
+            }
+            const buffers: Array<Transferable> = [];
+            const messageToPost: MessageData = {
+                ...message,
+                id,
+                sourceMapId: this.mapId,
+                origin: location.origin,
+                data: serialize(message.data, buffers)
+            };
+            this.target.postMessage(messageToPost, {transfer: buffers});
+        });
+    }
+
+    receive(message: {data: MessageData}) {
+        const data = message.data;
+        const id = data.id;
+        if (data.origin !== 'file://' && location.origin !== 'file://' && data.origin !== 'resource://android' && location.origin !== 'resource://android' && data.origin !== location.origin) {
+            return;
+        }
+        if (data.targetMapId && this.mapId !== data.targetMapId) {
+            return;
+        }
+        if (data.type === '<cancel>') {
+            // Remove the original request from the queue. This is only possible if it
+            // hasn't been kicked off yet. The id will remain in the queue, but because
+            // there is no associated task, it will be dropped once it's time to execute it.
+            delete this.tasks[id];
+            const abortController = this.abortControllers[id];
+            delete this.abortControllers[id];
+            if (abortController) {
+                abortController.abort();
+            }
+            return;
+        }
+        if (isWorker(self) || data.mustQueue) {
+            // In workers, store the tasks that we need to process before actually processing them. This
+            // is necessary because we want to keep receiving messages, and in particular,
+            // <cancel> messages. Some tasks may take a while in the worker thread, so before
+            // executing the next task in our queue, postMessage preempts this and <cancel>
+            // messages can be processed. We're using a MessageChannel object to get throttle the
+            // process() flow to one at a time.
+            this.tasks[id] = data;
+            this.taskQueue.push(id);
+            this.invoker.trigger();
+            return;
+        }
+        // In the main thread, process messages immediately so that other work does not slip in
+        // between getting partial data back from workers.
+        this.processTask(id, data);
+    }
+
+    process() {
+        if (this.taskQueue.length === 0) {
+            return;
+        }
+        const id = this.taskQueue.shift();
+        const task = this.tasks[id];
+        delete this.tasks[id];
+        // Schedule another process call if we know there's more to process _before_ invoking the
+        // current task. This is necessary so that processing continues even if the current task
+        // doesn't execute successfully.
+        if (this.taskQueue.length > 0) {
+            this.invoker.trigger();
+        }
+        if (!task) {
+            // If the task ID doesn't have associated task data anymore, it was canceled.
+            return;
+        }
+
+        this.processTask(id, task);
+    }
+
+    async processTask(id: string, task: MessageData) {
+        if (task.type === '<response>') {
+            // The `completeTask` function in the counterpart actor has been called, and we are now
+            // resolving or rejecting the promise in the originating actor, if there is one.
+            const resolveReject = this.resolveRejects[id];
+            delete this.resolveRejects[id];
+            if (!resolveReject) {
+                // If we get a response, but don't have a resolve or reject, the request was canceled.
+                return;
+            }
+            if (task.error) {
+                resolveReject.reject(deserialize(task.error) as Error);
+            } else {
+                resolveReject.resolve(deserialize(task.data));
+            }
+            return;
+        }
+        if (!this.messageHandlers[task.type]) {
+            this.completeTask(id, new Error(`Could not find a registered handler for ${task.type}, map ID: ${this.mapId}, available handlers: ${Object.keys(this.messageHandlers).join(', ')}`));
+            return;
+        }
+        const params = deserialize(task.data) as RequestResponseMessageMap[MessageType][0];
+        const abortController = new AbortController();
+        this.abortControllers[id] = abortController;
+        try {
+            const data = await this.messageHandlers[task.type](task.sourceMapId, params, abortController);
+            this.completeTask(id, null, data);
+        } catch (err) {
+            this.completeTask(id, err);
+        }
+    }
+
+    completeTask(id: string, err: Error, data?: RequestResponseMessageMap[MessageType][1]) {
+        const buffers: Array<Transferable> = [];
+        delete this.abortControllers[id];
+        const responseMessage: MessageData = {
+            id,
+            type: '<response>',
+            sourceMapId: this.mapId,
+            origin: location.origin,
+            error: err ? serialize(err) : null,
+            data: serialize(data, buffers)
+        };
+        this.target.postMessage(responseMessage, {transfer: buffers});
+    }
+
+    remove() {
+        this.invoker.remove();
+        this.subscription.unsubscribe();
+    }
+}

package/src/util/actor_messages.ts

@@ -0,0 +1,149 @@
+import type {LoadGeoJSONParameters} from '../source/geojson_worker_source';
+import type {TileParameters, WorkerDEMTileParameters, WorkerTileParameters, WorkerTileResult} from '../source/worker_source';
+import type {DEMData} from '../data/dem_data';
+import type {StyleImage} from '../style/style_image';
+import type {StyleGlyph} from '../style/style_glyph';
+import type {PluginState} from '../source/rtl_text_plugin_status';
+import type {LayerSpecification} from '@maplibre/maplibre-gl-style-spec';
+import type {OverscaledTileID} from '../source/tile_id';
+import type {GetResourceResponse, RequestParameters} from './ajax';
+
+/**
+ * The parameters needed in order to get information about the cluster
+ */
+export type ClusterIDAndSource = {
+    type: 'geojson';
+    clusterId: number;
+    source: string;
+};
+
+/**
+ * Parameters needed to get the leaves of a cluster
+ */
+export type GetClusterLeavesParams = ClusterIDAndSource & { limit: number; offset: number };
+
+/**
+ * The result of the call to load a geojson source
+ */
+export type GeoJSONWorkerSourceLoadDataResult = {
+    resourceTiming?: {[_: string]: Array<PerformanceResourceTiming>};
+    abandoned?: boolean;
+};
+
+/**
+ * Parameters needed to remove a source
+ */
+export type RemoveSourceParams = {
+    source: string;
+    type: string;
+}
+
+/**
+ * Parameters needed to update the layers
+ */
+export type UpdateLayersParamaeters = {
+    layers: Array<LayerSpecification>;
+    removedIds: Array<string>;
+}
+
+/**
+ * Parameters needed to get the images
+ */
+export type GetImagesParameters = {
+    icons: Array<string>;
+    source: string;
+    tileID: OverscaledTileID;
+    type: string;
+}
+
+/**
+ * Parameters needed to get the glyphs
+ */
+export type GetGlyphsParameters = {
+    type: string;
+    stacks: {[_: string]: Array<number>};
+    source: string;
+    tileID: OverscaledTileID;
+}
+
+/**
+ * A response object returned when requesting glyphs
+ */
+export type GetGlyphsResponse = {
+    [stack: string]: {
+        [id: number]: StyleGlyph;
+    };
+}
+
+/**
+ * A response object returned when requesting images
+ */
+export type GetImagesResponse = {[_: string]: StyleImage}
+
+/**
+ * All the possible message types that can be sent to and from the worker
+ */
+export const enum MessageType {
+    loadDEMTile = 'LDT',
+    getClusterExpansionZoom = 'GCEZ',
+    getClusterChildren = 'GCC',
+    getClusterLeaves = 'GCL',
+    loadData = 'LD',
+    getData = 'GD',
+    loadTile = 'LT',
+    reloadTile = 'RT',
+    getGlyphs = 'GG',
+    getImages = 'GI',
+    setImages = 'SI',
+    setLayers = 'SL',
+    updateLayers = 'UL',
+    syncRTLPluginState = 'SRPS',
+    setReferrer = 'SR',
+    removeSource = 'RS',
+    removeMap = 'RM',
+    importScript = 'IS',
+    removeTile = 'RMT',
+    abortTile = 'AT',
+    removeDEMTile = 'RDT',
+    getResource = 'GR',
+}
+
+/**
+ * This is basically a mapping between all the calls that are made to and from the workers.
+ * The key is the event name, the first parameter is the event input type, and the last parameter is the output type.
+ */
+export type RequestResponseMessageMap = {
+    [MessageType.loadDEMTile]: [WorkerDEMTileParameters, DEMData];
+    [MessageType.getClusterExpansionZoom]: [ClusterIDAndSource, number];
+    [MessageType.getClusterChildren]: [ClusterIDAndSource, Array<GeoJSON.Feature>];
+    [MessageType.getClusterLeaves]: [GetClusterLeavesParams, Array<GeoJSON.Feature>];
+    [MessageType.loadData]: [LoadGeoJSONParameters, GeoJSONWorkerSourceLoadDataResult];
+    [MessageType.getData]: [LoadGeoJSONParameters, GeoJSON.GeoJSON];
+    [MessageType.loadTile]: [WorkerTileParameters, WorkerTileResult];
+    [MessageType.reloadTile]: [WorkerTileParameters, WorkerTileResult];
+    [MessageType.getGlyphs]: [GetGlyphsParameters, GetGlyphsResponse];
+    [MessageType.getImages]: [GetImagesParameters, GetImagesResponse];
+    [MessageType.setImages]: [string[], void];
+    [MessageType.setLayers]: [Array<LayerSpecification>, void];
+    [MessageType.updateLayers]: [UpdateLayersParamaeters, void];
+    [MessageType.syncRTLPluginState]: [PluginState, PluginState];
+    [MessageType.setReferrer]: [string, void];
+    [MessageType.removeSource]: [RemoveSourceParams, void];
+    [MessageType.removeMap]: [undefined, void];
+    [MessageType.importScript]: [string, void];
+    [MessageType.removeTile]: [TileParameters, void];
+    [MessageType.abortTile]: [TileParameters, void];
+    [MessageType.removeDEMTile]: [TileParameters, void];
+    [MessageType.getResource]: [RequestParameters, GetResourceResponse<any>];
+}
+
+/**
+ * The message to be sent by the actor
+ */
+export type ActorMessage<T extends MessageType> = {
+    type: T;
+    data: RequestResponseMessageMap[T][0];
+    targetMapId?: string | number | null;
+    mustQueue?: boolean;
+    sourceMapId?: string | number | null;
+};