1 | /**
|
---|
2 | * @license
|
---|
3 | * Copyright Google LLC All Rights Reserved.
|
---|
4 | *
|
---|
5 | * Use of this source code is governed by an MIT-style license that can be
|
---|
6 | * found in the LICENSE file at https://angular.io/license
|
---|
7 | */
|
---|
8 | import { Observable, Observer } from 'rxjs';
|
---|
9 | import { JsonObject, JsonValue, schema } from '../../json/index';
|
---|
10 | import { DeepReadonly } from '../../utils/index';
|
---|
11 | /**
|
---|
12 | * A job name is just a string (needs to be serializable).
|
---|
13 | */
|
---|
14 | export declare type JobName = string;
|
---|
15 | /**
|
---|
16 | * The job handler function, which is a method that's executed for the job.
|
---|
17 | */
|
---|
18 | export interface JobHandler<ArgT extends JsonValue, InputT extends JsonValue, OutputT extends JsonValue> {
|
---|
19 | (argument: ArgT, context: JobHandlerContext<ArgT, InputT, OutputT>): Observable<JobOutboundMessage<OutputT>>;
|
---|
20 | jobDescription: Partial<JobDescription>;
|
---|
21 | }
|
---|
22 | /**
|
---|
23 | * The context in which the job is run.
|
---|
24 | */
|
---|
25 | export interface JobHandlerContext<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
|
---|
26 | readonly description: JobDescription;
|
---|
27 | readonly scheduler: Scheduler<JsonValue, JsonValue, JsonValue>;
|
---|
28 | readonly dependencies: Job<JsonValue, JsonValue, JsonValue>[];
|
---|
29 | readonly inboundBus: Observable<JobInboundMessage<MinimumInputValueT>>;
|
---|
30 | }
|
---|
31 | /**
|
---|
32 | * Metadata associated with a job.
|
---|
33 | */
|
---|
34 | export interface JobDescription extends JsonObject {
|
---|
35 | readonly name: JobName;
|
---|
36 | readonly argument: DeepReadonly<schema.JsonSchema>;
|
---|
37 | readonly input: DeepReadonly<schema.JsonSchema>;
|
---|
38 | readonly output: DeepReadonly<schema.JsonSchema>;
|
---|
39 | }
|
---|
40 | /**
|
---|
41 | * Messages that can be sent TO a job. The job needs to listen to those.
|
---|
42 | */
|
---|
43 | export declare enum JobInboundMessageKind {
|
---|
44 | Ping = "ip",
|
---|
45 | Stop = "is",
|
---|
46 | Input = "in"
|
---|
47 | }
|
---|
48 | /** Base interface for the all job inbound messages. */
|
---|
49 | export interface JobInboundMessageBase extends JsonObject {
|
---|
50 | /**
|
---|
51 | * The kind of message this is.
|
---|
52 | */
|
---|
53 | readonly kind: JobInboundMessageKind;
|
---|
54 | }
|
---|
55 | /**
|
---|
56 | * A ping to the job. The job should reply with a pong as soon as possible.
|
---|
57 | */
|
---|
58 | export interface JobInboundMessagePing extends JobInboundMessageBase {
|
---|
59 | readonly kind: JobInboundMessageKind.Ping;
|
---|
60 | /**
|
---|
61 | * An ID that should be returned in the corresponding Pong.
|
---|
62 | */
|
---|
63 | readonly id: number;
|
---|
64 | }
|
---|
65 | /**
|
---|
66 | * Stop the job. This is handled by the job itself and jobs might not handle it. It will also
|
---|
67 | * unsubscribe from the Observable<>.
|
---|
68 | * This is equivalent to SIGTERM.
|
---|
69 | */
|
---|
70 | export interface JobInboundMessageStop extends JobInboundMessageBase {
|
---|
71 | readonly kind: JobInboundMessageKind.Stop;
|
---|
72 | }
|
---|
73 | /**
|
---|
74 | * A Job wants to send a message to a channel. This can be marshaled, and the Job object
|
---|
75 | * has helpers to transform this into an observable. The context also can create RxJS subjects that
|
---|
76 | * marshall messages through a channel.
|
---|
77 | */
|
---|
78 | export interface JobInboundMessageInput<InputT extends JsonValue> extends JobInboundMessageBase {
|
---|
79 | readonly kind: JobInboundMessageKind.Input;
|
---|
80 | /**
|
---|
81 | * The input being sent to the job.
|
---|
82 | */
|
---|
83 | readonly value: InputT;
|
---|
84 | }
|
---|
85 | export declare type JobInboundMessage<InputT extends JsonValue> = JobInboundMessagePing | JobInboundMessageStop | JobInboundMessageInput<InputT>;
|
---|
86 | /**
|
---|
87 | * Kind of messages that can be outputted from a job.
|
---|
88 | */
|
---|
89 | export declare enum JobOutboundMessageKind {
|
---|
90 | OnReady = "c",
|
---|
91 | Start = "s",
|
---|
92 | End = "e",
|
---|
93 | Pong = "p",
|
---|
94 | Output = "o",
|
---|
95 | ChannelCreate = "cn",
|
---|
96 | ChannelMessage = "cm",
|
---|
97 | ChannelError = "ce",
|
---|
98 | ChannelComplete = "cc"
|
---|
99 | }
|
---|
100 | /** Base interface for the all job messages. */
|
---|
101 | export interface JobOutboundMessageBase {
|
---|
102 | /**
|
---|
103 | * The job description.
|
---|
104 | */
|
---|
105 | readonly description: JobDescription;
|
---|
106 | /**
|
---|
107 | * The kind of message this is.
|
---|
108 | */
|
---|
109 | readonly kind: JobOutboundMessageKind;
|
---|
110 | }
|
---|
111 | /**
|
---|
112 | * The job has been created and will validate its input.
|
---|
113 | */
|
---|
114 | export interface JobOutboundMessageOnReady extends JobOutboundMessageBase {
|
---|
115 | readonly kind: JobOutboundMessageKind.OnReady;
|
---|
116 | }
|
---|
117 | /**
|
---|
118 | * The job started. This is done by the job itself.
|
---|
119 | */
|
---|
120 | export interface JobOutboundMessageStart extends JobOutboundMessageBase {
|
---|
121 | readonly kind: JobOutboundMessageKind.Start;
|
---|
122 | }
|
---|
123 | /**
|
---|
124 | * An output value is available.
|
---|
125 | */
|
---|
126 | export interface JobOutboundMessageOutput<OutputT extends JsonValue> extends JobOutboundMessageBase {
|
---|
127 | readonly kind: JobOutboundMessageKind.Output;
|
---|
128 | /**
|
---|
129 | * The message being outputted from the job.
|
---|
130 | */
|
---|
131 | readonly value: OutputT;
|
---|
132 | }
|
---|
133 | /**
|
---|
134 | * Base interface for all job message related to channels.
|
---|
135 | */
|
---|
136 | export interface JobOutboundMessageChannelBase extends JobOutboundMessageBase {
|
---|
137 | /**
|
---|
138 | * The name of the channel.
|
---|
139 | */
|
---|
140 | readonly name: string;
|
---|
141 | }
|
---|
142 | /**
|
---|
143 | * A job wants to send a message to a channel. This can be marshaled, and the Job object
|
---|
144 | * has helpers to transform this into an observable. The context also can create RxJS subjects that
|
---|
145 | * marshall messages through a channel.
|
---|
146 | */
|
---|
147 | export interface JobOutboundMessageChannelMessage extends JobOutboundMessageChannelBase {
|
---|
148 | readonly kind: JobOutboundMessageKind.ChannelMessage;
|
---|
149 | /**
|
---|
150 | * The message being sent to the channel.
|
---|
151 | */
|
---|
152 | readonly message: JsonValue;
|
---|
153 | }
|
---|
154 | /**
|
---|
155 | * A job wants to send an error to one of its channel. This is the equivalent of throwing through
|
---|
156 | * an Observable. The side channel will not receive any more messages after this, and will not
|
---|
157 | * complete.
|
---|
158 | */
|
---|
159 | export interface JobOutboundMessageChannelError extends JobOutboundMessageChannelBase {
|
---|
160 | readonly kind: JobOutboundMessageKind.ChannelError;
|
---|
161 | /**
|
---|
162 | * The error message being sent to the channel.
|
---|
163 | */
|
---|
164 | readonly error: JsonValue;
|
---|
165 | }
|
---|
166 | /**
|
---|
167 | * A job wants to create a new channel.
|
---|
168 | */
|
---|
169 | export interface JobOutboundMessageChannelCreate extends JobOutboundMessageChannelBase {
|
---|
170 | readonly kind: JobOutboundMessageKind.ChannelCreate;
|
---|
171 | }
|
---|
172 | /**
|
---|
173 | * A job wants to close the channel, as completed. This is done automatically when the job ends,
|
---|
174 | * or can be done from the job to close it. A closed channel might be reopened, but the user
|
---|
175 | * need to recall getChannel().
|
---|
176 | */
|
---|
177 | export interface JobOutboundMessageChannelComplete extends JobOutboundMessageChannelBase {
|
---|
178 | readonly kind: JobOutboundMessageKind.ChannelComplete;
|
---|
179 | }
|
---|
180 | /**
|
---|
181 | * OnEnd of the job run.
|
---|
182 | */
|
---|
183 | export interface JobOutboundMessageEnd extends JobOutboundMessageBase {
|
---|
184 | readonly kind: JobOutboundMessageKind.End;
|
---|
185 | }
|
---|
186 | /**
|
---|
187 | * A pong response from a ping input. The id is the same as the one passed in.
|
---|
188 | */
|
---|
189 | export interface JobOutboundMessagePong extends JobOutboundMessageBase {
|
---|
190 | readonly kind: JobOutboundMessageKind.Pong;
|
---|
191 | /**
|
---|
192 | * The ID that was passed in the `Ping` messages.
|
---|
193 | */
|
---|
194 | readonly id: number;
|
---|
195 | }
|
---|
196 | /**
|
---|
197 | * Generic message type.
|
---|
198 | */
|
---|
199 | export declare type JobOutboundMessage<OutputT extends JsonValue> = JobOutboundMessageOnReady | JobOutboundMessageStart | JobOutboundMessageOutput<OutputT> | JobOutboundMessageChannelCreate | JobOutboundMessageChannelMessage | JobOutboundMessageChannelError | JobOutboundMessageChannelComplete | JobOutboundMessageEnd | JobOutboundMessagePong;
|
---|
200 | /**
|
---|
201 | * The state of a job. These are changed as the job reports a new state through its messages.
|
---|
202 | */
|
---|
203 | export declare enum JobState {
|
---|
204 | /**
|
---|
205 | * The job was queued and is waiting to start.
|
---|
206 | */
|
---|
207 | Queued = "queued",
|
---|
208 | /**
|
---|
209 | * The job description was found, its dependencies (see "Synchronizing and Dependencies")
|
---|
210 | * are done running, and the job's argument is validated and the job's code will be executed.
|
---|
211 | */
|
---|
212 | Ready = "ready",
|
---|
213 | /**
|
---|
214 | * The job has been started. The job implementation is expected to send this as soon as its
|
---|
215 | * work is starting.
|
---|
216 | */
|
---|
217 | Started = "started",
|
---|
218 | /**
|
---|
219 | * The job has ended and is done running.
|
---|
220 | */
|
---|
221 | Ended = "ended",
|
---|
222 | /**
|
---|
223 | * An error occured and the job stopped because of internal state.
|
---|
224 | */
|
---|
225 | Errored = "errored"
|
---|
226 | }
|
---|
227 | /**
|
---|
228 | * A Job instance, returned from scheduling a job. A Job instance is _not_ serializable.
|
---|
229 | */
|
---|
230 | export interface Job<ArgumentT extends JsonValue = JsonValue, InputT extends JsonValue = JsonValue, OutputT extends JsonValue = JsonValue> {
|
---|
231 | /**
|
---|
232 | * Description of the job. Resolving the job's description can be done asynchronously, so this
|
---|
233 | * is an observable that will resolve when it's ready.
|
---|
234 | */
|
---|
235 | readonly description: Observable<JobDescription>;
|
---|
236 | /**
|
---|
237 | * Argument sent when scheduling the job. This is a copy of the argument.
|
---|
238 | */
|
---|
239 | readonly argument: ArgumentT;
|
---|
240 | /**
|
---|
241 | * The input to the job. This goes through the input channel as messages.
|
---|
242 | */
|
---|
243 | readonly input: Observer<InputT>;
|
---|
244 | /**
|
---|
245 | * Outputs of this job.
|
---|
246 | */
|
---|
247 | readonly output: Observable<OutputT>;
|
---|
248 | /**
|
---|
249 | * The current state of the job.
|
---|
250 | */
|
---|
251 | readonly state: JobState;
|
---|
252 | /**
|
---|
253 | * Get a channel that validates against the schema. Messages will be filtered by the schema.
|
---|
254 | * @param name The name of the channel.
|
---|
255 | * @param schema A schema to use to validate messages.
|
---|
256 | */
|
---|
257 | getChannel<T extends JsonValue>(name: string, schema?: schema.JsonSchema): Observable<T>;
|
---|
258 | /**
|
---|
259 | * Pings the job and wait for the resulting Pong before completing.
|
---|
260 | */
|
---|
261 | ping(): Observable<never>;
|
---|
262 | /**
|
---|
263 | * Stops the job from running. This is different than unsubscribing from the output as in it
|
---|
264 | * sends the JobInboundMessageKind.Stop raw input to the job.
|
---|
265 | */
|
---|
266 | stop(): void;
|
---|
267 | /**
|
---|
268 | * The JobInboundMessage messages TO the job.
|
---|
269 | */
|
---|
270 | readonly inboundBus: Observer<JobInboundMessage<InputT>>;
|
---|
271 | /**
|
---|
272 | * The JobOutboundMessage FROM the job.
|
---|
273 | */
|
---|
274 | readonly outboundBus: Observable<JobOutboundMessage<OutputT>>;
|
---|
275 | }
|
---|
276 | /**
|
---|
277 | * Options for scheduling jobs.
|
---|
278 | */
|
---|
279 | export interface ScheduleJobOptions {
|
---|
280 | /**
|
---|
281 | * Jobs that need to finish before scheduling this job. These dependencies will be passed
|
---|
282 | * to the job itself in its context.
|
---|
283 | */
|
---|
284 | dependencies?: Job | Job[];
|
---|
285 | }
|
---|
286 | export interface Registry<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
|
---|
287 | /**
|
---|
288 | * Get a job handler.
|
---|
289 | * @param name The name of the job to get a handler from.
|
---|
290 | */
|
---|
291 | get<A extends MinimumArgumentValueT, I extends MinimumInputValueT, O extends MinimumOutputValueT>(name: JobName): Observable<JobHandler<A, I, O> | null>;
|
---|
292 | }
|
---|
293 | /**
|
---|
294 | * An interface that can schedule jobs.
|
---|
295 | */
|
---|
296 | export interface Scheduler<MinimumArgumentValueT extends JsonValue = JsonValue, MinimumInputValueT extends JsonValue = JsonValue, MinimumOutputValueT extends JsonValue = JsonValue> {
|
---|
297 | /**
|
---|
298 | * Get a job description for a named job.
|
---|
299 | *
|
---|
300 | * @param name The name of the job.
|
---|
301 | * @returns A description, or null if no description is available for this job.
|
---|
302 | */
|
---|
303 | getDescription(name: JobName): Observable<JobDescription | null>;
|
---|
304 | /**
|
---|
305 | * Returns true if the job name has been registered.
|
---|
306 | * @param name The name of the job.
|
---|
307 | * @returns True if the job exists, false otherwise.
|
---|
308 | */
|
---|
309 | has(name: JobName): Observable<boolean>;
|
---|
310 | /**
|
---|
311 | * Pause the scheduler, temporary queueing _new_ jobs. Returns a resume function that should be
|
---|
312 | * used to resume execution. If multiple `pause()` were called, all their resume functions must
|
---|
313 | * be called before the Scheduler actually starts new jobs. Additional calls to the same resume
|
---|
314 | * function will have no effect.
|
---|
315 | *
|
---|
316 | * Jobs already running are NOT paused. This is pausing the scheduler only.
|
---|
317 | *
|
---|
318 | * @returns A function that can be run to resume the scheduler. If multiple `pause()` calls
|
---|
319 | * were made, all their return function must be called (in any order) before the
|
---|
320 | * scheduler can resume.
|
---|
321 | */
|
---|
322 | pause(): () => void;
|
---|
323 | /**
|
---|
324 | * Schedule a job to be run, using its name.
|
---|
325 | * @param name The name of job to be run.
|
---|
326 | * @param argument The argument to send to the job when starting it.
|
---|
327 | * @param options Scheduling options.
|
---|
328 | * @returns The job being run.
|
---|
329 | */
|
---|
330 | schedule<A extends MinimumArgumentValueT, I extends MinimumInputValueT, O extends MinimumOutputValueT>(name: JobName, argument: A, options?: ScheduleJobOptions): Job<A, I, O>;
|
---|
331 | }
|
---|
332 | export declare function isJobHandler<A extends JsonValue, I extends JsonValue, O extends JsonValue>(value: unknown): value is JobHandler<A, I, O>;
|
---|