@angular-devkit/architect 0.1500.0-next.4 → 0.1500.0-next.6

package/src/jobs/api.d.ts

@@ -0,0 +1,332 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+import { JsonObject, JsonValue, schema } from '@angular-devkit/core';
+import { Observable, Observer } from 'rxjs';
+import { DeepReadonly } from './types';
+/**
+ * A job name is just a string (needs to be serializable).
+ */
+export declare type JobName = string;
+/**
+ * The job handler function, which is a method that's executed for the job.
+ */
+export interface JobHandler<ArgT extends JsonValue, InputT extends JsonValue, OutputT extends JsonValue> {
+    (argument: ArgT, context: JobHandlerContext<ArgT, InputT, OutputT>): Observable<JobOutboundMessage<OutputT>>;
+    jobDescription: Partial<JobDescription>;
+}
+/**
+ * The context in which the job is run.
+ */
+export interface JobHandlerContext<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
+    readonly description: JobDescription;
+    readonly scheduler: Scheduler<JsonValue, JsonValue, JsonValue>;
+    readonly dependencies: Job<JsonValue, JsonValue, JsonValue>[];
+    readonly inboundBus: Observable<JobInboundMessage<MinimumInputValueT>>;
+}
+/**
+ * Metadata associated with a job.
+ */
+export interface JobDescription extends JsonObject {
+    readonly name: JobName;
+    readonly argument: DeepReadonly<schema.JsonSchema>;
+    readonly input: DeepReadonly<schema.JsonSchema>;
+    readonly output: DeepReadonly<schema.JsonSchema>;
+}
+/**
+ * Messages that can be sent TO a job. The job needs to listen to those.
+ */
+export declare enum JobInboundMessageKind {
+    Ping = "ip",
+    Stop = "is",
+    Input = "in"
+}
+/** Base interface for the all job inbound messages. */
+export interface JobInboundMessageBase extends JsonObject {
+    /**
+     * The kind of message this is.
+     */
+    readonly kind: JobInboundMessageKind;
+}
+/**
+ * A ping to the job. The job should reply with a pong as soon as possible.
+ */
+export interface JobInboundMessagePing extends JobInboundMessageBase {
+    readonly kind: JobInboundMessageKind.Ping;
+    /**
+     * An ID that should be returned in the corresponding Pong.
+     */
+    readonly id: number;
+}
+/**
+ * Stop the job. This is handled by the job itself and jobs might not handle it. It will also
+ * unsubscribe from the Observable<>.
+ * This is equivalent to SIGTERM.
+ */
+export interface JobInboundMessageStop extends JobInboundMessageBase {
+    readonly kind: JobInboundMessageKind.Stop;
+}
+/**
+ * A Job wants to send a message to a channel. This can be marshaled, and the Job object
+ * has helpers to transform this into an observable. The context also can create RxJS subjects that
+ * marshall messages through a channel.
+ */
+export interface JobInboundMessageInput<InputT extends JsonValue> extends JobInboundMessageBase {
+    readonly kind: JobInboundMessageKind.Input;
+    /**
+     * The input being sent to the job.
+     */
+    readonly value: InputT;
+}
+export declare type JobInboundMessage<InputT extends JsonValue> = JobInboundMessagePing | JobInboundMessageStop | JobInboundMessageInput<InputT>;
+/**
+ * Kind of messages that can be outputted from a job.
+ */
+export declare enum JobOutboundMessageKind {
+    OnReady = "c",
+    Start = "s",
+    End = "e",
+    Pong = "p",
+    Output = "o",
+    ChannelCreate = "cn",
+    ChannelMessage = "cm",
+    ChannelError = "ce",
+    ChannelComplete = "cc"
+}
+/** Base interface for the all job messages. */
+export interface JobOutboundMessageBase {
+    /**
+     * The job description.
+     */
+    readonly description: JobDescription;
+    /**
+     * The kind of message this is.
+     */
+    readonly kind: JobOutboundMessageKind;
+}
+/**
+ * The job has been created and will validate its input.
+ */
+export interface JobOutboundMessageOnReady extends JobOutboundMessageBase {
+    readonly kind: JobOutboundMessageKind.OnReady;
+}
+/**
+ * The job started. This is done by the job itself.
+ */
+export interface JobOutboundMessageStart extends JobOutboundMessageBase {
+    readonly kind: JobOutboundMessageKind.Start;
+}
+/**
+ * An output value is available.
+ */
+export interface JobOutboundMessageOutput<OutputT extends JsonValue> extends JobOutboundMessageBase {
+    readonly kind: JobOutboundMessageKind.Output;
+    /**
+     * The message being outputted from the job.
+     */
+    readonly value: OutputT;
+}
+/**
+ * Base interface for all job message related to channels.
+ */
+export interface JobOutboundMessageChannelBase extends JobOutboundMessageBase {
+    /**
+     * The name of the channel.
+     */
+    readonly name: string;
+}
+/**
+ * A job wants to send a message to a channel. This can be marshaled, and the Job object
+ * has helpers to transform this into an observable. The context also can create RxJS subjects that
+ * marshall messages through a channel.
+ */
+export interface JobOutboundMessageChannelMessage extends JobOutboundMessageChannelBase {
+    readonly kind: JobOutboundMessageKind.ChannelMessage;
+    /**
+     * The message being sent to the channel.
+     */
+    readonly message: JsonValue;
+}
+/**
+ * A job wants to send an error to one of its channel. This is the equivalent of throwing through
+ * an Observable. The side channel will not receive any more messages after this, and will not
+ * complete.
+ */
+export interface JobOutboundMessageChannelError extends JobOutboundMessageChannelBase {
+    readonly kind: JobOutboundMessageKind.ChannelError;
+    /**
+     * The error message being sent to the channel.
+     */
+    readonly error: JsonValue;
+}
+/**
+ * A job wants to create a new channel.
+ */
+export interface JobOutboundMessageChannelCreate extends JobOutboundMessageChannelBase {
+    readonly kind: JobOutboundMessageKind.ChannelCreate;
+}
+/**
+ * A job wants to close the channel, as completed. This is done automatically when the job ends,
+ * or can be done from the job to close it. A closed channel might be reopened, but the user
+ * need to recall getChannel().
+ */
+export interface JobOutboundMessageChannelComplete extends JobOutboundMessageChannelBase {
+    readonly kind: JobOutboundMessageKind.ChannelComplete;
+}
+/**
+ * OnEnd of the job run.
+ */
+export interface JobOutboundMessageEnd extends JobOutboundMessageBase {
+    readonly kind: JobOutboundMessageKind.End;
+}
+/**
+ * A pong response from a ping input. The id is the same as the one passed in.
+ */
+export interface JobOutboundMessagePong extends JobOutboundMessageBase {
+    readonly kind: JobOutboundMessageKind.Pong;
+    /**
+     * The ID that was passed in the `Ping` messages.
+     */
+    readonly id: number;
+}
+/**
+ * Generic message type.
+ */
+export declare type JobOutboundMessage<OutputT extends JsonValue> = JobOutboundMessageOnReady | JobOutboundMessageStart | JobOutboundMessageOutput<OutputT> | JobOutboundMessageChannelCreate | JobOutboundMessageChannelMessage | JobOutboundMessageChannelError | JobOutboundMessageChannelComplete | JobOutboundMessageEnd | JobOutboundMessagePong;
+/**
+ * The state of a job. These are changed as the job reports a new state through its messages.
+ */
+export declare enum JobState {
+    /**
+     * The job was queued and is waiting to start.
+     */
+    Queued = "queued",
+    /**
+     * The job description was found, its dependencies (see "Synchronizing and Dependencies")
+     * are done running, and the job's argument is validated and the job's code will be executed.
+     */
+    Ready = "ready",
+    /**
+     * The job has been started. The job implementation is expected to send this as soon as its
+     * work is starting.
+     */
+    Started = "started",
+    /**
+     * The job has ended and is done running.
+     */
+    Ended = "ended",
+    /**
+     * An error occured and the job stopped because of internal state.
+     */
+    Errored = "errored"
+}
+/**
+ * A Job instance, returned from scheduling a job. A Job instance is _not_ serializable.
+ */
+export interface Job<ArgumentT extends JsonValue = JsonValue, InputT extends JsonValue = JsonValue, OutputT extends JsonValue = JsonValue> {
+    /**
+     * Description of the job. Resolving the job's description can be done asynchronously, so this
+     * is an observable that will resolve when it's ready.
+     */
+    readonly description: Observable<JobDescription>;
+    /**
+     * Argument sent when scheduling the job. This is a copy of the argument.
+     */
+    readonly argument: ArgumentT;
+    /**
+     * The input to the job. This goes through the input channel as messages.
+     */
+    readonly input: Observer<InputT>;
+    /**
+     * Outputs of this job.
+     */
+    readonly output: Observable<OutputT>;
+    /**
+     * The current state of the job.
+     */
+    readonly state: JobState;
+    /**
+     * Get a channel that validates against the schema. Messages will be filtered by the schema.
+     * @param name The name of the channel.
+     * @param schema A schema to use to validate messages.
+     */
+    getChannel<T extends JsonValue>(name: string, schema?: schema.JsonSchema): Observable<T>;
+    /**
+     * Pings the job and wait for the resulting Pong before completing.
+     */
+    ping(): Observable<never>;
+    /**
+     * Stops the job from running. This is different than unsubscribing from the output as in it
+     * sends the JobInboundMessageKind.Stop raw input to the job.
+     */
+    stop(): void;
+    /**
+     * The JobInboundMessage messages TO the job.
+     */
+    readonly inboundBus: Observer<JobInboundMessage<InputT>>;
+    /**
+     * The JobOutboundMessage FROM the job.
+     */
+    readonly outboundBus: Observable<JobOutboundMessage<OutputT>>;
+}
+/**
+ * Options for scheduling jobs.
+ */
+export interface ScheduleJobOptions {
+    /**
+     * Jobs that need to finish before scheduling this job. These dependencies will be passed
+     * to the job itself in its context.
+     */
+    dependencies?: Job | Job[];
+}
+export interface Registry<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
+    /**
+     * Get a job handler.
+     * @param name The name of the job to get a handler from.
+     */
+    get<A extends MinimumArgumentValueT, I extends MinimumInputValueT, O extends MinimumOutputValueT>(name: JobName): Observable<JobHandler<A, I, O> | null>;
+}
+/**
+ * An interface that can schedule jobs.
+ */
+export interface Scheduler<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
+    /**
+     * Get a job description for a named job.
+     *
+     * @param name The name of the job.
+     * @returns A description, or null if no description is available for this job.
+     */
+    getDescription(name: JobName): Observable<JobDescription | null>;
+    /**
+     * Returns true if the job name has been registered.
+     * @param name The name of the job.
+     * @returns True if the job exists, false otherwise.
+     */
+    has(name: JobName): Observable<boolean>;
+    /**
+     * Pause the scheduler, temporary queueing _new_ jobs. Returns a resume function that should be
+     * used to resume execution. If multiple `pause()` were called, all their resume functions must
+     * be called before the Scheduler actually starts new jobs. Additional calls to the same resume
+     * function will have no effect.
+     *
+     * Jobs already running are NOT paused. This is pausing the scheduler only.
+     *
+     * @returns A function that can be run to resume the scheduler. If multiple `pause()` calls
+     *          were made, all their return function must be called (in any order) before the
+     *          scheduler can resume.
+     */
+    pause(): () => void;
+    /**
+     * Schedule a job to be run, using its name.
+     * @param name The name of job to be run.
+     * @param argument The argument to send to the job when starting it.
+     * @param options Scheduling options.
+     * @returns The job being run.
+     */
+    schedule<A extends MinimumArgumentValueT, I extends MinimumInputValueT, O extends MinimumOutputValueT>(name: JobName, argument: A, options?: ScheduleJobOptions): Job<A, I, O>;
+}
+export declare function isJobHandler<A extends JsonValue, I extends JsonValue, O extends JsonValue>(value: unknown): value is JobHandler<A, I, O>;

package/src/jobs/api.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.io/license
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isJobHandler = exports.JobState = exports.JobOutboundMessageKind = exports.JobInboundMessageKind = void 0;
+/**
+ * Messages that can be sent TO a job. The job needs to listen to those.
+ */
+var JobInboundMessageKind;
+(function (JobInboundMessageKind) {
+    JobInboundMessageKind["Ping"] = "ip";
+    JobInboundMessageKind["Stop"] = "is";
+    // Channel specific messages.
+    JobInboundMessageKind["Input"] = "in";
+    // Input channel does not allow completion / error. Erroring this will just close the Subject
+    // but not notify the job.
+})(JobInboundMessageKind = exports.JobInboundMessageKind || (exports.JobInboundMessageKind = {}));
+/**
+ * Kind of messages that can be outputted from a job.
+ */
+var JobOutboundMessageKind;
+(function (JobOutboundMessageKind) {
+    // Lifecycle specific messages.
+    JobOutboundMessageKind["OnReady"] = "c";
+    JobOutboundMessageKind["Start"] = "s";
+    JobOutboundMessageKind["End"] = "e";
+    JobOutboundMessageKind["Pong"] = "p";
+    // Feedback messages.
+    JobOutboundMessageKind["Output"] = "o";
+    // Channel specific messages.
+    JobOutboundMessageKind["ChannelCreate"] = "cn";
+    JobOutboundMessageKind["ChannelMessage"] = "cm";
+    JobOutboundMessageKind["ChannelError"] = "ce";
+    JobOutboundMessageKind["ChannelComplete"] = "cc";
+})(JobOutboundMessageKind = exports.JobOutboundMessageKind || (exports.JobOutboundMessageKind = {}));
+/**
+ * The state of a job. These are changed as the job reports a new state through its messages.
+ */
+var JobState;
+(function (JobState) {
+    /**
+     * The job was queued and is waiting to start.
+     */
+    JobState["Queued"] = "queued";
+    /**
+     * The job description was found, its dependencies (see "Synchronizing and Dependencies")
+     * are done running, and the job's argument is validated and the job's code will be executed.
+     */
+    JobState["Ready"] = "ready";
+    /**
+     * The job has been started. The job implementation is expected to send this as soon as its
+     * work is starting.
+     */
+    JobState["Started"] = "started";
+    /**
+     * The job has ended and is done running.
+     */
+    JobState["Ended"] = "ended";
+    /**
+     * An error occured and the job stopped because of internal state.
+     */
+    JobState["Errored"] = "errored";
+})(JobState = exports.JobState || (exports.JobState = {}));
+function isJobHandler(value) {
+    const job = value;
+    return (typeof job == 'function' && typeof job.jobDescription == 'object' && job.jobDescription !== null);
+}
+exports.isJobHandler = isJobHandler;

package/src/jobs/architecture.md

@@ -0,0 +1,260 @@
+# Overview
+
+Jobs is a high-order API that adds inputs, runtime type checking, sequencing, and other
+functionality on top of RxJS' `Observable`s.
+
+# Background
+
+An `Observable` (at a higher level) is a function that receives a `Subscriber`, and outputs
+multiple values, and finishes once it calls the `Subscriber.prototype.complete()` method (in
+JavaScript):
+
+```javascript
+const output1To10EverySecond = function (subscriber) {
+  let t = 0;
+  const i = setInterval(() => {
+    t++;
+    subscriber.next(t);
+    if (t === 10) {
+      subscriber.complete(t);
+    }
+  }, 1000);
+  return () => clearInterval(i);
+};
+
+const stream$ = new Observable(output1To10EverySecond);
+// Start the function, and output 1 to 100, once per line.
+stream$.subscribe((x) => console.log(x));
+```
+
+This, of course, can be typed in TypeScript, but those types are not enforced at runtime.
+
+# Glossary
+
+- `job handler`. The function that implements the job's logic.
+- `raw input`. The input observable sending messages to the job. These messages are of type
+  `JobInboundMessage`.
+- `raw output`. The output observer returned from the `job handler`. Messages on this observable
+  are of type `JobOutboundMessage`.
+
+# Description
+
+A `JobHandler`, similar to observables, is a function that receives an argument and a context, and
+returns an `Observable` of messages, which can include outputs that are typed at runtime (using a
+Json Schema):
+
+```javascript
+const output1ToXEverySecond = function (x, context) {
+  return new Observable((subscriber) => {
+    let t = 0;
+
+    // Notify our users that the actual work is started.
+    subscriber.next({ kind: JobOutboundMessageKind.Start });
+    const i = setInterval(() => {
+      t++;
+      subscriber.next({ kind: JobOutboundMessageKind.Output, value: t });
+      if (t === x) {
+        subscriber.next({ kind: JobOutboundMessageKind.End });
+        subscriber.complete();
+      }
+    }, 1000);
+
+    return () => {
+      clearInterval(i);
+    };
+  });
+};
+
+// For now, jobs can not be called without a registry and scheduler.
+const registry = new SimpleJobRegistry();
+registry.register('output-from-1-to-x', output1ToXEverySecond, {
+  argument: { type: 'number' },
+  output: { type: 'number' },
+});
+const scheduler = new SimpleScheduler(registry);
+
+// Need to keep the same name that the registry would understand.
+// Count from 1 to 10.
+const job = scheduler.schedule('output-from-1-to-x', 10);
+
+// A Job<> instance has more members, but we only want the output values here.
+job.output.subscribe((x) => console.log(x));
+```
+
+This seems like a lot of boilerplate in comparison, but there are a few advantages;
+
+1. lifecycle. Jobs can tell when they start doing work and when work is done.
+1. everything is typed, even at runtime.
+1. the context also contains an input Observable that receives typed input messages, including
+   input values, and stop requests.
+1. jobs can also schedule other jobs and wait for them, even if they don't know if a job is
+   implemented in the system.
+
+## Diagram
+
+A simpler way to think about jobs in contrast to observables is that job are closer to a Unix
+process. It has an argument (command line flags), receive inputs (STDIN and interrupt signals),
+and output values (STDOUT) as well as diagnostic (STDERR). They can be plugged one into another
+(piping), and can be transformed, synchronized and scheduled (fork, exec, cron).
+
+```plain
+- given A the type of the argument
+- given I the type of the input
+- given O the type of the output
+
+                              ,______________________
+    JobInboundMessage<I> --> | handler(argument: A) |  --> JobOutboundMessage<O>
+                                                            - JobOutboundMessageKind.Output
+                                                            - ...
+```
+
+`JobInboundMessage` includes:
+
+1. `JobInboundMessageKind.Ping`. A simple message that should be answered with
+   `JobOutboundMessageKind.Pong` when the job is responsive. The `id` field of the message should
+   be used when returning `Pong`.
+1. `JobInboundMessageKind.Stop`. The job should be stopped. This is used when
+   cancelling/unsubscribing from the `output` (or by calling `stop()`). Any inputs or outputs
+   after this message will be ignored.
+1. `JobInboundMessageKind.Input` is used when sending inputs to a job. These correspond to the
+   `next` methods of an `Observer` and are reported to the job through its `context.input`
+   Observable. There is no way to communicate an error to the job.
+
+`JobOutboundMessage` includes:
+
+1. `JobOutboundMessageKind.Ready`. The `Job<>` was created, its dependencies are done, and the
+   library is validating Argument and calling the internal job code.
+1. `JobOutboundMessageKind.Start`. The job code itself should send that message when started.
+   `createJobHandler()` will do it automatically.
+1. `JobOutboundMessageKind.End`. The job has ended. This is done by the job itself and should
+   always be sent when completed. The scheduler will listen to this message to set the state and
+   unblock dependent jobs. `createJobHandler()` automatically send this message.
+1. `JobOutboundMessageKind.Pong`. The job should answer a `JobInboundMessageKind.Ping` message with
+   this. Automatically done by `createJobHandler()`.
+1. `JobOutboundMessageKind.Output`. An `Output` has been generated by the job.
+1. `JobOutboundMessageKind.ChannelMessage`, `JobOutboundMessageKind.ChannelError` and
+   `JobOutboundMessageKind.ChannelComplete` are used for output channels. These correspond to
+   the `next`, `error` and `complete` methods of an `Observer` and are available to the callee
+   through the `job.channels` map of Observable.
+
+Utilities should have some filtering and dispatching to separate observables, as a convenience for
+the user. An example of this would be the `Job.prototype.output` observable which only contains
+the value contained by messages of type `JobOutboundMessageKind.Output`.
+
+# Higher Order Jobs
+
+Because jobs are expected to be pure functions, they can be composed or transformed to create
+more complex behaviour, similar to how RxJS operators can transform observables.
+
+```javascript
+// Runs a job on the hour, every hour, regardless of how long the job takes.
+// This creates a job function that can be registered by itself.
+function scheduleJobOnTheHour(jobFunction) {
+  return function (argument, context) {
+    return new Observable((observer) => {
+      let timeout = 0;
+
+      function _timeoutToNextHour() {
+        // Just wait until the next hour.
+        const t = new Date();
+        const secondsToNextHour = 3600 - t.getSeconds() - t.getMinutes() * 60;
+        timeout = setTimeout(_scheduleJobAndWaitAnHour, secondsToNextHour);
+      }
+
+      function _scheduleJobAndWaitAnHour() {
+        jobFunction(argument, context).subscribe(
+          (message) => observer.next(message),
+          (error) => observer.error(error),
+          // Do not forward completion, but use it to schedule the next job run.
+          () => {
+            _timeoutToNextHour();
+          },
+        );
+      }
+
+      // Kick off by waiting for next hour.
+      _timeoutToNextHour();
+
+      return () => clearTimeout(timeout);
+    });
+  };
+}
+```
+
+Another way to compose jobs is to schedule jobs based on their name, from other jobs.
+
+```javascript
+// Runs a job on the hour, every hour, regardless of how long the job takes.
+// This creates a high order job by getting a job name and an argument, and scheduling the job
+// every hour.
+function scheduleJobOnTheHour(job, context) {
+  const { name, argument } = job; // Destructure our input.
+
+  return new Observable((observer) => {
+    let timeout = 0;
+
+    function _timeoutToNextHour() {
+      // Just wait until the next hour.
+      const t = new Date();
+      const secondsToNextHour = 3600 - t.getSeconds() - t.getMinutes() * 60;
+      timeout = setTimeout(_scheduleJobAndWaitAnHour, secondsToNextHour);
+    }
+
+    function _scheduleJobAndWaitAnHour() {
+      const subJob = context.scheduler.schedule(name, argument);
+      // We do not forward the input to the sub-job but that would be a valid example as well.
+      subJob.outboundBus.subscribe(
+        (message) => observer.next(message),
+        (error) => observer.error(error),
+        // Do not forward completion, but use it to schedule the next job run.
+        () => {
+          _timeoutToNextHour();
+        },
+      );
+    }
+
+    // Kick off by waiting for next hour.
+    _timeoutToNextHour();
+
+    return () => clearTimeout(timeout);
+  });
+}
+
+const registry = new SimpleJobRegistry();
+registry.register('schedule-job-on-the-hour', scheduleJobOnTheHour, {
+  argument: {
+    properties: {
+      name: { type: 'string' },
+      argument: { type: true },
+    },
+  },
+});
+
+// Implementation left to the reader.
+registry.register('copy-files-from-a-to-b', require('some-package/copy-job'));
+
+const scheduler = new SimpleScheduler(registry);
+
+// A rudimentary backup system.
+const job = scheduler.schedule('schedule-job-on-the-hour', {
+  name: 'copy-files-from-a-to-b',
+  argument: {
+    from: '/some-directory/to/backup',
+    to: '/volumes/usb-key',
+  },
+});
+job.output.subscribe((x) => console.log(x));
+```
+
+# Limitations
+
+Jobs input, output and argument must be serializable to JSONs. This is a big limitation in usage,
+but comes with the benefit that jobs can be serialized and called across memory boundaries. An
+example would be an operator that takes a module path and run the job from that path in a separate
+process. Or even a separate server, using HTTP calls.
+
+Another limitation is that the boilerplate is complex. Manually managing start/end life cycle, and
+other messages such as ping/pong, etc. is tedious and requires a lot of code. A good way to keep
+this limitation under control is to provide helpers to create `JobHandler`s which manage those
+messages for the developer. A simple handler could be to get a `Promise` and return the output of
+that promise automatically.