serverless-offline 14.6.0 → 14.7.0

package/README.md

@@ -32,23 +32,14 @@
   <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/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">
     <img src="https://img.shields.io/npm/dependency-version/serverless-offline/peer/serverless.svg?style=flat-square">
   </a>
-  <a href="https://github.com/prettier/prettier">
-    <img src="https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square">
-  </a>
   <img src="https://img.shields.io/npm/l/serverless-offline.svg?style=flat-square">
   <a href="#contributing">
     <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square">
   </a>
-  <a href="https://gitter.im/serverless-offline/community">
-    <img src="https://badges.gitter.im/serverless-offline.png">
-  </a>
 </p>
 
 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.
@@ -59,7 +50,7 @@ To do so, it starts an HTTP server that handles the request's lifecycle like API
 - [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...
+- And more: integrations, authorizers, proxies, timeouts, responseParameters, HTTPS, CORS, etc.
 
 This plugin is updated by its users, I just do maintenance and ensure that PRs are relevant to the community. In other words, if you [find a bug or want a new feature](https://github.com/dherault/serverless-offline/issues), please help us by becoming one of the [contributors](https://github.com/dherault/serverless-offline/graphs/contributors) :v: ! See the [contributing section](#contributing).
 
@@ -104,7 +95,7 @@ First, add Serverless Offline to your project:
 
 `npm install serverless-offline --save-dev`
 
-Then inside your project's `serverless.yml` file add following entry to the plugins section: `serverless-offline`. If there is no plugin section you will need to add it to the file.
+Then inside your project's `serverless.yml` file add the following entry to the plugins section: `serverless-offline`. If there is no plugin section you will need to add it to the file.
 
 **Note that the "plugin" section for serverless-offline must be at root level on serverless.yml.**
 
@@ -119,15 +110,15 @@ You can check whether you have successfully installed the plugin by running the
 
 `serverless --verbose`
 
-the console should display _Offline_ as one of the plugins now available in your Serverless project.
+The console should display _Offline_ as one of the plugins now available in your Serverless project.
 
 ## Usage and command line options
 
-In your project root run:
+In your project root, run:
 
 `serverless offline` or `sls offline`.
 
-to list all the options for the plugin run:
+To list all the options for the plugin, run:
 
 `sls offline --help`
 
@@ -145,8 +136,8 @@ Default: '\*'
 
 #### corsDisallowCredentials
 
-When provided, the default Access-Control-Allow-Credentials header value will be passed as 'false'.\
-Default: true
+When provided, sets the Access-Control-Allow-Credentials header to 'false'.\
+Default (without flag): credentials are allowed ('true')
 
 #### corsExposedHeaders
 
@@ -181,7 +172,7 @@ Enforce secure cookies
 
 #### host
 
--o Host name to listen on.<br />
+Host name to listen on.<br />
 Default: localhost
 
 #### httpPort
@@ -191,7 +182,7 @@ Default: 3000
 
 #### httpsProtocol
 
--H To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files.
+To enable HTTPS, specify directory (relative to your cwd, typically your project dir) for both cert.pem and key.pem files.
 
 #### ignoreJWTSignature
 
@@ -205,7 +196,7 @@ Default: 3002
 #### layersDir
 
 The directory layers should be stored in.<br />
-Default: ${codeDir}/.serverless-offline/layers'
+Default: '${codeDir}/.serverless-offline/layers'
 
 #### localEnvironment
 
@@ -226,17 +217,21 @@ Remove sponsor message from the output.
 
 #### noTimeout
 
--t Disables the timeout feature.
+Disables the timeout feature.
 
 #### prefix
 
--p Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead.<br />
+Adds a prefix to every path, to send your requests to http://localhost:3000/[prefix]/[your_path] instead.<br />
 Default: ''
 
 #### reloadHandler
 
 Reloads handler with each request.
 
+#### rubyWatchDirs
+
+List of directories to watch for Ruby file changes. Automatically restarts the Ruby process on change, enabling hot-reload during local development.
+
 #### resourceRoutes
 
 Turns on loading of your HTTP proxy settings from serverless.yml.
@@ -280,7 +275,7 @@ custom:
   serverless-offline:
     httpsProtocol: 'dev-certs'
     httpPort: 4000
-      foo: 'bar'
+    foo: 'bar'
 ```
 
 Options passed on the command line override YAML options.
@@ -296,7 +291,7 @@ By default you can send your requests to `http://localhost:3000/`. Please note t
 
 ### node.js
 
-Lambda handlers with `serverless-offline` for the `node.js` runtime can run in different execution modes and have some differences with a variety of pros and cons. they are currently mutually exclusive and it's not possible to use a combination, e.g. use `in-process` for one Lambda, and `worker-threads` for another. It is planned to combine the flags into one single flag in the future and also add support for combining run modes.
+Lambda handlers with `serverless-offline` for the `node.js` runtime can run in different execution modes and have some differences with a variety of pros and cons. They are currently mutually exclusive and it's not possible to use a combination, e.g. use `in-process` for one Lambda, and `worker-threads` for another. It is planned to combine the flags into one single flag in the future and also add support for combining run modes.
 
 #### worker-threads (default)
 
@@ -331,7 +326,7 @@ NOTE:
 
 ### Python, Ruby, Go, Java (incl. Kotlin, Groovy, Scala)
 
-the Lambda handler process is running in a child process.
+The Lambda handler process is running in a child process.
 
 ## Invoke Lambda
 
@@ -389,7 +384,7 @@ export async function handler() {
 }
 ```
 
-You can also invoke using the aws cli by specifying `--endpoint-url`
+You can also invoke using the AWS CLI by specifying `--endpoint-url`
 
 ```
 aws lambda invoke /dev/null \
@@ -415,7 +410,7 @@ offline: Function names exposed for local invocation by aws-sdk:
 ```
 
 To list the available manual invocation paths exposed for targeting
-by `aws-sdk` and `aws-cli`, use `SLS_DEBUG=*` with `serverless offline`. After the invoke server starts up, full list of endpoints will be displayed:
+by `aws-sdk` and `aws-cli`, use `SLS_DEBUG=*` with `serverless offline`. After the invoke server starts up, the full list of endpoints will be displayed:
 
 ```
 SLS_DEBUG=* serverless offline
@@ -433,7 +428,7 @@ offline: Function names exposed for local invocation by aws-sdk:
 
 You can manually target these endpoints with a REST client to debug your lambda
 function if you want to. Your `POST` JSON body will be the `Payload` passed to your function if you were
-to calling it via `aws-sdk`.
+to call it via `aws-sdk`.
 
 ## The `process.env.IS_OFFLINE` variable
 
@@ -441,7 +436,7 @@ Will be `"true"` in your handlers when using `serverless-offline`.
 
 ## Docker and Layers
 
-To use layers with serverless-offline, you need to have the `useDocker` option set to true. This can either be by using the `--useDocker` command, or in your serverless.yml like this:
+To use layers with serverless-offline, you need to have the `useDocker` option set to true. This can be done either by using the `--useDocker` command, or in your serverless.yml like this:
 
 ```yml
 custom:
@@ -453,7 +448,7 @@ This will allow the docker container to look up any information about layers, do
 
 - AWS as a provider, it won't work with other provider types.
 - Layers that are compatible with your runtime.
-- ARNs for layers. Local layers aren't supported as yet.
+- ARNs for layers. Local layers are not yet supported.
 - A local AWS account set-up that can query and download layers.
 
 If you're using least-privilege principals for your AWS roles, this policy should get you by:
@@ -471,7 +466,7 @@ If you're using least-privilege principals for your AWS roles, this policy shoul
 }
 ```
 
-Once you run a function that boots up the Docker container, it'll look through the layers for that function, download them in order to your layers folder, and save a hash of your layers so it can be re-used in future. You'll only need to re-download your layers if they change in the future. If you want your layers to re-download, simply remove your layers folder.
+Once you run a function that boots up the Docker container, it'll look through the layers for that function, download them in order to your layers folder, and save a hash of your layers so it can be re-used in the future. You'll only need to re-download your layers if they change in the future. If you want your layers to re-download, simply remove your layers folder.
 
 You should then be able to invoke functions as normal, and they're executed against the layers in your docker container.
 
@@ -541,7 +536,7 @@ The plugin only supports retrieving Tokens from headers. You can configure the h
 
 ### Remote authorizers
 
-You are able to mock the response from remote authorizers by setting the environmental variable `AUTHORIZER` before running `sls offline start`
+You are able to mock the response from remote authorizers by setting the environment variable `AUTHORIZER` before running `sls offline start`
 
 Example:
 
@@ -566,7 +561,7 @@ offline:
 ```
 
 ```js
-// ./path/to/customer-authentication-provider.js
+// ./path/to/custom-authentication-provider.js
 
 module.exports = function (endpoint, functionKey, method, path) {
   return {
@@ -584,7 +579,7 @@ module.exports = function (endpoint, functionKey, method, path) {
 }
 ```
 
-A working example of injecting a custom authorization provider can be found in the projects integration tests under the folder [`custom-authentication`](./tests/integration/custom-authentication).
+A working example of injecting a custom authorization provider can be found in the project's integration tests under the folder [`custom-authentication`](./tests/integration/custom-authentication).
 
 ## Custom headers
 
@@ -622,7 +617,7 @@ You can use [serverless-dotenv-plugin](https://github.com/colynb/serverless-dote
 [Serverless doc](https://serverless.com/framework/docs/providers/aws/events/apigateway#request-templates)
 ~ [AWS doc](http://docs.aws.amazon.com/apigateway/latest/developerguide/models-mappings.html#models-mappings-mappings)
 
-You can supply response and request templates for each function. This is optional. To do so you will have to place function specific template files in the same directory as your function file and add the .req.vm extension to the template filename.
+You can supply response and request templates for each function. This is optional. To do so, you will have to place function-specific template files in the same directory as your function file and add the .req.vm extension to the template filename.
 For example,
 if your function is in code-file: `helloworld.js`,
 your response template should be in file: `helloworld.res.vm` and your request template in file `helloworld.req.vm`.
@@ -776,17 +771,17 @@ apiGatewayManagementApi.postToConnection({
 
 Where the `event` is received in the lambda handler function.
 
-There's support for [websocketsApiRouteSelectionExpression](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html) in it's basic form: `$request.body.x.y.z`, where the default value is `$request.body.action`.
+There's support for [websocketsApiRouteSelectionExpression](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-selection-expressions.html) in its basic form: `$request.body.x.y.z`, where the default value is `$request.body.action`.
 
 ## Debug process
 
-Serverless offline plugin will respond to the overall framework settings and output additional information to the console in debug mode. In order to do this you will have to set the `SLS_DEBUG` environmental variable. You can run the following in the command line to switch to debug mode execution.
+The Serverless offline plugin will respond to the overall framework settings and output additional information to the console in debug mode. In order to do this you will have to set the `SLS_DEBUG` environmental variable. You can run the following in the command line to switch to debug mode execution.
 
 > Unix: `export SLS_DEBUG=*`
 
 > Windows: `SET SLS_DEBUG=*`
 
-Interactive debugging is also possible for your project if you have installed the node-inspector module and chrome browser. You can then run the following command line inside your project's root.
+Interactive debugging is also possible for your project if you have installed the node-inspector module and Chrome browser. You can then run the following command line inside your project's root.
 
 Initial installation:
 `npm install -g node-inspector`
@@ -800,7 +795,7 @@ Depending on the breakpoint, you may need to call the URL path for your function
 
 ### Interactive Debugging with Visual Studio Code (VSC)
 
-With newer versions of node (6.3+) the node inspector is already part of your node environment and you can take advantage of debugging inside your IDE with source-map support. Here is the example configuration to debug interactively with VSC. It has two steps.
+With newer versions of Node.js (6.3+) the node inspector is already part of your Node.js environment and you can take advantage of debugging inside your IDE with source-map support. Here is the example configuration to debug interactively with VSC. It has two steps.
 
 #### Step 1 : Adding a launch configuration in IDE
 
@@ -818,9 +813,9 @@ Add a new [launch configuration](https://code.visualstudio.com/docs/editor/debug
 }
 ```
 
-#### Step2 : Adding a debug script
+#### Step 2: Adding a debug script
 
-You will also need to add a `debug` script reference in your `package.json file`
+You will also need to add a `debug` script reference in your `package.json` file
 
 Add this to the `scripts` section:
 
@@ -837,13 +832,13 @@ Example:
 }
 ```
 
-In VSC, you can, then, add breakpoints to your code. To start a debug sessions you can either start your script in `package.json` by clicking the hovering debug intellisense icon or by going to your debug pane and selecting the Debug Serverless Offline configuration.
+In VSC, you can, then, add breakpoints to your code. To start a debug session you can either start your script in `package.json` by clicking the hovering debug intellisense icon or by going to your debug pane and selecting the Debug Serverless Offline configuration.
 
 ## Resource permissions and AWS profile
 
-Lambda functions assume an IAM role during execution: the framework creates this role and set all the permission provided in the `iamRoleStatements` section of `serverless.yml`.
+Lambda functions assume an IAM role during execution: the framework creates this role and sets all the permissions provided in the `iamRoleStatements` section of `serverless.yml`.
 
-However, serverless offline makes use of your local AWS profile credentials to run the lambda functions and that might result in a different set of permissions. By default, the aws-sdk would load credentials for you default AWS profile specified in your configuration file.
+However, serverless offline makes use of your local AWS profile credentials to run the lambda functions and that might result in a different set of permissions. By default, the aws-sdk would load credentials for your default AWS profile specified in your configuration file.
 
 You can change this profile directly in the code or by setting proper environment variables. Setting the `AWS_PROFILE` environment variable before calling `serverless` offline to a different profile would effectively change the credentials, e.g.
 
@@ -852,13 +847,13 @@ 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 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.
+Specifically, Lambda currently runs on Node.js v18.x, v20.x and v22.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
 
 When combining this plugin with other plugins there are a few things that you need to keep in mind.
 
-You should run `serverless offline start` instead of `serverless offline`. The `start` command fires the `offline:start:init` and `offline:start:end` lifecycle hooks which can be used by other plugins to process your code, add resources, perform cleanups, etc.
+You should run `serverless offline start` instead of `serverless offline`. The `start` command fires the `offline:start:init` and `offline:start:end` lifecycle hooks, which can be used by other plugins to process your code, add resources, perform cleanups, etc.
 
 The order in which plugins are added to `serverless.yml` is relevant.
 Plugins are executed in order, so plugins that process your code or add resources should be added first so they are ready when this plugin starts.
@@ -873,7 +868,7 @@ plugins:
   - serverless-offline # runs last so your code has been pre-processed and dynamo is ready
 ```
 
-That works because all those plugins listen to the `offline:start:init` to do their processing.
+That works because all those plugins listen to the `offline:start:init` hook to do their processing.
 Similarly they listen to `offline:start:end` to perform cleanup (stop dynamo db, remove temporary files, etc).
 
 ## Credits and inspiration
@@ -889,7 +884,6 @@ MIT
 Yes, thank you!
 This plugin is community-driven, most of its features are from different authors.
 Please update the docs and tests and add your name to the package.json file.
-We try to follow [Airbnb's JavaScript Style Guide](https://github.com/airbnb/javascript).
 
 ## Contributors
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-offline",
-  "version": "14.6.0",
+  "version": "14.7.0",
   "description": "Emulate AWS λ and API Gateway locally when developing your Serverless project",
   "license": "MIT",
   "exports": {
@@ -14,8 +14,8 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "list-contributors": "echo 'clone https://github.com/mgechev/github-contributors-list.git first, then run npm install' && cd ../github-contributors-list && node bin/githubcontrib --owner dherault --repo serverless-offline --sortBy contributions --sortOrder desc > contributors.md",
-    "prepare-release": "commit-and-tag-version && prettier --write CHANGELOG.md",
     "prepublishOnly": "npm run lint",
+    "changelog": "auto-changelog",
     "prettier": "prettier --check .",
     "prettier:fix": "prettier --write .",
     "test": "mocha --require ./tests/mochaHooks.cjs",
@@ -51,32 +51,14 @@
   "engines": {
     "node": ">=20.0.0"
   },
-  "commit-and-tag-version": {
-    "skip": {
-      "commit": true,
-      "tag": true
-    },
-    "types": [
-      {
-        "type": "feat",
-        "section": "Features"
-      },
-      {
-        "type": "fix",
-        "section": "Bug Fixes"
-      },
-      {
-        "type": "perf",
-        "section": "Performance Improvements"
-      },
-      {
-        "type": "refactor",
-        "section": "Maintenance Improvements"
-      }
-    ]
+  "auto-changelog": {
+    "output": "CHANGELOG.md",
+    "unreleased": false,
+    "commitLimit": false,
+    "hideCredit": true
   },
   "dependencies": {
-    "@aws-sdk/client-lambda": "^3.1045.0",
+    "@aws-sdk/client-lambda": "^3.1052.0",
     "@hapi/boom": "^10.0.1",
     "@hapi/h2o2": "^10.0.4",
     "@hapi/hapi": "^21.4.9",
@@ -98,24 +80,24 @@
     "node-schedule": "^2.1.1",
     "p-memoize": "^7.1.1",
     "tree-kill": "^1.2.2",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.3",
     "velocityjs": "^2.1.6",
-    "ws": "^8.20.0"
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@istanbuljs/esm-loader-hook": "^0.3.0",
     "archiver": "^7.0.1",
-    "commit-and-tag-version": "^12.7.3",
+    "auto-changelog": "^2.5.1",
     "eslint": "^8.57.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-prettier": "^5.5.5",
     "eslint-plugin-unicorn": "^54.0.0",
-    "mocha": "^10.7.3",
+    "mocha": "^11.7.6",
     "nyc": "^17.0.0",
     "prettier": "^3.8.3",
-    "serverless": "^4.35.1"
+    "serverless": "^4.36.1"
   },
   "peerDependencies": {
     "serverless": "^4.0.0"

package/src/config/commandOptions.js

@@ -116,6 +116,11 @@ export default {
     type: "boolean",
     usage: "Turns on loading of your HTTP proxy settings from serverless.yml.",
   },
+  rubyWatchDirs: {
+    type: "string",
+    usage:
+      "Comma-separated list of directories to watch for Ruby (.rb) file changes. When set, the persistent Ruby process is automatically restarted on change for hot reload.",
+  },
   terminateIdleLambdaTime: {
     type: "string",
     usage:

package/src/config/defaultOptions.js

@@ -23,6 +23,7 @@ export default {
   preLoadModules: "",
   reloadHandler: false,
   resourceRoutes: false,
+  rubyWatchDirs: [],
   terminateIdleLambdaTime: 60,
   useDocker: false,
   useInProcess: false,

package/src/lambda/handler-runner/HandlerRunner.js

@@ -79,7 +79,7 @@ export default class HandlerRunner {
     if (supportedRuby.has(runtime)) {
       const { default: RubyRunner } = await import("./ruby-runner/index.js")
 
-      return new RubyRunner(this.#funOptions, this.#env)
+      return new RubyRunner(this.#funOptions, this.#env, this.#options)
     }
 
     if (supportedJava.has(runtime)) {

package/src/lambda/handler-runner/ruby-runner/RubyRunner.js

@@ -1,8 +1,10 @@
+import { spawn } from "node:child_process"
+import { watch } from "node:fs"
 import { EOL, platform } from "node:os"
-import { relative } from "node:path"
-import { cwd } from "node:process"
+import { resolve, relative } from "node:path"
+import process, { cwd, nextTick } from "node:process"
+import { createInterface } from "node:readline"
 import { join } from "desm"
-import { execa } from "execa"
 import { log } from "../../../utils/log.js"
 import { splitHandlerPathAndName } from "../../../utils/index.js"
 
@@ -12,28 +14,199 @@ const { hasOwn } = Object
 export default class RubyRunner {
   static #payloadIdentifier = "__offline_payload__"
 
+  static #errorIdentifier = "__offline_error__"
+
   #env = null
 
-  #handlerName = null
+  #handlerProcess = null
+
+  #readline = null
+
+  #runtime = null
+
+  #spawnArgs = null
+
+  #spawnError = null
+
+  #spawnOptions = null
+
+  #watchers = []
+
+  #debounceTimer = null
+
+  #busy = false
+
+  #restartQueued = false
+
+  #watchDirs = []
 
-  #handlerPath = null
+  // Serializes concurrent run() calls so writes to the shared Ruby stdin
+  // and reads from stdout cannot interleave.
+  #queue = Promise.resolve()
 
-  constructor(funOptions, env) {
+  // Spawn a persistent Ruby process in the constructor (mirrors PythonRunner).
+  // The process stays alive across invocations and communicates via stdin/stdout.
+  // File changes trigger an automatic restart when rubyWatchDirs is configured.
+  constructor(funOptions, env, options = {}) {
     const [handlerPath, handlerName] = splitHandlerPathAndName(
       funOptions.handler,
     )
 
     this.#env = env
-    this.#handlerName = handlerName
-    this.#handlerPath = handlerPath
+    this.#runtime = platform() === "win32" ? "ruby.exe" : "ruby"
+
+    this.#spawnArgs = [
+      join(import.meta.url, "invoke.rb"),
+      relative(cwd(), handlerPath),
+      handlerName,
+    ]
+
+    this.#spawnOptions = {
+      env: options.localEnvironment
+        ? { ...process.env, ...this.#env }
+        : { ...this.#env },
+    }
+
+    const rawWatchDirs = options.rubyWatchDirs ?? []
+    this.#watchDirs =
+      typeof rawWatchDirs === "string"
+        ? rawWatchDirs
+            .split(",")
+            .map((dir) => dir.trim())
+            .filter(Boolean)
+        : rawWatchDirs
+
+    this.#spawnProcess()
+
+    if (this.#watchDirs.length > 0) {
+      this.#setupFileWatcher()
+    }
+  }
+
+  #spawnProcess() {
+    this.#spawnError = null
+    this.#readline = null
+
+    this.#handlerProcess = spawn(
+      this.#runtime,
+      this.#spawnArgs,
+      this.#spawnOptions,
+    )
+
+    // Persistent error listener so an async spawn failure (e.g., Ruby not
+    // on PATH) does not crash serverless-offline with an unhandled "error"
+    // event. The stored error is surfaced from the next run() call.
+    this.#handlerProcess.on("error", (err) => {
+      this.#spawnError = err
+      log.error(`Ruby process error: ${err.message}`)
+    })
+
+    // When spawn fails synchronously the returned ChildProcess can have
+    // null stdio streams. Mark a spawn error immediately so the next run()
+    // rejects with a useful message instead of letting createInterface or
+    // stderr.on() throw on null streams.
+    if (!this.#handlerProcess.stdout || !this.#handlerProcess.stderr) {
+      this.#spawnError = new Error(
+        `Failed to spawn Ruby process "${this.#runtime}". Is Ruby installed and on PATH?`,
+      )
+      return
+    }
+
+    this.#readline = createInterface({
+      input: this.#handlerProcess.stdout,
+    })
+  }
+
+  #setupFileWatcher() {
+    const watchDirs = this.#watchDirs.map((dir) => resolve(cwd(), dir))
+
+    for (const dir of watchDirs) {
+      try {
+        const watcher = watch(
+          dir,
+          { recursive: true },
+          (_eventType, filename) => {
+            if (!filename?.endsWith(".rb")) {
+              return
+            }
+
+            this.#onFileChanged(filename)
+          },
+        )
+
+        this.#watchers.push(watcher)
+      } catch (err) {
+        log.warning(
+          `Ruby hot-reload watcher could not be enabled for "${dir}": ${err.message}. ` +
+            "Recursive fs.watch may not be supported on this platform.",
+        )
+      }
+    }
+  }
+
+  #onFileChanged(filename) {
+    if (this.#debounceTimer) {
+      clearTimeout(this.#debounceTimer)
+    }
+
+    this.#debounceTimer = setTimeout(() => {
+      log.notice(`Ruby file changed: ${filename}, reloading handler...`)
+      this.#scheduleRestart()
+    }, 100)
+  }
+
+  #scheduleRestart() {
+    if (this.#busy) {
+      // Defer restart until the current invocation completes
+      this.#restartQueued = true
+    } else {
+      this.#restartProcess()
+    }
+  }
+
+  #restartProcess() {
+    this.#disposeProcess()
+    this.#spawnProcess()
+  }
+
+  #disposeProcess() {
+    if (this.#readline) {
+      this.#readline.close()
+      this.#readline = null
+    }
+
+    if (this.#handlerProcess && this.#handlerProcess.exitCode == null) {
+      try {
+        this.#handlerProcess.kill()
+      } catch (err) {
+        if (err.code !== "ESRCH") {
+          log.warning(`Failed to kill Ruby process: ${err.message}`)
+        }
+      }
+    }
+
+    this.#handlerProcess = null
   }
 
-  // no-op
   // () => void
-  cleanup() {}
+  cleanup() {
+    for (const watcher of this.#watchers) {
+      watcher.close()
+    }
+
+    this.#watchers = []
+
+    if (this.#debounceTimer) {
+      clearTimeout(this.#debounceTimer)
+      this.#debounceTimer = null
+    }
+
+    this.#disposeProcess()
+  }
 
   #parsePayload(value) {
     let payload
+    let error
 
     for (const item of value.split(EOL)) {
       let json
@@ -46,61 +219,171 @@ export default class RubyRunner {
         // no-op
       }
 
-      // now let's see if we have a property __offline_payload__
-      if (
-        json &&
-        typeof json === "object" &&
-        hasOwn(json, RubyRunner.#payloadIdentifier)
-      ) {
-        payload = json[RubyRunner.#payloadIdentifier]
+      if (json && typeof json === "object") {
+        if (hasOwn(json, RubyRunner.#errorIdentifier)) {
+          error = json[RubyRunner.#errorIdentifier]
+        } else if (hasOwn(json, RubyRunner.#payloadIdentifier)) {
+          payload = json[RubyRunner.#payloadIdentifier]
+        } else {
+          log.notice(item)
+        }
       } else {
         log.notice(item)
       }
     }
 
-    return payload
+    return { error, payload }
   }
 
   // invokeLocalRuby, loosely based on:
   // https://github.com/serverless/serverless/blob/v1.50.0/lib/plugins/aws/invokeLocal/index.js#L556
-  // invoke.rb, copy/pasted entirely as is:
-  // https://github.com/serverless/serverless/blob/v1.50.0/lib/plugins/aws/invokeLocal/invoke.rb
   async run(event, context) {
-    const runtime = platform() === "win32" ? "ruby.exe" : "ruby"
+    // Chain onto the queue so each invocation has exclusive access to the
+    // shared stdin/stdout channel. Errors in the chain must not poison
+    // subsequent runs.
+    const result = this.#queue.then(() => this.#runOne(event, context))
+    this.#queue = result.then(
+      () => {},
+      () => {},
+    )
+    return result
+  }
 
-    // https://docs.aws.amazon.com/lambda/latest/dg/ruby-context.html
+  async #runOne(event, context) {
+    // Respawn if the Ruby process died (handler crash, OOM kill, etc.) or
+    // failed to spawn previously. Without this, subsequent runs would fail
+    // with EPIPE forever.
+    if (
+      this.#handlerProcess == null ||
+      this.#handlerProcess.exitCode != null ||
+      this.#spawnError != null ||
+      this.#readline == null
+    ) {
+      this.#disposeProcess()
+      this.#spawnProcess()
+    }
 
-    // https://docs.aws.amazon.com/lambda/latest/dg/ruby-context.html
-    // exclude callbackWaitsForEmptyEventLoop, don't mutate context
-    const { callbackWaitsForEmptyEventLoop, ..._context } = context
+    // If respawn also failed (e.g., Ruby is still missing), bail out with
+    // the stored spawn error rather than touching null streams below.
+    if (this.#spawnError != null || this.#readline == null) {
+      throw this.#spawnError ?? new Error("Ruby process is not running")
+    }
 
-    const input = stringify({
-      context: _context,
-      event,
-    })
+    this.#busy = true
 
-    // console.log(input)
-
-    const { stderr, stdout } = await execa(
-      runtime,
-      [
-        join(import.meta.url, "invoke.rb"),
-        relative(cwd(), this.#handlerPath),
-        this.#handlerName,
-      ],
-      {
-        env: this.#env,
-        input,
-        // shell: true,
-      },
-    )
+    try {
+      return await new Promise((res, rej) => {
+        // https://docs.aws.amazon.com/lambda/latest/dg/ruby-context.html
+        // exclude callbackWaitsForEmptyEventLoop, don't mutate context
+        const { callbackWaitsForEmptyEventLoop, ..._context } = context
 
-    if (stderr) {
-      // TODO
+        const input = stringify({
+          context: _context,
+          event,
+        })
 
-      log.notice(stderr)
-    }
+        const handlerProcess = this.#handlerProcess
+        const readline = this.#readline
+
+        let onLine
+        let onErr
+        let onProcessError
+        let onProcessExit
+
+        const cleanupListeners = () => {
+          // Defensive null guards: readline/stderr should be present here
+          // because #runOne() bails out before listener attachment when
+          // they are null, but a process can crash mid-flight.
+          readline?.removeListener("line", onLine)
+          handlerProcess.stderr?.removeListener("data", onErr)
+          handlerProcess.removeListener("error", onProcessError)
+          handlerProcess.removeListener("exit", onProcessExit)
+        }
+
+        const settleResolve = (value) => {
+          cleanupListeners()
+          res(value)
+        }
+
+        const settleReject = (err) => {
+          cleanupListeners()
+          rej(err)
+        }
+
+        onErr = (data) => {
+          // TODO
 
-    return this.#parsePayload(stdout)
+          log.notice(data.toString())
+        }
+
+        onProcessError = (err) => {
+          settleReject(err)
+        }
+
+        onProcessExit = (code, signal) => {
+          settleReject(
+            new Error(
+              `Ruby process exited unexpectedly (code=${code}, signal=${signal}) before responding`,
+            ),
+          )
+        }
+
+        onLine = (line) => {
+          try {
+            const { error, payload } = this.#parsePayload(line.toString())
+
+            if (error !== undefined) {
+              const err = new Error(error.errorMessage ?? "Ruby handler error")
+              err.name = error.errorType ?? "RubyHandlerError"
+              if (error.stackTrace) {
+                err.stack = `${err.name}: ${err.message}\n${
+                  Array.isArray(error.stackTrace)
+                    ? error.stackTrace.join("\n")
+                    : error.stackTrace
+                }`
+              }
+              settleReject(err)
+              return
+            }
+
+            if (payload !== undefined) {
+              settleResolve(payload)
+            }
+          } catch (err) {
+            settleReject(err)
+          }
+        }
+
+        readline.on("line", onLine)
+        handlerProcess.stderr.on("data", onErr)
+        handlerProcess.once("error", onProcessError)
+        handlerProcess.once("exit", onProcessExit)
+
+        nextTick(() => {
+          try {
+            handlerProcess.stdin.write(input, (writeErr) => {
+              if (writeErr) {
+                settleReject(writeErr)
+                return
+              }
+              handlerProcess.stdin.write("\n", (nlErr) => {
+                if (nlErr) {
+                  settleReject(nlErr)
+                }
+              })
+            })
+          } catch (err) {
+            settleReject(err)
+          }
+        })
+      })
+    } finally {
+      this.#busy = false
+
+      if (this.#restartQueued) {
+        this.#restartQueued = false
+        this.#restartProcess()
+      }
+    }
   }
 }

package/src/lambda/handler-runner/ruby-runner/invoke.rb

@@ -1,4 +1,7 @@
-# copy/pasted entirely from:
+# Persistent Ruby invoke script for serverless-offline.
+# Mirrors the Python runner pattern: spawn once, loop forever via stdin/stdout.
+#
+# Original one-shot version was based on:
 # https://github.com/serverless/serverless/blob/v1.50.0/lib/plugins/aws/invokeLocal/invoke.rb
 
 require 'json'
@@ -28,26 +31,6 @@ class FakeLambdaContext
   def get_remaining_time_in_millis
     [@timeout*1000 - ((Time.now() - @created_time)*1000).round, 0].max
   end
-
-  # def invoked_function_arn
-  #   "arn:aws:lambda:serverless:#{function_name}"
-  # end
-  #
-  # def memory_limit_in_mb
-  #   return @memory_limit_in_mb
-  # end
-  #
-  # def log_group_name
-  #   return @log_group_name
-  # end
-  #
-  # def log_stream_name
-  #   return Time.now.strftime('%Y/%m/%d') +'/[$' + function_version + ']58419525dade4d17a495dceeeed44708'
-  # end
-  #
-  # def log(message)
-  #   puts message
-  # end
 end
 
 
@@ -56,7 +39,7 @@ def attach_tty
     $stdin.reopen "/dev/tty", "a+"
   end
 rescue
-  puts "tty unavailable"
+  $stderr.puts "tty unavailable"
 end
 
 if __FILE__ == $0
@@ -68,8 +51,7 @@ if __FILE__ == $0
   handler_path = ARGV[0]
   handler_name = ARGV[1]
 
-  input = JSON.load($stdin) || {}
-
+  # Load the handler module ONCE at startup
   require("./#{handler_path}")
 
   # handler name is either a global method or a static method in a class
@@ -77,16 +59,46 @@ if __FILE__ == $0
   handler_method, handler_class = handler_name.split(".").reverse
   handler_class ||= "Kernel"
 
-  attach_tty
-
-  context = FakeLambdaContext.new(context: input['context'])
-  result = Object.const_get(handler_class).send(handler_method, event: input['event'], context: context)
+  # Keep a reference to the original stdin for reading from the parent process
+  original_stdin = $stdin.dup
 
-  data = {
-      # just an identifier to distinguish between
-      # interesting data (result) and stdout/print
-      '__offline_payload__': result
-  }
+  attach_tty
 
-  puts data.to_json
+  # Persistent loop: read JSON from stdin, invoke handler, write result to stdout
+  while (line = original_stdin.gets)
+    line = line.strip
+    next if line.empty?
+
+    begin
+      input = JSON.parse(line)
+
+      context = FakeLambdaContext.new(context: input['context'] || {})
+      result = Object.const_get(handler_class).send(handler_method, event: input['event'], context: context)
+
+      data = {
+        # just an identifier to distinguish between
+        # interesting data (result) and stdout/print
+        '__offline_payload__': result
+      }
+
+      $stdout.write(data.to_json)
+      $stdout.write("\n")
+      $stdout.flush
+    rescue => e
+      $stderr.write("#{e.class}: #{e.message}\n")
+      $stderr.write(e.backtrace.join("\n") + "\n")
+      $stderr.flush
+
+      error_data = {
+        '__offline_error__': {
+          'errorType' => e.class.name,
+          'errorMessage' => e.message,
+          'stackTrace' => e.backtrace
+        }
+      }
+      $stdout.write(error_data.to_json)
+      $stdout.write("\n")
+      $stdout.flush
+    end
+  end
 end