@alterior/tasks 3.5.3 → 3.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alterior/tasks",
-  "version": "3.5.3",
+  "version": "3.5.6",
   "description": "Flexible background task system",
   "author": "The Alterior Project (https://github.com/alterior-mvc)",
   "license": "MIT",
@@ -40,11 +40,11 @@
     "docs": "typedoc ."
   },
   "dependencies": {
-    "@alterior/annotations": "^3.4.0",
+    "@alterior/annotations": "^3.5.6",
     "@alterior/common": "^3.4.0",
-    "@alterior/di": "^3.5.3",
-    "@alterior/logging": "^3.5.3",
-    "@alterior/runtime": "^3.5.3",
+    "@alterior/di": "^3.5.6",
+    "@alterior/logging": "^3.5.6",
+    "@alterior/runtime": "^3.5.6",
     "bull": "^3.18.0",
     "kind-of": ">=6.0.3",
     "tslib": "^2.3.1"
@@ -60,5 +60,5 @@
     "swagger-editor-dist": "^3.9.0",
     "wtfnode": "^0.7.0"
   },
-  "gitHead": "808d85ec078d91261d8388c717d77c02aefc568a"
+  "gitHead": "220e169fc8c855dc0935620bdb5efb1e9a2b86a7"
 }

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './tasks';
+export * from './task-runner';
+export * from './task-worker';
+
+export * from './tasks.module';

package/src/task-runner.ts

@@ -0,0 +1,33 @@
+import { Injectable, Inject } from "@alterior/di";
+import { QUEUE_OPTIONS, TaskJob, TaskAnnotation, TaskModuleOptionsRef, TaskModuleOptions, TaskWorkerRegistry, Constructor, Worker, RemoteWorker, RemoteService } from "./tasks";
+import { InvalidOperationError, ArgumentError } from "@alterior/common";
+
+@Injectable()
+export class TaskRunner {
+    constructor(
+        private _registry : TaskWorkerRegistry
+    ) {
+    }
+
+    get registry() {
+        return this._registry;
+    }
+
+    /**
+     * Acquire a Remote for the given service where any calls to the remote will 
+     * resolve to a QueueJob which can be further interacted with. Promise will 
+     * resolve once the item has been successfully delivered to the event queue.
+     */
+    worker<T extends Worker>(workerClass : Constructor<T>): RemoteWorker<T> {
+        return this.registry.get<T>(workerClass).async;
+    }
+
+    /**
+     * Acquire a Remote for the given service where any calls to the remote will await 
+     * the full completion of the remote call and resolve to the return value of the 
+     * remote function. If you only want to enqueue a task, use `worker()` instead.
+     */
+    service<T extends Worker>(workerClass : Constructor<T>): RemoteService<T> {
+        return this.registry.get<T>(workerClass).sync;
+    }
+}

package/src/task-worker.ts

@@ -0,0 +1,136 @@
+import { InvalidOperationError, ArgumentError, ArgumentNullError } from "@alterior/common";
+import { Injector, Provider, ReflectiveInjector } from "@alterior/di";
+import { TaskAnnotation, TaskJob, TaskModuleOptions, TaskQueueClient, Worker } from "./tasks";
+import { ApplicationOptions } from "@alterior/runtime";
+import { Type } from "@alterior/runtime";
+import * as Queue from "bull";
+import { Logger } from "@alterior/logging";
+import * as util from 'util';
+
+export interface TaskHandler {
+	worker : Worker;
+    handler : (methodName : string, args : any[]) => Promise<any>;
+}
+
+export class TaskWorker {
+    constructor(
+		private _injector : Injector,
+		private _client : TaskQueueClient,
+        private _options : TaskModuleOptions,
+		private _appOptions : ApplicationOptions,
+		private _logger : Logger
+    ) {
+		if (!_injector)
+			throw new ArgumentNullError(`injector`);
+
+		if (!_options)
+			throw new ArgumentNullError(`options`);
+
+		if (!_appOptions)
+			throw new ArgumentNullError(`appOptions`);
+
+    }
+
+    public get injector() {
+        return this._injector;
+    }
+
+    public get options() {
+        return this._options;
+    }
+
+    public get appOptions() {
+        return this._appOptions;
+    }
+
+    private _taskHandlers = {};
+
+	get queue() {
+		return this._client.queue;
+	}
+
+	stop() {
+		this.queue.close();
+	}
+
+	start() {
+		this.queue.process(async (job : Queue.Job<TaskJob>, done) => {
+			let task = job.data;
+
+			if (!task || !task.id) {
+				console.log(`TaskWorker: Could not process invalid task:`);
+				console.dir(task, { depth: 3 });
+				console.log(`Associated job data:`);
+				console.dir(job, { depth: 3 });
+
+				await job.discard();
+
+				done(new Error(`Invalid job task`), null);
+			}
+
+			let handler : TaskHandler = this._taskHandlers[task.id];
+
+			if (!handler) {
+				console.error(`No handler for task ID '${task.id}'! Check that your worker class declares this task ID!`);
+				
+				console.info(`Task was: `);
+				console.dir(task, { depth: 3 });
+
+				console.info(`Registered worker IDs: ${Object.keys(this._taskHandlers).join(', ')}`);
+			}
+
+			await this._logger.withContext(
+				{ host: 'tasks', worker: handler.worker }, 
+				`TaskWorker | ${handler.worker.constructor.name}.${task.method}(${task.args.map(x => util.inspect(x, false, 2)).join(', ')})`, 
+				async () => {
+					this._logger.info(`TaskWorker: ${task.method}() of worker ${handler.worker.constructor.name} (ID '${task.id}')`);
+					try {
+						let result = await handler.handler(task.method, task.args);
+						done(undefined, result);
+					} catch (e) {
+						console.error(`Caught error while running task ${job.data.id}.${job.data.method || 'execute'}():`);
+						console.error(e);
+						
+						done(e);
+					}
+				}
+			);
+		});
+	}
+
+    registerHandler(name : string, handler : TaskHandler) {
+        this._taskHandlers[name] = handler;
+	}
+	
+	registerClasses(taskClasses : Function[]) {
+
+		let providers : Provider[] = taskClasses as Provider[];
+        let ownInjector = ReflectiveInjector.resolveAndCreate(providers, this.injector);
+		let allRoutes = [];
+
+		let tasks = taskClasses.map(taskClass => {
+
+			let id = taskClass.name;
+			let annotation = TaskAnnotation.getForClass(taskClass);
+			let instance : Worker = ownInjector.get(taskClass);
+
+			if (instance.name)
+				id = instance.name;
+
+			if (annotation && annotation.id)
+				id = annotation.id;
+
+			this.registerHandler(id, {
+				worker: instance,
+				handler: async (methodName, args) => {
+					let impl = instance.constructor.prototype[methodName];
+
+					if (typeof impl !== 'function' || methodName.startsWith('_'))
+						throw new InvalidOperationError(`Invalid task method ${methodName}`);
+					
+					return await instance[methodName](...args);
+				}
+			});
+		});
+	}
+}

package/src/tasks.module.ts

@@ -0,0 +1,99 @@
+import { Module, Injectable, Optional } from "@alterior/di";
+import { OnInit, Application, RolesService, Constructor } from "@alterior/runtime";
+import * as Queue from "bull";
+import { TaskModuleOptions, TaskModuleOptionsRef, TaskQueueClient, TaskWorkerRegistry } from "./tasks";
+import { TaskRunner } from "./task-runner";
+import { TaskWorker } from "./task-worker";
+import { Logger, LoggingModule } from "@alterior/logging";
+
+/**
+ * Import this into your application module to run tasks enqueued by other 
+ * services on a shared queue. The tasks which can be processed are specified 
+ * in the `tasks` field of one or more modules.
+ */
+@Module({
+    providers: [
+        TaskQueueClient, 
+        TaskWorkerRegistry, 
+        TaskRunner
+    ],
+    imports: [
+        LoggingModule
+    ]
+})
+export class TasksModule implements OnInit {
+    constructor(
+        private app : Application,
+        private rolesService : RolesService,
+        private client : TaskQueueClient,
+        private workerRegistry : TaskWorkerRegistry,
+        private logger : Logger,
+        @Optional() private _options : TaskModuleOptionsRef
+    ) {
+
+    }
+
+    /**
+     * Used when importing this module from the root (app) module
+     * using the default configuration.
+     * Should be called only once in the application.
+     */
+    public static forRoot() {
+        return this.configure({});
+    }
+
+    /**
+     * Create a configured version of the WebServerModule that can be then 
+     * be imported into an entry module (or feature module).
+     * @param options The options to use for the web server
+     */
+    public static configure(options : TaskModuleOptions) {
+        return {
+            $module: TasksModule,
+            providers: [
+                { provide: TaskModuleOptionsRef, useValue: new TaskModuleOptionsRef(options) }
+            ]
+        }
+    }
+
+    worker : TaskWorker;
+
+    get options(): TaskModuleOptions {
+        return this._options ? this._options.options : {} || {};
+    }
+
+    get tasks(): Function[] {
+        return [].concat(...this.app.runtime.definitions.map(x => x.metadata.tasks || []));
+    }
+
+    altOnInit() {
+
+        this.workerRegistry.registerClasses(this.tasks);
+
+        this.worker = new TaskWorker(
+            this.app.runtime.injector, 
+            this.client, 
+            this.options, 
+            this.app.options,
+            this.logger
+        );
+        this.worker.registerClasses(this.tasks);
+
+        let self = this;
+
+        this.rolesService.registerRole({
+            identifier: 'task-worker',
+            instance: this,
+            name: 'Task Worker',
+            summary: 'Pulls from the task queue and executes them using task classes registered in the module tree',
+            async start() {
+                self.worker.start();
+            },
+
+            async stop() {
+                self.worker.stop();
+            }
+        })
+
+    }
+}

package/src/tasks.ts

@@ -0,0 +1,229 @@
+import { Annotation, MetadataName, AnnotationDecorator } from "@alterior/annotations";
+import { Injectable, InjectionToken, Optional, Injector, Provider, ReflectiveInjector } from "@alterior/di";
+import BullQueue from "bull";
+
+export interface TaskModuleOptions {
+    queueName? : string;
+    queueOptions? : BullQueue.QueueOptions;
+}
+
+
+/**
+ * This injectable allows configuration of the task system. 
+ * Include a provider for the injection token `QUEUE_OPTIONS`
+ * which provides an instance of this class. 
+ * 
+ * For instance: `[ provide: QUEUE_OPTIONS, useValue: new TaskClientOptionsRef({ optionsHere }) ]`
+ * 
+ */
+@Injectable()
+export class TaskModuleOptionsRef {
+    constructor(options : TaskModuleOptions) {
+        this.options = options;
+    }
+
+    public options : TaskModuleOptions;
+}
+
+export interface TaskJob {
+    id : string;
+    method : string;
+    args : any[];
+}
+
+export const QUEUE_OPTIONS = new InjectionToken<BullQueue.QueueOptions>('QueueOptions');
+
+@MetadataName('@alterior/tasks:Task')
+export class TaskAnnotation extends Annotation {
+    constructor(readonly id? : string) {
+        super();
+    }
+}
+
+export const Task = TaskAnnotation.decorator();
+
+export abstract class Worker {
+    abstract get name() : string;
+    get options() : JobOptions { return undefined; }
+
+    protected get currentJob() : QueueJob<TaskJob> {
+        return Zone.current.get('workerStateJob');
+    }
+}
+
+export type RemoteService<T> = {
+    [P in keyof T]: 
+        T[P] extends (...args: any[]) => any ? 
+            // methods
+            (ReturnType<T[P]> extends Promise<any> ?
+                T[P] // dont modify methods that are already promises
+                : (...args : Parameters<T[P]>) => Promise<ReturnType<T[P]>>
+            )
+            // fields
+            : never
+    ;
+} & {
+    withOptions(options : JobOptions) : RemoteService<T>;
+}
+
+export type RemoteWorker<T> = {
+    [P in keyof T]: 
+        T[P] extends (...args: any[]) => any ? 
+            // methods
+            (...args : Parameters<T[P]>) => Promise<QueueJob<TaskJob>>
+            
+            // fields
+            : never
+    ;
+} & {
+    withOptions(options : JobOptions) : RemoteWorker<T>;
+};
+
+export type QueueOptions = BullQueue.QueueOptions;
+export type JobOptions = BullQueue.JobOptions;
+export type QueueJob<T> = BullQueue.Job<T>;
+export type Queue<T> = BullQueue.Queue<T>;
+
+export interface Constructor<T> {
+    new (...args) : T;
+}
+
+export type PromiseWrap<T> = T extends PromiseLike<any> ? T : Promise<T>;
+
+export class TaskWorkerProxy {
+    private static create<T extends Worker>(handler : (key, ...args) => any): any {
+        return <RemoteWorker<T>> new Proxy({}, {
+            get(t, key : string, receiver) {
+                return (...args) => handler(key, ...args);
+            }
+        })
+    }
+
+    static createAsync<T extends Worker>(queueClient : TaskQueueClient, id : string, options? : JobOptions): RemoteWorker<T> {
+        return this.create(
+            (method, ...args) => {
+                if (method === 'withOptions')
+                    return TaskWorkerProxy.createAsync(queueClient, id, Object.assign({}, options, args[0]));
+                else
+                    return queueClient.enqueue({ id, method, args }, options)
+            }
+        );
+    }
+    
+    static createSync<T extends Worker>(queueClient : TaskQueueClient, id : string, options? : JobOptions): RemoteService<T> {
+        return this.create( 
+            (method, ...args) => {
+                if (method === 'withOptions')
+                    return TaskWorkerProxy.createSync(queueClient, id, Object.assign({}, options, args[0]));
+                else
+                    return queueClient.enqueue({ id, method, args }, options).then(v => v.finished);
+            }
+        );
+    }
+}
+
+interface TaskWorkerEntry<T extends Worker = any> {
+    type : Constructor<T>;
+    local : T;
+    async : RemoteWorker<T>;
+    sync : RemoteService<T>;
+}
+
+
+@Injectable()
+export class TaskQueueClient {
+    constructor(
+        @Optional()
+        private optionsRef : TaskModuleOptionsRef
+    ) {
+        this._queue = new BullQueue(this.queueName, this.queueOptions);
+    }
+
+    _queue : BullQueue.Queue;
+
+    get queue(): Queue<TaskJob> {
+        return this._queue;
+    }
+    
+    /**
+     * Get the task client options. See 
+     */
+    get options(): TaskModuleOptions {
+        return (this.optionsRef ? this.optionsRef.options : undefined) || {};
+    }
+
+    get queueName(): string {
+        return this.options.queueName || 'alteriorTasks';
+    }
+
+    get queueOptions() {
+        let queueOptions = Object.assign({}, this.options.queueOptions);
+
+        if (!queueOptions.redis) {
+            queueOptions.redis = {
+                port: 6379,
+                host: '127.0.0.1',
+                db: 6
+            }
+        }
+
+        return queueOptions;
+    }
+
+    /**
+     * Enqueue a new task. To handle the task on the worker side, register for it with `.process()`
+     */
+    async enqueue(data : TaskJob, opts? : JobOptions): Promise<QueueJob<TaskJob>> {
+        return await this._queue.add(data, opts);
+    }
+}
+
+@Injectable()
+export class TaskWorkerRegistry {
+    constructor(
+        private injector : Injector,
+        private client : TaskQueueClient
+    ) {
+
+    }
+
+    private _entries : { [name : string] : TaskWorkerEntry } = {};
+
+    private registerClass(injector : Injector, taskClass : Constructor<Worker>) {
+        let instance = <Worker> injector.get(taskClass);
+        let id = instance.name;
+        
+        if (this._entries[id])
+            throw new Error(`Another worker is already registered with name '${id}'`);
+
+        this._entries[id] = {
+            type: <any> taskClass,
+            local: instance,
+            sync: TaskWorkerProxy.createSync(this.client, id, instance.options),
+            async: TaskWorkerProxy.createAsync(this.client, id, instance.options)
+        };
+    }
+
+    get all() : TaskWorkerEntry[] {
+        return Object.values(this._entries);
+    }
+
+    get<T extends Worker>(cls : Constructor<T>): TaskWorkerEntry<T> {
+        let entry = this.all.find(x => x.type === cls);
+
+        if (!entry)
+            throw new Error(`Worker class ${cls.name} is not registered. Add it to the 'tasks' property of a module or call TaskWorkerRegistry.register(${cls.name})`);
+        
+        return <TaskWorkerEntry<T>> entry;
+    }
+
+    getByName(name : string) {
+        return this._entries[name];
+    }
+
+    registerClasses(classes : Function[]) {
+        let taskClasses : Constructor<Worker>[] = classes as any;
+        let ownInjector = ReflectiveInjector.resolveAndCreate(taskClasses as Provider[], this.injector);
+        taskClasses.forEach(taskClass => this.registerClass(ownInjector, taskClass));
+    }
+}

package/dist.esm/test.js

@@ -1,7 +0,0 @@
-import "reflect-metadata";
-import { suite } from 'razmin';
-suite()
-    .withTimeout(10 * 1000)
-    .include(['**/*.test.js'])
-    .run();
-//# sourceMappingURL=test.js.map