@kensio/yulin 1.21.31 → 1.21.33

package/dist/util/process/sim-process-environment-reads.js

@@ -0,0 +1,94 @@
+/**
+ * Records the names code reads from the host process.env.
+ *
+ * SimLambdaEnvironmentConflicts warns that a module-scope read sees the host
+ * value of a variable instead of the function's own. Whether that matters
+ * depends on a read having happened at all, which configuration cannot tell.
+ * This keeps the evidence: the host environment is handed out behind a Proxy
+ * that notes each name read through it.
+ *
+ * Enumerating the whole environment is not counted as reading every name in
+ * it. Node.js copies process.env key by key when it spawns a child process,
+ * and so does any tool that snapshots it, and none of that is handler code
+ * capturing a value it later depends on. An enumeration is recognised by its
+ * shape: the property reads that follow a listing of the keys, in the order
+ * the listing gave them. Its reads are recorded as they happen and taken off
+ * the record again once every key has been read, so a listing that is not
+ * followed by a complete copy hides nothing. A module copying the environment
+ * with a spread at module scope is missed as a result.
+ */
+export class SimProcessEnvironmentReads {
+    names = new Set();
+    /**
+     * The environment objects each watching Proxy stands in front of, so that
+     * assigning one back to process.env does not stack a Proxy on a Proxy.
+     */
+    targets = new WeakMap();
+    /**
+     * The keys of an enumeration in progress, and how far its reads have got.
+     */
+    enumeration;
+    /**
+     * Whether code has read the name through a watched environment.
+     */
+    wasRead(name) {
+        return this.names.has(name);
+    }
+    /**
+     * A view of the environment that records the names read through it.
+     *
+     * Writes and deletes go straight to the environment, so a value assigned
+     * through the view is coerced to a string as process.env would coerce it.
+     */
+    watch(environment) {
+        const target = this.unwrap(environment);
+        const view = new Proxy(target, {
+            get: (watched, key) => {
+                if (typeof key === "string") {
+                    this.recordRead(key);
+                }
+                return Reflect.get(watched, key);
+            },
+            set: (watched, key, value) => Reflect.set(watched, key, value),
+            ownKeys: (watched) => {
+                const keys = Reflect.ownKeys(watched);
+                this.enumeration = { keys, next: 0, added: [] };
+                return keys;
+            },
+        });
+        this.targets.set(view, target);
+        return view;
+    }
+    /**
+     * The environment behind a watching view, or the environment itself when it
+     * is not one.
+     */
+    unwrap(environment) {
+        return this.targets.get(environment) ?? environment;
+    }
+    /**
+     * Note a read, and take an enumeration's reads off the record once it has
+     * read every key.
+     */
+    recordRead(name) {
+        const enumeration = this.enumeration;
+        if (enumeration === undefined ||
+            enumeration.keys[enumeration.next] !== name) {
+            this.enumeration = undefined;
+            this.names.add(name);
+            return;
+        }
+        enumeration.next += 1;
+        if (!this.names.has(name)) {
+            this.names.add(name);
+            enumeration.added.push(name);
+        }
+        if (enumeration.next < enumeration.keys.length) {
+            return;
+        }
+        for (const added of enumeration.added) {
+            this.names.delete(added);
+        }
+        this.enumeration = undefined;
+    }
+}

package/dist/util/process/sim-process-environment.d.ts

@@ -20,19 +20,33 @@
  *
  * The one thing this cannot reach is a read that already happened. A handler
  * module doing `const TABLE = process.env.TABLE_NAME` at module scope is
- * evaluated when the test file imports it, long before any run, so it captures
+ * evaluated when the test file imports it, long before any run, and captures
  * the host value. Reads inside the handler body see the run's own variables.
- * See SimLambdaEnvironmentConflicts, which warns when that distinction
- * actually changes what the code sees.
+ *
+ * Outside a run, process.env is the host environment behind a
+ * SimProcessEnvironmentReads view, which records the names read. The patch is
+ * installed when this module loads, which is when Yulin is imported, so a
+ * module-scope read in a handler imported after Yulin is on record.
+ * SimLambdaEnvironmentConflicts warns from that record, and only for a name
+ * whose early read changed what the code saw. A read made before Yulin was
+ * imported is invisible to it.
  */
 declare class SimProcessEnvironment {
     private readonly storage;
+    private readonly reads;
     private hostEnvironment;
-    private installed;
+    private hostView;
+    constructor();
     /**
      * Run something with the given variables as its process.env.
      */
     run<T>(variables: Record<string, string>, run: () => Promise<T>): Promise<T>;
+    /**
+     * Whether code read the name from process.env while no run was active.
+     *
+     * Reads made before this module loaded are not on record.
+     */
+    wasReadOutsideRun(name: string): boolean;
     /**
      * The host process environment, ignoring any run in progress.
      */
@@ -51,14 +65,23 @@ declare class SimProcessEnvironment {
      *
      * process.env is a plain configurable data property on process, so it can
      * be replaced with a getter. Outside a simulated run the getter hands back
-     * the untouched host environment object, so the patch is inert: anything
-     * that reads, writes, or stubs process.env normally is unaffected.
+     * the host environment behind a view that records the names read, and
+     * passes every read, write and delete through to it. Anything that reads,
+     * writes, or stubs process.env normally is unaffected.
      *
-     * Installed once and never removed. Removing it would be unsafe while
-     * another run is in flight, and there is nothing to gain: an installed patch
-     * with no run in progress behaves exactly like no patch at all.
+     * Installed once, at construction, and never removed. Removing it would be
+     * unsafe while another run is in flight, and there is nothing to gain. With
+     * no run in progress, the patch passes everything through to the host
+     * environment.
      */
     private install;
+    /**
+     * Make the environment the host environment, and watch reads of it.
+     *
+     * Code saving process.env and assigning it back hands over the watching
+     * view, which is unwrapped so that views do not nest.
+     */
+    private useHostEnvironment;
     /**
      * Apply an assignment to process.env as a whole.
      *

package/dist/util/process/sim-process-environment.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { SimProcessEnvironmentReads } from "./sim-process-environment-reads.js";
 /**
  * The process.env in-process handler code sees while a simulated run lasts.
  *
@@ -21,22 +22,39 @@ import { AsyncLocalStorage } from "node:async_hooks";
  *
  * The one thing this cannot reach is a read that already happened. A handler
  * module doing `const TABLE = process.env.TABLE_NAME` at module scope is
- * evaluated when the test file imports it, long before any run, so it captures
+ * evaluated when the test file imports it, long before any run, and captures
  * the host value. Reads inside the handler body see the run's own variables.
- * See SimLambdaEnvironmentConflicts, which warns when that distinction
- * actually changes what the code sees.
+ *
+ * Outside a run, process.env is the host environment behind a
+ * SimProcessEnvironmentReads view, which records the names read. The patch is
+ * installed when this module loads, which is when Yulin is imported, so a
+ * module-scope read in a handler imported after Yulin is on record.
+ * SimLambdaEnvironmentConflicts warns from that record, and only for a name
+ * whose early read changed what the code saw. A read made before Yulin was
+ * imported is invisible to it.
  */
 class SimProcessEnvironment {
     storage = new AsyncLocalStorage();
+    reads = new SimProcessEnvironmentReads();
     hostEnvironment = process.env;
-    installed = false;
+    hostView = process.env;
+    constructor() {
+        this.install();
+    }
     /**
      * Run something with the given variables as its process.env.
      */
     async run(variables, run) {
-        this.install();
         return await this.storage.run(variables, run);
     }
+    /**
+     * Whether code read the name from process.env while no run was active.
+     *
+     * Reads made before this module loaded are not on record.
+     */
+    wasReadOutsideRun(name) {
+        return this.reads.wasRead(name);
+    }
     /**
      * The host process environment, ignoring any run in progress.
      */
@@ -65,27 +83,35 @@ class SimProcessEnvironment {
      *
      * process.env is a plain configurable data property on process, so it can
      * be replaced with a getter. Outside a simulated run the getter hands back
-     * the untouched host environment object, so the patch is inert: anything
-     * that reads, writes, or stubs process.env normally is unaffected.
+     * the host environment behind a view that records the names read, and
+     * passes every read, write and delete through to it. Anything that reads,
+     * writes, or stubs process.env normally is unaffected.
      *
-     * Installed once and never removed. Removing it would be unsafe while
-     * another run is in flight, and there is nothing to gain: an installed patch
-     * with no run in progress behaves exactly like no patch at all.
+     * Installed once, at construction, and never removed. Removing it would be
+     * unsafe while another run is in flight, and there is nothing to gain. With
+     * no run in progress, the patch passes everything through to the host
+     * environment.
      */
     install() {
-        if (this.installed) {
-            return;
-        }
-        this.hostEnvironment = process.env;
+        this.useHostEnvironment(process.env);
         Object.defineProperty(process, "env", {
             configurable: true,
             enumerable: true,
-            get: () => this.storage.getStore() ?? this.hostEnvironment,
+            get: () => this.storage.getStore() ?? this.hostView,
             set: (replacement) => {
                 this.replaceVariables(replacement);
             },
         });
-        this.installed = true;
+    }
+    /**
+     * Make the environment the host environment, and watch reads of it.
+     *
+     * Code saving process.env and assigning it back hands over the watching
+     * view, which is unwrapped so that views do not nest.
+     */
+    useHostEnvironment(environment) {
+        this.hostEnvironment = this.reads.unwrap(environment);
+        this.hostView = this.reads.watch(this.hostEnvironment);
     }
     /**
      * Apply an assignment to process.env as a whole.
@@ -104,7 +130,7 @@ class SimProcessEnvironment {
     replaceVariables(replacement) {
         const store = this.storage.getStore();
         if (store === undefined) {
-            this.hostEnvironment = replacement;
+            this.useHostEnvironment(replacement);
             return;
         }
         const replacing = Object.entries(replacement);

package/dist/util/schedule/cron/sim-cron-field-bounds.js

@@ -58,5 +58,5 @@ export function boundsOf(spec, written, stepped) {
         ];
     }
     const only = valueOf(spec, written);
-    return stepped ? [only, spec.maximum] : [only, only];
+    return [only, stepped ? spec.maximum : only];
 }

package/docs/services/lambda/README.md

@@ -3355,6 +3355,12 @@ console in the two situations where the difference changes what your code sees:
 - a declared variable whose name the host process also sets, with a different value
 - two simulated functions declaring the same variable name with different values
 
+Either one is reported only once code has read that name from `process.env` with no invocation
+running. Yulin records those reads from the moment it is imported. A read made earlier is invisible
+to it (a handler module imported ahead of Yulin, or a setup file that loads first), and so is a copy
+of the whole environment such as `{ ...process.env }`. Neither produces a warning. A handler that
+reads its variables inside the handler function produces none either.
+
 ## The time inside a handler
 
 A function runs on its simulation's clock, and so does the function code. `Date.now()` and

package/docs/services/s3/README.md

@@ -531,6 +531,74 @@ reports it there.
 An Object uploaded in parts gets a different form. See
 [Uploading an Object in parts](#uploading-an-object-in-parts).
 
+## Conditional writes
+
+`PutObject`, `CopyObject` and `CompleteMultipartUpload` take `IfNoneMatch` and `IfMatch`, which
+state what the key has to hold before the write goes ahead. `IfNoneMatch: "*"` writes only to a key
+that holds nothing. `IfMatch` writes only over an Object with that ETag. A write whose condition
+fails is refused with `PreconditionFailed` (status `412`), and the Object already under the key is
+left as it was.
+
+```typescript sim-s3-conditional-write
+/**
+ * Writing a simulated S3 Object only where the key is free.
+ */
+
+import {
+  CopyObjectCommand,
+  CreateBucketCommand,
+  PutObjectCommand,
+} from "@aws-sdk/client-s3";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const simS3 = simAws.s3();
+
+await simS3.createBucket(new CreateBucketCommand({ Bucket: "audio-bucket" }));
+
+await simS3.putObject(
+  new PutObjectCommand({
+    Bucket: "audio-bucket",
+    Key: "uploads/take-1.mp3",
+    Body: "first take",
+  }),
+);
+
+for (let attempt = 0; attempt < 2; attempt++) {
+  try {
+    await simS3.copyObject(
+      new CopyObjectCommand({
+        Bucket: "audio-bucket",
+        Key: "shared/take.mp3",
+        CopySource: "audio-bucket/uploads/take-1.mp3",
+        IfNoneMatch: "*",
+      }),
+    );
+    console.log("copied");
+  } catch (error) {
+    // The second attempt finds the shared key taken.
+    if (error instanceof Error && error.name === "PreconditionFailed") {
+      console.log("already there");
+    } else {
+      throw error;
+    }
+  }
+}
+```
+
+Writes to one key run one at a time. Of several conditional writes racing for an empty key, the first
+to finish succeeds and the rest are refused. `IfMatch` on a key holding nothing answers `NoSuchKey`. On a versioned Bucket both conditions look at
+the current version, and a delete marker counts as nothing. `IfNoneMatch` on a write accepts only
+`*`, and real S3 refuses anything else with `NotImplemented`.
+
+A copy also takes conditions on its source. `CopySourceIfMatch`, `CopySourceIfNoneMatch`,
+`CopySourceIfModifiedSince` and `CopySourceIfUnmodifiedSince` refuse the copy with
+`PreconditionFailed` when the source does not meet them. An ETag condition outranks the date
+condition paired with it, as RFC 7232 has it. The served endpoint reads all of these from the same
+headers real S3 does.
+
+A failed completion leaves the upload in place, and it can be completed again.
+
 ## Uploading an Object in parts
 
 Yulin supports multipart upload through the SDK and served S3 endpoint. This covers the operations
@@ -834,9 +902,6 @@ See [Serve simulated S3 on localhost](#serve-simulated-s3-on-localhost) for sett
 - Both Buckets have to belong to the same simulated S3. A copy across Accounts or Regions is left
   out.
 - A presigned copy is left out, and so is a copy reaching a Bucket through simulated CloudFront.
-- `CopySourceIfMatch`, `CopySourceIfNoneMatch`, `CopySourceIfModifiedSince` and
-  `CopySourceIfUnmodifiedSince` are ignored. A conditional copy happens whatever the condition
-  says.
 - `ACL` is ignored. Sim S3 models no Object ACL.
 - A `versionId` in `CopySource` is refused with `NotImplemented`.
 - A copy of an Object that was uploaded in parts gets a plain ETag rather than the multipart form.
@@ -3252,6 +3317,22 @@ The `getBucketWebsiteUrl(...)` method returns the simulated S3 website URL for t
 `localUrl(...)` method on the localhost server adapts that URL so the request is sent to the local
 server while preserving the simulated S3 website hostname.
 
+### AWS CLI uploads
+
+Set `preferred_transfer_client` to `classic` in the AWS config file used for the simulated
+endpoint:
+
+```ini
+[default]
+s3 =
+    preferred_transfer_client = classic
+```
+
+The CLI's [automatic transfer-client selection](https://docs.aws.amazon.com/cli/latest/topic/s3-config.html#preferred-transfer-client)
+can choose CRT. Its uploads use streaming payload trailers, which Yulin's signature verifier
+does not support. Those requests fail with `403`. The classic client supports the single-file
+and multipart uploads exercised by Yulin's CLI tests.
+
 ## Presigned URLs
 
 Sim S3 serves a REST API endpoint alongside the website endpoint, and it accepts presigned URLs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.31",
+  "version": "1.21.33",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -293,13 +293,13 @@
     "eslint-plugin-jsdoc": "^64.0.1",
     "eslint-plugin-no-secrets": "^2.3.3",
     "eslint-plugin-security": "^4.0.1",
-    "eslint-plugin-unicorn": "^74.0.0",
+    "eslint-plugin-unicorn": "^76.0.0",
     "execa": "^10.0.0",
     "fta-cli": "^3.0.0",
     "hyparquet": "^1.29.2",
     "hyparquet-writer": "^0.16.9",
     "node-sql-parser": "^5.4.0",
-    "oxfmt": "^0.72.0",
+    "oxfmt": "^0.73.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",