333 lines
12 KiB
TypeScript
333 lines
12 KiB
TypeScript
|
/**
|
||
|
* @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 { Observable, Observer } from 'rxjs';
|
||
|
import { JsonObject, JsonValue, schema } from '../../json/index';
|
||
|
import { DeepReadonly } from '../../utils/index';
|
||
|
/**
|
||
|
* 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>;
|