serverless-offline 14.5.0 → 14.7.0

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