serverless-offline 8.7.0 → 9.0.0

package/src/ServerlessOffline.js

@@ -0,0 +1,412 @@
+import process, { env, exit } from 'node:process'
+import { log } from '@serverless/utils/log.js'
+import chalk from 'chalk'
+import {
+  commandOptions,
+  CUSTOM_OPTION,
+  defaultOptions,
+  SERVER_SHUTDOWN_TIMEOUT,
+} from './config/index.js'
+
+export default class ServerlessOffline {
+  #cliOptions = null
+
+  #http = null
+
+  #lambda = null
+
+  #options = null
+
+  #schedule = null
+
+  #serverless = null
+
+  #webSocket = null
+
+  constructor(serverless, cliOptions) {
+    this.#cliOptions = cliOptions
+    this.#serverless = serverless
+
+    this.commands = {
+      offline: {
+        // add start nested options
+        commands: {
+          functionsUpdated: {
+            lifecycleEvents: ['cleanup'],
+            type: 'entrypoint',
+          },
+          start: {
+            lifecycleEvents: ['init', 'ready', 'end'],
+            options: commandOptions,
+            usage:
+              'Simulates API Gateway to call your lambda functions offline using backward compatible initialization.',
+          },
+        },
+        lifecycleEvents: ['start'],
+        options: commandOptions,
+        usage: 'Simulates API Gateway to call your lambda functions offline.',
+      },
+    }
+
+    this.hooks = {
+      'offline:functionsUpdated:cleanup': this.#cleanupFunctions.bind(this),
+      'offline:start': this.#startWithExplicitEnd.bind(this),
+      'offline:start:end': this.end.bind(this),
+      'offline:start:init': this.start.bind(this),
+      'offline:start:ready': this.#ready.bind(this),
+    }
+  }
+
+  // Entry point for the plugin (sls offline) when running 'sls offline start'
+  async start() {
+    // Put here so available everywhere, not just in handlers
+    env.IS_OFFLINE = true
+
+    this.#mergeOptions()
+
+    const { httpEvents, lambdas, scheduleEvents, webSocketEvents } =
+      this.#getEvents()
+
+    // if (lambdas.length > 0) {
+    await this.#createLambda(lambdas)
+    // }
+
+    const eventModules = []
+
+    if (httpEvents.length > 0) {
+      eventModules.push(this.#createHttp(httpEvents))
+    }
+
+    if (!this.#options.disableScheduledEvents && scheduleEvents.length > 0) {
+      eventModules.push(this.#createSchedule(scheduleEvents))
+    }
+
+    if (webSocketEvents.length > 0) {
+      eventModules.push(this.#createWebSocket(webSocketEvents))
+    }
+
+    await Promise.all(eventModules)
+  }
+
+  async #ready() {
+    await this.#listenForTermination()
+  }
+
+  async end(skipExit) {
+    log.info('Halting offline server')
+
+    const eventModules = []
+
+    if (this.#lambda) {
+      eventModules.push(this.#lambda.cleanup())
+      eventModules.push(this.#lambda.stop(SERVER_SHUTDOWN_TIMEOUT))
+    }
+
+    if (this.#http) {
+      eventModules.push(this.#http.stop(SERVER_SHUTDOWN_TIMEOUT))
+    }
+
+    // if (this.#schedule) {
+    //   eventModules.push(this.#schedule.stop())
+    // }
+
+    if (this.#webSocket) {
+      eventModules.push(this.#webSocket.stop(SERVER_SHUTDOWN_TIMEOUT))
+    }
+
+    await Promise.all(eventModules)
+
+    if (!skipExit) {
+      exit(0)
+    }
+  }
+
+  async #cleanupFunctions() {
+    if (this.#lambda) {
+      log.debug('Forcing cleanup of Lambda functions')
+      await this.#lambda.cleanup()
+    }
+  }
+
+  /**
+   * Entry point for the plugin (serverless offline) when running 'serverless offline'
+   * The call to this.end() would terminate the process before 'offline:start:end' could be consumed
+   * by downstream plugins. When running serverless offline that can be expected, but docs say that
+   * 'serverless offline start' will provide the init and end hooks for other plugins to consume
+   * */
+  async #startWithExplicitEnd() {
+    await this.start()
+    await this.#ready()
+    this.end()
+  }
+
+  async #listenForTermination() {
+    const command = await new Promise((resolve) => {
+      process
+        // SIGINT will be usually sent when user presses ctrl+c
+        .on('SIGINT', () => resolve('SIGINT'))
+        // SIGTERM is a default termination signal in many cases,
+        // for example when "killing" a subprocess spawned in node
+        // with child_process methods
+        .on('SIGTERM', () => resolve('SIGTERM'))
+    })
+
+    log.info(`Got ${command} signal. Offline Halting...`)
+  }
+
+  async #createLambda(lambdas, skipStart) {
+    const { default: Lambda } = await import('./lambda/index.js')
+
+    this.#lambda = new Lambda(this.#serverless, this.#options)
+
+    this.#lambda.create(lambdas)
+
+    if (!skipStart) {
+      await this.#lambda.start()
+    }
+  }
+
+  async #createHttp(events, skipStart) {
+    const { default: Http } = await import('./events/http/index.js')
+
+    this.#http = new Http(this.#serverless, this.#options, this.#lambda)
+
+    await this.#http.registerPlugins()
+
+    this.#http.create(events)
+
+    // HTTP Proxy defined in Resource
+    this.#http.createResourceRoutes()
+
+    // Not found handling
+    // we have to create the 404 routes last, otherwise we could have
+    // collisions with catch all routes, e.g. any (proxy+}
+    this.#http.create404Route()
+
+    if (!skipStart) {
+      await this.#http.start()
+    }
+  }
+
+  async #createSchedule(events) {
+    const { default: Schedule } = await import('./events/schedule/index.js')
+
+    this.#schedule = new Schedule(
+      this.#lambda,
+      this.#serverless.service.provider.region,
+    )
+
+    this.#schedule.create(events)
+  }
+
+  async #createWebSocket(events) {
+    const { default: WebSocket } = await import('./events/websocket/index.js')
+
+    this.#webSocket = new WebSocket(
+      this.#serverless,
+      this.#options,
+      this.#lambda,
+    )
+
+    this.#webSocket.create(events)
+
+    return this.#webSocket.start()
+  }
+
+  #mergeOptions() {
+    const {
+      service: { custom = {}, provider },
+    } = this.#serverless
+
+    const customOptions = custom[CUSTOM_OPTION]
+
+    // merge options
+    // order of Precedence: command line options, custom options, defaults.
+    this.#options = {
+      ...defaultOptions,
+      ...customOptions,
+      ...this.#cliOptions,
+    }
+
+    // Parse CORS options
+    this.#options.corsAllowHeaders = this.#options.corsAllowHeaders
+      .replace(/\s/g, '')
+      .split(',')
+    this.#options.corsAllowOrigin = this.#options.corsAllowOrigin
+      .replace(/\s/g, '')
+      .split(',')
+    this.#options.corsExposedHeaders = this.#options.corsExposedHeaders
+      .replace(/\s/g, '')
+      .split(',')
+
+    if (this.#options.corsDisallowCredentials) {
+      this.#options.corsAllowCredentials = false
+    }
+
+    this.#options.corsConfig = {
+      credentials: this.#options.corsAllowCredentials,
+      exposedHeaders: this.#options.corsExposedHeaders,
+      headers: this.#options.corsAllowHeaders,
+      origin: this.#options.corsAllowOrigin,
+    }
+
+    log.notice()
+    log.notice(
+      `Starting Offline at stage ${provider.stage} ${chalk.gray(
+        `(${provider.region})`,
+      )}`,
+    )
+    log.notice()
+    log.debug('options:', this.#options)
+  }
+
+  #getEvents() {
+    const { service } = this.#serverless
+
+    const httpEvents = []
+    const lambdas = []
+    const scheduleEvents = []
+    const webSocketEvents = []
+
+    const functionKeys = service.getAllFunctions()
+
+    let hasPrivateHttpEvent = false
+
+    functionKeys.forEach((functionKey) => {
+      const functionDefinition = service.getFunction(functionKey)
+
+      lambdas.push({ functionDefinition, functionKey })
+
+      const events = service.getAllEventsInFunction(functionKey) || []
+
+      events.forEach((event) => {
+        const { http, httpApi, schedule, websocket } = event
+
+        if ((http || httpApi) && functionDefinition.handler) {
+          const httpEvent = {
+            functionKey,
+            handler: functionDefinition.handler,
+            http: http || httpApi,
+          }
+
+          if (httpApi) {
+            // Ensure definitions for 'httpApi' events are objects so that they can be marked
+            // with an 'isHttpApi' property (they are handled differently to 'http' events)
+            if (typeof httpEvent.http === 'string') {
+              httpEvent.http = {
+                routeKey: httpEvent.http === '*' ? '$default' : httpEvent.http,
+              }
+            } else if (typeof httpEvent.http === 'object') {
+              if (!httpEvent.http.method) {
+                log.warning(
+                  `Event definition is missing a method for function "${functionKey}"`,
+                )
+                httpEvent.http.method = ''
+              }
+              if (
+                httpEvent.http.method === '*' &&
+                httpEvent.http.path === '*'
+              ) {
+                httpEvent.http.routeKey = '$default'
+              } else {
+                const resolvedMethod =
+                  httpEvent.http.method === '*'
+                    ? 'ANY'
+                    : httpEvent.http.method.toUpperCase()
+                httpEvent.http.routeKey = `${resolvedMethod} ${httpEvent.http.path}`
+              }
+              // Clear these properties to avoid confusion (they will be derived from the routeKey
+              // when needed later)
+              delete httpEvent.http.method
+              delete httpEvent.http.path
+            } else {
+              log.warning(
+                `Event definition must be a string or object but received ${typeof httpEvent.http} for function "${functionKey}"`,
+              )
+              httpEvent.http.routeKey = ''
+            }
+
+            httpEvent.http.isHttpApi = true
+            if (
+              functionDefinition.httpApi &&
+              functionDefinition.httpApi.payload
+            ) {
+              httpEvent.http.payload = functionDefinition.httpApi.payload
+            } else {
+              httpEvent.http.payload =
+                service.provider.httpApi && service.provider.httpApi.payload
+                  ? service.provider.httpApi.payload
+                  : '2.0'
+            }
+          }
+
+          if (http && http.private) {
+            hasPrivateHttpEvent = true
+          }
+
+          httpEvents.push(httpEvent)
+        }
+
+        if (schedule) {
+          scheduleEvents.push({
+            functionKey,
+            schedule,
+          })
+        }
+
+        if (websocket) {
+          webSocketEvents.push({
+            functionKey,
+            websocket,
+          })
+        }
+      })
+    })
+
+    // for simple API Key authentication model
+    if (hasPrivateHttpEvent) {
+      log.notice(`Key with token: ${this.#options.apiKey}`)
+
+      if (this.#options.noAuth) {
+        log.notice(
+          'Authorizers are turned off. You do not need to use x-api-key header.',
+        )
+      } else {
+        log.notice('Remember to use x-api-key on the request headers')
+      }
+    }
+
+    return {
+      httpEvents,
+      lambdas,
+      scheduleEvents,
+      webSocketEvents,
+    }
+  }
+
+  // TODO FIXME
+  // TEMP quick fix to expose for testing, look for better solution
+  internals() {
+    return {
+      createHttp: (events, skipStart) => {
+        return this.#createHttp(events, skipStart)
+      },
+
+      createLambda: (lambdas, skipStart) => {
+        return this.#createLambda(lambdas, skipStart)
+      },
+
+      getApiGatewayServer: () => {
+        return this.#http.getServer()
+      },
+
+      getEvents: () => {
+        return this.#getEvents()
+      },
+
+      mergeOptions: () => {
+        this.#mergeOptions()
+      },
+    }
+  }
+}

package/src/config/commandOptions.js

@@ -0,0 +1,155 @@
+export default {
+  apiKey: {
+    type: 'string',
+    usage:
+      'Defines the API key value to be used for endpoints marked as private. Defaults to a random hash.',
+  },
+  corsAllowHeaders: {
+    type: 'string',
+    usage:
+      'Used to build the Access-Control-Allow-Headers header for CORS support.',
+  },
+  corsAllowOrigin: {
+    type: 'string',
+    usage:
+      'Used to build the Access-Control-Allow-Origin header for CORS support.',
+  },
+  corsDisallowCredentials: {
+    type: 'boolean',
+    usage:
+      'Used to override the Access-Control-Allow-Credentials default (which is true) to false.',
+  },
+  corsExposedHeaders: {
+    type: 'string',
+    usage:
+      'Used to build the Access-Control-Exposed-Headers response header for CORS support',
+  },
+  disableCookieValidation: {
+    type: 'boolean',
+    usage: 'Used to disable cookie-validation on hapi.js-server',
+  },
+  disableScheduledEvents: {
+    type: 'boolean',
+    usage:
+      'Disables all scheduled events. Overrides configurations in serverless.yml. Default: false',
+  },
+  dockerHost: {
+    type: 'string',
+    usage: 'The host name of Docker. Default: localhost',
+  },
+  dockerHostServicePath: {
+    type: 'string',
+    usage:
+      'Defines service path which is used by SLS running inside Docker container',
+  },
+  dockerNetwork: {
+    type: 'string',
+    usage: 'The network that the Docker container will connect to',
+  },
+  dockerReadOnly: {
+    type: 'boolean',
+    usage: 'Marks if the docker code layer should be read only. Default: true',
+  },
+  enforceSecureCookies: {
+    type: 'boolean',
+    usage: 'Enforce secure cookies',
+  },
+  functionCleanupIdleTimeSeconds: {
+    type: 'string',
+    usage: 'Number of seconds until an idle function is eligible for cleanup',
+  },
+  hideStackTraces: {
+    type: 'boolean',
+    usage: 'Hide the stack trace on lambda failure. Default: false',
+  },
+  host: {
+    shortcut: 'o',
+    type: 'string',
+    usage: 'The host name to listen on. Default: localhost',
+  },
+  httpPort: {
+    type: 'string',
+    usage: 'HTTP port to listen on. Default: 3000',
+  },
+  httpsProtocol: {
+    shortcut: 'H',
+    type: 'string',
+    usage:
+      'To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files.',
+  },
+  ignoreJWTSignature: {
+    type: 'boolean',
+    usage:
+      "When using HttpApi with a JWT authorizer, don't check the signature of the JWT token. This should only be used for local development.",
+  },
+  lambdaPort: {
+    type: 'string',
+    usage: 'Lambda http port to listen on. Default: 3002',
+  },
+  layersDir: {
+    type: 'string',
+    usage:
+      'The directory layers should be stored in. Default: {codeDir}/.serverless-offline/layers',
+  },
+  noAuth: {
+    type: 'boolean',
+    usage: 'Turns off all authorizers',
+  },
+  noPrependStageInUrl: {
+    type: 'boolean',
+    usage: "Don't prepend http routes with the stage.",
+  },
+  noStripTrailingSlashInUrl: {
+    type: 'boolean',
+    usage: "Don't strip trailing slash from http routes.",
+  },
+  noTimeout: {
+    shortcut: 't',
+    type: 'boolean',
+    usage: 'Disables the timeout feature.',
+  },
+  prefix: {
+    shortcut: 'p',
+    type: 'string',
+    usage:
+      'Adds a prefix to every path, to send your requests to http://localhost:3000/prefix/[your_path] instead.',
+  },
+  printOutput: {
+    type: 'boolean',
+    usage: 'Outputs your lambda response to the terminal.',
+  },
+  reloadHandler: {
+    type: 'boolean',
+    usage: 'Reloads handler with each request.',
+  },
+  resourceRoutes: {
+    type: 'boolean',
+    usage: 'Turns on loading of your HTTP proxy settings from serverless.yml.',
+  },
+  useChildProcesses: {
+    type: 'boolean',
+    usage: 'Use separate node process to run handlers',
+  },
+  useDocker: {
+    type: 'boolean',
+    usage: 'Uses docker for node/python/ruby/provided',
+  },
+  useInProcess: {
+    type: 'boolean',
+    usage: "Run handlers in the same process as 'serverless-offline'",
+  },
+  webSocketHardTimeout: {
+    type: 'string',
+    usage:
+      'Set WebSocket hard timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table). Default: 7200 (2 hours)',
+  },
+  webSocketIdleTimeout: {
+    type: 'string',
+    usage:
+      'Set WebSocket idle timeout in seconds to reproduce AWS limits (https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-execution-service-websocket-limits-table). Default: 600 (10 minutes)',
+  },
+  websocketPort: {
+    type: 'string',
+    usage: 'Websocket port to listen on. Default: 3001',
+  },
+}

package/src/config/constants.js

@@ -0,0 +1,22 @@
+// dummy placeholder url for the WHATWG URL constructor
+// https://github.com/nodejs/node/issues/12682
+export const BASE_URL_PLACEHOLDER = 'http://example'
+
+export const CUSTOM_OPTION = 'serverless-offline'
+
+export const DEFAULT_LAMBDA_RUNTIME = 'nodejs12.x'
+
+// https://docs.aws.amazon.com/lambda/latest/dg/limits.html
+export const DEFAULT_LAMBDA_MEMORY_SIZE = 1024
+// default function timeout in seconds
+export const DEFAULT_LAMBDA_TIMEOUT = 900 // 15 min
+
+// timeout for all connections to be closed
+export const SERVER_SHUTDOWN_TIMEOUT = 5000
+
+export const DEFAULT_WEBSOCKETS_API_ROUTE_SELECTION_EXPRESSION =
+  '$request.body.action'
+
+export const DEFAULT_WEBSOCKETS_ROUTE = '$default'
+
+export const DEFAULT_DOCKER_CONTAINER_PORT = 9001

package/{dist → src}/config/defaultOptions.js

@@ -1,17 +1,8 @@
-"use strict";
+import { createApiKey } from '../utils/index.js'
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = void 0;
-
-var _index = require("../utils/index.js");
-
-var _default = {
-  allowCache: false,
-  apiKey: (0, _index.createApiKey)(),
-  corsAllowCredentials: true,
-  // TODO no CLI option
+export default {
+  apiKey: createApiKey(),
+  corsAllowCredentials: true, // TODO no CLI option
   corsAllowHeaders: 'accept,content-type,x-api-key,authorization',
   corsAllowOrigin: '*',
   corsExposedHeaders: 'WWW-Authenticate,Server-Authorization',
@@ -35,12 +26,12 @@ var _default = {
   noTimeout: false,
   prefix: '',
   printOutput: false,
+  reloadHandler: false,
   resourceRoutes: false,
   useChildProcesses: false,
   useDocker: false,
-  useWorkerThreads: false,
+  useInProcess: false,
   webSocketHardTimeout: 7200,
   webSocketIdleTimeout: 600,
-  websocketPort: 3001
-};
-exports.default = _default;
+  websocketPort: 3001,
+}

package/src/config/index.js

@@ -0,0 +1,4 @@
+export { default as commandOptions } from './commandOptions.js'
+export * from './constants.js'
+export { default as defaultOptions } from './defaultOptions.js'
+export * from './supportedRuntimes.js'

package/src/config/supportedRuntimes.js

@@ -0,0 +1,47 @@
+// native runtime support for AWS
+// https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html
+
+// .NET CORE
+export const supportedDotnetcore = new Set([
+  // 'dotnet6',
+  // 'dotnetcore3.1',
+])
+
+// GO
+export const supportedGo = new Set(['go1.x'])
+
+// JAVA
+export const supportedJava = new Set(['java8', 'java8.al2', 'java11'])
+
+// NODE.JS
+export const supportedNodejs = new Set([
+  'nodejs12.x',
+  'nodejs14.x',
+  'nodejs16.x',
+])
+
+// PROVIDED
+export const supportedProvided = new Set(['provided', 'provided.al2'])
+
+// PYTHON
+export const supportedPython = new Set([
+  'python3.6',
+  'python3.7',
+  'python3.8',
+  'python3.9',
+])
+
+// RUBY
+export const supportedRuby = new Set(['ruby2.7'])
+
+// deprecated runtimes
+// https://docs.aws.amazon.com/lambda/latest/dg/runtime-support-policy.html
+export const supportedRuntimes = new Set([
+  ...supportedDotnetcore,
+  ...supportedGo,
+  ...supportedJava,
+  ...supportedNodejs,
+  ...supportedProvided,
+  ...supportedPython,
+  ...supportedRuby,
+])