serverless-llrt-analyzer 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# serverless-llrt-analyzer
+
+Serverless Framework plugin to flip Lambda functions to [AWS LLRT](https://github.com/awslabs/llrt)
+(QuickJS, ~10x faster cold starts) with **one line per function** — plus a
+deploy-time compatibility guard so you can't ship an incompatible function.
+
+Thin Serverless adapter over the [`@davidwells/llrt-analyzer`](../llrt-analyzer) core.
+
+## Install
+
+```bash
+npm i -D serverless-llrt-analyzer   # pulls in @davidwells/llrt-analyzer
+```
+
+## Use
+
+```yaml
+plugins:
+  - serverless-esbuild        # (your bundler, if any)
+  - serverless-llrt-analyzer
+
+custom:
+  llrt:
+    layerArn: arn:aws:lambda:us-east-1:xxxx:layer:llrt-arm64:1   # required
+    verify: true              # default true — fail the deploy on a real blocker
+
+functions:
+  api:        { handler: src/app.handler, llrt: true }   # -> provided.al2023 + arm64 + LLRT layer
+  warmer:     { handler: src/warmer.warm, llrt: true }
+  processImg: { handler: src/img.handler }               # stays nodejs (mixed-runtime is fine)
+```
+
+Reverting is deleting the `llrt: true` line.
+
+## What it does at package time
+
+For each `llrt: true` function:
+
+```
+api  ->  runtime: provided.al2023   architecture: arm64   layers: [ <llrt layer> ]
+```
+
+Unflagged functions are untouched.
+
+## The guard (`custom.llrt.verify`, default on)
+
+Before packaging, it runs `llrt-analyzer`'s **static tier** against each flagged
+function and aborts the deploy on a fatal blocker:
+
+```
+Error: [llrt] function "api" is NOT LLRT-compatible:
+    - node:crypto.timingSafeEqual: LLRT's node:crypto does not export
+      "timingSafeEqual" — use a supported alternative or keep this on Node.
+  Remove `llrt: true` or fix the blocker(s). (set custom.llrt.verify:false to bypass)
+```
+
+For the definitive verdict (actually runs the handler under the LLRT binary and
+diffs behavior), run the core in CI: `llrt-analyzer <service> --local`.
+
+## Getting the layer ARN (one command)
+
+```bash
+llrt-analyzer publish-layer --arch arm64 --region us-east-1 \
+  --ssm /my-svc/prod/llrt-layer-arn
+```
+
+This downloads the pinned LLRT lambda bootstrap, publishes it as a layer, prints
+the ARN, and (with `--ssm`) writes it to SSM — then reference it as
+`custom.llrt.layerArn: ${ssm:/my-svc/${self:provider.stage}/llrt-layer-arn}`.
+`llrt-analyzer init` prints the whole snippet to paste.
+
+## Bundler wiring (automatic)
+
+If you use `serverless-esbuild`, the plugin **auto-wires it** for LLRT: it marks
+`@aws-sdk/*` / `@smithy/*` / `@aws-crypto/*` **external** (LLRT ships its own SDK)
+and sets `format: esm`. These are safe for the Node functions too (the Lambda
+Node runtimes also provide `@aws-sdk`), so `llrt: true` really is the whole
+change. Opt out with `custom.llrt.autoEsbuild: false`.

package/index.js

@@ -0,0 +1,150 @@
+// @ts-check
+'use strict'
+/**
+ * serverless-llrt-analyzer — Serverless Framework plugin (Consumer 1 of the
+ * generic `@davidwells/llrt-analyzer` core).
+ *
+ * Declarative per-function opt-in: mark a function `llrt: true` and this plugin
+ * swaps it to the LLRT custom runtime at package time (provided.al2023 + arm64 +
+ * the LLRT bootstrap layer), leaving unflagged functions on Node (mixed-runtime
+ * services are first-class). Reverting is one line (remove the flag).
+ *
+ * It ALSO guards: when custom.llrt.verify is on, it runs the analyzer's static
+ * tier against each flagged function and fails the deploy if a fatal blocker is
+ * found (e.g. node:crypto.timingSafeEqual) — you can't accidentally ship an
+ * incompatible function to LLRT.
+ *
+ *   plugins:
+ *     - serverless-llrt-analyzer
+ *   custom:
+ *     llrt:
+ *       layerArn: arn:aws:lambda:us-east-1:xxxx:layer:llrt-arm64:1   # required
+ *       verify: true            # optional: analyzer guard (default true)
+ *   functions:
+ *     api:      { handler: src/app.handler, llrt: true }
+ *     warmer:   { handler: src/warmer.warm, llrt: true }
+ *     processImg: { handler: src/img.handler }   # stays node
+ *
+ * The heavy analysis lives in the `llrt-analyzer` package (a peer of this one);
+ * this plugin is a thin Serverless adapter over it.
+ */
+const path = require('path')
+const fs = require('fs')
+
+class LlrtServerlessPlugin {
+  /**
+   * @param {any} serverless
+   * @param {any} [options]
+   * @param {any} [io]
+   * @param {{ analyzeFunction?: Function }} [deps] test seam — inject the core
+   *   analyzer so the guard is unit-testable without resolving/installing core.
+   */
+  constructor(serverless, options, io, deps) {
+    this.serverless = serverless
+    this.options = options || {}
+    this.log = (io && io.log && io.log.notice) || ((m) => serverless.cli && serverless.cli.log(`[llrt] ${m}`))
+    this.injectedAnalyze = (deps && deps.analyzeFunction) || null
+    this.hooks = {
+      'before:package:createDeploymentArtifacts': () => this.apply(),
+      'before:deploy:function:packageFunction': () => this.apply(),
+      'before:package:function:package': () => this.apply(),
+    }
+  }
+
+  /** Resolve the core analyzer's analyzeFunction (injected in tests). */
+  analyzer() {
+    if (this.injectedAnalyze) return this.injectedAnalyze
+    // eslint-disable-next-line global-require
+    return require('@davidwells/llrt-analyzer').analyzeFunction
+  }
+
+  llrtConfig() {
+    const custom = (this.serverless.service && this.serverless.service.custom) || {}
+    return custom.llrt || {}
+  }
+
+  flaggedFunctions() {
+    const fns = (this.serverless.service && this.serverless.service.functions) || {}
+    return Object.entries(fns).filter(([, def]) => def && def.llrt === true)
+  }
+
+  async apply() {
+    if (this.__applied) return
+    this.__applied = true
+    const flagged = this.flaggedFunctions()
+    if (flagged.length === 0) return
+    const cfg = this.llrtConfig()
+
+    if (cfg.verify !== false) await this.guard(flagged)
+
+    for (const [name, def] of flagged) {
+      def.runtime = 'provided.al2023'
+      def.architecture = def.architecture || 'arm64'
+      if (cfg.layerArn) def.layers = uniq([...(def.layers || []), cfg.layerArn])
+      else this.log(`WARNING: function "${name}" is llrt:true but custom.llrt.layerArn is unset — package the LLRT bootstrap yourself.`)
+      this.log(`function "${name}" -> LLRT (provided.al2023, ${def.architecture})`)
+    }
+    // Signal the esbuild step (if any) that LLRT bundling rules apply.
+    const service = this.serverless.service
+    service.custom = service.custom || {}
+    service.custom.__llrtFunctions = flagged.map(([n]) => n)
+
+    if (cfg.autoEsbuild !== false) this.autoWireEsbuild()
+  }
+
+  /**
+   * Auto-wire serverless-esbuild for LLRT (idea #4): LLRT needs its handlers
+   * bundled as ESM with the AWS SDK left EXTERNAL (LLRT ships its own SDK), so
+   * the flip is genuinely one line. serverless-esbuild config is global (not
+   * per-function), but these settings are SAFE for the Node functions too — the
+   * Lambda Node runtimes also provide @aws-sdk, and ESM output is fine there.
+   * Escape hatch: custom.llrt.autoEsbuild: false.
+   */
+  autoWireEsbuild() {
+    const custom = this.serverless.service.custom || {}
+    const eb = custom.esbuild
+    if (!eb || typeof eb !== 'object') return // serverless-esbuild not in use — nothing to wire
+    const wantExternal = ['@aws-sdk/*', '@smithy/*', '@aws-crypto/*']
+    const existing = Array.isArray(eb.external) ? eb.external : []
+    const added = wantExternal.filter((e) => !existing.includes(e))
+    if (added.length) eb.external = [...existing, ...added]
+    if (!eb.format) eb.format = 'esm'
+    if (added.length || eb.format === 'esm') {
+      this.log(`serverless-esbuild wired for LLRT (external += ${added.join(', ') || '(none)'}, format=${eb.format})`)
+    }
+  }
+
+  /** Analyzer guard: fail the deploy on a fatal LLRT blocker. */
+  async guard(flagged) {
+    const analyzeFunction = this.analyzer()
+    const servicePath = this.serverless.config && this.serverless.config.servicePath ? this.serverless.config.servicePath : process.cwd()
+    for (const [name, def] of flagged) {
+      const entryPoint = this.resolveHandlerFile(servicePath, def.handler)
+      if (!entryPoint) continue
+      // eslint-disable-next-line no-await-in-loop
+      const v = await analyzeFunction({ entryPoint, projectDir: servicePath, fn: name, tiers: ['static'] })
+      const fatal = (v.blockers || []).filter((b) => b.fatal)
+      if (fatal.length) {
+        const lines = fatal.map((b) => `    - ${b.api}: ${b.fix}`).join('\n')
+        throw new Error(`[llrt] function "${name}" is NOT LLRT-compatible:\n${lines}\n  Remove \`llrt: true\` or fix the blocker(s). (set custom.llrt.verify:false to bypass)`)
+      }
+      this.log(`function "${name}" passed the LLRT static guard`)
+    }
+  }
+
+  resolveHandlerFile(servicePath, handler) {
+    if (!handler || typeof handler !== 'string') return null
+    const fileRel = handler.slice(0, handler.lastIndexOf('.'))
+    for (const e of ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs']) {
+      const p = path.join(servicePath, fileRel + e)
+      if (fs.existsSync(p)) return p
+    }
+    return null
+  }
+}
+
+function uniq(arr) {
+  return [...new Set(arr)]
+}
+
+module.exports = LlrtServerlessPlugin

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "serverless-llrt-analyzer",
+  "version": "0.1.0",
+  "description": "Serverless Framework plugin to flip Lambda functions to AWS LLRT (llrt: true) for ~10x faster cold starts, with a deploy-time compatibility guard powered by llrt-analyzer.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "uvu . \".*\\.test\\.js$\""
+  },
+  "keywords": [
+    "serverless",
+    "serverless-plugin",
+    "llrt",
+    "aws-lambda",
+    "cold-start",
+    "provided.al2023"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavidWells/smart-ci.git",
+    "directory": "packages/serverless-llrt-analyzer"
+  },
+  "bugs": {
+    "url": "https://github.com/DavidWells/smart-ci/issues"
+  },
+  "homepage": "https://github.com/DavidWells/smart-ci/tree/master/packages/serverless-llrt-analyzer#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "@davidwells/llrt-analyzer": "^0.1.0"
+  },
+  "devDependencies": {
+    "uvu": "^0.5.6"
+  }
+}