@kensio/yulin 1.21.9 → 1.21.11

package/dist/service/lambda/event-source/poll/sim-lambda-stream-bisect.js

@@ -0,0 +1,79 @@
+/**
+ * How much of a failing batch the next delivery may carry.
+ *
+ * A mapping asked to bisect halves a batch its function threw on, and halves
+ * again on each further error, until a failing batch holds one record. That is
+ * how the record that broke the batch ends up delivered on its own, and how the
+ * records beside it get through.
+ *
+ * A split is progress rather than another attempt at the same work, so it puts
+ * the retry count back to the start. Without that the simulator's own cap of
+ * five attempts would discard a batch of a hundred long before it was down to
+ * one record. A batch halves at every step, so the splitting ends on its own,
+ * and the single record it ends on is then counted and discarded as any failing
+ * batch is.
+ *
+ * Two numbers say what the next read may take. The half is how many records a
+ * delivery may carry, and the remainder is how many records of the batch being
+ * split are still to get through. Reading the lower of the two is what keeps a
+ * record written while the splitting is going on out of it: the halves are the
+ * batch that failed, and a record that arrived afterwards belongs to the batch
+ * after it. The mapping's own batch size comes back once the whole of the split
+ * batch is through.
+ */
+export class SimLambdaStreamBisect {
+    enabled;
+    #half;
+    #remaining = 0;
+    constructor(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * How many records the next read may take, within the mapping's batch size.
+     */
+    sizeWithin(batchSize) {
+        const half = this.#half;
+        return half === undefined
+            ? batchSize
+            : Math.min(half, this.#remaining, batchSize);
+    }
+    /**
+     * Split a batch the function threw on, answering with whether it split.
+     *
+     * A batch the function reported partial failures on is left alone. Lambda
+     * bisects around an error the handler raised, and a report already says which
+     * record to go back to.
+     */
+    split(outcome) {
+        const count = outcome.records.length;
+        if (!this.enabled || !outcome.functionError || count < 2) {
+            return false;
+        }
+        this.#half = Math.ceil(count / 2);
+        this.#remaining = count;
+        return true;
+    }
+    /**
+     * Take records of the batch being split that the mapping is finished with,
+     * whether the function handled them, they were discarded, or they aged out.
+     *
+     * The whole of the split batch being through is what puts the mapping back on
+     * full batches.
+     */
+    finished(count) {
+        if (this.#half === undefined || count <= 0) {
+            return;
+        }
+        this.#remaining -= count;
+        if (this.#remaining <= 0) {
+            this.reset();
+        }
+    }
+    /**
+     * Read whole batches again.
+     */
+    reset() {
+        this.#half = undefined;
+        this.#remaining = 0;
+    }
+}

package/dist/service/lambda/event-source/poll/sim-lambda-stream-progress-state.d.ts

@@ -2,6 +2,7 @@ import { SimLambdaStreamExpiry } from "./sim-lambda-stream-expiry.js";
 import { SimLambdaStreamFailureDestination } from "./sim-lambda-stream-failure-destination.js";
 import { SimLambdaStreamCursor } from "./sim-lambda-stream-cursor.js";
 import { SimLambdaStreamRetry } from "./sim-lambda-stream-retry.js";
+import { SimLambdaStreamBisect } from "./sim-lambda-stream-bisect.js";
 import type { BackgroundScheduler, BackgroundTask } from "../../../../util/background/background.js";
 import type { SimLambdaEventSourceMapping } from "../sim-lambda-event-source-mapping.js";
 import type { SimLambdaEventSourceStreamProgressBatch } from "../stream/sim-lambda-event-source-streams.js";
@@ -16,6 +17,7 @@ export declare class SimLambdaStreamProgressState {
     readonly failures: SimLambdaStreamFailureDestination;
     readonly cursor: SimLambdaStreamCursor;
     readonly retry: SimLambdaStreamRetry;
+    readonly bisect: SimLambdaStreamBisect;
     constructor(properties: SimLambdaStreamProgressProperties);
     handled(batch: SimLambdaEventSourceStreamProgressBatch): void;
 }

package/dist/service/lambda/event-source/poll/sim-lambda-stream-progress-state.js

@@ -3,6 +3,7 @@ import { SimLambdaStreamBatchAge } from "./sim-lambda-stream-batch-age.js";
 import { SimLambdaStreamFailureDestination } from "./sim-lambda-stream-failure-destination.js";
 import { SimLambdaStreamCursor } from "./sim-lambda-stream-cursor.js";
 import { SimLambdaStreamRetry } from "./sim-lambda-stream-retry.js";
+import { SimLambdaStreamBisect } from "./sim-lambda-stream-bisect.js";
 import { PollSchedule } from "../../../../util/background/poll-schedule.js";
 import { assertDefined } from "../../../../util/type-guard/defined.js";
 /** Own the per-shard retry state and its expiry and destination collaborators. */
@@ -11,6 +12,7 @@ export class SimLambdaStreamProgressState {
     failures;
     cursor;
     retry;
+    bisect;
     constructor(properties) {
         const { mapping, background } = properties;
         this.failures = new SimLambdaStreamFailureDestination(mapping);
@@ -22,6 +24,7 @@ export class SimLambdaStreamProgressState {
         assertDefined(streamRetryLimits, "stream mapping retry limits");
         this.cursor = new SimLambdaStreamCursor(start, new PollSchedule(properties));
         this.retry = new SimLambdaStreamRetry(streamRetryLimits, background);
+        this.bisect = new SimLambdaStreamBisect(streamRetryLimits.bisectBatchOnFunctionError);
         this.expiry = new SimLambdaStreamExpiry({
             age: new SimLambdaStreamBatchAge(streamRetryLimits, background),
             cursor: this.cursor,

package/dist/service/lambda/event-source/poll/sim-lambda-stream-progress.d.ts

@@ -15,6 +15,11 @@ export declare class SimLambdaStreamProgress {
      * Where the next read starts.
      */
     get position(): SimLambdaEventSourceStreamPosition;
+    /**
+     * How many records the next read may take, which is the mapping's batch size
+     * until a batch is being bisected.
+     */
+    batchSizeWithin(batchSize: number): number;
     /**
      * Take a read that came back with nothing.
      *
@@ -23,9 +28,17 @@ export declare class SimLambdaStreamProgress {
      * than working out a new one each time.
      */
     caughtUp(batch: SimLambdaEventSourceStreamProgressBatch): void;
+    /**
+     * Drop the records at the front of a batch that are too old to hand over,
+     * answering with where the live ones start.
+     *
+     * Records that aged out are as finished with as records the function took, so
+     * a batch being split counts them off its remainder too.
+     */
     before(records: readonly SimLambdaStreamRecordTime[], batch: SimLambdaEventSourceStreamProgressBatch, simFunction: SimLambdaFunction): Promise<number>;
     /**
-     * Take what became of a batch: move past it, or wait and try it again.
+     * Take what became of a batch: move past it, split it, or wait and try it
+     * again.
      */
     after(outcome: SimLambdaStreamBatchOutcome, batch: SimLambdaEventSourceStreamProgressBatch, simFunction: SimLambdaFunction): Promise<void>;
     /**

package/dist/service/lambda/event-source/poll/sim-lambda-stream-progress.js

@@ -17,6 +17,13 @@ export class SimLambdaStreamProgress {
     get position() {
         return this.state.cursor.position;
     }
+    /**
+     * How many records the next read may take, which is the mapping's batch size
+     * until a batch is being bisected.
+     */
+    batchSizeWithin(batchSize) {
+        return this.state.bisect.sizeWithin(batchSize);
+    }
     /**
      * Take a read that came back with nothing.
      *
@@ -27,21 +34,36 @@ export class SimLambdaStreamProgress {
     caughtUp(batch) {
         this.state.cursor.advanceTo(batch.next);
     }
+    /**
+     * Drop the records at the front of a batch that are too old to hand over,
+     * answering with where the live ones start.
+     *
+     * Records that aged out are as finished with as records the function took, so
+     * a batch being split counts them off its remainder too.
+     */
     async before(records, batch, simFunction) {
-        return await this.state.expiry.before(records, batch, simFunction);
+        const firstLive = await this.state.expiry.before(records, batch, simFunction);
+        this.state.bisect.finished(firstLive);
+        return firstLive;
     }
     /**
-     * Take what became of a batch: move past it, or wait and try it again.
+     * Take what became of a batch: move past it, split it, or wait and try it
+     * again.
      */
     async after(outcome, batch, simFunction) {
         this.state.failures.invoked(outcome);
         if (outcome.isHandled) {
+            this.state.bisect.finished(outcome.records.length);
             this.handled(batch);
             return;
         }
+        if (this.state.bisect.split(outcome)) {
+            this.state.retry.reset();
+        }
         const again = this.state.retry.after(outcome, this.position);
         const notification = this.state.failures.deliver(this.state.retry.discarded, batch, simFunction);
         if (again === undefined) {
+            this.state.bisect.finished(outcome.records.length);
             this.handled(batch);
         }
         else {

package/dist/service/lambda/event-source/sim-lambda-event-source-retry-limits.d.ts

@@ -1,12 +1,13 @@
 import { type SimLambdaEventSourceRetryLimitsInput, SimLambdaStreamRetryLimits } from "./sim-lambda-stream-retry-limits.js";
 /**
- * Whether the event source a mapping names has failed-batch limits at all.
+ * Whether the event source a mapping names decides for itself what becomes of
+ * a failed batch.
  *
- * A stream does: a record stays on the stream whatever the function makes of
- * it, so the mapping is the only thing that decides when to stop trying. A
- * queue does not, because a message the function never handles goes to the
- * queue's own redrive policy, and real Lambda refuses a request that names
- * either limit for one.
+ * A stream leaves it to the mapping: a record stays on the stream whatever the
+ * function makes of it, so the mapping is the only thing that decides when to
+ * stop trying and whether to split the batch first. A queue does not, because a
+ * message the function never handles goes to the queue's own redrive policy,
+ * and real Lambda refuses a request that names any of the three for one.
  */
 export interface SimLambdaEventSourceRetryLimitRules {
     /**
@@ -23,7 +24,7 @@ export declare class SimLambdaNoRetryLimits implements SimLambdaEventSourceRetry
     private readonly insteadDescription;
     constructor(sourceDescription: string, insteadDescription: string);
     /**
-     * Refuse both limits, since this source is not the one counting.
+     * Refuse all three, since this source is not the one counting.
      */
     limitsIn(input: SimLambdaEventSourceRetryLimitsInput): SimLambdaStreamRetryLimits | undefined;
 }

package/dist/service/lambda/event-source/sim-lambda-event-source-retry-limits.js

@@ -11,7 +11,7 @@ export class SimLambdaNoRetryLimits {
         this.insteadDescription = insteadDescription;
     }
     /**
-     * Refuse both limits, since this source is not the one counting.
+     * Refuse all three, since this source is not the one counting.
      */
     limitsIn(input) {
         const named = namedLimit(input);
@@ -40,7 +40,10 @@ function namedLimit(input) {
     if (input.maximumRetryAttempts !== undefined) {
         return "MaximumRetryAttempts";
     }
-    return input.maximumRecordAgeInSeconds === undefined
+    if (input.maximumRecordAgeInSeconds !== undefined) {
+        return "MaximumRecordAgeInSeconds";
+    }
+    return input.bisectBatchOnFunctionError === undefined
         ? undefined
-        : "MaximumRecordAgeInSeconds";
+        : "BisectBatchOnFunctionError";
 }

package/dist/service/lambda/event-source/sim-lambda-stream-retry-limits.d.ts

@@ -9,6 +9,7 @@
 export interface SimLambdaEventSourceRetryLimitsInput {
     readonly maximumRetryAttempts?: number | undefined;
     readonly maximumRecordAgeInSeconds?: number | undefined;
+    readonly bisectBatchOnFunctionError?: boolean | undefined;
 }
 /**
  * The failed-batch limits a mapping reports back, as Lambda names them.
@@ -16,22 +17,29 @@ export interface SimLambdaEventSourceRetryLimitsInput {
 export interface SimLambdaStreamRetryLimitsConfiguration {
     readonly MaximumRetryAttempts: number;
     readonly MaximumRecordAgeInSeconds: number;
+    readonly BisectBatchOnFunctionError: boolean;
 }
 /**
- * When a stream mapping stops delivering a batch its function keeps failing.
+ * What a stream mapping does with a batch its function keeps failing.
  *
- * The two limits are one thing rather than two, because they end the same
- * lifecycle: a record leaves the mapping when it has had its retries or when it
- * is too old to be worth another, whichever comes first. Both are held as
- * Lambda states them, with `-1` for no limit, so a Get or a List reports back
- * exactly what was asked for.
+ * The three settings are one thing rather than three, because they run the same
+ * lifecycle. A failing batch is split around the record that broke it where the
+ * mapping was asked to bisect, and a record leaves the mapping when it has had
+ * its retries or when it is too old to be worth another, whichever comes first.
+ * The limits are held as Lambda states them, with `-1` for no limit, so a Get
+ * or a List reports back exactly what was asked for.
  */
 export declare class SimLambdaStreamRetryLimits {
     readonly maximumRetryAttempts: number;
     readonly maximumRecordAgeInSeconds: number;
+    /**
+     * Whether a batch the function threw on is split in half and delivered again
+     * as two batches.
+     */
+    readonly bisectBatchOnFunctionError: boolean;
     constructor(input?: SimLambdaEventSourceRetryLimitsInput);
     /**
-     * The two limits as a Get, a List or a create response reports them.
+     * The three settings as a Get, a List or a create response reports them.
      */
     configuration(): SimLambdaStreamRetryLimitsConfiguration;
     /**

package/dist/service/lambda/event-source/sim-lambda-stream-retry-limits.js

@@ -23,17 +23,23 @@ const maximumRecordAgeLimit = 604_800;
 const defaultAttemptLimit = 5;
 const millisecondsPerSecond = 1000;
 /**
- * When a stream mapping stops delivering a batch its function keeps failing.
+ * What a stream mapping does with a batch its function keeps failing.
  *
- * The two limits are one thing rather than two, because they end the same
- * lifecycle: a record leaves the mapping when it has had its retries or when it
- * is too old to be worth another, whichever comes first. Both are held as
- * Lambda states them, with `-1` for no limit, so a Get or a List reports back
- * exactly what was asked for.
+ * The three settings are one thing rather than three, because they run the same
+ * lifecycle. A failing batch is split around the record that broke it where the
+ * mapping was asked to bisect, and a record leaves the mapping when it has had
+ * its retries or when it is too old to be worth another, whichever comes first.
+ * The limits are held as Lambda states them, with `-1` for no limit, so a Get
+ * or a List reports back exactly what was asked for.
  */
 export class SimLambdaStreamRetryLimits {
     maximumRetryAttempts;
     maximumRecordAgeInSeconds;
+    /**
+     * Whether a batch the function threw on is split in half and delivered again
+     * as two batches.
+     */
+    bisectBatchOnFunctionError;
     constructor(input = {}) {
         this.maximumRetryAttempts = checkedLimit({
             value: input.maximumRetryAttempts,
@@ -47,14 +53,16 @@ export class SimLambdaStreamRetryLimits {
             maximum: maximumRecordAgeLimit,
             unit: "seconds",
         });
+        this.bisectBatchOnFunctionError = input.bisectBatchOnFunctionError ?? false;
     }
     /**
-     * The two limits as a Get, a List or a create response reports them.
+     * The three settings as a Get, a List or a create response reports them.
      */
     configuration() {
         return {
             MaximumRetryAttempts: this.maximumRetryAttempts,
             MaximumRecordAgeInSeconds: this.maximumRecordAgeInSeconds,
+            BisectBatchOnFunctionError: this.bisectBatchOnFunctionError,
         };
     }
     /**

package/dist/service/logs/group/sim-logs-arn.d.ts

@@ -33,3 +33,18 @@ export declare function simLogsAnyLogGroupArn(scope: SimAwsAccountRegionScope):
  * The ARN of a log stream inside a log group.
  */
 export declare function simLogsLogStreamArn(scope: SimAwsAccountRegionScope, logGroupName: string, logStreamName: string): string;
+/**
+ * The account, region and group name a log group ARN carries, or undefined
+ * for a string that is not one.
+ *
+ * Both forms are read. `DescribeLogGroups` reports `logGroupArn` without a
+ * trailing wildcard, while the `arn` field and CDK's `logGroup.logGroupArn`
+ * both end in `:*`, and a template naming either means the same group. A log
+ * group name cannot contain a colon, so what follows `log-group:` is the name
+ * up to an optional trailing `:*`.
+ */
+export declare function simLogsParsedLogGroupArn(arn: string): {
+    readonly accountId: string;
+    readonly regionName: string;
+    readonly logGroupName: string;
+} | undefined;

package/dist/service/logs/group/sim-logs-arn.js

@@ -42,3 +42,36 @@ export function simLogsAnyLogGroupArn(scope) {
 export function simLogsLogStreamArn(scope, logGroupName, logStreamName) {
     return `${simLogsLogGroupArn(scope, logGroupName)}:log-stream:${logStreamName}`;
 }
+/**
+ * The account, region and group name a log group ARN carries, or undefined
+ * for a string that is not one.
+ *
+ * Both forms are read. `DescribeLogGroups` reports `logGroupArn` without a
+ * trailing wildcard, while the `arn` field and CDK's `logGroup.logGroupArn`
+ * both end in `:*`, and a template naming either means the same group. A log
+ * group name cannot contain a colon, so what follows `log-group:` is the name
+ * up to an optional trailing `:*`.
+ */
+export function simLogsParsedLogGroupArn(arn) {
+    const [prefix, partition, service, region, account, resourceType, ...rest] = arn.split(":");
+    if (prefix !== "arn" ||
+        service !== "logs" ||
+        resourceType !== "log-group" ||
+        !isPresent(partition) ||
+        !isPresent(region) ||
+        !isPresent(account)) {
+        return undefined;
+    }
+    const [logGroupName, wildcard, ...extra] = rest;
+    if (logGroupName === undefined ||
+        logGroupName.length === 0 ||
+        extra.length > 0 ||
+        (wildcard !== undefined && wildcard !== "*")) {
+        return undefined;
+    }
+    return { accountId: account, regionName: region, logGroupName };
+}
+/** Whether an ARN component was written at all. */
+function isPresent(component) {
+    return component !== undefined && component.length > 0;
+}

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.