@kensio/yulin 1.21.10 → 1.21.11

package/dist/service/apigatewayv2/serve/sim-http-api-may-invoke.d.ts

@@ -0,0 +1,19 @@
+import type { SimHttpApiMatch } from "../api/sim-http-api-match.js";
+import type { SimHttpApi } from "../api/sim-http-api.js";
+import type { SimHttpApiFunctionTarget } from "./sim-http-api-function-target.js";
+interface SimHttpApiMayInvokeInput {
+    readonly api: SimHttpApi;
+    readonly match: SimHttpApiMatch;
+    readonly request: Request;
+}
+/**
+ * Whether the API lacks permission to invoke a function behind one of its
+ * routes.
+ *
+ * The route the request matched is supplied as the source ARN, so a permission
+ * granted for one route does not open another. This is the API's own question
+ * rather than the client's, whose was already answered by the route's
+ * authorization.
+ */
+export declare function simHttpApiMayNotInvoke(input: SimHttpApiMayInvokeInput, target: SimHttpApiFunctionTarget): boolean;
+export {};

package/dist/service/apigatewayv2/serve/sim-http-api-may-invoke.js

@@ -0,0 +1,19 @@
+import { SimHttpApiExecuteApiArn } from "../api/sim-http-api-execute-api-arn.js";
+import { SimHttpApiInvokeAuthorizer } from "./auth/sim-http-api-invoke-authorizer.js";
+/**
+ * Whether the API lacks permission to invoke a function behind one of its
+ * routes.
+ *
+ * The route the request matched is supplied as the source ARN, so a permission
+ * granted for one route does not open another. This is the API's own question
+ * rather than the client's, whose was already answered by the route's
+ * authorization.
+ */
+export function simHttpApiMayNotInvoke(input, target) {
+    const { api, match, request } = input;
+    return new SimHttpApiInvokeAuthorizer({ iam: target.iam }).authorize({
+        api,
+        target,
+        sourceArn: SimHttpApiExecuteApiArn.forMatchedRoute(api, match, request.method),
+    }).isDenied;
+}

package/dist/service/apigatewayv2/serve/sim-http-api-serve-pipeline.d.ts

@@ -0,0 +1,27 @@
+import type { SimAwsServiceRequest } from "../../../serve/controller/sim-service-controller.js";
+import type { SimApiGatewayV2Router } from "./sim-api-gateway-v2-router.js";
+import type { SimHttpApiServed, SimHttpApiServedRequest } from "./sim-http-api-served.js";
+interface SimHttpApiServePipelineProperties {
+    readonly router: SimApiGatewayV2Router;
+}
+/**
+ * Takes one request the resolver matched to a stage through the three things
+ * that stand between it and a response.
+ *
+ * The stage's throttle is asked first. A flood of requests to a throttled
+ * route invokes neither the authorizer nor the integration, and AWS publishes
+ * no order between the two. The client's own authorization comes next, so a
+ * request with no credentials is refused whether or not the integration
+ * behind the route would work. What each step decided is carried out with the
+ * response, because the stage's access log describes the request afterwards
+ * and a refused request is the case that log exists for.
+ */
+export declare class SimHttpApiServePipeline {
+    #private;
+    constructor(properties: SimHttpApiServePipelineProperties);
+    /**
+     * Serve one request, and report what each step of serving it decided.
+     */
+    run(serving: SimHttpApiServedRequest, serviceRequest: SimAwsServiceRequest): Promise<SimHttpApiServed>;
+}
+export {};

package/dist/service/apigatewayv2/serve/sim-http-api-serve-pipeline.js

@@ -0,0 +1,75 @@
+import { SimHttpApiRouteAuthorizer } from "./auth/sim-http-api-route-authorizer.js";
+import { SimApiGatewayV2ErrorResponse } from "./sim-api-gateway-v2-error-response.js";
+import { SimHttpApiIntegrationInvocation } from "./sim-http-api-integration-invocation.js";
+import { SimHttpApiRefusalResponse } from "./sim-http-api-refusal-response.js";
+/**
+ * Takes one request the resolver matched to a stage through the three things
+ * that stand between it and a response.
+ *
+ * The stage's throttle is asked first. A flood of requests to a throttled
+ * route invokes neither the authorizer nor the integration, and AWS publishes
+ * no order between the two. The client's own authorization comes next, so a
+ * request with no credentials is refused whether or not the integration
+ * behind the route would work. What each step decided is carried out with the
+ * response, because the stage's access log describes the request afterwards
+ * and a refused request is the case that log exists for.
+ */
+export class SimHttpApiServePipeline {
+    #router;
+    #routeAuthorizer;
+    #integration;
+    #errorResponse = new SimApiGatewayV2ErrorResponse();
+    #refusalResponse = new SimHttpApiRefusalResponse();
+    constructor(properties) {
+        this.#router = properties.router;
+        // The clock is the router's, so the event timestamps and the token expiry
+        // checks belong to the same simulation.
+        this.#routeAuthorizer = new SimHttpApiRouteAuthorizer({
+            clock: properties.router.simAws,
+            functions: properties.router,
+        });
+        this.#integration = new SimHttpApiIntegrationInvocation({
+            router: properties.router,
+            clock: properties.router.simAws,
+        });
+    }
+    /**
+     * Serve one request, and report what each step of serving it decided.
+     */
+    async run(serving, serviceRequest) {
+        const { request } = serviceRequest;
+        const { api, match, domainName, rawPath, requestId } = serving;
+        // What the authorizer's event and the integration's event both describe.
+        const asked = { api, match, request, domainName, rawPath, requestId };
+        // The throttle takes a token from the route's bucket, and a route whose
+        // bucket is empty is answered here. Neither the authorizer nor the
+        // integration runs for it, and the stage's access log is the only place
+        // the refusal is recorded.
+        if (!match.stage.admits(match.route.routeKey)) {
+            return { response: this.#errorResponse.tooManyRequests() };
+        }
+        const authorization = await this.#routeAuthorizer.authorize({
+            ...asked,
+            caller: serviceRequest.caller,
+            iam: this.#router.iamFor(api),
+        });
+        // A refusal is carried out alongside its response, because the access log
+        // line reports what the authorizer said. An unmet route scope, an
+        // `AWS_IAM` route IAM did not allow, and a Lambda authorizer that said no
+        // all arrive here.
+        if (!authorization.admitted) {
+            return {
+                response: this.#refusalResponse.build(authorization),
+                authorization,
+            };
+        }
+        const clock = this.#router.simAws;
+        const invokedAt = clock.now().getTime();
+        const outcome = await this.#integration.invoke({ ...asked, authorization });
+        const integration = {
+            ...outcome,
+            integrationLatency: clock.now().getTime() - invokedAt,
+        };
+        return { response: integration.response, authorization, integration };
+    }
+}

package/dist/service/apigatewayv2/serve/sim-http-api-served.d.ts

@@ -0,0 +1,22 @@
+import type { SimHttpApiAuthorization } from "../api/authorizer/sim-http-api-authorization.js";
+import type { SimHttpApiIntegrationOutcome } from "./sim-http-api-integration-outcome.js";
+import type { SimHttpApiServing } from "./sim-http-api-serving.js";
+/**
+ * What one request through the endpoint produced, gathered as it happened so
+ * that the stage's access log can describe it afterwards.
+ *
+ * A request the stage's throttle refused has neither an authorization nor an
+ * integration, and one an authorizer refused has an authorization alone.
+ */
+export interface SimHttpApiServed {
+    readonly response: Response;
+    readonly authorization?: SimHttpApiAuthorization | undefined;
+    readonly integration?: SimHttpApiIntegrationOutcome | undefined;
+}
+/**
+ * A serving the controller has stamped with the id this request is logged and
+ * reported under, which every path below it then names.
+ */
+export interface SimHttpApiServedRequest extends SimHttpApiServing {
+    readonly requestId: string;
+}

package/dist/service/apigatewayv2/serve/sim-http-api-served.js

@@ -0,0 +1 @@
+export {};

package/dist/service/apigatewayv2/serve/sim-http-api-serving.d.ts

@@ -21,6 +21,18 @@ export interface SimHttpApiServing {
      * carrying.
      */
     readonly rawPath: string;
+    /**
+     * The id this request is logged and reported under, settled by the
+     * controller before anything runs. The resolver leaves it out, and the
+     * controller adds it to the serving it passes on.
+     */
+    readonly requestId?: string | undefined;
+    /**
+     * The API mapping base path this request matched, for a request that
+     * reached a custom domain. It is the empty string for a mapping serving the
+     * root of its domain, and absent for the generated endpoint.
+     */
+    readonly basePathMatched?: string | undefined;
 }
 /**
  * What an HTTP API endpoint decided about one request before any of it ran.

package/dist/service/apigatewayv2/serve/sim-http-api-serving.js

@@ -107,6 +107,7 @@ export class SimHttpApiServingResolver {
                 match,
                 domainName: domain.domainName,
                 rawPath: mapping.apiMappingKey.remainingPath(path),
+                basePathMatched: mapping.apiMappingKey.value,
             },
         };
     }

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.

package/package.json

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