@specific.dev/spectest 0.34.0 → 0.35.0

package/dist/components/aws.d.ts

@@ -101,7 +101,14 @@ export declare function aws(opts?: AwsOptions): {
     };
     env: {
         AWS_DEFAULT_REGION: string;
+        LAMBDA_EXECUTOR: string;
+        LAMBDA_STRICT: string;
+        LAMBDA_DOCKER_NETWORK: string;
     };
+    volumes: {
+        source: string;
+        target: string;
+    }[];
     ports: number[];
     readyCheck: {
         type: "http";

package/dist/components/aws.js

@@ -19,9 +19,37 @@
 // pinned rather than floated. It replaced LocalStack, which folded its
 // Apache-2.0 Community edition into one paid product in March 2026 (current
 // images demand a LOCALSTACK_AUTH_TOKEN). MiniStack also suits fork-per-test
-// far better: ~270 MB against ~1 GB, a ~2 s boot, and Lambda on an in-process
-// warm worker pool instead of sibling containers — so no docker socket is
-// bind-mounted and there is no host-architecture workaround on Graviton.
+// far better: ~270 MB against ~1 GB and a ~2 s boot.
+//
+// Lambda runs in MiniStack's **docker** executor, never its default `local`
+// one, because `local` has no runtime fidelity at all: it maps `python*` to
+// its own `sys.executable` and `nodejs*` to its own `node`, so the declared
+// `Runtime` selects only the language. A function declared `python3.11` runs
+// on the emulator image's CPython 3.13/musl, and one declared `nodejs20.x`
+// runs on Node 24 — which is why a native wheel built for the real target
+// fails to import ("No module named 'pydantic_core._pydantic_core'"). The
+// docker executor runs the handler under AWS's own Runtime Interface
+// Emulator in `public.ecr.aws/lambda/<runtime>`, giving the real
+// interpreter, glibc, `/var/task` and `AWS_EXECUTION_ENV`. Measured on
+// aarch64: it is also ~7x FASTER per warm invoke (7 ms against 53 ms) at
+// ~25-40 MiB per function container.
+//
+// None of this is configurable, on purpose — a knob here is a knob between
+// "behaves like AWS" and "does not".
+//
+// The cost is a bind-mount of the VM's own docker socket, which the daemon
+// already supports (`ensureVolumes` treats an existing non-directory source
+// as a thing to mount as-is). The RIE containers are ordinary VM containers
+// on `spectest-net`, so they ride snapshots and forks like any service: a
+// per-test fork inherits its parent's already-warm function.
+//
+// Landmine: the runtime images are pulled from `public.ecr.aws`, which the
+// in-VM dockerd reaches DIRECTLY. Its `registry-mirrors` only ever applies
+// to Docker Hub, so the zot mirror (which does carry public.ecr.aws, on
+// :5004) is NOT consulted. MiniStack's own `MINISTACK_IMAGE_PREFIX` cannot
+// close that gap either: it prepends rather than replacing the registry
+// host. Routing these pulls through zot needs a pre-pull of
+// `spectest-host:5004/lambda/<rt>` retagged to the `public.ecr.aws` name.
 //
 // Like `email()`'s mail server, the product name stays out of every
 // user-facing surface (docs, examples, error messages). Users get "the AWS
@@ -73,6 +101,13 @@ const AWS_HOST_PATTERNS = [
     "*.amazonaws.com.cn",
     ...AWS_CN_REGIONS.map((r) => `*.${r}.amazonaws.com.cn`),
 ];
+/** The VM's own docker socket, bind-mounted so the emulator can start the
+ *  official AWS runtime containers. This is the VM's dockerd, inside the
+ *  hermetic environment — the same daemon that runs the services. */
+const DOCKER_SOCKET = "/var/run/docker.sock";
+/** The network the function containers join, so a handler reaches the other
+ *  services and the AWS endpoints by the same names a test uses. */
+const SPECTEST_NETWORK = "spectest-net";
 /** Region the emulator's own tools default to — the AWS CLI refuses to run
  *  without one. Only the *container's* default; it constrains nothing about
  *  the app, and every region is served regardless. A `setup` hook that drives
@@ -144,7 +179,18 @@ export function aws(opts = {}) {
     const lambdas = opts.lambdas ?? {};
     const service = {
         image: { type: "registry", reference: AWS_IMAGE },
-        env: { AWS_DEFAULT_REGION: CONTAINER_DEFAULT_REGION },
+        env: {
+            AWS_DEFAULT_REGION: CONTAINER_DEFAULT_REGION,
+            // Run every function in the official AWS runtime image rather than in
+            // the emulator's own interpreter — see the note at the top of the file.
+            LAMBDA_EXECUTOR: "docker",
+            // No silent fall-back to the low-fidelity executor. If the runtime
+            // container cannot start, say so instead of running the handler on the
+            // wrong interpreter and failing later, somewhere else.
+            LAMBDA_STRICT: "1",
+            LAMBDA_DOCKER_NETWORK: SPECTEST_NETWORK,
+        },
+        volumes: [{ source: DOCKER_SOCKET, target: DOCKER_SOCKET }],
         ports: [AWS_PORT],
         readyCheck: {
             type: "http",
@@ -226,9 +272,10 @@ async function deployLambda(service, projectRoot, name, spec) {
         Handler: spec.handler ?? "index.handler",
         Role: spec.role ?? DEFAULT_ROLE_ARN,
         Timeout: spec.timeoutSecs ?? 30,
-        // Fixed, and not an option: the emulated cloud runs handlers in a shared
-        // worker pool rather than a memory-capped sandbox, so the number changes
-        // nothing about how a function behaves here.
+        // Fixed, and not an option: the emulated cloud reports this number back
+        // as `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` but never caps the runtime
+        // container at it, so the number changes nothing about how a function
+        // behaves here.
         MemorySize: MEMORY_MB,
         ...(spec.env ? { Environment: { Variables: spec.env } } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",