@kensio/yulin 1.21.10 → 1.21.12

package/dist/service/wafv2/web-acl/sim-waf-association-config.js

@@ -0,0 +1,92 @@
+import { SimWafInvalidParameterException, SimWafUnsimulatedInputException, } from "../error/sim-wafv2.error.js";
+/**
+ * How much of a request body WAF reads for a resource type given no
+ * `AssociationConfig`.
+ *
+ * CloudFront, API Gateway and Cognito all default to 16 KB. A load balancer
+ * and an AppSync API are fixed at 8 KB, and a web ACL cannot be put in front
+ * of either one here.
+ */
+export const simWafBodyInspectionLimitBytes = 16_384;
+/**
+ * The four sizes `DefaultSizeInspectionLimit` names, in bytes.
+ */
+const inspectionLimits = new Map([
+    ["KB_16", 16_384],
+    ["KB_32", 32_768],
+    ["KB_48", 49_152],
+    ["KB_64", 65_536],
+]);
+const simulatedResourceTypes = [
+    "CLOUDFRONT",
+    "API_GATEWAY",
+    "COGNITO_USER_POOL",
+];
+/**
+ * How much of a request body a web ACL's rules read, by resource type.
+ *
+ * A web ACL holds one of these whether or not it was written with an
+ * `AssociationConfig`, and a resource type the config left out reads the
+ * default 16 KB.
+ */
+export class SimWafBodyInspectionLimits {
+    limits;
+    constructor(limits) {
+        this.limits = limits;
+    }
+    /**
+     * Read the limits an `AssociationConfig` sets, refusing anything WAF would
+     * refuse and anything this simulation cannot apply.
+     */
+    static read(input) {
+        const configured = Object.entries(input?.RequestBody ?? {});
+        const limits = new Map();
+        for (const [resourceType, config] of configured) {
+            limits.set(simulatedResourceType(resourceType), inspectionLimit(resourceType, config));
+        }
+        return new SimWafBodyInspectionLimits(limits);
+    }
+    /**
+     * How many bytes of a body a request reaching one resource type is inspected
+     * for.
+     *
+     * A request evaluated against a web ACL that no resource holds names no
+     * resource type, and reads the default.
+     */
+    bytesFor(resourceType) {
+        if (resourceType === undefined) {
+            return simWafBodyInspectionLimitBytes;
+        }
+        return this.limits.get(resourceType) ?? simWafBodyInspectionLimitBytes;
+    }
+}
+/**
+ * Hold a `RequestBody` key to the resource types this simulation associates.
+ */
+function simulatedResourceType(resourceType) {
+    const simulated = simulatedResourceTypes.find((candidate) => candidate === resourceType);
+    if (simulated === undefined) {
+        throw new SimWafUnsimulatedInputException(`AssociationConfig sets the body inspection limit for ${resourceType} ` +
+            `resources, and ${simulatedResourceTypes.join(" and ")} are the ` +
+            `types a web ACL goes in front of in Yulin`);
+    }
+    return simulated;
+}
+/**
+ * Read one resource type's `DefaultSizeInspectionLimit`.
+ *
+ * An entry carrying no size is refused the same way one carrying a size WAF
+ * has no setting for is. A template writes this part of a web ACL by hand, and
+ * an entry that says nothing about the limit it is there to set is a mistake
+ * worth reporting as one.
+ */
+function inspectionLimit(resourceType, config) {
+    const limit = config?.DefaultSizeInspectionLimit;
+    const bytes = limit === undefined ? undefined : inspectionLimits.get(limit);
+    if (bytes === undefined) {
+        throw new SimWafInvalidParameterException(`Error reason: The DefaultSizeInspectionLimit ${String(limit)} is one ` +
+            `of ${inspectionLimits.keys().toArray().join(", ")}, field: ` +
+            `ASSOCIATION_CONFIG, parameter: ${resourceType}`);
+    }
+    return bytes;
+}

package/dist/service/wafv2/web-acl/sim-waf-web-acl-configuration.d.ts

@@ -1,4 +1,5 @@
 import { SimWafAction } from "./sim-waf-action.js";
+import type { SimWafAssociationConfigInput } from "./sim-waf-association-config.js";
 import type { SimWafActionInput } from "./sim-waf-action.type.js";
 import type { SimWafCustomResponseBodies } from "./sim-waf-custom-response.type.js";
 import type { SimWafRuleInput } from "./sim-waf-rule.type.js";
@@ -11,6 +12,7 @@ export interface SimWafWebAclConfiguration {
     readonly customResponseBodies?: SimWafCustomResponseBodies | undefined;
     readonly visibilityConfig?: unknown;
     readonly description?: string | undefined;
+    readonly associationConfig?: SimWafAssociationConfigInput | undefined;
 }
 /**
  * Read the action a request no rule claims is given.

package/dist/service/wafv2/web-acl/sim-waf-web-acl.d.ts

@@ -1,6 +1,7 @@
 import { type SimWafDecision } from "../evaluate/sim-waf-decision.js";
 import type { SimWafInspectedRequest } from "../evaluate/sim-waf-inspected-request.js";
 import { SimWafResource, type SimWafResourceProperties } from "../resource/sim-waf-resource.js";
+import { type SimWafBodyInspectionResourceType } from "./sim-waf-association-config.js";
 import type { SimWafWebAclRuleScope } from "./sim-waf-rule.type.js";
 import { type SimWafWebAclConfiguration } from "./sim-waf-web-acl-configuration.js";
 interface SimWafWebAclProperties extends SimWafResourceProperties, SimWafWebAclRuleScope {
@@ -43,6 +44,14 @@ export declare class SimWafWebAcl extends SimWafResource {
      * refuses an update keeps the rules it had rather than being left with none.
      */
     reconfigure(configuration: SimWafWebAclConfiguration, lockToken: string | undefined): void;
+    /**
+     * How many bytes of a request body this web ACL reads in front of one
+     * resource type.
+     *
+     * `AssociationConfig` raises it per resource type, and a web ACL written
+     * without one reads the 16 KB default everything it protects has.
+     */
+    bodyInspectionLimitBytes(resourceType: SimWafBodyInspectionResourceType | undefined): number;
     /**
      * Decide what happens to one request.
      */

package/dist/service/wafv2/web-acl/sim-waf-web-acl.js

@@ -1,6 +1,7 @@
 import { simWafDecision, } from "../evaluate/sim-waf-decision.js";
 import { simWafEvaluateRules } from "../evaluate/sim-waf-evaluate-rules.js";
 import { SimWafResource, } from "../resource/sim-waf-resource.js";
+import { SimWafBodyInspectionLimits, } from "./sim-waf-association-config.js";
 import { compileSimWafWebAclRules } from "./sim-waf-rules.js";
 import { simWafWebAclCapacity } from "./sim-waf-web-acl-capacity.js";
 import { readSimWafDefaultAction, } from "./sim-waf-web-acl-configuration.js";
@@ -29,6 +30,7 @@ export class SimWafWebAcl extends SimWafResource {
     #defaultAction;
     #rules;
     #capacity;
+    #bodyInspectionLimits;
     constructor(properties) {
         super("webacl", properties);
         this.#scope = properties;
@@ -36,6 +38,7 @@ export class SimWafWebAcl extends SimWafResource {
         this.#defaultAction = readSimWafDefaultAction(properties.configuration);
         this.#rules = compileSimWafWebAclRules(properties.configuration, this.#scope);
         this.#capacity = simWafWebAclCapacity(properties.configuration.rules);
+        this.#bodyInspectionLimits = SimWafBodyInspectionLimits.read(properties.configuration.associationConfig);
         this.labelNamespace =
             `awswaf:${properties.accountRegionScope.accountId}:webacl:` +
                 `${properties.name}:`;
@@ -61,12 +64,24 @@ export class SimWafWebAcl extends SimWafResource {
     reconfigure(configuration, lockToken) {
         const defaultAction = readSimWafDefaultAction(configuration);
         const rules = compileSimWafWebAclRules(configuration, this.#scope);
+        const bodyInspectionLimits = SimWafBodyInspectionLimits.read(configuration.associationConfig);
         this.takeLock(lockToken);
         this.replaceDescription(configuration.description);
         this.#configuration = configuration;
         this.#defaultAction = defaultAction;
         this.#rules = rules;
         this.#capacity = simWafWebAclCapacity(configuration.rules);
+        this.#bodyInspectionLimits = bodyInspectionLimits;
+    }
+    /**
+     * How many bytes of a request body this web ACL reads in front of one
+     * resource type.
+     *
+     * `AssociationConfig` raises it per resource type, and a web ACL written
+     * without one reads the 16 KB default everything it protects has.
+     */
+    bodyInspectionLimitBytes(resourceType) {
+        return this.#bodyInspectionLimits.bytesFor(resourceType);
     }
     /**
      * Decide what happens to one request.

package/docs/services/apigatewayv2/README.md

@@ -666,8 +666,146 @@ route configured that way is served unthrottled.
 `GetStages` answers with the settings a stage was created with. `AWS::ApiGatewayV2::Stage` deploys
 both properties as well (see [CloudFormation](#cloudformation)). The three members of `RouteSettings`
 that say nothing about throttling, `DetailedMetricsEnabled`, `LoggingLevel` and `DataTraceEnabled`,
-are refused by `CreateStage`. A template carrying one deploys, and the member it named is recorded on
-`stack.ignoredProperties`.
+are refused by `CreateStage`. They are execution logging, which is a different log from the one
+[`AccessLogSettings` writes](#writing-a-stages-access-log). A template carrying one deploys, and the
+member it named is recorded on `stack.ignoredProperties`.
+
+## Writing a stage's access log
+
+`AccessLogSettings` sends one line per request to a CloudWatch Logs log group. `DestinationArn` names
+the group and `Format` is the line, with `$context` variables substituted from the request that
+produced it.
+
+The line is written whether or not an integration ran. A request the stage throttle refused, one a
+Lambda authorizer denied, and one with no identity source header all reach the log group, and for
+those the access log is the only record of the request.
+
+```typescript sim-apigatewayv2-access-log
+/**
+ * Recording a simulated HTTP API stage's access log, including a request the
+ * stage's throttle refused.
+ */
+
+import {
+  CreateApiCommand,
+  CreateIntegrationCommand,
+  CreateRouteCommand,
+  CreateStageCommand,
+} from "@aws-sdk/client-apigatewayv2";
+import {
+  CreateLogGroupCommand,
+  FilterLogEventsCommand,
+} from "@aws-sdk/client-cloudwatch-logs";
+import {
+  AddPermissionCommand,
+  CreateFunctionCommand,
+} from "@aws-sdk/client-lambda";
+
+import { SimAws } from "@kensio/yulin";
+import { makeLambdaZipFileInput } from "@kensio/yulin/lambda";
+import { serveSimAws } from "@kensio/yulin/serve";
+
+const simAws = new SimAws();
+const logGroupName = "/aws/vendedlogs/user-api";
+
+await simAws.logs().createLogGroup(new CreateLogGroupCommand({ logGroupName }));
+
+const { FunctionArn } = await simAws.lambda().createFunction(
+  new CreateFunctionCommand({
+    FunctionName: "users",
+    Role: "arn:aws:iam::111111111111:role/UsersRole",
+    Code: {
+      ZipFile: makeLambdaZipFileInput(() => ({
+        statusCode: 200,
+        headers: { "content-type": "text/plain" },
+        body: "ok",
+      })),
+    },
+  }),
+);
+
+const apiGateway = simAws.apiGatewayV2();
+const { ApiId, ApiEndpoint } = await apiGateway.createApi(
+  new CreateApiCommand({ Name: "users", ProtocolType: "HTTP" }),
+);
+
+const { IntegrationId } = await apiGateway.createIntegration(
+  new CreateIntegrationCommand({
+    ApiId,
+    IntegrationType: "AWS_PROXY",
+    IntegrationUri: FunctionArn,
+    PayloadFormatVersion: "2.0",
+  }),
+);
+
+await apiGateway.createRoute(
+  new CreateRouteCommand({
+    ApiId,
+    RouteKey: "GET /user/profile",
+    Target: `integrations/${IntegrationId}`,
+  }),
+);
+
+await apiGateway.createStage(
+  new CreateStageCommand({
+    ApiId,
+    StageName: "$default",
+    AutoDeploy: true,
+    DefaultRouteSettings: { ThrottlingRateLimit: 1, ThrottlingBurstLimit: 1 },
+    AccessLogSettings: {
+      DestinationArn: `arn:aws:logs:us-east-1:888888888888:log-group:${logGroupName}:*`,
+      Format:
+        "$context.httpMethod $context.path $context.status " +
+        "$context.error.message",
+    },
+  }),
+);
+
+await simAws.lambda().addPermission(
+  new AddPermissionCommand({
+    FunctionName: "users",
+    StatementId: "api-gateway-invoke",
+    Action: "lambda:InvokeFunction",
+    Principal: "apigateway.amazonaws.com",
+    SourceArn: `arn:aws:execute-api:us-east-1:888888888888:${ApiId}/*/*`,
+  }),
+);
+
+const srv = await serveSimAws({ simAws });
+simAws.clock().freeze();
+
+const profile = srv.localUrl(`${ApiEndpoint}/user/profile`);
+await fetch(profile);
+await fetch(profile);
+
+const { events } = await simAws
+  .logs()
+  .filterLogEvents(new FilterLogEventsCommand({ logGroupName }));
+
+const lines = events ?? [];
+
+for (const event of lines) {
+  console.log(event.message);
+}
+
+await srv.close();
+```
+
+The served request and the throttled one are both there. A variable with no value renders as a dash,
+which is what `$context.error.message` does for the request the integration answered:
+
+```text
+GET /user/profile 200 -
+GET /user/profile 429 Too Many Requests
+```
+
+The lines go to the log group and nowhere else. An API answering a few hundred requests in one test
+file would otherwise bury the suite's own output, so nothing here is forwarded to the console the way
+a [Lambda handler's output](https://yulinsim.dev/services/lambda/#capturing-handler-output) is.
+
+A `DestinationArn` naming a log group nothing has created yet is written to anyway, and the group is
+made by the first line. `Format` is copied through apart from its `$context` references, so a JSON
+format string arrives as JSON.
 
 ## Protecting a route with a Cognito user pool
 
@@ -2287,7 +2425,7 @@ parts behaves differently to the template. The simulated properties are:
 - `Integration`: `ApiId`, `IntegrationType`, `IntegrationUri`, `PayloadFormatVersion`, `Description`
 - `Route`: `ApiId`, `RouteKey`, `Target`, `AuthorizationType`, `AuthorizerId`, `AuthorizationScopes`
 - `Stage`: `ApiId`, `StageName`, `AutoDeploy`, `StageVariables`, `Description`,
-  `DefaultRouteSettings`, `RouteSettings`
+  `DefaultRouteSettings`, `RouteSettings`, `AccessLogSettings`
 
 CDK's `HttpIamAuthorizer` deploys too. It emits no `AWS::ApiGatewayV2::Authorizer` and no
 `AuthorizerId`, only `AuthorizationType: "AWS_IAM"` on the `Route`, and the deployed route then
@@ -2436,6 +2574,9 @@ the simulation without being given one. See the
   under their own path segment, including stage variables
 - `DefaultRouteSettings` and `RouteSettings` throttling, with a token bucket per route refilling
   against the simulated clock and a 429 for the requests past it
+- `AccessLogSettings`, writing one line per request to the log group `DestinationArn` names, with the
+  `Format` string's `$context` variables substituted, including for a request the throttle or an
+  authorizer refused before any integration ran
 - Serving the generated endpoint through `serveSimAws`, invoking the integrated function with a
   payload format 2.0 event and turning its result back into an HTTP response
 - The invoke permission of an integration's function and of an authorizer's, each evaluated against
@@ -2474,9 +2615,24 @@ Current documented limitations:
 - Deployments are outside the simulation, so `CreateStage` requires `AutoDeploy: true`. A stage
   without it serves whichever Deployment it was given, which on real AWS is nothing until one is
   created.
-- `AccessLogSettings` on a stage is refused, as is any other option `CreateStage` takes and this one
-  lacks. `RouteSettings` and `DefaultRouteSettings` are taken, and only their throttling members are
-  read. `DetailedMetricsEnabled`, `LoggingLevel` and `DataTraceEnabled` are refused by name.
+- Any option `CreateStage` takes and this one lacks is refused. `RouteSettings` and
+  `DefaultRouteSettings` are taken, and only their throttling members are read.
+  `DetailedMetricsEnabled`, `LoggingLevel` and `DataTraceEnabled` are refused by name. Those three
+  are execution logging, which is a different log from the access log and is not simulated.
+- An access log `DestinationArn` has to name a CloudWatch Logs log group. A Kinesis Data Firehose
+  delivery stream, which a REST API stage may name, is refused.
+- The access log variables carrying a value are `accountId`, `apiId`, `domainName`, `domainPrefix`,
+  `stage`, `routeKey`, `httpMethod`, `path`, `protocol`, `requestId`, `extendedRequestId`,
+  `requestTime`, `requestTimeEpoch`, `status`, `responseLength`, `responseLatency`,
+  `identity.sourceIp`, `identity.userAgent`, `integrationStatus`, `integrationLatency`,
+  `integrationErrorMessage`, `authorizer.error`, `error.message`, `error.messageString`,
+  `customDomain.basePathMatched`, the `integration.*` aliases, and `authorizer.claims.<property>` and
+  `authorizer.<property>` from the route's authorizer. Anything else AWS documents renders as a dash.
+- `responseLatency` and `integrationLatency` are simulated milliseconds, so a test holding the clock
+  still logs zero rather than however long the process took.
+- The access log stream is named for the hour it was written in, dated from the simulation's clock.
+  Real API Gateway appends an identifier this simulation has no counterpart for, so a test should
+  filter the log group rather than name the stream.
 - `AWS_PROXY` is the only integration type, and its URI must name a Lambda function ARN, written
   either as that ARN or as the
   `arn:aws:apigateway:<region>:lambda:path/2015-03-31/functions/<function-arn>/invocations` form.

package/docs/services/wafv2/README.md

@@ -173,9 +173,22 @@ resource, and `CreateWebACL` here refuses it too.
 Matching is case sensitive, as it is on AWS. A rule that means to ignore case says so with a
 `LOWERCASE` transformation and a lower case search string.
 
-WAF stops reading a body, a header set or a cookie set at 8 KB. The rule's `OversizeHandling` says
-what content past that point counts as. `MATCH` and `NO_MATCH` settle the statement without looking,
-and `CONTINUE` inspects as much as WAF would have read.
+WAF stops reading a header set or a cookie set at 8 KB. A body runs to 16 KB, the figure
+CloudFront, API Gateway and Cognito all send for inspection, and a web ACL raises it to 32, 48 or 64
+KB with `AssociationConfig`:
+
+```typescript
+AssociationConfig: {
+  RequestBody: {
+    CLOUDFRONT: { DefaultSizeInspectionLimit: "KB_64" },
+  },
+},
+```
+
+The key is the resource type the raised limit applies to, and `CLOUDFRONT`, `API_GATEWAY` and
+`COGNITO_USER_POOL` are the three a web ACL goes in front of here. The rule's `OversizeHandling`
+says what content past the limit counts as. `MATCH` and `NO_MATCH` settle the statement without
+looking, and `CONTINUE` inspects as much as WAF would have read.
 
 ## Rate limiting
 
@@ -1363,8 +1376,9 @@ fields to match. The `Captcha` and `Challenge` actions are refused, along with t
 `ChallengeConfig` and `TokenDomains` that configure them, because a browser has to answer them.
 
 Tags, logging, sampled requests and CloudWatch metrics for a web ACL are not simulated.
-`AssociationConfig`, `DataProtectionConfig`, `OnSourceDDoSProtectionConfig` and `ApplicationConfig`
-are refused for the same reason, each naming what it would have configured.
+`DataProtectionConfig`, `OnSourceDDoSProtectionConfig` and `ApplicationConfig` are refused for the
+same reason, each naming what it would have configured. An `AssociationConfig` naming a resource
+type this simulation has no association for is refused too.
 
 ## Supported operations
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.10",
+  "version": "1.21.12",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",