import * as webpack from "webpack" ; import { CostSnapshot } from "./cost" ; import { keysOf , Statistics } from "./shared" ; import { CpuMeasurement , FunctionCall } from "./wrapper" ; public export type Provider = "aws" | "google" | "local" ; /**
 * Options for the  CommonOptions . include option.
 *  public export interface IncludeOption { /**
     * The path to the directory or glob to add to the cloud function.
     */ path : string ; /**
     * The working directory if `path` is relative. Defaults to `process.cwd()`.
     * For example, if `cwd` is `"foo"` and `path` is `"bar"`, then the
     * contents of the directory `foo/bar/` will be added to the remote
     * function under the path `bar/`.
     */ cwd ? : string ; } /**
 * Options common across all faast.js providers. Used as argument to  faast .
 *  remarks There are also more specific options for each provider. See
 *  AwsOptions ,  GoogleOptions , and  LocalOptions .
 *  public export interface CommonOptions { remarks If a child process is not created, faast runs in the same node instance
     * as the user code and may not execute in a timely fashion because user
     * code may
     *  https .
     * Creating a child process for user code allows faast.js to continue
     * executing even if user code never yields. This provides better
     * reliability and functionality:
     *
     * - Detect timeout errors more reliably, even if the function doesn't
     *   relinquish the CPU. Not applicable to AWS, which sends separate failure
     *   messages in case of timeout. See  CommonOptions . timeout .
     *
     * - CPU metrics used for detecting invocations with high latency, which can
     *   be used for automatically retrying calls to reduce tail latency.
     *
     * The cost of creating a child process is mainly in the memory overhead of
     * creating another node process.
      childProcess ? : boolean ; remarks The concurrency limit applies to all invocations of all of the faast
     * functions summed together. It is not a per-function limit. To apply a
     * per-function limit, use  throttle . A value of 0 is equivalent to
     * Infinity. A value of 1 ensures mutually exclusive invocations.
      concurrency ? : number ; /**
     * A user-supplied description for this function, which may make it easier
     * to track different functions when multiple functions are created.
     */ description ? : string ; /**
     * Exclude a subset of files included by  CommonOptions . include .
     *  remarks exclude ? : string [ ] ; remarks rate ? : number ; /**
     * Environment variables available during serverless function execution.
     * Default: \{\}.
     */ env ? : { [ key ] : string ; } ; remarks Garbage collection deletes resources that were created by previous
     * instantiations of faast that were not cleaned up by
     *  FaastModule . cleanup , either because it was not called or because
     * the process terminated and did not execute this cleanup step. In `"auto"`
     * mode, garbage collection may be throttled to run up to once per hour no
     * matter how many faast.js instances are created. In `"force"` mode,
     * garbage collection is run without regard to whether another gc has
     * already been performed recently. In `"off"` mode, garbage collection is
     * skipped entirely. This can be useful for performance-sensitive tests, or
     * for more control over when gc is performed.
     *
     * Garbage collection is cloud-specific, but in general garbage collection
     * should not interfere with the behavior or performance of faast cloud
     * functions. When  FaastModule . cleanup runs, it waits for garbage
     * collection to complete. Therefore the cleanup step can in some
     * circumstances take a significant amount of time even after all
     * invocations have returned.
     *
     * It is generally recommended to leave garbage collection in `"auto"` mode,
     * otherwise garbage resources may accumulate over time and you will
     * eventually hit resource limits on your account.
     *
     * Also see  CommonOptions . retentionInDays .
      gc ? : "auto" | "force" | "off" ; /**
     * Include files to make available in the remote function. See
     *  IncludeOption .
     *  remarks Each include entry is a directory or glob pattern. Paths can be specified
     * as relative or absolute paths. Relative paths are resolved relative to
     * the current working directory, or relative to the `cwd` option.
     *
     * If the include entry is a directory `"foo/bar"`, the directory
     * `"./foo/bar"` will be available in the cloud function. Directories are
     * recursively added.
     *
     * Glob patterns use the syntax of
     *  https .
     *
     * Also see  CommonOptions . exclude for file exclusions.
      include ? : ( string | IncludeOption ) [ ] ; remarks maxRetries ? : number ; remarks memorySize ? : number ; remarks mode ? : "https" | "queue" | "auto" ; remarks By default, faast.js will use webpack to bundle dependencies your remote
     * module imports. In normal usage there is no need to specify a separate
     * package.json, as webpack will statically analyze your imports and
     * determine which files to bundle.
     *
     * However, there are some use cases where this is not enough. For example,
     * some dependencies contain native code compiled during installation, and
     * webpack cannot bundle these native modules. such as dependencies with
     * native code.  or are specifically not designed to work with webpack. In
     * these cases, you can create a separate `package.json` for these
     * dependencies and pass the filename as the `packageJson` option. If
     * `packageJson` is an `object`, it is assumed to be a parsed JSON object
     * with the same structure as a package.json file (useful for specifying a
     * synthetic `package.json` directly in code).
     *
     * The way the `packageJson` is handled varies by provider:
     *
     * - local: Runs `npm install` in a temporary directory it prepares for the
     *   function.
     *
     * - google: uses Google Cloud Function's
     *    https .
     *
     * - aws: Recursively calls faast.js to run `npm install` inside a separate
     *   lambda function specifically created for this purpose. Faast.js uses
     *   lambda to install dependencies to ensure that native dependencies are
     *   compiled in an environment that can produce binaries linked against
     *   lambda's
     *    https .
     *   Packages are saved in a Lambda Layer.
     *
     * For AWS, if  CommonOptions . useDependencyCaching is `true` (which
     * is the default), then the Lambda Layer created will be reused in future
     * function creation requests if the contents of `packageJson` are the same.
     *
     * The `FAAST_PACKAGE_DIR` environment variable can be useful for debugging
     * `packageJson` issues.
      packageJson ? : string | object ; /**
     * Cache installed dependencies from  CommonOptions . packageJson . Only
     * applies to AWS. Default: true.
     *  remarks useDependencyCaching ? : boolean ; remarks Garbage collection only deletes resources after they age beyond a certain
     * number of days. This option specifies how many days old a resource needs
     * to be before being considered garbage by the collector. Note that this
     * setting is not recorded when the resources are created. For example,
     * suppose this is the sequence of events:
     *
     * - Day 0: `faast()` is called with `retentionInDays` set to 5. Then, the
     *   function crashes (or omits the call to  FaastModule . cleanup ).
     *
     * - Day 1: `faast()` is called with `retentionInDays` set to 1.
     *
     * In this sequence of events, on Day 0 the garbage collector runs and
     * removes resources with age older than 5 days. Then the function leaves
     * new garbage behind because it crashed or did not complete cleanup. On Day
     * 1, the garbage collector runs and deletes resources at least 1 day old,
     * which includes garbage left behind from Day 0 (based on the creation
     * timestamp of the resources). This deletion occurs even though retention
     * was set to 5 days when resources were created on Day 0.
     *
     * On Google, logs are retained according to Google's default expiration
     * policy (30 days) instead of being deleted by garbage collection.
     *
     * Note that if `retentionInDays` is set to 0, garbage collection will
     * remove all resources, even ones that may be in use by other running faast
     * instances. Not recommended.
     *
     * See  CommonOptions . gc .
      retentionInDays ? : number ; remarks beta speculativeRetryThreshold ? : number ; remarks Each provider has a maximum time limit for how long invocations can run
     * before being automatically terminated (or frozen). The following are the
     * maximum time limits as of February 2019:
     *
     * - aws:
     *    https *
     * - google:  https *
     * - local: unlimited
     *
     * Faast.js has a proactive timeout detection feature. It automatically
     * attempts to detect when the time limit is about to be reached and
     * proactively sends a timeout exception. Faast does this because not all
     * providers reliably send timely feedback when timeouts occur, leaving
     * developers to look through cloud logs. In general faast.js' timeout will
     * be up to 5s earlier than the timeout specified, in order to give time to
     * allow faast.js to send a timeout message. Proactive timeout detection
     * only works with  CommonOptions . childProcess set to `true` (the
     * default).
      timeout ? : number ; remarks By default, faast.js uses webpack to bundle the code package. Webpack
     * automatically handles finding and bundling dependencies, adding source
     * mappings, etc. If you need specialized bundling, use this option to add
     * or override the default webpack configuration. The library
     *  https is
     * used to combine configurations.
     *
     * ```typescript
     * const config: webpack.Configuration = merge({
     *     entry,
     *     mode: "development",
     *     output: {
     *         path: "/",
     *         filename: outputFilename,
     *         libraryTarget: "commonjs2"
     *     },
     *     target: "node",
     *     resolveLoader: { modules: [__dirname, `${__dirname}/dist}`] },
     *     node: { global: true, __dirname: false, __filename: false }
     *   },
     *   webpackOptions);
     * ```
     *
     * Take care when setting the values of `entry`, `output`, or
     * `resolveLoader`. If these options are overwritten, faast.js may fail to
     * bundle your code. In particular, setting `entry` to an array value will
     * help `webpack-merge` to concatenate its value instead of replacing the
     * value that faast.js inserts for you.
     *
     * Default:
     *
     * - aws: `{ externals: [new RegExp("^aws-sdk/?")] }`. In the lambda
     *   environment `"aws-sdk"` is available in the ambient environment and
     *   does not need to be bundled.
     *
     * - other providers: `{}`
     *
     * The `FAAST_PACKAGE_DIR` environment variable can be useful for debugging
     * webpack issues.
      webpackOptions ? : webpack . Configuration ; remarks Arguments to cloud functions are automatically serialized with
     * `JSON.stringify` with a custom replacer that handles built-in JavaScript
     * types such as `Date` and `Buffer`. Return values go through the same
     * process. Some JavaScript objects cannot be serialized. By default
     * `validateSerialization` will verify that every argument and return value
     * can be serialized and deserialized without losing information. A
     * `FaastError` will be thrown if faast.js detects a problem according to
     * the following procedure:
     *
     * 1. Serialize arguments and return values with `JSON.stringify` using a
     *    special `replacer` function.
     *
     * 2. Deserialize the values with `JSON.parse` with a special `reviver`
     *    function.
     *
     * 3. Use
     *     https *    to compare the original object with the deserialized object from step
     *    2.
     *
     * There is some overhead to this process because each argument is
     * serialized and deserialized, which can be costly if arguments or return
     * values are large.
      validateSerialization ? : boolean ; internal debugOptions ? : { [ key ] : boolean ; } ; } export const commonDefaults = { childProcess : true , concurrency : 100 , description : "" , exclude : [ ] , include : [ ] , rate : 0 , env : { } , gc : "auto" , maxRetries : 2 , memorySize : 1024 , mode : "auto" , packageJson : "" , useDependencyCaching : true , retentionInDays : 1 , speculativeRetryThreshold : 3 , timeout : 60 , webpackOptions : { } , validateSerialization : true , debugOptions : { } } ; /**
 * Options that apply to the  FaastModule . cleanup method.
 *  public export interface CleanupOptions { remarks The cleanup operation has two functions: stopping the faast.js runtime
     * and deleting cloud resources that were instantiated. If `deleteResources`
     * is false, then only the runtime is stopped and no cloud resources are
     * deleted. This can be useful for debugging and examining the state of
     * resources created by faast.js.
     *
     * It is supported to call  FaastModule . cleanup twice: once with
     * `deleteResources` set to `false`, which only stops the runtime, and then
     * again set to `true` to delete resources. This can be useful for testing.
      deleteResources ? : boolean ; remarks Some resources are cached persistently between calls for performance
     * reasons. If this option is set to true, these cached resources are
     * deleted when cleanup occurs, instead of being left behind for future use.
     * For example, on AWS this includes the Lambda Layers that are created for
     *  CommonOptions . packageJson dependencies. Note that only the cached
     * resources created by this instance of FaastModule are deleted, not cached
     * resources from other FaastModules. This is similar to setting
     * `useCachedDependencies` to `false` during function construction, except
     * `deleteCaches` can be set at function cleanup time, and any other
     * FaastModules created before cleanup may use the cached Layers.
      deleteCaches ? : boolean ; remarks gcTimeout ? : number ; } export const CleanupOptionDefaults = { deleteResources : true , deleteCaches : false , gcTimeout : 10 } ; remarks public export class FunctionStats { /**
     * Statistics for how long invocations stay in the local queue before being
     * sent to the cloud provider.
     */ localStartLatency = new Statistics ( ) ; /**
     * Statistics for how long requests take to start execution after being sent
     * to the cloud provider. This typically includes remote queueing and cold
     * start times. Because this measurement requires comparing timestamps from
     * different machines, it is subject to clock skew and other effects, and
     * should not be considered highly accurate. It can be useful for detecting
     * excessively high latency problems. Faast.js attempt to correct for clock
     * skew heuristically.
     */ remoteStartLatency = new Statistics ( ) ; /**
     * Statistics for function execution time in milliseconds.  This is measured
     * as wall clock time inside the cloud function, and does not include the
     * time taken to send the response to the response queue. Note that most
     * cloud providers round up to the next 100ms for pricing.
     */ executionTime = new Statistics ( ) ; /**
     * Statistics for how long it takes to send the response to the response
     * queue.
     */ sendResponseLatency = new Statistics ( ) ; /**
     * Statistics for how long it takes to return a response from the end of
     * execution time to the receipt of the response locally. This measurement
     * requires comparing timestamps from different machines, and is subject to
     * clock skew and other effects. It should not be considered highly
     * accurate. It can be useful for detecting excessively high latency
     * problems. Faast.js attempts to correct for clock skew heuristically.
     */ returnLatency = new Statistics ( ) ; /**
     * Statistics for amount of time billed. This is similar to
     *  FunctionStats . executionTime except each sampled time is rounded
     * up to the next 100ms.
      estimatedBilledTime = new Statistics ( ) ; /**
     * The number of invocations attempted. If an invocation is retried, this
     * only counts the invocation once.
     */ invocations = 0 ; /**
     * The number of invocations that were successfully completed.
     */ completed = 0 ; /**
     * The number of invocation retries attempted. This counts retries
     * attempted by faast.js to recover from transient errors, but does not
     * count retries by the cloud provider.
     */ retries = 0 ; /**
     * The number of invocations that resulted in an error. If an invocation is
     * retried, an error is only counted once, no matter how many retries were
     * attempted.
     */ errors = 0 ; returns toString ( ) { return `completed: ${ this . completed }, retries: ${ this . retries }, errors: ${ this . errors }, executionTime.mean: ${ this . executionTime . mean }ms` ; } internal clone ( ) { const rv = Object . assign ( Object . create ( Object . getPrototypeOf ( this ) ) , this ) ; for ( const key of keysOf ( rv ) ) { if ( typeof rv [ key ] !== "number" ) { rv [ key ] = rv [ key ] . clone ( ) ; } } return rv ; } } export class FunctionExecutionMetrics { secondMetrics : Statistics [ ] = [ ] ; } export type CallId = string ; export interface ResponseContext { type : "fulfill" | "reject" ; value : string ; callId : CallId ; isErrorObject ? : boolean ; remoteExecutionStartTime ? : number ; remoteExecutionEndTime ? : number ; logUrl ? : string ; instanceId ? : string ; executionId ? : string ; memoryUsage ? : NodeJS . MemoryUsage ; timestamp ? : number ; } export interface PromiseResponseMessage extends ResponseContext { kind : "promise" ; } export interface IteratorResponseMessage extends ResponseContext { kind : "iterator" ; sequence : number ; } export interface FunctionStartedMessage { kind : "functionstarted" ; callId : CallId ; } export interface CpuMetricsMessage { kind : "cpumetrics" ; callId : CallId ; metrics : CpuMeasurement ; } export interface PollResult { Messages : Message [ ] ; isFullMessageBatch ? : boolean ; } export type Message = PromiseResponseMessage | IteratorResponseMessage | FunctionStartedMessage | CpuMetricsMessage ; export type Kind = Message [ "kind" ] ; export type UUID = string ; export function filterMessages < K extends Kind > ( messages , kind ) { return messages . filter ( ( msg ) : msg is Extract < Message , { kind : K ; } > => msg . kind === kind ) ; } export interface ProviderImpl < O extends CommonOptions , S > { name : Provider ; defaults : Required < O > ; initialize ( serverModule , nonce , options ) : Promise < S > ; costSnapshot ( state , stats ) : Promise < CostSnapshot > ; cleanup ( state , options ) : Promise < void > ; logUrl ( state ) : string ; invoke ( state , request , cancel ) : Promise < void > ; poll ( state , cancel ) : Promise < PollResult > ; responseQueueId ( state ) : string ; }