@kensio/yulin 1.20.14 → 1.20.16

package/docs/lint/README.md

@@ -0,0 +1,176 @@
+# Linting CFF JS2
+
+CloudFront Functions run JS2, ECMAScript 5.1 with a named subset of ES 6 to 12 on top, rather than
+a current JavaScript engine. A class or a `for...of` is a syntax error, and CloudFront refuses the
+code when you upload it. A call to `fetch` parses, and then fails at the edge, where that global is
+absent and there is no network to reach. Both are a long way from where the code was written, and
+Yulin publishes lint configs that refuse the same things in the editor.
+
+The configs apply to `**/*.cff.js` files. That is the naming
+[sim CloudFront](https://yulinsim.dev/services/cloudfront/ "Simulated CloudFront usage docs") already uses for
+CloudFront Function source.
+
+Every restriction comes from the runtime's
+[own feature list](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-javascript-runtime-20.html),
+an allow-list, and anything outside it is unsupported. None of it is house style. A rule
+banning syntax JS2 accepts would send you away from code that works.
+
+## Setting it up with ESLint
+
+`@kensio/yulin/eslint` exports a flat config to spread into your own. It restricts itself to
+`**/*.cff.js`. The rest of your config still applies everywhere else.
+
+```typescript cff-js2-eslint-config
+/**
+ * An ESLint config that lints CloudFront Function files as JS2.
+ */
+
+import eslint from "@eslint/js";
+import { defineConfig } from "eslint/config";
+
+import { cloudFrontFunctionsJs2 } from "@kensio/yulin/eslint";
+
+export default defineConfig(
+  eslint.configs.recommended,
+
+  // Applies only to **/*.cff.js, so it goes after the configs it relaxes.
+  ...cloudFrontFunctionsJs2,
+);
+```
+
+It goes after any config whose rules it needs to turn off. That is a short list. `const`, `let`,
+template literals, arrow functions, rest parameters and `async`/`await` all work in JS2, and the
+rules asking for them stay on. Only `object-shorthand` is switched off, because shorthand property
+names are ES 6 literal syntax the runtime lacks.
+
+`eslint` and `typescript-eslint` are optional peer dependencies, needed only if you use this export.
+
+## Setting it up with Oxlint
+
+`@kensio/yulin/oxlint` ships the same rules as an Oxlint config fragment to extend. The rules
+themselves are one plugin loaded by both linters. The two configs report the same things in the same
+places.
+
+```json
+{
+  "extends": ["./node_modules/@kensio/yulin/cffjs2.oxlintrc.json"],
+  "rules": {
+    "no-console": "error"
+  }
+}
+```
+
+Oxlint's `extends` takes a file path rather than a package name. The path into `node_modules` is
+written out in full. The file sits in the package root. A build that moves what it emits under
+`dist/` leaves the path alone. The fragment brings its own `overrides` entry scoped to `**/*.cff.js`
+and the JS plugin the rules live in, and leaves every other file to your own rules.
+
+The plugin is loaded through Oxlint's JS plugin support, which needs Oxlint 1.77 or later.
+
+## What is reported
+
+Each restriction is its own rule, under the `cff-js2` name in both linters.
+
+| Rule                            | What it refuses                                          |
+| ------------------------------- | -------------------------------------------------------- |
+| `cff-js2/no-import`             | `import` declarations, apart from `cloudfront`           |
+| `cff-js2/only-handler-export`   | Any export other than `export function handler(...)`     |
+| `cff-js2/only-built-in-require` | Requiring anything but `querystring`, `crypto`, `buffer` |
+| `cff-js2/no-class`              | Class declarations and expressions                       |
+| `cff-js2/no-generator`          | Generators and `yield`                                   |
+| `cff-js2/no-destructuring`      | Object and array destructuring                           |
+| `cff-js2/no-spread`             | Spread syntax, but not rest parameters                   |
+| `cff-js2/no-for-of`             | `for...of`, in favour of an index-based loop             |
+| `cff-js2/no-unavailable-global` | Globals the runtime does not have, such as `fetch`       |
+
+`cff-js2/no-unavailable-global` covers three groups. `fetch`, `XMLHttpRequest` and `WebSocket` need
+a network the runtime lacks. `process` needs Node.js. `setTimeout`, `setInterval`, `setImmediate`
+and `clearTimeout` need an event loop a Function never gets. The rule resolves names through scope
+rather than matching them as text, and a local variable named `fetch` or a property named
+`event.fetch` is left alone. Each report says why the global is missing, because `fetch` being
+absent for want of a network and `setTimeout` for want of an event loop call for different rewrites.
+
+Alongside these, both configs turn on `no-eval`, `no-new-func` and `no-implied-eval`, which the
+runtime refuses outright. They also set `no-unused-vars` to leave `handler` alone, since it is the
+entry point CloudFront calls.
+
+## What is not reported
+
+These all work in JS2 and no rule here objects to them:
+
+- Template literals, including interpolation and nesting
+- Arrow functions and rest parameters
+- `const` and `let`
+- `async` and `await`
+- `Promise`, including `all`, `allSettled`, `any` and `race`
+- `Buffer`, and `require` of `querystring`, `crypto` or `buffer`
+- `import cf from "cloudfront"`, which a Function needs for `cf.kvs()` and
+  `cf.updateRequestOrigin()`
+- `String.prototype.replaceAll`, `atob`, `btoa` and numeric separators
+
+## Turning one restriction off
+
+Rules are individual. A restriction you disagree with can be switched off on its own. In ESLint:
+
+```typescript cff-js2-eslint-relax
+/**
+ * Allowing class syntax in CloudFront Function files.
+ */
+
+import { defineConfig } from "eslint/config";
+
+import { cloudFrontFunctionsJs2 } from "@kensio/yulin/eslint";
+
+export default defineConfig(...cloudFrontFunctionsJs2, {
+  files: ["**/*.cff.js"],
+  rules: {
+    "cff-js2/no-class": "off",
+  },
+});
+```
+
+In Oxlint, the same thing goes in an `overrides` entry after the `extends`:
+
+```json
+{
+  "extends": ["./node_modules/@kensio/yulin/cffjs2.oxlintrc.json"],
+  "overrides": [
+    {
+      "files": ["**/*.cff.js"],
+      "rules": {
+        "cff-js2/no-class": "off"
+      }
+    }
+  ]
+}
+```
+
+## Available functionality
+
+- A flat ESLint config at `@kensio/yulin/eslint`, exported as `cloudFrontFunctionsJs2`
+- An Oxlint config fragment at `cffjs2.oxlintrc.json` in the package root, with the object it is
+  generated from exported as `cloudFrontFunctionsJs2Oxlint` from `@kensio/yulin/oxlint`
+- Nine `cff-js2` rules, one per restriction, shared by both linters
+- Scoping to `**/*.cff.js`, leaving a repository's own rules untouched elsewhere
+
+## Limitations
+
+Where the configs knowingly stop short:
+
+- **`async` arguments and closures are not checked.** JS2 supports `async` and `await`, but not
+  `async` arguments or closures, and `await` only inside an `async` function. Where the runtime's
+  wording stops short of saying exactly which forms those are, no rule guesses at it. A Function can
+  pass the lint and still be refused for one.
+- **The list of unavailable globals is the useful part of one, not all of it.** It names what test
+  code and Node habits reach for. A global outside that list goes unreported, even if JS2 lacks it.
+- **The rules are syntactic.** Nothing here knows CloudFront's size limit on Function code or its CPU
+  budget. A Function that passes the lint can still be refused at publication for being too large or
+  too slow. No rule checks which methods of a supported built-in you call either, and the runtime
+  supports only some of them.
+- **Only the `cff-js2` rules are shared between the linters.** ESLint and Oxlint each bring their own
+  built-in rules, and their own defaults for which are on. A `.cff.js` file linted by both may pick
+  up findings from one that the other lacks.
+- **Oxlint's JS plugin support is in alpha.** It is what loads these rules into Oxlint, and its API
+  is still moving upstream.
+- **The Oxlint fragment is extended by path.** Oxlint has no package-name resolution in `extends`.
+  The written-out path into `node_modules` depends on your installer's layout.

package/docs/non-aws-dependencies/README.md

@@ -0,0 +1,261 @@
+# Non-AWS dependencies
+
+Most applications talk to something other than AWS, such as a Redis or a Postgres. This page covers
+what happens to those when the application runs under Yulin.
+
+## Two kinds of dependency
+
+A simulated Lambda function and a simulated ECS container both run your own code in the same Node.js
+process as the test. Everything that code talks to falls into one of two categories.
+
+Simulated AWS services are handled by Yulin. A DynamoDB call reaches an in-memory table and an S3
+call reaches an in-memory bucket, with no network involved. [AWS SDK interception](https://yulinsim.dev/sdk/)
+is how an ordinary SDK client in the code under test gets there.
+
+Everything else is yours to provide, and connects the way it normally would. Yulin leaves it alone
+entirely, with no simulation and no interception. Code that opens a Redis connection opens a real
+one, to whatever address it was given.
+
+## Pointing the code at your own dependency
+
+A deployed Lambda function or ECS container reads its connection details from environment variables.
+The simulated ones do the same. A function's `Environment.Variables` and a container definition's
+`environment` are visible through `process.env` while the code runs, so pointing the application
+somewhere else means setting the value it already reads. No Yulin feature is involved, and the code
+under test stays as it is.
+
+```typescript non-aws-dependency-lambda
+/**
+ * Pointing a simulated Lambda function at a dependency Yulin does not
+ * simulate, alongside one it does.
+ */
+
+import { CreateFunctionCommand, InvokeCommand } from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+
+const simAws = new SimAws();
+const lambda = simAws.lambda();
+
+await lambda.createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "rates",
+    Role: "arn:aws:iam::111111111111:role/RatesRole",
+    Environment: {
+      Variables: {
+        // Simulated by Yulin, reached with no network involved.
+        TABLE_NAME: "rates",
+        // Yours. A deployment points this at ElastiCache. A test points it
+        // at whatever it wants the code to talk to instead.
+        CACHE_URL: "redis://127.0.0.1:6379",
+      },
+    },
+    Code: {
+      ZipFile: makeLambdaZipFileInput(() => ({
+        // Building a Redis client from the second value involves nothing of
+        // Yulin's. It is an ordinary environment variable read.
+        tableName: process.env["TABLE_NAME"],
+        cacheUrl: process.env["CACHE_URL"],
+      })),
+    },
+  }),
+);
+
+const output = await lambda.invoke(
+  new InvokeCommand({ FunctionName: "rates" }),
+);
+
+if (output.Payload === undefined) throw new Error("No invoke Payload");
+// {"tableName":"rates","cacheUrl":"redis://127.0.0.1:6379"}
+console.log(Buffer.from(output.Payload).toString());
+```
+
+What that address points at is up to the test. A Redis running on localhost, one the test suite
+starts in a container, or a stand-in the test defines itself all work, because the application is
+doing what it always does with the value it is given.
+
+## A container reading from both
+
+The worked example below runs one simulated ECS container that writes to a simulated DynamoDB table
+and reads from a cache of its own. The two categories sit next to each other in the same handler and
+are configured the same way, through the container definition's `environment`.
+
+The cache here is a stand-in defined by the example, and it works with no server running. A real
+client built from `CACHE_URL` would go in the same place.
+
+```typescript non-aws-dependency-ecs
+/**
+ * A simulated ECS container writing to a simulated DynamoDB table and reading
+ * from a cache of its own.
+ */
+
+import {
+  CreateTableCommand,
+  DynamoDBClient,
+  GetItemCommand,
+  PutItemCommand,
+} from "@aws-sdk/client-dynamodb";
+import {
+  CreateClusterCommand,
+  RegisterTaskDefinitionCommand,
+  RunTaskCommand,
+} from "@aws-sdk/client-ecs";
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+
+import { SimSdk } from "@kensio/yulin/sdk";
+
+/**
+ * Where the worker reads exchange rates from.
+ *
+ * A deployment builds a Redis client from the URL. This example stands one in,
+ * so nothing has to be running for it to work.
+ */
+class RateCache {
+  constructor(private readonly url: string) {}
+
+  rate(currency: string): Promise<string> {
+    console.log(`reading ${currency} from ${this.url}`);
+    // reading GBP from redis://127.0.0.1:6379
+    return Promise.resolve("1.27");
+  }
+}
+
+using simSdk = new SimSdk();
+const { simAws } = simSdk;
+const ecs = simAws.ecs();
+
+simSdk.intercept(DynamoDBClient);
+
+await simAws.dynamoDb().createTable(
+  new CreateTableCommand({
+    TableName: "rates",
+    KeySchema: [{ AttributeName: "currency", KeyType: "HASH" }],
+    AttributeDefinitions: [{ AttributeName: "currency", AttributeType: "S" }],
+    BillingMode: "PAY_PER_REQUEST",
+  }),
+);
+
+const taskRole = await simAws.iam().createRole(
+  new CreateRoleCommand({
+    RoleName: "RatesTaskRole",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { Service: "ecs-tasks.amazonaws.com" },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+
+await simAws.iam().putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "RatesTaskRole",
+    PolicyName: "WriteRates",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "dynamodb:PutItem",
+        Resource:
+          `arn:aws:dynamodb:${simAws.defaultRegionName}:` +
+          `${simAws.defaultAccountId}:table/rates`,
+      },
+    }),
+  }),
+);
+
+await ecs.createCluster(new CreateClusterCommand({}));
+
+ecs.bindContainer({
+  family: "rates-worker",
+  containerName: "app",
+  run: async () => {
+    // Both reads happen inside the handler, so they see the container's own
+    // variables rather than the test process's.
+    const cache = new RateCache(process.env["CACHE_URL"] ?? "");
+    const rate = await cache.rate("GBP");
+
+    await new DynamoDBClient({}).send(
+      new PutItemCommand({
+        TableName: process.env["TABLE_NAME"],
+        Item: { currency: { S: "GBP" }, rate: { S: rate } },
+      }),
+    );
+  },
+});
+
+await ecs.registerTaskDefinition(
+  new RegisterTaskDefinitionCommand({
+    family: "rates-worker",
+    taskRoleArn: taskRole.Role.Arn,
+    containerDefinitions: [
+      {
+        name: "app",
+        image: "rates-worker:1",
+        environment: [
+          // Simulated by Yulin, reached with no network involved.
+          { name: "TABLE_NAME", value: "rates" },
+          // Yours, connected to the way it normally would be.
+          { name: "CACHE_URL", value: "redis://127.0.0.1:6379" },
+        ],
+      },
+    ],
+  }),
+);
+
+await ecs.runTask(new RunTaskCommand({ taskDefinition: "rates-worker" }));
+await simAws.backgroundTasksComplete();
+
+const stored = await simAws.dynamoDb().getItem(
+  new GetItemCommand({
+    TableName: "rates",
+    Key: { currency: { S: "GBP" } },
+  }),
+);
+
+console.log(stored.Item?.["rate"]?.S); // "1.27"
+```
+
+The DynamoDB write is authorized as the task role, in the same way it would be in a deployment. The
+cache read passes through no authorization at all, because IAM has no part in it.
+
+## Sidecar containers are not started
+
+A task definition sometimes declares the dependency itself as a second container, such as a Redis
+running next to the application in the same task. Yulin never looks inside a container image, and
+the only thing it can run is JavaScript or TypeScript in its own process. An image holding a Redis
+server is beyond it.
+
+The container is stored and reported back as declared, and it is recorded as not simulated when the
+task runs, with a reason saying so. An application expecting it has to be given something else to
+talk to. Set the variable holding the address to something that answers, whether that is a Redis you
+run yourself or a stand-in, in the same way as for any other dependency of your own.
+
+## Reads happen inside the handler
+
+Handler code gets the function's or the container's variables while it runs, and reads the host
+process environment otherwise. A read at module scope, as in `const url = process.env.CACHE_URL` at
+the top of a file, happens when the test imports that file rather than when the code runs. It sees
+the host value.
+
+That matters here because a connection is often built at module scope. Read inside the handler, or
+build the client there, to get the configured value. Sim Lambda warns on the console when the
+difference changes what the code sees, which is covered under
+[environment variables](https://yulinsim.dev/services/lambda/#environment-variables) on the simulated Lambda
+page. Zip code running in the vm runtime is unaffected, because it is imported during an invocation.
+
+## Limitations
+
+Current documented limitations:
+
+- Everything outside the simulated AWS services is yours to run and to tear down. Yulin starts none
+  of it.
+- A dependency declared as a sidecar container in an ECS task definition is not started, because
+  Yulin never runs a container image.
+- A connection built at module scope reads the host environment rather than the function's or the
+  container's, since the value is read before anything runs.
+- There is no interception point for a non-AWS dependency. The way to send the code somewhere else
+  is the environment variable it already reads, or an injection point in the code itself.