@kensio/yulin 1.21.7 → 1.21.9

package/docs/services/apigateway/README.md

@@ -1,16 +1,11 @@
 # Simulated API Gateway REST APIs
 
-Yulin includes a simulated API Gateway v1 service, reachable as `simAws.apiGateway()`. It covers the
-REST API resource tree, the methods declared on it, a Lambda proxy integration behind each method,
-and the deployments and stages that publish them. REST-API-specific types are imported from the
-`@kensio/yulin/apigateway` subpath.
+Yulin simulates API Gateway REST APIs (the v1 API) with Lambda proxy integrations. Use
+`simAws.apiGateway()` directly or intercept an `APIGatewayClient`. REST API types are available from
+`@kensio/yulin/apigateway`.
 
-This is the v1 service. HTTP APIs are v2, on a separate SDK client, and they are documented under
-[API Gateway HTTP APIs](https://yulinsim.dev/services/apigatewayv2/). The two hold separate state. A REST API created here
-stays out of `simAws.apiGatewayV2()`.
-
-A handler behind a REST API can be tested against a real HTTP request, with no hand-built event to
-keep in step.
+HTTP APIs use the separate `simAws.apiGatewayV2()` service. See
+[API Gateway HTTP APIs](https://yulinsim.dev/services/apigatewayv2/).
 
 ## Creating a REST API
 
@@ -48,13 +43,13 @@ console.log(typeof created.rootResourceId);
 // "string"
 ```
 
-A REST API name identifies nothing. Two APIs in one account and region may share a name, and the id
-is what tells them apart. Hold the id the create returns.
+A REST API name is a label. Two APIs in the same account and region may share a name. Use the ID
+returned by `CreateRestApiCommand` to address the API.
 
 ## Building the path tree
 
-A REST API path is a chain of resources, each holding one segment. `CreateResourceCommand` adds a
-segment under a parent and reports the full path its place in the tree gives it.
+A REST API stores its path as a tree of resources. Each resource holds one segment.
+`CreateResourceCommand` adds a segment below a parent and returns its full path.
 
 ```typescript sim-apigateway-resource-tree
 /**
@@ -103,18 +98,17 @@ console.log(listed.items.map((resource) => resource.path));
 // [ "/", "/orders", "/orders/{orderId}" ]
 ```
 
-A segment is a literal such as `orders`, a path parameter such as `{orderId}`, or a greedy path
-parameter such as `{proxy+}`. A greedy segment matches the rest of the request path. A resource
-holding one therefore takes no children, and adding under it is refused.
+A segment may be literal (`orders`), a path parameter (`{orderId}`), or a greedy path parameter
+(`{proxy+}`). A greedy segment matches the rest of the path and cannot have children.
 
 Deleting a resource deletes everything under it, the way real API Gateway does. The root resource
 stays, because every REST API has one.
 
 ## Methods and their integrations
 
-A method is declared on a resource with `PutMethodCommand`, and what it does with a request goes
-behind it with `PutIntegrationCommand`. Both address the same resource id and HTTP method, since a
-REST API method has no id of its own.
+`PutMethodCommand` declares a method on a resource. `PutIntegrationCommand` connects that method to
+a Lambda function. Both commands use the resource ID and HTTP method because a method has no ID of
+its own.
 
 ```typescript sim-apigateway-method-integration
 /**
@@ -184,18 +178,15 @@ console.log(method.methodIntegration?.uri);
 // echoed back as one line, the way it was configured
 ```
 
-The integration URI is written either as the bare function ARN, which CDK emits, or wrapped in the
-API Gateway invoke path above, which CloudFormation templates and OpenAPI documents emit. Both reach
-the same function, and the string is echoed back as it was configured, the way real API Gateway does.
-A version or alias qualifier on the end of the ARN is kept. An integration built on an alias
-therefore follows that alias.
+The integration URI may be a function ARN or the API Gateway invocation URI shown above. CDK emits
+the first form. CloudFormation templates and OpenAPI documents commonly emit the second. A version
+or alias qualifier is preserved. An integration that names an alias follows that alias.
 
 Deleting a method deletes its integration, because a REST API integration is part of the method.
 
 ## Deployments and stages
 
-A REST API has an invocation URL once a stage exists, and every stage is the first path segment of
-that URL. An HTTP API can serve a `$default` stage at the root, and a REST API always carries the
+A REST API gets an invocation URL when it has a stage. The stage name is always the first path
 segment.
 
 ```typescript sim-apigateway-deploy-stage
@@ -249,15 +240,13 @@ console.log(restApi?.invokeUrl("prod"));
 `invokeUrl` is a simulator accessor. Real API Gateway reports no endpoint for a REST API and leaves
 callers to build the URL themselves. CDK's `RestApi.urlForPath` builds the same one.
 
-Real API Gateway freezes the resources and methods into a deployment, and an edit made afterwards
-reaches no client until another deployment is created. Here a stage serves the API's current
-resources. A test that edits a method sees the change straight away, with no redeployment in
-between. That is the one place this departs from AWS.
+Stages serve the API's current resources and methods. Changes take effect immediately. AWS freezes
+the configuration in a deployment and requires another deployment before changes become visible.
 
 ## Serving a request
 
-A request to the stage's invoke URL walks the resource tree to a method and invokes that method's
-integration, and the handler's response becomes the HTTP response.
+A request to a stage selects a resource and method, then invokes its integration. The Lambda result
+becomes the HTTP response.
 
 ```typescript sim-apigateway-serve
 /**
@@ -300,14 +289,13 @@ console.log(await response.text());
 await srv.close();
 ```
 
-`simRestApiLambdaProxyFactory` builds the function, the resources, the method, the integration, the
-invoke permission and the deployment in one call. A test about serving wants all of them and is
-about none of them. A test about the commands themselves sends them one at a time.
+`simRestApiLambdaProxyFactory` creates a ready-to-call REST API in one operation. It creates the
+function, resources, method, integration, invoke permission and deployment.
 
 ### The event a handler receives
 
-A REST API sends payload format 1.0. It carries both a single-value and a multi-value map for the
-headers and the query string, and it sends `null` for an empty map where format 2.0 omits the field:
+A REST API sends a payload format 1.0 event. Headers and query parameters appear in both single-value
+and multi-value maps. Empty values use `null`:
 
 | Field                                                      | Empty case |
 | ---------------------------------------------------------- | ---------- |
@@ -319,18 +307,15 @@ headers and the query string, and it sends `null` for an empty map where format
 client asked for, stage segment and all. A handler behind a `{proxy+}` reads `resource` to tell which
 template caught its request.
 
-Each format's handler reads the other format's event wrongly. One function behind both an HTTP API
-and a REST API therefore has to pick a side.
+REST API and HTTP API events have different shapes. A handler shared by both must handle both
+formats explicitly.
 
 ### The response a handler returns
 
-A REST API proxy integration takes one shape. A result carrying a numeric `statusCode` becomes the
-response, and `multiValueHeaders` sends a header more than once. Anything else is a 502 with
-`Internal server error`. That is what real API Gateway answers when it cannot read the integration
-response. Payload format 2.0 is the lenient one, wrapping an unrecognised value in a 200, and a
-handler relying on that behaves differently here for the same reason it does on AWS.
+A REST API proxy result must contain a numeric `statusCode`. Use `multiValueHeaders` to send the
+same header more than once. An invalid result produces a 502 response with `Internal server error`.
 
-### Answers when the request matches nothing
+### Responses before an integration runs
 
 | Case                                          | Answer                             |
 | --------------------------------------------- | ---------------------------------- |
@@ -340,8 +325,8 @@ handler relying on that behaves differently here for the same reason it does on
 | No integration, no function, or no permission | 502 `Internal server error`        |
 | The handler threw                             | 502 `Internal server error`        |
 
-`Missing Authentication Token` is the wording real API Gateway is well known for. It answers a path
-that matched nothing just as much as one that needed credentials.
+API Gateway uses `Missing Authentication Token` for an unmatched path or method, even when the
+request did not require authentication.
 
 ### The invoke permission
 
@@ -467,9 +452,8 @@ is named `ANY`, whatever method the client sent.
 
 Real `CreateStage` carries no method settings. AWS sets them with `UpdateStage` patch operations,
 which are outside this simulation, or from an `AWS::ApiGateway::Stage`. The `methodSettings` input
-above is this simulator's own, so that a test can throttle a stage without a template, and the SDK's
-`CreateStageCommand` declares no such member. `GetStage` reports the settings the way AWS reports
-them.
+above is specific to Yulin and lets a test configure throttling without a template. The SDK's
+`CreateStageCommand` has no such member. `GetStage` reports the settings in the AWS response shape.
 
 ## Authorizing a method
 
@@ -482,8 +466,8 @@ function answers an IAM policy document, evaluated for `execute-api:Invoke` agai
 request being made. Whatever `context` it returns reaches the handler.
 
 A `REQUEST` authorizer sends the whole request to its function (see
-[A REQUEST authorizer](#a-request-authorizer)), so it can identify a caller by several headers
-together or by the query string. It answers the same policy document.
+[A REQUEST authorizer](#a-request-authorizer)). It can identify a caller from several headers or
+query parameters. It answers the same policy document.
 
 ```typescript sim-apigateway-token-authorizer
 /**
@@ -674,9 +658,8 @@ left out.
 | `pathParameters`, `stageVariables`                         | What the resource path captured, and the stage's variables     |
 | `requestContext`                                           | The same block a handler gets, without the `authorizer` member |
 
-The maps are empty objects where the request supplied nothing. An integration event sends `null`
-there, and AWS's own example of the authorizer event sends `{}`, so a function reading
-`event.queryStringParameters.plan` finds nothing rather than throwing.
+The maps are empty objects when the request supplies no values. Integration events use `null` for
+the same fields. AWS's authorizer event examples use `{}`.
 
 ### Answering with a policy
 
@@ -710,8 +693,8 @@ authorizer's own logs, and IAM never sees it.
 ### The context the handler receives
 
 `context` reaches the handler under `requestContext.authorizer`, flattened alongside `principalId`.
-Payload format 2.0 keeps the context in a block of its own, so a handler moved between a REST API and
-an HTTP API reads a different shape.
+Payload format 2.0 keeps the context in its own block. A handler shared with an HTTP API must handle
+both shapes.
 
 An open method has no caller to describe, and leaves `requestContext.authorizer` out of the event
 altogether.
@@ -976,9 +959,8 @@ An admitted caller reaches the handler under `requestContext.identity`.
 | `user`      | The caller's ARN                   |
 | `userArn`   | The caller's ARN                   |
 
-Real API Gateway puts the unique id of the principal in `caller` and `user`, such as `AIDA...` for a
-User. A request carries no such id into the simulation, so the ARN identifying the caller goes in
-every field that can be filled from it.
+Real API Gateway puts the principal's unique ID in `caller` and `user`, such as `AIDA...` for a user.
+The simulation receives only the caller ARN and uses it for each identity field it can populate.
 
 A method of any other authorization type leaves those four `null`, and so does an `AWS_IAM` method
 called by a principal with no ARN behind it. `accessKey`, `apiKey`, `apiKeyId`, `principalOrgId` and
@@ -987,8 +969,8 @@ request itself and are filled for every method.
 
 ## Authorizing a method with a user pool
 
-A `COGNITO_USER_POOLS` authorizer verifies the token itself against the keys the user pools it names
-publish. Nothing is invoked, so there is no function to write and no policy to answer.
+A `COGNITO_USER_POOLS` authorizer verifies the token against the keys published by its user pools.
+It uses no Lambda function or returned policy.
 `CreateAuthorizerCommand` takes the pools as `providerARNs`, and `PutMethodCommand` binds the
 authorizer to a method with `authorizationType: "COGNITO_USER_POOLS"`.
 
@@ -1118,8 +1100,8 @@ two groups arrive as `[Admins Readers]`.
 }
 ```
 
-An HTTP API puts the same claims under `requestContext.authorizer.jwt.claims`, with the scopes
-beside them, so a handler moved between the two reads a different shape.
+An HTTP API puts the same claims under `requestContext.authorizer.jwt.claims`, with scopes beside
+them. A handler shared by both API types must handle both shapes.
 
 ### Scopes
 
@@ -1141,9 +1123,8 @@ token, since an id token carries no `scope` claim at all.
 | A token that has expired, or has no `exp` at all           | 401 `Unauthorized`                                   |
 | A verified token claiming none of the method's scopes      | 403 `User is not authorized to access this resource` |
 
-Every refusal up to and including the claim checks is the same 401, so a client learns that its
-token was not accepted and nothing about which check it failed. An unmet scope is the one 403: the
-token was accepted, and it does not allow this method.
+Token parsing and claim failures return the same 401 response. An unmet scope returns 403 because
+the token was valid but did not allow the method.
 
 The token is taken with or without the `Bearer` scheme in front of it. The identity source is one
 header, as it is for a `TOKEN` authorizer.
@@ -1503,7 +1484,7 @@ AWS sorts what an import finds into three categories, and the third is valid Ope
 leaves unsupported without a request validator. AWS ignores it silently, and so does this:
 `requestBody`, the content schemas under `responses`, `components.schemas`, and an operation's
 `parameters`, `summary`, `description` and `tags`. Request validation is refused at the root of the
-document, so a request whose body contradicts a declared schema still reaches the handler.
+document. A request body is not checked against the declared schema.
 `operationId` is ignored too, since it only supplies the `OperationName` a method carries for
 documentation.
 
@@ -1902,8 +1883,8 @@ and `Stage`, including the template CDK synthesizes from a `RestApi` or a `Lambd
   that is the form the platform's `Headers` hands over. Real API Gateway reports each separately.
 - A Lambda authorizer's `context` reaches the handler as the authorizer returned it. AWS accepts a
   string, a number or a boolean for each value, and how it renders them is not published.
-- A Cognito authorizer reads a `providerARN` for the pool id it names, so a pool in another account
-  is verified against whenever this simulation holds it. `identityValidationExpression`, which real
+- A Cognito authorizer resolves a `providerARN` by pool ID across the simulated accounts.
+  `identityValidationExpression`, which real
   API Gateway matches a token against before verifying it, is outside this.
 - Binary media types negotiated by `Accept`, CORS preflight and gateway responses are outside this.
   A response body is still base64 decoded when the handler says `isBase64Encoded`.

package/docs/services/apigatewayv2/README.md

@@ -1,11 +1,9 @@
 # Simulated API Gateway HTTP APIs
 
-Yulin includes a simulated API Gateway v2 service, reachable as `simAws.apiGatewayV2()`. It covers
-HTTP APIs with a Lambda proxy integration. A handler that runs behind an HTTP API can be tested
-against a real HTTP request, with no hand-built event to keep in step.
+Yulin simulates API Gateway HTTP APIs with Lambda proxy integrations. Use
+`simAws.apiGatewayV2()` directly or intercept an `ApiGatewayV2Client`.
 
-This is HTTP APIs only. WebSocket APIs and REST APIs (the older API Gateway v1 service, on a
-separate SDK client) are outside it.
+REST APIs use the separate `simAws.apiGateway()` service. WebSocket APIs are unsupported.
 
 ## Creating an API
 
@@ -46,21 +44,19 @@ The endpoint names the API id and the region, as a real one does:
 https://a1b2c3d4e5.execute-api.eu-west-1.amazonaws.com
 ```
 
-A name is a label here, as it is on real AWS. Two APIs in one Account and Region may share a name,
-and only the id tells them apart.
+An API name is a label. Two APIs in the same account and region may share a name. Use the API ID to
+address it.
 
 ## Routing requests to a Lambda function
 
-An API needs three more resources before it serves anything. Those are an integration naming the
-function, a route pointing at that integration, and a stage to serve it from. The function also has to allow API
-Gateway to invoke it. That grant is a permission on the function, not on the API. See
+An API needs an integration, a route and a stage before it can serve requests. The function must
+also grant API Gateway permission to invoke it. See
 [Granting the API permission to invoke the function](#granting-the-api-permission-to-invoke-the-function).
-Once all of that exists, `serveSimAws` answers requests to the generated endpoint by invoking the
-function.
 
-Pass the API endpoint through `srv.localUrl(...)`. It keeps the endpoint's hostname and sends the
-request to the local server, the way it adapts simulated S3 website and Lambda Function URL
-endpoints.
+`serveSimAws` then routes requests from the generated endpoint to the function.
+
+Pass the API endpoint to `srv.localUrl(...)` before making a local HTTP request. The returned URL
+keeps the simulated hostname and points at the local server.
 
 ```typescript sim-apigatewayv2-lambda-proxy
 /**
@@ -152,12 +148,11 @@ Region. It is looked up where its ARN says it is.
 
 ## Granting the API permission to invoke the function
 
-A Lambda proxy integration works once the function's resource policy allows
-`apigateway.amazonaws.com` to invoke it. The console adds that permission for you. An integration
-created through CloudFormation, the CLI or an SDK leaves it to you. That is what
-`AddPermissionCommand` in the example above does. Without it the request is answered with a 500 and
-`{"message":"Internal Server Error"}`, and the handler never runs. CDK's `HttpLambdaIntegration`
-emits the same grant as an `AWS::Lambda::Permission`.
+A Lambda proxy integration requires a resource-based permission for
+`apigateway.amazonaws.com`. Add it with `AddPermissionCommand` or deploy an
+`AWS::Lambda::Permission`. Without the permission, the API returns 500 with
+`{"message":"Internal Server Error"}` and does not invoke the handler. CDK's
+`HttpLambdaIntegration` creates this permission.
 
 Each request is authorized as `lambda:InvokeFunction` on the function ARN, with the caller being the
 service principal `apigateway.amazonaws.com`. The function's own resource policy is the whole
@@ -204,9 +199,8 @@ arn:aws:apigateway:eu-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:eu-
 
 A Lambda `REQUEST` authorizer's `AuthorizerUri` takes the same qualifier.
 
-The qualifier is read when the request arrives. A route built on the alias `live` runs whichever
-version `live` points at now, and `UpdateAliasCommand` carries the route to another version with the
-API untouched. (That is how a deployment behind an HTTP API usually moves on AWS.)
+The qualifier is resolved for each request. A route that uses the `live` alias follows changes made
+by `UpdateAliasCommand` without changing the API.
 
 The invoke permission is granted on the qualifier as well. An alias holds a resource policy of its
 own, and a grant made on the function admits an unqualified call and says nothing about `live`. Pass
@@ -336,8 +330,7 @@ was never created does. The endpoint answers 500 and the handler never runs.
 
 ## Route keys
 
-A route key is either the literal `$default` or an upper-case HTTP method and a path separated by one
-space:
+A route key is `$default` or an uppercase HTTP method followed by a path:
 
 ```text
 GET /pets
@@ -370,7 +363,7 @@ Gateway refuses it too is unestablished. This is stricter than AWS is known to b
 
 ## Which route serves a request
 
-More than one route may match a request, and the most specific one takes it. In order:
+When several routes match, Yulin selects one in this order:
 
 1. A route matching the whole path beats a route ending in a greedy parameter, which beats
    `$default`.
@@ -402,9 +395,8 @@ A request whose path matches a route with a different method matches no route at
 
 ## Path parameters and named stages
 
-What a route captured reaches the handler as `event.pathParameters`. A named stage is served under
-its own path segment. Stage selection runs before route selection, and the routes never see the stage
-name.
+Captured route parameters are available as `event.pathParameters`. A named stage uses the first path
+segment. Yulin removes that segment before selecting a route.
 
 ```typescript sim-apigatewayv2-routes
 /**
@@ -529,16 +521,14 @@ left out the same way when the stage has none.
 
 ## Throttling a stage and a route
 
-A stage holds a token bucket for every route it serves. `DefaultRouteSettings` sets the rate and the
-burst those buckets start with, and a `RouteSettings` entry keyed by route key overrides them for the
-route it names. `ThrottlingRateLimit` is requests per second, and `ThrottlingBurstLimit` is how many
-requests a route will take at once.
+Each stage keeps a token bucket per route. `DefaultRouteSettings` sets the default rate and burst.
+`RouteSettings` can override them by route key. `ThrottlingRateLimit` is requests per second and
+`ThrottlingBurstLimit` is the number accepted at once.
 
 A request that finds an empty bucket is answered 429 with `{"message":"Too Many Requests"}`. The
 route's authorizer and its integration are both skipped.
 
-The buckets refill against the simulated clock. Freeze it, spend a route's burst, assert on the 429,
-then move a second on and watch the route serve again.
+Buckets refill against the simulated clock. Advance the clock to test recovery after a 429 response.
 
 ```typescript sim-apigatewayv2-throttling
 /**
@@ -681,8 +671,8 @@ are refused by `CreateStage`. A template carrying one deploys, and the member it
 
 ## Protecting a route with a Cognito user pool
 
-A JWT authorizer verifies a signed token before the integration is invoked. `CreateAuthorizerCommand`
-creates one, and a route asks for it with `AuthorizationType: "JWT"` and the authorizer's id.
+A JWT authorizer verifies a signed token before invoking the integration. Create it with
+`CreateAuthorizerCommand`, then set `AuthorizationType: "JWT"` and `AuthorizerId` on the route.
 
 The issuer is a URL. Point it at a [simulated Cognito user pool](https://yulinsim.dev/services/cognito/ "Simulated Cognito docs")
 and the pool's own signing key verifies the token. A token from `InitiateAuthCommand` or
@@ -852,9 +842,8 @@ console.log(expired.status); // 401
 await srv.close();
 ```
 
-The verification is real. The token is parsed, its `alg` has to be `RS256`, its `kid` has to name a
-key the issuer publishes, and the signature is checked against that key with `node:crypto`. The whole
-check runs in process, with no network fetch and no verification library.
+Yulin parses the token, requires `alg` to be `RS256`, resolves `kid` against the issuer's keys and
+checks the signature with `node:crypto`. Verification runs in process.
 
 ### What a refused request gets back
 
@@ -933,9 +922,8 @@ left out of its events entirely.
 
 ## Protecting a route with IAM
 
-A route declared `AuthorizationType: "AWS_IAM"` reaches its integration only when the caller is
-allowed `execute-api:Invoke` on the ARN of the route being called. IAM itself decides. The route takes
-no authorizer, and naming one is refused.
+A route with `AuthorizationType: "AWS_IAM"` requires `execute-api:Invoke` on the request ARN. The
+route has no separate authorizer.
 
 The caller comes from the request, through either a SigV4 signature or an `x-sim-aws-caller` header
 naming a principal directly. A request offering neither is anonymous, owns no policies, and is
@@ -948,14 +936,13 @@ The ARN a request is authorized against is:
 arn:aws:execute-api:<region>:<account>:<apiId>/<stage>/<METHOD>/<path>
 ```
 
-- The Account and Region are the API's own, not the caller's.
+- The account and region identify the API.
 - The stage is the one that served the request, so `$default` for the default stage.
 - The method is the one the client sent, upper case. A `GET` reaching a route keyed `ANY /orders`
   gives `GET`.
-- The path is the request path with the stage segment and the leading slash taken off, so
-  `/dev/orders/42` served from stage `dev` gives `orders/42`. This is the path asked for, not the route
-  key, because a policy is written against it by hand. A request to the API root gives an ARN ending
-  `/GET/`.
+- The path is the request path without the stage segment or leading slash. `/dev/orders/42` on stage
+  `dev` becomes `orders/42`. It uses the requested path, including resolved parameter values. A
+  request to the API root produces an ARN ending in `/GET/`.
 
 An identity policy may wildcard any part of that. `<apiId>/*`, `<apiId>/$default/*` and
 `<apiId>/*/GET/orders/*` all allow a `GET` of `/orders/42` on the default stage.
@@ -1132,13 +1119,13 @@ Account.
 
 ## Protecting a route with a Lambda authorizer
 
-A Lambda `REQUEST` authorizer runs a function of its own before the integration is invoked, and that
-function decides. `CreateAuthorizerCommand` with `AuthorizerType: "REQUEST"` creates one, and a route
-asks for it with `AuthorizationType: "CUSTOM"` and the authorizer's id.
+A Lambda `REQUEST` authorizer invokes a function before the integration. Create it with
+`AuthorizerType: "REQUEST"`, then configure the route with `AuthorizationType: "CUSTOM"` and the
+authorizer ID.
 
-`IdentitySource` is what the request has to carry before the function is invoked at all. Each entry
-is `$request.header.<name>` or `$request.querystring.<name>`, and a request missing any one of them is
-refused without the function running.
+`IdentitySource` lists values required before invoking the authorizer. Each entry is
+`$request.header.<name>` or `$request.querystring.<name>`. A missing value returns 401 without running
+the function.
 
 `EnableSimpleResponses: true` asks the function for `{ isAuthorized, context }`. With it off, the
 function answers a `principalId` and an IAM `policyDocument` instead. Either way, the `context` it
@@ -1357,9 +1344,8 @@ is a different grant from the integration's, and a function used for both needs
 
 ### Caching the authorizer's decision
 
-`AuthorizerResultTtlInSeconds` holds a decision for that many seconds, and a request presenting the
-same identity source values within it is served from that decision without the function running
-again. AWS accepts up to 3600. The default, 0, holds no decision at all.
+`AuthorizerResultTtlInSeconds` caches a decision by identity source values. AWS accepts values up to
+3,600 seconds. The default of zero disables caching.
 
 The key is the identity source values and nothing else, so one decision covers every route of the API
 that uses the authorizer. Adding `$context.routeKey` as an identity source puts the route in the key.
@@ -1517,8 +1503,7 @@ ran.
 
 ## The event the handler receives
 
-The handler is invoked with the API Gateway HTTP API payload format 2.0 event, exported as
-`SimPayload2Event`:
+The handler receives a payload format 2.0 event, exported as `SimPayload2Event`:
 
 ```json
 {
@@ -1630,9 +1615,8 @@ endpoint, and has
 
 ## The response the handler returns
 
-A handler returning an object with a `statusCode` produces that HTTP response. Its `headers` are
-sent as headers, its `cookies` become `set-cookie` headers, and an empty body is sent as no body,
-leaving a 204 a valid response.
+A result with `statusCode` becomes the HTTP response. `headers` are sent as response headers,
+`cookies` become `set-cookie` headers and an omitted body stays empty.
 
 A handler returning anything else produces a 200 whose body is that value as JSON. That includes an
 object with no `statusCode` in it. A handler returning `{ body: "hi" }` produces a 200 whose body is
@@ -1640,8 +1624,8 @@ the JSON `{"body":"hi"}` with `content-type: application/json`. Real API Gateway
 
 ## Reading an API back
 
-`GetApisCommand`, `GetIntegrationsCommand`, `GetRoutesCommand` and `GetStagesCommand` list what an
-API has. Each answers in full, as paging is outside the simulation.
+`GetApisCommand`, `GetIntegrationsCommand`, `GetRoutesCommand` and `GetStagesCommand` list the API's
+resources. Each command returns all results because pagination is unsupported.
 
 ```typescript sim-apigatewayv2-list-resources
 /**
@@ -1684,10 +1668,9 @@ console.log(stages.Items[0]?.StageVariables);
 
 ## Deleting what an API has
 
-`DeleteRouteCommand`, `DeleteIntegrationCommand` and `DeleteStageCommand` each take one resource off
-an API and leave the rest of it in place. A deleted route stops matching, and a request that used to
-reach it is answered the way any unmatched request is. A deleted stage stops resolving. A request
-addressed to it finds no stage, while the routes it served are still served by the API's other stages.
+`DeleteRouteCommand`, `DeleteIntegrationCommand` and `DeleteStageCommand` remove one resource. A
+deleted route stops matching. Deleting a stage removes its URL while leaving the API's routes
+available through other stages.
 
 An integration a route still points at cannot be deleted. That is a `BadRequestException` naming the
 routes in the way, as it is on real AWS, and an API comes apart routes first and then the integrations
@@ -1761,8 +1744,7 @@ const integrations = await apiGateway.getIntegrations(
 console.log(routes.Items.length, integrations.Items.length);
 ```
 
-`DeleteApiCommand` deletes the API and everything under it, so taking a whole API away needs none of
-these.
+`DeleteApiCommand` deletes the API and all of its resources.
 
 ## Turning the generated endpoint off
 
@@ -1774,9 +1756,8 @@ status nor the body for that case, so both are what a disabled endpoint was obse
 
 ## Serving an API on a custom domain name
 
-`CreateDomainNameCommand` creates a domain that answers on a hostname the project owns.
-`CreateApiMappingCommand` points a base path of that domain at one API and one of its stages. A
-domain with no mapping answers 404 to everything.
+`CreateDomainNameCommand` creates a custom domain. `CreateApiMappingCommand` maps a base path to an
+API stage. A domain with no mapping returns 404.
 
 An empty `ApiMappingKey` maps the root of the domain. Every request reaching the domain goes to that
 API, with the path as the client sent it. A non-empty key is one or more path segments (`orders`,