serverless-offline 9.1.0 → 9.1.1

package/README.md

@@ -7,8 +7,8 @@
   <a href="https://www.npmjs.com/package/serverless-offline">
     <img src="https://img.shields.io/npm/v/serverless-offline.svg?style=flat-square">
   </a>
-  <a href="https://github.com/dherault/serverless-offline/actions?query=workflow%3ACI">
-    <img src="https://img.shields.io/github/workflow/status/dherault/serverless-offline/CI?style=flat-square">
+  <a href="https://github.com/dherault/serverless-offline/actions/workflows/integrate.yml">
+    <img src="https://img.shields.io/github/workflow/status/dherault/serverless-offline/Integrate">
   </a>
   <img src="https://img.shields.io/node/v/serverless-offline.svg?style=flat-square">
   <a href="https://github.com/serverless/serverless">
@@ -29,9 +29,9 @@
 This [Serverless](https://github.com/serverless/serverless) plugin emulates [AWS λ](https://aws.amazon.com/lambda) and [API Gateway](https://aws.amazon.com/api-gateway) on your local machine to speed up your development cycles.
 To do so, it starts an HTTP server that handles the request's lifecycle like APIG does and invokes your handlers.
 
-**Features:**
+**Features**
 
-- [Node.js](https://nodejs.org), [Python](https://www.python.org), [Ruby](https://www.ruby-lang.org) and [Go](https://golang.org) λ runtimes.
+- [Node.js](https://nodejs.org), [Python](https://www.python.org), [Ruby](https://www.ruby-lang.org), [Go](https://golang.org), [Java](https://www.java.com) (incl. [Kotlin](https://kotlinlang.org), [Groovy](https://groovy-lang.org), [Scala](https://www.scala-lang.org)) λ runtimes.
 - Velocity templates support.
 - Lazy loading of your handler files.
 - And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, CORS, etc...
@@ -42,6 +42,7 @@ This plugin is updated by its users, I just do maintenance and ensure that PRs a
 
 - [Installation](#installation)
 - [Usage and command line options](#usage-and-command-line-options)
+- [Run modes](#run-modes)
 - [Usage with `invoke`](#usage-with-invoke)
 - [The `process.env.IS_OFFLINE` variable](#the-processenvis_offline-variable)
 - [Docker and Layers](#docker-and-layers)
@@ -84,7 +85,7 @@ Then inside your project's `serverless.yml` file add following entry to the plug
 
 It should look something like this:
 
-```YAML
+```yml
 plugins:
   - serverless-offline
 ```
@@ -146,13 +147,13 @@ All CLI options are optional:
 
 Any of the CLI options can be added to your `serverless.yml`. For example:
 
-```
+```yml
 custom:
   serverless-offline:
-    httpsProtocol: "dev-certs"
+    httpsProtocol: 'dev-certs'
     httpPort: 4000
     stageVariables:
-      foo: "bar"
+      foo: 'bar'
 ```
 
 Options passed on the command line override YAML options.
@@ -164,18 +165,64 @@ By default you can send your requests to `http://localhost:3000/`. Please note t
   But if you send an `application/x-www-form-urlencoded` or a `multipart/form-data` body with an `application/json` (or no) Content-Type, API Gateway won't parse your data (you'll get the ugly raw as input), whereas the plugin will answer 400 (malformed JSON).
   Please consider explicitly setting your requests' Content-Type and using separate templates.
 
+## Run modes
+
+### node.js
+
+Lambda handlers for the `node.js` runtime can run in different execution modes with `serverless-offline` and they have subtle differences with a variety of pros and cons. they are mutually exclusive and it is planned to combine the flags into one single flag in the future.
+
+#### worker-threads (default)
+
+- handlers run in their own context
+- memory is not being shared between handlers, memory consumption is therefore higher
+- memory is being released when handlers reload or after usage
+- environment (process.env) is not being shared across handlers
+- global state is not being shared across handlers
+- easy debugging
+
+#### in-process
+
+- handlers run in the same context (instance) as `serverless` and `serverless-offline`
+- memory is being shared across lambda handlers as well as with `serverless` and `serverless-offline`
+- no reloading capabilities as it is [currently] not possible to implement for commonjs handlers (without memory leaks) and for esm handlers
+- environment (process.env) is being shared across handlers as well as with `serverless` and `serverless-offline`
+- global state is being shared across lambda handlers as well as with `serverless` and `serverless-offline`
+- easy debugging
+
+#### child-processes
+
+- handlers run in a separate node.js instance
+- memory is not being shared between handlers, memory consumption is therefore higher
+- memory is being released when handlers reload or after usage
+- environment (process.env) is not being shared across handlers
+- global state is not being shared across handlers
+- debugging more complicated
+
+#### docker
+
+- handlers run in a docker container
+- memory is not being shared between handlers, memory consumption is therefore higher
+- memory is being released when handlers reload or after usage
+- environment (process.env) is not being shared across handlers
+- global state is not being shared across handlers
+- debugging more complicated
+
+### Python, Ruby, Go, Java (incl. Kotlin, Groovy, Scala)
+
+the Lambda handler process is running in a child process.
+
 ## Usage with `invoke`
 
-To use `Lambda.invoke` you need to set the lambda endpoint to the serverless-offline endpoint:
+To use `Lambda.invoke` you need to set the lambda endpoint to the `serverless-offline` endpoint:
 
 ```js
+const { env } = require('node:process')
 const { Lambda } = require('aws-sdk')
 
 const lambda = new Lambda({
   apiVersion: '2015-03-31',
-  // endpoint needs to be set only if it deviates from the default, e.g. in a dev environment
-  // process.env.SOME_VARIABLE could be set in e.g. serverless.yml for provider.environment or function.environment
-  endpoint: process.env.SOME_VARIABLE
+  // endpoint needs to be set only if it deviates from the default
+  endpoint: env.IS_OFFLINE
     ? 'http://localhost:3002'
     : 'https://lambda.us-east-1.amazonaws.com',
 })
@@ -184,15 +231,33 @@ const lambda = new Lambda({
 All your lambdas can then be invoked in a handler using
 
 ```js
+const { Buffer } = require('node:buffer')
+const { Lambda } = require('aws-sdk')
+
+const { stringify } = JSON
+
+const lambda = new Lambda({
+  apiVersion: '2015-03-31',
+  endpoint: 'http://localhost:3002',
+})
+
 exports.handler = async function () {
+  const clientContextData = stringify({ foo: 'foo' })
+
   const params = {
+    ClientContext: Buffer.from(clientContextData).toString('base64'),
     // FunctionName is composed of: service name - stage - function name, e.g.
     FunctionName: 'myServiceName-dev-invokedHandler',
     InvocationType: 'RequestResponse',
-    Payload: JSON.stringify({ data: 'foo' }),
+    Payload: stringify({ data: 'foo' }),
   }
 
   const response = await lambda.invoke(params).promise()
+
+  return {
+    body: stringify(response),
+    statusCode: 200,
+  }
 }
 ```
 
@@ -244,7 +309,7 @@ to calling it via `aws-sdk`.
 
 ## The `process.env.IS_OFFLINE` variable
 
-Will be `"true"` in your handlers and throughout the plugin.
+Will be `"true"` in your handlers when using `serverless-offline`.
 
 ## Docker and Layers
 
@@ -326,11 +391,11 @@ Only [custom authorizers](https://aws.amazon.com/blogs/compute/introducing-custo
 
 The Custom authorizer is passed an `event` object as below:
 
-```javascript
+```js
 {
-  "type": "TOKEN",
   "authorizationToken": "<Incoming bearer token>",
-  "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>"
+  "methodArn": "arn:aws:execute-api:<Region id>:<Account id>:<API id>/<Stage>/<Method>/<Resource path>",
+  "type": "TOKEN"
 }
 ```
 
@@ -338,11 +403,11 @@ The `methodArn` does not include the Account id or API id.
 
 The plugin only supports retrieving Tokens from headers. You can configure the header as below:
 
-```javascript
+```js
 "authorizer": {
-  "type": "TOKEN",
+  "authorizerResultTtlInSeconds": "0",
   "identitySource": "method.request.header.Authorization", // or method.request.header.SomeOtherHeader
-  "authorizerResultTtlInSeconds": "0"
+  "type": "TOKEN"
 }
 ```
 
@@ -370,14 +435,14 @@ If your authentication needs are custom and not satisfied by the existing capabi
 ```js
 module.exports = function (endpoint, functionKey, method, path) {
   return {
-    name: 'your strategy name',
-    scheme: 'your scheme name',
-
     getAuthenticateFunction: () => ({
       async authenticate(request, h) {
         // your implementation
       },
     }),
+
+    name: 'your strategy name',
+    scheme: 'your scheme name',
   }
 }
 ```
@@ -441,7 +506,7 @@ Now let's make a request with this body: `{ "id": 1 }`
 
 AWS parses the event as such:
 
-```javascript
+```js
 {
   "payload": {
     "id": 1
@@ -453,7 +518,7 @@ AWS parses the event as such:
 
 Whereas Offline parses:
 
-```javascript
+```js
 {
   "payload": {
     "id": 1
@@ -505,7 +570,7 @@ Works out of the box. See examples in the manual_test directory.
 
 Example of enabling proxy:
 
-```
+```yml
 custom:
   serverless-offline:
     resourceRoutes: true
@@ -513,18 +578,18 @@ custom:
 
 or
 
-```
+```yml
     YourCloudFormationMethodId:
-      Type: AWS::ApiGateway::Method
       Properties:
         ......
         Integration:
           Type: HTTP_PROXY
           Uri: 'https://s3-${self:custom.region}.amazonaws.com/${self:custom.yourBucketName}/{proxy}'
           ......
+      Type: AWS::ApiGateway::Method
 ```
 
-```
+```yml
 custom:
   serverless-offline:
     resourceRoutes:
@@ -542,7 +607,7 @@ May not work properly. Please PR. (Difficulty: hard?)
 
 Example response velocity template:
 
-```javascript
+```js
 "responseParameters": {
   "method.response.header.X-Powered-By": "Serverless", // a string
   "method.response.header.Warning": "integration.response.body", // the whole response
@@ -559,7 +624,9 @@ Usage in order to send messages back to clients:
 Or,
 
 ```js
-const apiGatewayManagementApi = new AWS.ApiGatewayManagementApi({
+const { ApiGatewayManagementApi } = require('aws-sdk')
+
+const apiGatewayManagementApi = new ApiGatewayManagementApi({
   apiVersion: '2018-11-29',
   endpoint: 'http://localhost:3001',
 });
@@ -648,7 +715,7 @@ You can change this profile directly in the code or by setting proper environmen
 ## Simulation quality
 
 This plugin simulates API Gateway for many practical purposes, good enough for development - but is not a perfect simulator.
-Specifically, Lambda currently runs on Node.js v10.x, v12.x and v14.x ([AWS Docs](https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html)), whereas _Offline_ runs on your own runtime where no memory limits are enforced.
+Specifically, Lambda currently runs on Node.js v12.x, v14.x and v16.x ([AWS Docs](https://docs.aws.amazon.com/lambda/latest/dg/current-supported-versions.html)), whereas _Offline_ runs on your own runtime where no memory limits are enforced.
 
 ## Usage with other plugins
 
@@ -661,7 +728,7 @@ Plugins are executed in order, so plugins that process your code or add resource
 
 For example:
 
-```yaml
+```yml
 plugins:
   - serverless-middleware # modifies some of your handler based on configuration
   - serverless-webpack # package your javascript handlers using webpack

package/package.json

@@ -1,7 +1,7 @@
 {
   "dedicatedTo": "Blue, a great migrating bird.",
   "name": "serverless-offline",
-  "version": "9.1.0",
+  "version": "9.1.1",
   "description": "Emulate AWS λ and API Gateway locally when developing your Serverless project",
   "license": "MIT",
   "main": "./src/index.js",
@@ -194,7 +194,7 @@
     "@hapi/boom": "^10.0.0",
     "@hapi/h2o2": "^9.1.0",
     "@hapi/hapi": "^20.2.2",
-    "aws-sdk": "^2.1181.0",
+    "aws-sdk": "^2.1184.0",
     "boxen": "^7.0.0",
     "chalk": "^5.0.1",
     "execa": "^6.1.0",

package/src/config/constants.js

@@ -9,7 +9,7 @@ export const DEFAULT_LAMBDA_RUNTIME = 'nodejs14.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
+export const DEFAULT_LAMBDA_TIMEOUT = 6 // 6 seconds
 
 // timeout for all connections to be closed
 export const SERVER_SHUTDOWN_TIMEOUT = 5000

package/src/lambda/LambdaFunction.js

@@ -15,8 +15,8 @@ import {
 } from '../config/index.js'
 import { createUniqueId, splitHandlerPathAndName } from '../utils/index.js'
 
-const { entries, fromEntries } = Object
 const { ceil } = Math
+const { entries, fromEntries } = Object
 
 export default class LambdaFunction {
   #artifact = null

package/src/lambda/handler-runner/child-process-runner/ChildProcessRunner.js

@@ -41,14 +41,18 @@ export default class ChildProcessRunner {
       },
     )
 
-    const message = new Promise((res, rej) => {
-      childProcess.on('message', (data) => {
-        if (data.error) rej(data.error)
-        else res(data)
+    let message
+
+    try {
+      message = new Promise((res, rej) => {
+        childProcess.on('message', (data) => {
+          if (data.error) rej(data.error)
+          else res(data)
+        })
       })
-    }).finally(() => {
+    } finally {
       childProcess.kill()
-    })
+    }
 
     childProcess.send({
       context,

package/src/lambda/handler-runner/docker-runner/DockerContainer.js

@@ -12,6 +12,8 @@ import pRetry from 'p-retry'
 import DockerImage from './DockerImage.js'
 
 const { stringify } = JSON
+const { floor, log: mathLog } = Math
+const { parseFloat } = Number
 const { entries, hasOwn } = Object
 
 export default class DockerContainer {
@@ -402,7 +404,7 @@ export default class DockerContainer {
     const dm = decimals < 0 ? 0 : decimals
     const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
 
-    const i = Math.floor(Math.log(bytes) / Math.log(k))
+    const i = floor(mathLog(bytes) / mathLog(k))
 
     return `${parseFloat((bytes / k ** i).toFixed(dm))} ${sizes[i]}`
   }

package/src/lambda/handler-runner/go-runner/GoRunner.js

@@ -1,9 +1,9 @@
 import { mkdir, readFile, rm, rmdir, writeFile } from 'node:fs/promises'
 import { EOL } from 'node:os'
-import { sep, resolve, parse as pathParse } from 'node:path'
 import process, { chdir, cwd } from 'node:process'
+import { parse as pathParse, resolve, sep } from 'node:path'
 import { log } from '@serverless/utils/log.js'
-import { execa, execaSync } from 'execa'
+import { execa } from 'execa'
 
 const { parse, stringify } = JSON
 
@@ -18,10 +18,10 @@ export default class GoRunner {
 
   #handlerPath = null
 
-  #tmpPath = null
-
   #tmpFile = null
 
+  #tmpPath = null
+
   constructor(funOptions, env) {
     const { handlerPath, codeDir } = funOptions
 
@@ -34,8 +34,10 @@ export default class GoRunner {
     try {
       // refresh go.mod
       await rm(this.#tmpFile)
-      execaSync('go', ['mod', 'tidy'])
-      await rmdir(this.#tmpPath, { recursive: true })
+      await execa('go', ['mod', 'tidy'])
+      await rmdir(this.#tmpPath, {
+        recursive: true,
+      })
     } catch {
       // @ignore
     }
@@ -122,8 +124,11 @@ export default class GoRunner {
       chdir(cwdPath.substring(0, cwdPath.indexOf('main.go')))
 
       // Make sure we have the mock-lambda runner
-      execaSync('go', ['get', 'github.com/icarus-sullivan/mock-lambda@e065469'])
-      execaSync('go', ['build'])
+      await execa('go', [
+        'get',
+        'github.com/icarus-sullivan/mock-lambda@e065469',
+      ])
+      await execa('go', ['build'])
     } catch {
       // @ignore
     }

package/src/lambda/handler-runner/in-process-runner/InProcessRunner.js

@@ -3,6 +3,7 @@ import { performance } from 'node:perf_hooks'
 import process from 'node:process'
 import { log } from '@serverless/utils/log.js'
 
+const { floor } = Math
 const { assign } = Object
 
 const require = createRequire(import.meta.url)
@@ -88,11 +89,11 @@ export default class InProcessRunner {
       ...context,
       done: (err, data) => callback(err, data),
       fail: (err) => callback(err),
-      getRemainingTimeInMillis: () => {
+      getRemainingTimeInMillis() {
         const timeLeft = executionTimeout - performance.now()
 
         // just return 0 for now if we are beyond alotted time (timeout)
-        return timeLeft > 0 ? timeLeft : 0
+        return timeLeft > 0 ? floor(timeLeft) : 0
       },
       succeed: (res) => callback(null, res),
     }

package/src/lambda/handler-runner/worker-thread-runner/workerThreadHelper.js

@@ -2,10 +2,10 @@ import { env } from 'node:process'
 import { parentPort, workerData } from 'node:worker_threads'
 import InProcessRunner from '../in-process-runner/index.js'
 
-const { functionKey, handlerName, handlerPath } = workerData
+const { functionKey, handlerName, handlerPath, timeout } = workerData
 
 parentPort.on('message', async (messageData) => {
-  const { context, event, port, timeout } = messageData
+  const { context, event, port } = messageData
 
   // TODO we could probably cache this in the module scope?
   const inProcessRunner = new InProcessRunner(