lambder 7.2.5 → 8.0.2

package/dist/mock/LambderMockTypes.d.ts

@@ -8,7 +8,7 @@
 import type { z } from "zod";
 import type { LambderApiMode, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractGuardInputsOf, LambderContractGuardNames, LambderContractGuardsOf, LambderContractIdempotencyOf, LambderContractKeysWithMode, LambderContractMode, LambderContractRateLimitOf } from "../shared/wire/LambderApiContract.js";
 import type { LambderApiGuard, LambderGuardDataOf, LambderGuardMetaMap } from "../api/LambderApiGuards.js";
-import type { LambderApiRateLimitPolicyConfig } from "../api/LambderApiRateLimits.js";
+import type { LambderApiRateLimitPolicyConfig, LambderContextRateLimit, LambderContextRateLimitCheck } from "../api/LambderApiRateLimits.js";
 import type { LambderApiCallContext } from "../api/LambderApiCallContext.js";
 import type { LambderApiRequest } from "../api/LambderApiRequest.js";
 import type { LambderHttpStatusCode } from "../shared/wire/LambderHttpStatus.js";
@@ -28,21 +28,16 @@ export type LambderMockOutputOf<C, K extends keyof C> = C[K] extends {
  * `never`, so a typo is an error on the key itself.
  *
  * Needed once per nesting level: inferring a generic from an object literal
- * (`const G`, `const P` on create()) switches excess-property checking off for
- * the WHOLE literal, nested objects included, so `idempotency: { failOpn:
- * false }` compiled, was dropped in silence, and left the runtime on the
- * default. Intersected into a nested position rather than applied to the
- * option type as a whole, because the type variable has to stay naked
- * somewhere for the literal to be inferred from at all.
+ * (`const G`, `const P` on create()) switches excess-property checking off
+ * for the WHOLE literal, so `idempotency: { failOpn: false }` would compile
+ * and be dropped. Intersected into a nested position because the type
+ * variable must stay naked somewhere for the literal to be inferred at all.
+ * `unknown` for a non-object (`idempotency: true`), since mapping Boolean's
+ * prototype keys to `never` would refuse the boolean form.
  *
- * `unknown` for anything that is not an object (`idempotency: true`), which
- * intersects away: `keyof boolean` is Boolean's own prototype members, and
- * mapping those to `never` would refuse the boolean form outright.
- *
- * The server's create() has the same construction in `LambderNoExtraKeys`
- * (core/Lambder.ts). It is written twice on purpose: `lambder/mock` is
- * browser-safe by its import graph, and reaching into core/ for a type alias
- * would pull the server's whole type graph (aws-lambda included) back into it.
+ * Duplicates `LambderNoExtraKeys` (core/LambderCreateOptions.ts) on purpose: importing it
+ * would pull the server's type graph (aws-lambda included) into the
+ * browser-safe `lambder/mock`.
  */
 export type LambderMockSurplusKeys<TOptions, TShape> = [
     TOptions
@@ -55,8 +50,16 @@ export type LambderMockSurplusKeys<TOptions, TShape> = [
 export type LambderMockCallContext<S = any> = LambderApiCallContext<S> & {
     apiName: string;
     request: LambderApiRequest;
-    /** Create, rotate, refresh and end sessions, exactly as a server handler does through getSessionController(ctx). */
-    sessions: LambderSessionController<S>;
+    /** Create, rotate, refresh and end sessions, exactly as a server handler does through its own ctx.sessionController. */
+    sessionController: LambderSessionController<S>;
+    /**
+     * Charges a named policy from code, as a server handler does through its
+     * own ctx.rateLimit: a 429 refusal when it is over. The name is any
+     * string and the key optional here; the charge checks both.
+     */
+    rateLimit: LambderContextRateLimit<Record<string, LambderApiRateLimitPolicyConfig>>;
+    /** The same count, answered instead of thrown, as ctx.isRateLimited on the server. */
+    isRateLimited: LambderContextRateLimitCheck<Record<string, LambderApiRateLimitPolicyConfig>>;
     signal: AbortSignal;
     /**
      * The envelope fields that travel beside the payload, the mock's stand-in
@@ -88,18 +91,17 @@ export type LambderMockContext<C, K extends keyof C, S, G> = Omit<LambderMockCal
 };
 /**
  * The guard map a mock app must declare: one guard per name any endpoint of
- * the contract declares, and for every guard the contract knows in
- * guardInput mode, a `guardInput` schema whose output is what the server
- * inferred. A guard a public endpoint names may not require a session, since
- * an entry naming one cannot be registered. A missing name, a schema that
- * parses to something else, or a session guard where the contract has a
- * public endpoint fails at the `guards` option.
+ * the contract declares, plus, for each guardInput-mode guard, a `guardInput`
+ * schema whose input is what the contract says a client sends. A guard a
+ * public endpoint names may not require a session. A missing name, a schema
+ * that parses to something else, or such a session guard fails at the
+ * `guards` option.
  */
 export type LambderMockGuards<C, S = any> = {
     [N in LambderContractGuardNames<C>]: LambderApiGuard<any, any, any, LambderMockCallContext<S>, LambderMockSessionCallContext<S>>;
 } & {
     [N in LambderContractGuardInputNames<C>]: {
-        guardInput: z.ZodType<LambderContractGuardInput<C, N>, any>;
+        guardInput: z.ZodType<unknown, LambderContractGuardInput<C, N>>;
     };
 } & {
     [N in LambderContractGuardNames<C, "public">]: {
@@ -110,14 +112,10 @@ export type LambderMockHandler<C, K extends keyof C, S, G> = (ctx: LambderMockCo
 /**
  * The guards field of an entry: required whenever the contract declares any
  * guard for the endpoint, and type-equal to the server's own declaration.
- *
- * Keyed on the guards themselves rather than on guardInputs, because the
- * restatement is the only thing that tells the runtime which guards to run:
- * a guard the entry leaves out simply does not run, and the mock answers 200
- * where the server answers notAuthorized. The guards that carry no
- * guardInput are exactly the "may this role call it" ones (session-only,
- * param-only), so keying on guardInputs made the authorization checks the
- * droppable half.
+ * The restatement is what tells the runtime which guards to run, so a guard
+ * left out would let the mock answer 200 where the server answers
+ * notAuthorized. Keyed on the guards rather than on guardInputs, since the
+ * guards without a guardInput are the "may this role call it" ones.
  */
 type LambderMockGuardsField<C, K extends keyof C> = [
     LambderContractGuardsOf<C, K>
@@ -128,10 +126,9 @@ type LambderMockGuardsField<C, K extends keyof C> = [
 };
 /**
  * The rate-limit field of an entry: required whenever the contract declares
- * one, absent otherwise. Same reasoning as LambderMockGuardsField, and the
- * argument transfers word for word: the restatement is the only thing that
- * tells the runtime to apply the limit, so an entry that leaves it out
- * answers 200 where the server answers 429.
+ * one, absent otherwise. As with LambderMockGuardsField, the restatement is
+ * the only thing that tells the runtime to apply the limit, so an entry that
+ * left it out would answer 200 where the server answers 429.
  */
 type LambderMockRateLimitField<C, K extends keyof C> = [
     LambderContractRateLimitOf<C, K>
@@ -157,56 +154,47 @@ type LambderMockIdempotencyField<C, K extends keyof C> = [
  * What override() hands back: call restore() to put the original handler
  * back.
  *
- * Restore and nothing else. The handle also carried a `[Symbol.dispose]`
- * member, for `using`, and that member is declared in `lib: ESNext` alone: a
- * consumer on `lib: ES2022` (a Vue app's own setting, and the only consumer
- * this package has) got TS2550 "Property 'dispose' does not exist on type
- * 'SymbolConstructor'" out of the published .d.ts, from importing the entry at
- * all, whenever skipLibCheck was off. A scoped override is a try/finally,
- * which needs no lib.
+ * Deliberately no `[Symbol.dispose]` for `using`: it is declared only in
+ * `lib: ESNext`, so a consumer on `lib: ES2022` with skipLibCheck off would
+ * get TS2550 from the published .d.ts just by importing the entry. A scoped
+ * override is a try/finally, which needs no lib.
  */
 export type LambderMockOverride = {
     restore(): void;
 };
 /**
- * What an entry's `input` schema must parse to: the endpoint's contract
- * input, in both directions.
- *
- * One direction is not enough, and the missing one is the direction the drift
- * actually travels in. `z.ZodType<Input>` is covariant in its output, so a
- * schema parsing to a SUBTYPE of the contract input passed: an extra required
- * field, or a literal where the contract says string. Such a schema refuses
- * payloads the server accepts, and the mock then answers 422 to a call that
- * works against the real backend, which is the exact failure the schema was
- * added to reproduce, produced by the thing added to reproduce it. Requiring
- * assignability the other way as well makes the schema's output the contract's
- * input and nothing else.
+ * What an entry's `input` schema must take and give: it takes exactly the
+ * endpoint's contract input (the form a client posts), in both directions,
+ * and what it parses to still reads as that input, which is how the mock's
+ * handler is typed. `z.ZodType<Input>` alone is covariant, so a schema
+ * taking a SUBTYPE (an extra required field, a literal where the contract
+ * says string) would pass, and the mock would then answer 422 to payloads
+ * the server accepts. A default passes (the parsed field is simply there);
+ * a transform that changes a field's type does not, since the handler would
+ * read it as the posted type.
  *
  * Intersected onto the schema rather than mapped to `never`, so the compiler
- * quotes the reason at the `input` property. `z.any()` passes in both
- * directions, which is the one deliberate escape hatch; `z.unknown()` does
- * not.
+ * quotes the reason at the `input` property. `z.any()` passes both ways as
+ * the one deliberate escape hatch; `z.unknown()` does not.
  */
 type LambderMockInputPin<C, K extends keyof C, TSchema extends z.ZodType> = [
-    z.output<TSchema>
-] extends [LambderMockInputOf<C, K>] ? ([LambderMockInputOf<C, K>] extends [z.output<TSchema>] ? unknown : {
-    "LambderMockApp: this input schema parses to less than the endpoint takes (an extra required field, or a narrower type), so the mock would answer 422 to payloads the server accepts": LambderMockInputOf<C, K>;
+    z.input<TSchema>
+] extends [LambderMockInputOf<C, K>] ? ([LambderMockInputOf<C, K>] extends [z.input<TSchema>] ? ([z.output<TSchema>] extends [LambderMockInputOf<C, K>] ? unknown : {
+    "LambderMockApp: this input schema transforms the payload into a type the mock handler is not typed for (it reads the payload as the endpoint's contract input)": LambderMockInputOf<C, K>;
 }) : {
-    "LambderMockApp: this input schema parses to something else than the endpoint's contract input": LambderMockInputOf<C, K>;
+    "LambderMockApp: this input schema takes less than the endpoint takes (an extra required field, or a narrower type), so the mock would answer 422 to payloads the server accepts": LambderMockInputOf<C, K>;
+}) : {
+    "LambderMockApp: this input schema takes something else than the endpoint's contract input": LambderMockInputOf<C, K>;
 };
 /** An entry written in full: the declarations restated and pinned, plus the handler. */
 export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType> = LambderMockGuardsField<C, K> & LambderMockRateLimitField<C, K> & LambderMockIdempotencyField<C, K> & {
     /**
-     * A schema to validate the posted payload against, which makes the mock
-     * answer 422 exactly as the server would. Optional, and deliberately the
-     * mock's own: the contract is a type, so the server's schemas do not exist
-     * at runtime on this side, and importing them would put the whole endpoint
-     * surface into the browser bundle. Restate the shape for the endpoints
-     * whose rejection path a test needs to exercise; leave it off and a bad
-     * payload reaches the handler, as it does today.
-     *
-     * Pinned to the contract's input all the same: the schema is the mock's,
-     * but what it parses to is the server's, in both directions (see
+     * A schema to validate the posted payload against, so the mock answers
+     * 422 exactly as the server would. Optional, and the mock's own: the
+     * contract is type-only, and importing the server's schemas would put the
+     * whole endpoint surface into the browser bundle. Restate it for endpoints
+     * whose rejection path a test exercises; without it a bad payload reaches
+     * the handler. What it parses to is pinned to the contract's input (see
      * LambderMockInputPin).
      */
     input?: TInputSchema & LambderMockInputPin<C, K, TInputSchema>;
@@ -215,14 +203,9 @@ export type LambderMockEntryOptions<C, K extends keyof C, S, G, TInputSchema ext
 /**
  * What publicApi/sessionApi accept: a bare handler only for an endpoint the
  * contract declares nothing for, the full options otherwise, so the form that
- * cannot carry a restatement is unavailable exactly where one is owed.
- *
- * All three declarations, not guards alone. The three fields above make each
- * restatement required INSIDE the options form, and the bare handler is the
- * form that has no fields at all, so keying this on guards left every
- * guardless endpoint free to drop its rate limit and its idempotency again:
- * the handler ran twice for one key and a perMin limit never answered 429,
- * which is the whole of what those two fields exist to prevent.
+ * cannot carry a restatement is unavailable exactly where one is owed. Keyed
+ * on all three declarations: keyed on guards alone, a guardless endpoint
+ * could drop its rate limit and idempotency through the bare form.
  */
 export type LambderMockEntryInput<C, K extends keyof C, S, G, TInputSchema extends z.ZodType = z.ZodType> = [
     LambderContractGuardsOf<C, K> | LambderContractRateLimitOf<C, K> | LambderContractIdempotencyOf<C, K>
@@ -244,13 +227,9 @@ export type LambderMockSlice<C, K extends keyof C & string> = {
 };
 /**
  * What restNotMocked(reason) hands register(): "every endpoint the slices
- * beside me leave out is not mocked, for this reason".
- *
- * A one-field object rather than a slice, because it names no endpoint: it
- * answers the names nothing else claimed, and which those are is only known
- * once the other arguments have been read. Every check below filters it out
- * before it reads a name, so the field it does carry is neither a stray nor
- * half of a duplicate; the one clause it changes is completeness.
+ * beside me leave out is not mocked, for this reason". A one-field object
+ * rather than a slice, because it names no endpoint; every check below
+ * filters it out before reading names, so it changes only completeness.
  */
 export type LambderMockRestEntry = {
     readonly restNotMockedReason: string;
@@ -259,15 +238,11 @@ export type LambderMockRestEntry = {
  * The names one slice holds; distributes over a union of slices.
  *
  * A slice typed with an index signature (`Record<string, LambderMockEntry>`,
- * or a list built in a loop) holds `string` as its key type, which would
- * subtract every name from the missing list and pass the completeness check
- * while registering almost nothing. Such a slice names nothing the compiler
- * can check, so it contributes nothing here and LambderMockUncheckableSlices
- * reports it for what it is.
- *
- * The rest entry contributes nothing either, and for the opposite reason: the
- * one key it carries is not an endpoint name, so reading it would report
- * "restNotMockedReason" as a stray, and two rest entries as a duplicate of it.
+ * a list built in a loop) has `string` as its key type, which would pass the
+ * completeness check while registering almost nothing, so it contributes
+ * nothing here and LambderMockUncheckableSlices reports it. The rest entry
+ * contributes nothing either: its one key is not an endpoint name, and
+ * reading it would report "restNotMockedReason" as a stray or a duplicate.
  */
 type LambderMockSliceNames<S> = S extends unknown ? (S extends LambderMockRestEntry ? never : (string extends keyof S ? never : keyof S & string)) : never;
 /**
@@ -288,10 +263,9 @@ type LambderMockHasRestEntry<Slices extends readonly unknown[]> = [
  * The endpoints register() would leave unanswered: the ones no slice covers,
  * unless a rest entry stands for them.
  *
- * The completeness clause and nothing else. An endpoint the rest entry answers
- * is still an endpoint with no mock of its own, which is what
- * LambderMockMissingNames says and why that one keeps its meaning; what the
- * rest entry changes is whether leaving it out is a mistake.
+ * Separate from LambderMockMissingNames, because an endpoint the rest entry
+ * answers still has no mock of its own; the rest entry only changes whether
+ * leaving it out is a mistake.
  */
 type LambderMockUncoveredNames<C, Slices extends readonly unknown[]> = LambderMockHasRestEntry<Slices> extends true ? never : LambderMockMissingNames<C, Slices>;
 /** Names the slices carry that the contract does not declare. */
@@ -300,14 +274,10 @@ export type LambderMockStrayNames<C, Slices extends readonly unknown[]> = Exclud
 export type LambderMockDuplicateNames<Slices extends readonly unknown[]> = Slices extends readonly [infer Head, ...infer Tail] ? (LambderMockSliceNames<Head> & LambderMockSliceNames<Tail[number]>) | LambderMockDuplicateNames<Tail> : never;
 /**
  * True for a slice list whose length the compiler does not know: an array
- * type rather than a tuple, `length: number`.
- *
- * Every check below is written over a tuple, and an array type quietly
- * disables all of them: the overlap and index-signature walks fall to their
- * `never` base case on the first step, and completeness reduces to "the
- * element type mentions these names", which one element satisfies as well as
- * twenty. `const slices = [userMocks, orderMocks]` spread into register() is
- * exactly that type, so the array form is refused rather than passed.
+ * type rather than a tuple. Every check here walks a tuple, and an array
+ * type quietly disables them all (completeness reduces to "the element type
+ * mentions these names"), so the array form, such as a spread
+ * `const slices = [userMocks, orderMocks]`, is refused.
  */
 type LambderMockUncountableSlices<Slices extends readonly unknown[]> = number extends Slices["length"] ? true : false;
 /**

package/dist/mock/lambderMockInvokeTransport.d.ts

@@ -4,14 +4,12 @@ import { type LambderApiRequest } from "../api/LambderApiRequest.js";
  * The fields of an invoke's synthesized event this transport reads, declared
  * structurally rather than imported as APIGatewayProxyEventV2.
  *
- * `lambder/mock` is browser-safe, and its type graph is part of that claim: a
- * type-only import of the invoke caller pulled `aws-lambda` and
- * `@aws-sdk/client-lambda` into the .d.ts graph of the mock entry, so a
- * frontend compiling without `skipLibCheck` and without those @types got
- * errors from inside node_modules for a module it never loads. Every field a
- * real event carries is optional here and no field is required, so a real
- * event is assignable and the returned function still fits
- * LambderInvokeTransport wherever a caller expects one.
+ * `lambder/mock` is browser-safe, type graph included: a type-only import of
+ * the invoke caller would pull `aws-lambda` and `@aws-sdk/client-lambda` into
+ * the mock entry's .d.ts graph, and a frontend compiling without
+ * `skipLibCheck` or those @types would get errors from a module it never
+ * loads. Every field is optional, so a real event is assignable and the
+ * returned function still fits LambderInvokeTransport.
  */
 export type LambderMockInvokeEvent = {
     body?: string | undefined;
@@ -37,11 +35,11 @@ export type LambderMockInvokeResult = {
     };
 };
 /**
- * The mock app as the callee of a LambderInvokeCaller: the invoke's
- * synthesized event is read the way the callee's createContext would read
- * it, and the answer goes back as the Lambda response object the caller
- * decodes. So a server test can point its typed invoke caller at a mock of
- * the function it depends on, with the same registry a browser test uses.
+ * The mock app as the callee of a LambderInvokeCaller: the synthesized event
+ * is read the way the callee's createContext would read it, and the answer
+ * goes back as the Lambda response object the caller decodes. A server test
+ * can then point its typed invoke caller at a mock of the function it
+ * depends on, with the same registry a browser test uses.
  */
 export declare const lambderMockInvokeTransport: (mockApp: {
     handleRequest(request: LambderApiRequest): Promise<LambderApiAnswer>;

package/dist/mock/lambderMockInvokeTransport.js

@@ -1,13 +1,13 @@
-import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { base64ToText } from "../shared/util/LambderBase64.js";
 import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
 /**
- * The mock app as the callee of a LambderInvokeCaller: the invoke's
- * synthesized event is read the way the callee's createContext would read
- * it, and the answer goes back as the Lambda response object the caller
- * decodes. So a server test can point its typed invoke caller at a mock of
- * the function it depends on, with the same registry a browser test uses.
+ * The mock app as the callee of a LambderInvokeCaller: the synthesized event
+ * is read the way the callee's createContext would read it, and the answer
+ * goes back as the Lambda response object the caller decodes. A server test
+ * can then point its typed invoke caller at a mock of the function it
+ * depends on, with the same registry a browser test uses.
  */
 export const lambderMockInvokeTransport = (mockApp) => async (event, { signal }) => {
     const rawBody = event.body ?? "";
@@ -21,10 +21,11 @@ export const lambderMockInvokeTransport = (mockApp) => async (event, { signal })
     }
     const headers = lowercaseHeaderNames(event.headers);
     const cookies = cookieValuesByName(event.cookies ?? []);
-    // The address the synthesized event carries in sourceIp, as the server's
-    // createContext reads it; no forwarding header is trusted here either,
-    // so a per-IP limit keys the same address under both adapters.
-    const request = readApiEnvelope(post, {
+    // A POST of another type is no API call on the server either. The
+    // address is the one the synthesized event carries in sourceIp, as the
+    // server's createContext reads it; no forwarding header is trusted here
+    // either, so a per-IP limit keys the same address under both adapters.
+    const request = isApiCallContentType(headers) && readApiEnvelope(post, {
         headers, cookies,
         ip: normalizeClientIp(event.requestContext?.http?.sourceIp ?? ""),
         host: headers.host || event.requestContext?.domainName || "lambder-invoke",

package/dist/mock/lambderMockMswHandler.d.ts

@@ -4,13 +4,11 @@ import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 /**
  * The parts of the msw module the adapter uses: `import * as msw from "msw"`.
  *
- * Written so the real package satisfies it, which is the whole point of a
- * structural declaration and was not true of the previous one. msw's resolver
- * answers a Response, or `undefined` to hand the request back (its
- * AsyncResponseResolverReturnType), and a resolver declared to return
- * `Promise<unknown>` is not assignable to that, so `http.post` did not fit
- * here and the handler this returned did not fit `setupWorker`. Both errors
- * landed on the documented five-line wiring.
+ * Written so the real package satisfies it. msw's resolver answers a
+ * Response, or `undefined` to hand the request back (its
+ * AsyncResponseResolverReturnType); a resolver declared to return
+ * `Promise<unknown>` is not assignable to that, so `http.post` would not fit
+ * here and the returned handler would not fit `setupWorker`.
  */
 export type LambderMswModule = {
     http: {
@@ -43,10 +41,10 @@ export type LambderMockMswTarget = {
     /**
      * The host the runtime's cookies belong to, which this adapter's jar is
      * scoped by. The runtime's value, not the request URL's: signIn plants at
-     * the app's cookieHost and the direct transport's jar sends from there, so
-     * an adapter scoping by whatever host the page is served from held the
-     * session cookies at a host it never sent them to, and every session call
-     * behind the worker answered sessionExpired with a full jar.
+     * the app's cookieHost and the direct transport's jar sends from there.
+     * Scoped by the page's host instead, the jar would hold session cookies
+     * at a host it never sends them to, and every session call behind the
+     * worker would answer sessionExpired with a full jar.
      */
     readonly cookieHost: string;
 };
@@ -54,25 +52,31 @@ export type LambderMockMswTarget = {
  * ONE MSW request handler for the whole API path, over the mock app: the
  * opt-in that makes mocked calls appear in the browser's network panel as
  * genuine requests, with real method, status, timing and bodies. The request
- * is read the way the server reads it, its headers and Cookie header
- * included.
+ * is read the way the server reads it, headers included, with the cookies a
+ * browser would send.
  *
- * Session cookies are held in a jar here rather than by the browser, because
- * the browser will not hold them: a response a service worker synthesizes
- * never reaches the cookie store, and MSW's own jar comma-joins the
- * Set-Cookie headers before parsing them, which loses every cookie after the
- * first. So the answer's cookies go into the jar, the next request carries
- * them back, and the ones a page's scripts may see are mirrored into
- * document.cookie. The Set-Cookie headers still travel on the response, where
- * the network panel shows them.
+ * Session cookies are held in a jar here, because the browser will not hold
+ * them: a response a service worker synthesizes never reaches the cookie
+ * store, and MSW's own jar comma-joins the Set-Cookie headers before parsing
+ * them, losing every cookie after the first. So the answer's cookies go into
+ * the jar, the next request carries them back, and the ones a page's scripts
+ * may see are mirrored into document.cookie. The Set-Cookie headers still
+ * travel on the response, where the network panel shows them.
+ *
+ * A request's cookies are therefore the jar's and document.cookie's, never
+ * its Cookie header: MSW fills that from its own store, which captures the
+ * HttpOnly session cookie off those Set-Cookie headers and keeps it in
+ * localStorage across reloads. Reading it would send a second session after
+ * a user switch (every call answering sessionExpired), keep a cleared jar
+ * signed in, and put the raw token into request events.
  *
  * Lambder never depends on msw: the app installs it and passes the module
  * in. An injected network failure answers MSW's network error. A POST whose
  * body is not an API envelope is left to other handlers.
  *
  * Generic over the module so the handler keeps msw's own handler type, which
- * is what `setupWorker(...)` and `setupServer(...)` take. Returning `unknown`
- * made the documented wiring an error at the consumer.
+ * is what `setupWorker(...)` and `setupServer(...)` take; typed `unknown`,
+ * the documented wiring would be a type error at the consumer.
  */
 export declare const lambderMockMswHandler: <M extends LambderMswModule>(mockApp: LambderMockMswTarget, options: {
     msw: M;
@@ -86,12 +90,12 @@ export declare const lambderMockMswHandler: <M extends LambderMswModule>(mockApp
      * a partially mocked app runs in while its remaining endpoints still
      * come from a real backend.
      *
-     * This and `mockApp.restNotMocked(reason)` are the two answers to the
-     * same question, and the rest entry wins: it leaves the runtime with
-     * an entry for every name, so nothing is ever unmocked here and a call
-     * that would have gone to the network is answered notMocked instead.
-     * Pick the rest entry for an app with no backend to reach, and this
-     * for one whose remaining endpoints are served by a real one.
+     * This and `mockApp.restNotMocked(reason)` answer the same question,
+     * and the rest entry wins: it gives the runtime an entry for every
+     * name, so nothing is unmocked here and a call is answered notMocked
+     * rather than passed on. Pick the rest entry for an app with no
+     * backend to reach, and this for one whose remaining endpoints are
+     * served by a real one.
      */
     onUnmocked?: "refuse" | "passthrough";
     /** The client IP its calls are read as arriving from. Default: the runtime's own defaultClientIp. */

package/dist/mock/lambderMockMswHandler.js

@@ -1,5 +1,5 @@
 import { LambderMockTransportError } from "./LambderMockFailureInjector.js";
-import { readApiEnvelope, cookieValuesByName, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
+import { readApiEnvelope, cookieValuesByName, isApiCallContentType, lowercaseHeaderNames } from "../api/LambderApiRequest.js";
 import { getAnswerHeader } from "../shared/wire/LambderAnswerHeaders.js";
 import { LambderCookieJar } from "../shared/transport/LambderCookieJar.js";
 import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
@@ -7,25 +7,31 @@ import { normalizeClientIp } from "../shared/util/LambderClientIp.js";
  * ONE MSW request handler for the whole API path, over the mock app: the
  * opt-in that makes mocked calls appear in the browser's network panel as
  * genuine requests, with real method, status, timing and bodies. The request
- * is read the way the server reads it, its headers and Cookie header
- * included.
+ * is read the way the server reads it, headers included, with the cookies a
+ * browser would send.
  *
- * Session cookies are held in a jar here rather than by the browser, because
- * the browser will not hold them: a response a service worker synthesizes
- * never reaches the cookie store, and MSW's own jar comma-joins the
- * Set-Cookie headers before parsing them, which loses every cookie after the
- * first. So the answer's cookies go into the jar, the next request carries
- * them back, and the ones a page's scripts may see are mirrored into
- * document.cookie. The Set-Cookie headers still travel on the response, where
- * the network panel shows them.
+ * Session cookies are held in a jar here, because the browser will not hold
+ * them: a response a service worker synthesizes never reaches the cookie
+ * store, and MSW's own jar comma-joins the Set-Cookie headers before parsing
+ * them, losing every cookie after the first. So the answer's cookies go into
+ * the jar, the next request carries them back, and the ones a page's scripts
+ * may see are mirrored into document.cookie. The Set-Cookie headers still
+ * travel on the response, where the network panel shows them.
+ *
+ * A request's cookies are therefore the jar's and document.cookie's, never
+ * its Cookie header: MSW fills that from its own store, which captures the
+ * HttpOnly session cookie off those Set-Cookie headers and keeps it in
+ * localStorage across reloads. Reading it would send a second session after
+ * a user switch (every call answering sessionExpired), keep a cleared jar
+ * signed in, and put the raw token into request events.
  *
  * Lambder never depends on msw: the app installs it and passes the module
  * in. An injected network failure answers MSW's network error. A POST whose
  * body is not an API envelope is left to other handlers.
  *
  * Generic over the module so the handler keeps msw's own handler type, which
- * is what `setupWorker(...)` and `setupServer(...)` take. Returning `unknown`
- * made the documented wiring an error at the consumer.
+ * is what `setupWorker(...)` and `setupServer(...)` take; typed `unknown`,
+ * the documented wiring would be a type error at the consumer.
  */
 export const lambderMockMswHandler = (mockApp, options) => {
     const { msw, apiPath } = options;
@@ -38,13 +44,11 @@ export const lambderMockMswHandler = (mockApp, options) => {
     // cookies name.
     if (!options.cookieJar)
         mockApp.adoptCookieJar(jar);
-    // The runtime's default, not a second one of this adapter's own: an app
-    // that set defaultClientIp saw its address through the direct transport
-    // and 127.0.0.1 through the service worker, so a per-IP rate limit counted
-    // two clients where there was one and the two adapters disagreed about
-    // what ctx.request.ip is.
-    // Normalized the way every other adapter's is, so one address is one
-    // counter under a `per: "ip"` limit however it was spelled.
+    // The runtime's default, not one of this adapter's own, so the direct
+    // transport and the service worker agree on ctx.request.ip and a per-IP
+    // rate limit counts one client as one. Normalized the way every other
+    // adapter's is, so one address is one counter under a `per: "ip"` limit
+    // however it was spelled.
     const clientIp = normalizeClientIp(options.clientIp ?? mockApp.defaultClientIp);
     const handler = msw.http.post(apiPath, async ({ request }) => {
         let post;
@@ -54,27 +58,34 @@ export const lambderMockMswHandler = (mockApp, options) => {
         catch {
             return undefined;
         }
-        // Through the one header map every adapter builds, which is built on
-        // Object.create(null): a header literally named __proto__ was dropped
-        // here and landed as an own key on the server, and headers["toString"]
-        // handed a guard an inherited function where every other adapter gives
-        // undefined.
+        // Through the one header map every adapter builds, on
+        // Object.create(null): on a plain object, a header literally named
+        // __proto__ would be dropped here though the server keeps it as an own
+        // key, and headers["toString"] would hand a guard an inherited
+        // function where every other adapter gives undefined.
         const headers = lowercaseHeaderNames(Object.fromEntries(request.headers));
+        // A POST of another type is no API call on the server either: it
+        // goes on to MSW's other handlers and the network, as a non-envelope
+        // body does below, rather than working here and not in production.
+        if (!isApiCallContentType(headers))
+            return undefined;
+        // The cookies travel as `cookies` below, as the direct transport's do.
+        delete headers.cookie;
         const url = new URL(request.url);
         // Only the cookies whose scope covers this call, as a browser would
-        // send: reading the whole jar sent one host's session to another as
-        // soon as a jar was shared across hosts, and read cookies the request
-        // path was never in scope for. The host is the runtime's own, the path
-        // the one this call is going to. The jar's copies come first: where a
-        // name is in both, the jar holds what this runtime last set and the
-        // document's copy is the mirror of it, so the jar is the one to
-        // believe.
+        // send: the whole jar would send one host's session to another once a
+        // jar is shared across hosts, and cookies the request path is not in
+        // scope for. The host is the runtime's own, the path the one this call
+        // is going to. The jar's copies come first: where a name is in both,
+        // the jar holds what this runtime last set and the document's copy
+        // mirrors it, so the jar is the one to believe.
         const cookieScope = { host: mockApp.cookieHost, path: url.pathname };
         const cookies = cookieValuesByName(jar.cookiePairs(cookieScope));
         // Pair by pair, so a name the document holds at two scopes keeps both
         // values and the session controller can weigh them, as it does on
         // the server.
-        for (const [name, values] of Object.entries(cookieValuesByName((request.headers.get("cookie") ?? "").split(";")))) {
+        const pageCookies = typeof document === "undefined" ? "" : document.cookie;
+        for (const [name, values] of Object.entries(cookieValuesByName(pageCookies.split(";")))) {
             for (const value of values) {
                 if (!cookies[name]?.includes(value))
                     (cookies[name] ??= []).push(value);
@@ -105,12 +116,12 @@ export const lambderMockMswHandler = (mockApp, options) => {
         const setCookies = getAnswerHeader(answer.headers, "Set-Cookie") ?? [];
         jar.storeSetCookies(setCookies, cookieScope);
         // The cookies a page's own scripts may see are mirrored into
-        // document.cookie, so it reads the same in mocked development as it
-        // does against the real backend. Not decoration: the browser caller
-        // reads the CSRF token from there and posts it on the envelope, so
-        // without this every session call fails its CSRF check. Through the
-        // runtime, which is where the one mirror implementation lives and
-        // where what was planted is remembered for reset().
+        // document.cookie, so it reads the same in mocked development as
+        // against the real backend. Not decoration: the browser caller reads
+        // the CSRF token from there and posts it on the envelope, so without
+        // this every session call fails its CSRF check. Done by the runtime,
+        // which owns the one mirror implementation and remembers what was
+        // planted for reset().
         mockApp.mirrorCookiesIntoDocument(setCookies);
         const responseHeaders = new Headers();
         for (const [key, values] of Object.entries(answer.headers)) {