1 | import { AwsOptions, AwsState } from "./aws/aws-faast";
|
2 | import { CostSnapshot } from "./cost";
|
3 | import { GoogleOptions, GoogleState } from "./google/google-faast";
|
4 | import { LocalOptions, LocalState } from "./local/local-faast";
|
5 | import { CleanupOptions, CommonOptions, FunctionStats, Provider, ProviderImpl } from "./provider";
|
6 | /**
|
7 | * An array of all available provider.
|
8 | * @public
|
9 | */
|
10 | export declare const providers: Provider[];
|
11 | /**
|
12 | * `Async<T>` maps regular values to Promises and Iterators to AsyncIterators,
|
13 | * If `T` is already a Promise or an AsyncIterator, it remains the same. This
|
14 | * type is used to infer the return value of cloud functions from the types of
|
15 | * the functions in the user's input module.
|
16 | * @public
|
17 | */
|
18 | export declare type Async<T> = T extends AsyncGenerator<infer R> ? AsyncGenerator<R> : T extends Generator<infer R> ? AsyncGenerator<R> : T extends Promise<infer R> ? Promise<R> : Promise<T>;
|
19 | /**
|
20 | * `AsyncDetail<T>` is similar to {@link Async} except it maps retun values R to
|
21 | * `Detail<R>`, which is the return value with additional information about each
|
22 | * cloud function invocation.
|
23 | * @public
|
24 | */
|
25 | export declare type AsyncDetail<T> = T extends AsyncGenerator<infer R> ? AsyncGenerator<Detail<R>> : T extends Generator<infer R> ? AsyncGenerator<Detail<R>> : T extends Promise<infer R> ? Promise<Detail<R>> : Promise<Detail<T>>;
|
26 | /**
|
27 | * `ProxyModule<M>` is the type of {@link FaastModule.functions}.
|
28 | * @remarks
|
29 | * `ProxyModule<M>` maps an imported module's functions to promise-returning or
|
30 | * async-iteratable versions of those functions. Non-function exports of the
|
31 | * module are omitted. When invoked, the functions in a `ProxyModule` invoke a
|
32 | * remote cloud function.
|
33 | * @public
|
34 | */
|
35 | export declare type ProxyModule<M> = {
|
36 | [K in keyof M]: M[K] extends (...args: infer A) => infer R ? (...args: A) => Async<R> : never;
|
37 | };
|
38 | /**
|
39 | * Similar to {@link ProxyModule} except each function returns a {@link Detail}
|
40 | * object.
|
41 | * @remarks
|
42 | * See {@link FaastModule.functionsDetail}.
|
43 | * @public
|
44 | */
|
45 | export declare type ProxyModuleDetail<M> = {
|
46 | [K in keyof M]: M[K] extends (...args: infer A) => infer R ? (...args: A) => AsyncDetail<R> : never;
|
47 | };
|
48 | /**
|
49 | * A function return value with additional detailed information.
|
50 | * @public
|
51 | */
|
52 | export interface Detail<R> {
|
53 | /**
|
54 | * A Promise for the function's return value.
|
55 | */
|
56 | value: R;
|
57 | /**
|
58 | * The URL of the logs for the specific execution of this function call.
|
59 | * @remarks
|
60 | * This is different from the general logUrl from
|
61 | * {@link FaastModule.logUrl}, which provides a link to the logs for all
|
62 | * invocations of all functions within that module. Whereas this logUrl is
|
63 | * only for this specific invocation.
|
64 | */
|
65 | logUrl?: string;
|
66 | /**
|
67 | * If available, the provider-specific execution identifier for this
|
68 | * invocation.
|
69 | * @remarks
|
70 | * This ID may be added to the log entries for this invocation by the cloud
|
71 | * provider.
|
72 | */
|
73 | executionId?: string;
|
74 | /**
|
75 | * If available, the provider-specific instance identifier for this
|
76 | * invocation.
|
77 | * @remarks
|
78 | * This ID refers to the specific container or VM used to execute this
|
79 | * function invocation. The instance may be reused across multiple
|
80 | * invocations.
|
81 | */
|
82 | instanceId?: string;
|
83 | }
|
84 | /**
|
85 | * Summarize statistics about cloud function invocations.
|
86 | * @public
|
87 | */
|
88 | export declare class FunctionStatsEvent {
|
89 | /** The name of the cloud function the statistics are about. */
|
90 | readonly fn: string;
|
91 | /** See {@link FunctionStats}. */
|
92 | readonly stats: FunctionStats;
|
93 | /**
|
94 | * @internal
|
95 | */
|
96 | constructor(
|
97 | /** The name of the cloud function the statistics are about. */
|
98 | fn: string,
|
99 | /** See {@link FunctionStats}. */
|
100 | stats: FunctionStats);
|
101 | /**
|
102 | * Returns a string summarizing the statistics event.
|
103 | * @remarks
|
104 | * The string includes number of completed calls, errors, and retries, and
|
105 | * the mean execution time for the calls that completed within the last time
|
106 | * interval (1s).
|
107 | */
|
108 | toString(): string;
|
109 | }
|
110 | /**
|
111 | * The main interface for invoking, cleaning up, and managing faast.js cloud
|
112 | * functions. Returned by { faast}.
|
113 | *
|
114 | */
|
115 | export interface FaastModule<M extends object> {
|
116 | /** See {@link Provider}. */
|
117 | provider: Provider;
|
118 | /**
|
119 | * Each call of a cloud function creates a separate remote invocation.
|
120 | * @remarks
|
121 | * The module passed into {@link faast} or its provider-specific variants
|
122 | * ({@link faastAws}, {@link faastGoogle}, and {@link faastLocal}) is mapped
|
123 | * to a {@link ProxyModule} version of the module, which performs the
|
124 | * following mapping:
|
125 | *
|
126 | * - All function exports that are generators are mapped to async
|
127 | * generators.
|
128 | *
|
129 | * - All function exports that return async generators are preserved as-is.
|
130 | *
|
131 | * - All function exports that return promises have their type signatures
|
132 | * preserved as-is.
|
133 | *
|
134 | * - All function exports that return type T, where T is not a Promise,
|
135 | * Generator, or AsyncGenerator, are mapped to functions that return
|
136 | * Promise<T>. Argument types are preserved as-is.
|
137 | *
|
138 | * - All non-function exports are omitted in the remote module.
|
139 | *
|
140 | * Arguments and return values are serialized with `JSON.stringify` when
|
141 | * cloud functions are called, therefore what is received on the remote side
|
142 | * might not match what was sent. Faast.js attempts to detect nonsupported
|
143 | * arguments on a best effort basis.
|
144 | *
|
145 | * If the cloud function throws an exception or rejects its promise with an
|
146 | * instance of `Error`, then the function will reject with
|
147 | * {@link FaastError} on the local side. If the exception or rejection
|
148 | * resolves to any value that is not an instance of `Error`, the remote
|
149 | * function proxy will reject with the value of
|
150 | * `JSON.parse(JSON.stringify(err))`.
|
151 | *
|
152 | * Arguments and return values have size limitations that vary by provider
|
153 | * and mode:
|
154 | *
|
155 | * - AWS: 256KB in queue mode, 6MB arguments and 256KB return values in https mode. See
|
156 | * {@link https://docs.aws.amazon.com/lambda/latest/dg/limits.html | AWS Lambda Limits}.
|
157 | *
|
158 | * - Google: 10MB in https and queue modes. See
|
159 | * {@link https://cloud.google.com/functions/quotas | Google Cloud Function Quotas}.
|
160 | *
|
161 | * - Local: limited only by available memory and the limits of
|
162 | * {@link https://nodejs.org/api/child_process.html#child_process_subprocess_send_message_sendhandle_options_callback | childprocess.send}.
|
163 | *
|
164 | * Note that payloads may be base64 encoded for some providers and therefore
|
165 | * different in size than the original payload. Also, some bookkeeping data
|
166 | * are passed along with arguments and contribute to the size limit.
|
167 | */
|
168 | functions: ProxyModule<M>;
|
169 | /**
|
170 | * Similar to {@link FaastModule.functions} except each function returns a
|
171 | * {@link Detail} object
|
172 | * @remarks
|
173 | * Advanced users of faast.js may want more information about each function
|
174 | * invocation than simply the result of the function call. For example, the
|
175 | * specific logUrl for each invocation, to help with detailed debugging.
|
176 | * This interface provides a way to get this detailed information.
|
177 | */
|
178 | functionsDetail: ProxyModuleDetail<M>;
|
179 | /**
|
180 | * Stop the faast.js runtime for this cloud function and clean up ephemeral
|
181 | * cloud resources.
|
182 | * @returns a Promise that resolves when the `FaastModule` runtime stops and
|
183 | * ephemeral resources have been deleted.
|
184 | * @remarks
|
185 | * It is best practice to always call `cleanup` when done with a cloud
|
186 | * function. A typical way to ensure this in normal execution is to use the
|
187 | * `finally` construct:
|
188 | *
|
189 | * ```typescript
|
190 | * const faastModule = await faast("aws", m);
|
191 | * try {
|
192 | * // Call faastModule.functions.*
|
193 | * } finally {
|
194 | * // Note the `await`
|
195 | * await faastModule.cleanup();
|
196 | * }
|
197 | * ```
|
198 | *
|
199 | * After the cleanup promise resolves, the cloud function instance can no
|
200 | * longer invoke new calls on {@link FaastModule.functions}. However, other
|
201 | * methods on {@link FaastModule} are safe to call, such as
|
202 | * {@link FaastModule.costSnapshot}.
|
203 | *
|
204 | * Cleanup also stops statistics events (See {@link FaastModule.off}).
|
205 | *
|
206 | * By default, cleanup will delete all ephemeral cloud resources but leave
|
207 | * behind cached resources for use by future cloud functions. Deleted
|
208 | * resources typically include cloud functions, queues, and queue
|
209 | * subscriptions. Logs are not deleted by cleanup.
|
210 | *
|
211 | * Note that `cleanup` leaves behind some provider-specific resources:
|
212 | *
|
213 | * - AWS: Cloudwatch logs are preserved until the garbage collector in a
|
214 | * future cloud function instance deletes them. The default log expiration
|
215 | * time is 24h (or the value of {@link CommonOptions.retentionInDays}). In
|
216 | * addition, the AWS Lambda IAM role is not deleted by cleanup. This role
|
217 | * is shared across cloud function instances. Lambda layers are also not
|
218 | * cleaned up immediately on AWS when {@link CommonOptions.packageJson} is
|
219 | * used and {@link CommonOptions.useDependencyCaching} is true. Cached
|
220 | * layers are cleaned up by garbage collection. Also see
|
221 | * {@link CleanupOptions.deleteCaches}.
|
222 | *
|
223 | * - Google: Google Stackdriver automatically deletes log entries after 30
|
224 | * days.
|
225 | *
|
226 | * - Local: Logs are preserved in a temporary directory on local disk.
|
227 | * Garbage collection in a future cloud function instance will delete logs
|
228 | * older than 24h.
|
229 | */
|
230 | cleanup(options?: CleanupOptions): Promise<void>;
|
231 | /**
|
232 | * The URL of logs generated by this cloud function.
|
233 | * @remarks
|
234 | * Logs are not automatically downloaded because they cause outbound data
|
235 | * transfer, which can be expensive. Also, logs may arrive at the logging
|
236 | * service well after the cloud functions have completed. This log URL
|
237 | * specifically filters the logs for this cloud function instance.
|
238 | * Authentication is required to view cloud provider logs.
|
239 | *
|
240 | * The local provider returns a `file://` url pointing to a file for logs.
|
241 | */
|
242 | logUrl(): string;
|
243 | /**
|
244 | * Register a callback for statistics events.
|
245 | * @remarks
|
246 | * The callback is invoked once for each cloud function that was invoked
|
247 | * within the last 1s interval, with a {@link FunctionStatsEvent}
|
248 | * summarizing the statistics for each function. Typical usage:
|
249 | *
|
250 | * ```typescript
|
251 | * faastModule.on("stats", console.log);
|
252 | * ```
|
253 | */
|
254 | on(name: "stats", listener: (statsEvent: FunctionStatsEvent) => void): void;
|
255 | /**
|
256 | * Deregister a callback for statistics events.
|
257 | * @remarks
|
258 | * Stops the callback listener from receiving future function statistics
|
259 | * events. Calling {@link FaastModule.cleanup} also turns off statistics
|
260 | * events.
|
261 | */
|
262 | off(name: "stats", listener: (statsEvent: FunctionStatsEvent) => void): void;
|
263 | /**
|
264 | * Get a near real-time cost estimate of cloud function invocations.
|
265 | * @returns a Promise for a {@link CostSnapshot}.
|
266 | * @remarks
|
267 | * A cost snapshot provides a near real-time estimate of the costs of the
|
268 | * cloud functions invoked. The cost estimate only includes the cost of
|
269 | * successfully completed calls. Unsuccessful calls may lack the data
|
270 | * required to provide cost information. Calls that are still in flight are
|
271 | * not included in the cost snapshot. For this reason, it is typically a
|
272 | * good idea to get a cost snapshot after awaiting the result of
|
273 | * {@link FaastModule.cleanup}.
|
274 | *
|
275 | * Code example:
|
276 | *
|
277 | * ```typescript
|
278 | * const faastModule = await faast("aws", m);
|
279 | * try {
|
280 | * // invoke cloud functions on faastModule.functions.*
|
281 | * } finally {
|
282 | * await faastModule.cleanup();
|
283 | * const costSnapshot = await faastModule.costSnapshot();
|
284 | * console.log(costSnapshot);
|
285 | * }
|
286 | * ```
|
287 | */
|
288 | costSnapshot(): Promise<CostSnapshot>;
|
289 | /**
|
290 | * Statistics for a specific function or the entire faast.js module.
|
291 | *
|
292 | * @param functionName - The name of the function to retrieve statistics
|
293 | * for. If the function does not exist or has not been invoked, a new
|
294 | * instance of {@link FunctionStats} is returned with zero values. If
|
295 | * `functionName` omitted (undefined), then aggregate statistics are
|
296 | * returned that summarize all cloud functions within this faast.js module.
|
297 | * @returns an snapshot of {@link FunctionStats} at a point in time.
|
298 | */
|
299 | stats(functionName?: string): FunctionStats;
|
300 | }
|
301 | /**
|
302 | * Implementation of {@link FaastModule}.
|
303 | * @remarks
|
304 | * `FaastModuleProxy` provides a unified developer experience for faast.js
|
305 | * modules on top of provider-specific runtime APIs. Most users will not create
|
306 | * `FaastModuleProxy` instances themselves; instead use {@link faast}, or
|
307 | * {@link faastAws}, {@link faastGoogle}, or {@link faastLocal}.
|
308 | * `FaastModuleProxy` implements the {@link FaastModule} interface, which is the
|
309 | * preferred public interface for faast modules. `FaastModuleProxy` can be used
|
310 | * to access provider-specific details and state, and is useful for deeper
|
311 | * testing.
|
312 | * @public
|
313 | */
|
314 | export declare class FaastModuleProxy<M extends object, O, S> implements FaastModule<M> {
|
315 | private impl;
|
316 | /** @internal */
|
317 | readonly state: S;
|
318 | private fmodule;
|
319 | private modulePath;
|
320 | /** The options set for this instance, which includes default values. */
|
321 | readonly options: Required<CommonOptions>;
|
322 | /** The {@link Provider}, e.g. "aws" or "google". */
|
323 | provider: Provider;
|
324 | /** {@inheritdoc FaastModule.functions} */
|
325 | functions: ProxyModule<M>;
|
326 | /** {@inheritdoc FaastModule.functionsDetail} */
|
327 | functionsDetail: ProxyModuleDetail<M>;
|
328 | /** @internal */
|
329 | private _stats;
|
330 | private _cpuUsage;
|
331 | private _memoryLeakDetector;
|
332 | private _funnel;
|
333 | private _rateLimiter?;
|
334 | private _skew;
|
335 | private _statsTimer?;
|
336 | private _cleanupHooks;
|
337 | private _initialInvocationTime;
|
338 | private _callResultsPending;
|
339 | private _collectorPump;
|
340 | private _emitter;
|
341 | /**
|
342 | * Constructor
|
343 | * @internal
|
344 | */
|
345 | constructor(impl: ProviderImpl<O, S>,
|
346 | /** @internal */
|
347 | state: S, fmodule: M, modulePath: string,
|
348 | /** The options set for this instance, which includes default values. */
|
349 | options: Required<CommonOptions>);
|
350 | /** {@inheritdoc FaastModule.cleanup} */
|
351 | cleanup(userCleanupOptions?: CleanupOptions): Promise<void>;
|
352 | /** {@inheritdoc FaastModule.logUrl} */
|
353 | logUrl(): string;
|
354 | private startStats;
|
355 | private stopStats;
|
356 | /** {@inheritdoc FaastModule.on} */
|
357 | on(name: "stats", listener: (statsEvent: FunctionStatsEvent) => void): void;
|
358 | /** {@inheritdoc FaastModule.off} */
|
359 | off(name: "stats", listener: (statsEvent: FunctionStatsEvent) => void): void;
|
360 | private withCancellation;
|
361 | private processResponse;
|
362 | private invoke;
|
363 | private lookupFname;
|
364 | private createCallId;
|
365 | private wrapGenerator;
|
366 | private clearPending;
|
367 | private wrapFunction;
|
368 | /** {@inheritdoc FaastModule.costSnapshot} */
|
369 | costSnapshot(): Promise<CostSnapshot>;
|
370 | /** {@inheritdoc FaastModule.stats} */
|
371 | stats(functionName?: string): FunctionStats;
|
372 | private resultCollector;
|
373 | private adjustCollectorConcurrencyLevel;
|
374 | }
|
375 | /**
|
376 | * The return type of {@link faastAws}. See {@link FaastModuleProxy}.
|
377 | * @public
|
378 | */
|
379 | export declare type AwsFaastModule<M extends object = object> = FaastModuleProxy<M, AwsOptions, AwsState>;
|
380 | /**
|
381 | * The return type of {@link faastGoogle}. See {@link FaastModuleProxy}.
|
382 | * @public
|
383 | */
|
384 | export declare type GoogleFaastModule<M extends object = object> = FaastModuleProxy<M, GoogleOptions, GoogleState>;
|
385 | /**
|
386 | * The return type of {@link faastLocal}. See {@link FaastModuleProxy}.
|
387 | * @public
|
388 | */
|
389 | export declare type LocalFaastModule<M extends object = object> = FaastModuleProxy<M, LocalOptions, LocalState>;
|
390 | /**
|
391 | * The main entry point for faast with any provider and only common options.
|
392 | * @param provider - One of `"aws"`, `"google"`, or `"local"`. See
|
393 | * {@link Provider}.
|
394 | * @param fmodule - A module imported with `import * as X from "Y";`. Using
|
395 | * `require` also works but loses type information.
|
396 | * @param options - See {@link CommonOptions}.
|
397 | * @returns See {@link FaastModule}.
|
398 | * @remarks
|
399 | * Example of usage:
|
400 | * ```typescript
|
401 | * import { faast } from "faastjs";
|
402 | * import * as mod from "./path/to/module";
|
403 | * (async () => {
|
404 | * const faastModule = await faast("aws", mod);
|
405 | * try {
|
406 | * const result = await faastModule.functions.func("arg");
|
407 | * } finally {
|
408 | * await faastModule.cleanup();
|
409 | * }
|
410 | * })();
|
411 | * ```
|
412 | * @public
|
413 | */
|
414 | export declare function faast<M extends object>(provider: Provider, fmodule: M, options?: CommonOptions): Promise<FaastModule<M>>;
|
415 | /**
|
416 | * The main entry point for faast with AWS provider.
|
417 | * @param fmodule - A module imported with `import * as X from "Y";`. Using
|
418 | * `require` also works but loses type information.
|
419 | * @param options - Most common options are in {@link CommonOptions}.
|
420 | * Additional AWS-specific options are in {@link AwsOptions}.
|
421 | * @public
|
422 | */
|
423 | export declare function faastAws<M extends object>(fmodule: M, options?: AwsOptions): Promise<AwsFaastModule<M>>;
|
424 | /**
|
425 | * The main entry point for faast with Google provider.
|
426 | * @param fmodule - A module imported with `import * as X from "Y";`. Using
|
427 | * `require` also works but loses type information.
|
428 | * @param options - Most common options are in {@link CommonOptions}.
|
429 | * Additional Google-specific options are in {@link GoogleOptions}.
|
430 | * @public
|
431 | */
|
432 | export declare function faastGoogle<M extends object>(fmodule: M, options?: GoogleOptions): Promise<GoogleFaastModule<M>>;
|
433 | /**
|
434 | * The main entry point for faast with Local provider.
|
435 | * @param fmodule - A module imported with `import * as X from "Y";`. Using
|
436 | * `require` also works but loses type information.
|
437 | * @param options - Most common options are in {@link CommonOptions}.
|
438 | * Additional Local-specific options are in {@link LocalOptions}.
|
439 | * @returns a Promise for {@link LocalFaastModule}.
|
440 | * @public
|
441 | */
|
442 | export declare function faastLocal<M extends object>(fmodule: M, options?: LocalOptions): Promise<LocalFaastModule<M>>;
|