lambder 7.3.1 → 8.0.2

package/dist/shared/transport/LambderApiTransport.d.ts

@@ -16,9 +16,9 @@ export type LambderApiTransportRequest = {
     token: string;
     /**
      * The cookie name the caller reads that token from. A transport that
-     * fills the token in itself (the cookie-jar decorator, where there is no
-     * document to read) needs the same name, and taking it from the caller is
-     * what keeps the two from being configured apart.
+     * fills the token in itself (the cookie-jar decorator, with no document
+     * to read) needs the same name; taking it from the caller keeps the two
+     * from being configured apart.
      */
     csrfCookieKey?: string;
     siteHost: string;
@@ -36,10 +36,9 @@ export type LambderApiTransportRequest = {
 };
 /**
  * Why a transport could not deliver a call. `network` is the default reading
- * of a rejection: nothing came back. `protocol` says the call reached the
- * callee and no answer came of it, either because what came back was not one
- * or because the callee threw instead of answering, which is a server or
- * wiring fault and should not be reported to a developer as flaky
+ * of a rejection: nothing came back. `protocol` means the call reached the
+ * callee but produced no answer (what came back was not one, or the callee
+ * threw): a server or wiring fault, not to be reported as flaky
  * connectivity. `timeout` belongs to the caller, which knows whether its own
  * abort fired.
  */
@@ -60,27 +59,28 @@ export declare class LambderTransportFailure extends Error {
 export declare const isLambderTransportFailure: (err: unknown) => err is LambderTransportFailure;
 /**
  * Delivers one call and hands back the answer in the accessor form
- * resolveApiOutcome() reads. What a transport owes its caller, since nothing
- * but this contract stands between a call and a wrong outcome:
+ * resolveApiOutcome() reads. What a transport owes its caller:
  *
  * - **Any HTTP status is an answer.** A 4xx or 5xx resolves, status and body
  *   included, because resolveApiOutcome() is the one place that reads what a
- *   status means. A transport that rejects on a status throws away the
- *   envelope a refusal, a validation failure or a crash arrived in.
+ *   status means. Rejecting on a status would throw away the envelope a
+ *   refusal, a validation failure or a crash arrived in.
  * - **A rejection is a transport failure.** The caller reports it as
- *   `network` unless the transport threw a LambderTransportFailure naming
- *   another reason, or `timeout` when the caller's own abort fired. That is
- *   the channel for the real cause too: a LambderTransportFailure keeps it as
- *   `cause`, where the caller's `outcome.error` carries it.
+ *   `network`, as `timeout` when its own abort fired, or as the reason a
+ *   thrown LambderTransportFailure names. That failure's `cause` carries the
+ *   real error through to the caller's `outcome.error`.
  * - **`request.signal` must be honoured**, by rejecting as soon as it aborts.
- *   It is the only thing that makes the caller's `timeoutMs` and its per-call
- *   `signal` mean anything: a transport that ignores it leaves a call waiting
- *   for as long as the callee takes, whatever the caller asked for. Work
- *   already begun need not be cancellable (an in-process handler is not); the
- *   obligation is to stop waiting, not to stop the callee.
+ *   Without that, the caller's `timeoutMs` and per-call `signal` mean
+ *   nothing and a call waits as long as the callee takes. Work already begun
+ *   need not be cancellable (an in-process handler is not); the obligation
+ *   is to stop waiting, not to stop the callee.
  * - **Timeouts and retries belong to the caller.** A transport starts no
  *   clock of its own and retries nothing, so one call is one delivery
  *   attempt and an idempotency key means what it says.
+ * - **A transport that keeps the session's cookies itself reports its CSRF
+ *   tokens** on the answer (`csrfTokens`), the one it posted and a read of the
+ *   one it holds, since the caller otherwise judges a sessionExpired by
+ *   document.cookie, which such a transport never writes.
  *
  * Four transports ship: fetch (lambderFetchTransport, the browser default),
  * an in-process Lambder handler (lambderHandlerTransport, for tests), the
@@ -89,16 +89,16 @@ export declare const isLambderTransportFailure: (err: unknown) => err is Lambder
  */
 export type LambderApiTransport = (request: LambderApiTransportRequest) => Promise<LambderApiHttpAnswer>;
 /**
- * The fields of the request envelope, in the order they go on the wire: the
- * one statement of what a call sends, for every sender there is.
+ * The fields of the request envelope, in wire order: the one statement of
+ * what a call sends, for every sender.
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
- * its payload to decide whether to compress it, and splices that JSON onto the
- * end rather than parsing and stringifying it a second time
- * (buildEnvelopeJson, in invoke/LambderLambdaEvent.ts). The splice sits on top
- * of this function precisely so that a new envelope field cannot be added to
- * one sender and missed by the other, which nothing on the wire would catch.
+ * its payload to decide on compression, and splices that JSON onto the end
+ * rather than parsing and stringifying it again (buildEnvelopeJson, in
+ * invoke/LambderLambdaEvent.ts). The splice builds on this function so a new
+ * envelope field cannot reach one sender and miss the other, which nothing on
+ * the wire would catch.
  */
 export declare const buildEnvelopeFields: (fields: {
     apiName: string;

package/dist/shared/transport/LambderApiTransport.js

@@ -15,16 +15,16 @@ export class LambderTransportFailure extends Error {
 /** Brand-based type guard, so a duplicate install of the package still matches. */
 export const isLambderTransportFailure = (err) => err instanceof Error && err.isLambderTransportFailure === true;
 /**
- * The fields of the request envelope, in the order they go on the wire: the
- * one statement of what a call sends, for every sender there is.
+ * The fields of the request envelope, in wire order: the one statement of
+ * what a call sends, for every sender.
  *
  * Two senders write it. A transport hands the payload over as a value
  * (buildTransportEnvelope, below); LambderInvokeCaller has already serialized
- * its payload to decide whether to compress it, and splices that JSON onto the
- * end rather than parsing and stringifying it a second time
- * (buildEnvelopeJson, in invoke/LambderLambdaEvent.ts). The splice sits on top
- * of this function precisely so that a new envelope field cannot be added to
- * one sender and missed by the other, which nothing on the wire would catch.
+ * its payload to decide on compression, and splices that JSON onto the end
+ * rather than parsing and stringifying it again (buildEnvelopeJson, in
+ * invoke/LambderLambdaEvent.ts). The splice builds on this function so a new
+ * envelope field cannot reach one sender and miss the other, which nothing on
+ * the wire would catch.
  */
 export const buildEnvelopeFields = (fields) => ({
     apiName: fields.apiName,

package/dist/shared/transport/LambderCookieJar.d.ts

@@ -36,28 +36,23 @@ export declare const parseSetCookie: (header: string, now: number, requestPath?:
  * in-process handler transport in a Node test, and the mock runtime's direct
  * transport. It stores what an answer's Set-Cookie headers set, honours their
  * expiry and deletion, and hands back the Cookie pairs the next request should
- * carry. One jar is one browser; two jars are two.
+ * carry. One jar is one browser.
  *
- * The rules themselves are tough-cookie's, which is the reference
- * implementation of RFC 6265 and carries the public suffix list: domain and
- * path matching, default-path, Max-Age against Expires, Secure, HttpOnly, and
- * the __Host-/__Secure- prefixes. That list is the part worth importing rather
- * than writing. A hand-rolled check can tell that `Domain=com` is a registry
- * suffix by counting labels, and cannot tell that `co.uk` is one, so a
- * hand-rolled jar either trusts `Domain=co.uk` or bans every two-label domain.
+ * The rules (domain and path matching, default-path, Max-Age against Expires,
+ * Secure, HttpOnly, the __Host-/__Secure- prefixes) are tough-cookie's, the
+ * reference RFC 6265 implementation, imported for its public suffix list:
+ * counting labels can tell `Domain=com` is a registry suffix but not `co.uk`,
+ * so a hand-rolled jar either trusts `Domain=co.uk` or bans every two-label
+ * domain.
  *
- * What stays Lambder's is the shape of the questions a transport asks: whole
- * Set-Cookie header lists in (storeSetCookies), `name=value` pairs out
- * (cookiePairs), and a target given as a host and path rather than a URL,
- * since a transport that never speaks HTTP has no URL to give. A field the
- * caller omits is one it could not know, and an unknown field matches
- * anything: a jar pointed at a single host is the ordinary case, and refusing
- * to answer it until it can name that host would make the common setup the
- * awkward one.
+ * What stays Lambder's is the shape of a transport's questions: Set-Cookie
+ * header lists in (storeSetCookies), `name=value` pairs out (cookiePairs),
+ * and a target given as host and path, since a transport that never speaks
+ * HTTP has no URL. An omitted field matches anything, because a jar pointed
+ * at a single host is the ordinary case and should not have to name it.
  *
- * SameSite is stored but never consulted. It answers "did another site
- * initiate this", and a transport call has no initiating site: every call here
- * is same-site by construction.
+ * SameSite is stored but never consulted: it answers "did another site
+ * initiate this", and every transport call is same-site by construction.
  */
 export declare class LambderCookieJar {
     private readonly jar;
@@ -76,25 +71,24 @@ export declare class LambderCookieJar {
      * came from. Its `host` is the sending host, which every Domain is checked
      * against, and its `path` is the default Path of a cookie that names none.
      *
-     * A Domain the sender is not under does not narrow a cookie, it voids it
-     * (RFC 6265 section 5.3 step 6), and so does a Domain that is a public
-     * suffix. Both are how evil.example.com would otherwise plant a cookie
-     * that bank.example.com is handed on the next call.
+     * A Domain the sender is not under voids the cookie rather than narrowing
+     * it (RFC 6265 section 5.3 step 6), and so does a public-suffix Domain.
+     * Otherwise evil.example.com could plant a cookie that bank.example.com
+     * is handed on the next call.
      */
     storeSetCookies(headers: readonly string[], request?: LambderCookieTarget): void;
     /** Every live cookie. */
     list(): LambderStoredCookie[];
     /**
      * The Cookie header pairs the next request carries, as `name=value`, in
-     * the order RFC 6265 section 5.4 puts them in: the longest Path first,
-     * and among equal paths the one set first. Servers that read only the
-     * first value of a repeated name depend on that order, and so does any
-     * test reasoning about which of two same-named cookies wins.
+     * RFC 6265 section 5.4 order: longest Path first, and among equal paths
+     * the one set first. Servers that read only the first value of a repeated
+     * name depend on that order, as does any test about which of two
+     * same-named cookies wins.
      *
-     * Only the cookies whose scope covers the target travel. A field the
-     * target leaves out is one the caller could not know, and matches
-     * anything: a caller that cannot name its own host still gets the cookies
-     * of the one host its jar talks to.
+     * Only cookies whose scope covers the target travel. An omitted target
+     * field matches anything, so a caller that cannot name its host still
+     * gets the cookies of the one host its jar talks to.
      */
     cookiePairs(target?: LambderCookieTarget): string[];
     /**
@@ -107,10 +101,9 @@ export declare class LambderCookieJar {
     } & LambderCookieTarget): string | undefined;
     /**
      * The live cookies whose scope reaches this target, in RFC 6265 send
-     * order. Delegated to tough-cookie whenever the target names a host,
-     * which is the case worth getting exactly right; an unnamed host falls
-     * back to every cookie the jar holds, filtered by the rules that do not
-     * need one and ordered by the same rule.
+     * order. Delegated to tough-cookie whenever a host is known, the case
+     * worth getting exactly right; with no host, every cookie the jar holds
+     * is filtered by the rules that need none and ordered the same way.
      */
     private matchingCookies;
     /** Number of live cookies. */

package/dist/shared/transport/LambderCookieJar.js

@@ -6,10 +6,9 @@
 import { Cookie, CookieJar as ToughCookieJar, defaultPath, pathMatch } from "tough-cookie";
 /**
  * Stands in for the host of a jar that was never told one. Every store and
- * every read of such a jar uses it, so the jar is self-consistent: it behaves
- * as the browser of one unnamed host. `.invalid` is reserved by the IANA and
- * can never be a real name, so a cookie parked here can never match a real
- * target by accident.
+ * read of such a jar uses it, so the jar behaves consistently as the browser
+ * of one unnamed host. `.invalid` is IANA-reserved, so a cookie parked here
+ * can never match a real target by accident.
  */
 const UNNAMED_JAR_HOST = "lambder-cookie-jar.invalid";
 /** The host without its port, lowercased: "App.Test:3000" is "app.test", "[::1]:8080" is "[::1]". */
@@ -28,12 +27,11 @@ const urlFor = (host, path, secure) => `${secure ? "https" : "http"}://${host}${
 /**
  * When a cookie actually dies, as an absolute moment.
  *
- * Max-Age and Expires are stored separately and Max-Age wins, so reading the
- * `expires` field alone calls a `Max-Age=0` deletion immortal. The library's
- * own expiryTime() resolves Max-Age against whatever moment it is handed, and
- * against lastAccessed when handed nothing, so neither answers "when does this
- * die" on a fixed clock. A browser measures Max-Age from when the cookie
- * arrived, which is its creation.
+ * Max-Age and Expires are stored separately and Max-Age wins, so reading
+ * `expires` alone would call a `Max-Age=0` deletion immortal. The library's
+ * expiryTime() resolves Max-Age against whatever moment it is handed (or
+ * lastAccessed), so it cannot answer "when does this die" on a fixed clock.
+ * A browser measures Max-Age from when the cookie arrived, its creation.
  */
 const cookieExpiryAt = (cookie, now) => {
     if (typeof cookie.maxAge === "number") {
@@ -50,8 +48,8 @@ const storedFromCookie = (cookie, now) => {
         name: cookie.key ?? "",
         value: cookie.value ?? "",
         domain: hostOnly ? undefined : domain,
-        // A jar that never learned a host parked this under the stand-in,
-        // which is an implementation detail rather than something it knows.
+        // A jar that never learned a host parks cookies under the stand-in,
+        // an implementation detail rather than something it knows.
         ...(hostOnly && domain !== undefined && domain !== UNNAMED_JAR_HOST ? { host: domain } : {}),
         path: typeof cookie.path === "string" ? cookie.path : "/",
         expires: expiryAt,
@@ -68,11 +66,11 @@ export const parseSetCookie = (header, now, requestPath) => {
     const parsed = Cookie.parse(header, { loose: false });
     if (!parsed)
         return null;
-    // Cookie.parse stamps creation with the real clock, but the caller's `now`
-    // is the moment this header arrived, and Max-Age is measured from there.
+    // Cookie.parse stamps creation with the real clock, but Max-Age is
+    // measured from the caller's `now`, when this header arrived.
     parsed.creation = new Date(now);
-    // Resolve Max-Age against Expires on the caller's clock, the way the jar
-    // itself will, so a test moving time forward reads the same expiry here.
+    // Max-Age against Expires on the caller's clock, as the jar resolves it,
+    // so a test moving time forward reads the same expiry here.
     return {
         ...storedFromCookie(parsed, now),
         // Cookie.parse leaves an absent Path absent; the default-path is the
@@ -85,28 +83,23 @@ export const parseSetCookie = (header, now, requestPath) => {
  * in-process handler transport in a Node test, and the mock runtime's direct
  * transport. It stores what an answer's Set-Cookie headers set, honours their
  * expiry and deletion, and hands back the Cookie pairs the next request should
- * carry. One jar is one browser; two jars are two.
+ * carry. One jar is one browser.
  *
- * The rules themselves are tough-cookie's, which is the reference
- * implementation of RFC 6265 and carries the public suffix list: domain and
- * path matching, default-path, Max-Age against Expires, Secure, HttpOnly, and
- * the __Host-/__Secure- prefixes. That list is the part worth importing rather
- * than writing. A hand-rolled check can tell that `Domain=com` is a registry
- * suffix by counting labels, and cannot tell that `co.uk` is one, so a
- * hand-rolled jar either trusts `Domain=co.uk` or bans every two-label domain.
+ * The rules (domain and path matching, default-path, Max-Age against Expires,
+ * Secure, HttpOnly, the __Host-/__Secure- prefixes) are tough-cookie's, the
+ * reference RFC 6265 implementation, imported for its public suffix list:
+ * counting labels can tell `Domain=com` is a registry suffix but not `co.uk`,
+ * so a hand-rolled jar either trusts `Domain=co.uk` or bans every two-label
+ * domain.
  *
- * What stays Lambder's is the shape of the questions a transport asks: whole
- * Set-Cookie header lists in (storeSetCookies), `name=value` pairs out
- * (cookiePairs), and a target given as a host and path rather than a URL,
- * since a transport that never speaks HTTP has no URL to give. A field the
- * caller omits is one it could not know, and an unknown field matches
- * anything: a jar pointed at a single host is the ordinary case, and refusing
- * to answer it until it can name that host would make the common setup the
- * awkward one.
+ * What stays Lambder's is the shape of a transport's questions: Set-Cookie
+ * header lists in (storeSetCookies), `name=value` pairs out (cookiePairs),
+ * and a target given as host and path, since a transport that never speaks
+ * HTTP has no URL. An omitted field matches anything, because a jar pointed
+ * at a single host is the ordinary case and should not have to name it.
  *
- * SameSite is stored but never consulted. It answers "did another site
- * initiate this", and a transport call has no initiating site: every call here
- * is same-site by construction.
+ * SameSite is stored but never consulted: it answers "did another site
+ * initiate this", and every transport call is same-site by construction.
  */
 export class LambderCookieJar {
     // prefixSecurity "silent" drops a __Host-/__Secure- cookie that breaks its
@@ -129,25 +122,23 @@ export class LambderCookieJar {
      * came from. Its `host` is the sending host, which every Domain is checked
      * against, and its `path` is the default Path of a cookie that names none.
      *
-     * A Domain the sender is not under does not narrow a cookie, it voids it
-     * (RFC 6265 section 5.3 step 6), and so does a Domain that is a public
-     * suffix. Both are how evil.example.com would otherwise plant a cookie
-     * that bank.example.com is handed on the next call.
+     * A Domain the sender is not under voids the cookie rather than narrowing
+     * it (RFC 6265 section 5.3 step 6), and so does a public-suffix Domain.
+     * Otherwise evil.example.com could plant a cookie that bank.example.com
+     * is handed on the next call.
      */
     storeSetCookies(headers, request = {}) {
-        // The whole target, `secure` included: a cookie is judged against the
-        // channel it actually arrived on. Hardcoding https here accepted
-        // Secure cookies from a plain-http answer and then never sent one, so
-        // the jar held a session it could not use and said nothing.
+        // A cookie is judged against the channel it arrived on. Assuming https
+        // would accept Secure cookies from a plain-http answer and then never
+        // send them, leaving the jar silently holding an unusable session.
         const secure = request.secure !== false;
         const url = urlFor(this.hostFor(request.host), request.path, secure);
         const now = new Date(this.now());
         for (const header of headers) {
-            // tough-cookie checks the Domain, the prefixes and HttpOnly
-            // against the URL, but leaves the Secure attribute to the caller:
-            // RFC 6265 lets plain http set one and browsers stopped allowing
-            // it. A cookie this jar would refuse to send is one it refuses to
-            // keep.
+            // tough-cookie checks Domain, prefixes and HttpOnly against the
+            // URL but leaves Secure to the caller: RFC 6265 lets plain http
+            // set one, browsers do not. A cookie this jar would refuse to send
+            // is one it refuses to keep.
             if (!secure && Cookie.parse(header, { loose: false })?.secure)
                 continue;
             // ignoreError: a cookie a browser would refuse is one this jar
@@ -166,15 +157,14 @@ export class LambderCookieJar {
     }
     /**
      * The Cookie header pairs the next request carries, as `name=value`, in
-     * the order RFC 6265 section 5.4 puts them in: the longest Path first,
-     * and among equal paths the one set first. Servers that read only the
-     * first value of a repeated name depend on that order, and so does any
-     * test reasoning about which of two same-named cookies wins.
+     * RFC 6265 section 5.4 order: longest Path first, and among equal paths
+     * the one set first. Servers that read only the first value of a repeated
+     * name depend on that order, as does any test about which of two
+     * same-named cookies wins.
      *
-     * Only the cookies whose scope covers the target travel. A field the
-     * target leaves out is one the caller could not know, and matches
-     * anything: a caller that cannot name its own host still gets the cookies
-     * of the one host its jar talks to.
+     * Only cookies whose scope covers the target travel. An omitted target
+     * field matches anything, so a caller that cannot name its host still
+     * gets the cookies of the one host its jar talks to.
      */
     cookiePairs(target = {}) {
         return this.matchingCookies(target).map((cookie) => `${cookie.name}=${cookie.value}`);
@@ -190,10 +180,9 @@ export class LambderCookieJar {
     }
     /**
      * The live cookies whose scope reaches this target, in RFC 6265 send
-     * order. Delegated to tough-cookie whenever the target names a host,
-     * which is the case worth getting exactly right; an unnamed host falls
-     * back to every cookie the jar holds, filtered by the rules that do not
-     * need one and ordered by the same rule.
+     * order. Delegated to tough-cookie whenever a host is known, the case
+     * worth getting exactly right; with no host, every cookie the jar holds
+     * is filtered by the rules that need none and ordered the same way.
      */
     matchingCookies(target, includeHttpOnly = true) {
         const secure = target.secure !== false;
@@ -209,7 +198,7 @@ export class LambderCookieJar {
                 allPaths: target.path === undefined,
                 // tough-cookie returns store order unless asked; RFC 6265
                 // order is what a server reading the first of a repeated
-                // name actually gets.
+                // name gets.
                 sort: true,
             })
                 .map((cookie) => storedFromCookie(cookie, this.now()))
@@ -218,8 +207,8 @@ export class LambderCookieJar {
                 .filter((cookie) => cookie.expires === undefined || cookie.expires > this.now())
                 // tough-cookie treats a loopback or localhost target as a
                 // secure context and sends Secure cookies to it over http.
-                // This jar takes `secure: false` at its word in both
-                // directions, so what it stores and what it sends agree.
+                // This jar takes `secure: false` at its word both ways, so
+                // what it stores and what it sends agree.
                 .filter((cookie) => secure || !cookie.secure);
         }
         return this.list()
@@ -232,9 +221,8 @@ export class LambderCookieJar {
                 return false;
             return true;
         })
-            // The longest path first, as tough-cookie's own comparison does;
-            // the sort is stable, so equal paths keep the order they were
-            // stored in, which is the order they were created in.
+            // Longest path first, as tough-cookie sorts; the sort is stable,
+            // so equal paths keep their creation order.
             .sort((a, b) => b.path.length - a.path.length);
     }
     /** Number of live cookies. */

package/dist/shared/transport/lambderCookieJarTransport.d.ts

@@ -3,23 +3,21 @@ import type { LambderCookieJar } from "./LambderCookieJar.js";
 /**
  * Makes any transport carry a cookie jar the way a browser carries its
  * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
- * headers land in the jar, and, because a page's script reads the
- * non-HttpOnly CSRF cookie the same way, the request's `token` is filled
- * from the jar when the caller sent an empty one. This is how a session
- * survives between calls where there is no browser: in a Node test through
- * lambderHandlerTransport, or in the mock runtime's direct transport.
+ * headers land in the jar, and, as a page's script reads the non-HttpOnly
+ * CSRF cookie, the request's `token` is filled from the jar when the caller
+ * sent an empty one. This is how a session survives between calls without a
+ * browser: in a Node test through lambderHandlerTransport, or in the mock
+ * runtime's direct transport.
  *
  * The jar is only as scoped as the host it is told about. An absolute apiPath
  * carries one, `host` names one when the path is relative, and a browser's
- * caller falls back to its page's: an in-process or mock transport posts to a
- * relative path from a runtime with no location, so nothing there says which
- * host these cookies belong to. Without any of the three the jar is a single
- * host's, refusing Domain cookies it cannot check (see LambderCookieJar), so
- * give `host` (or the jar one) to any jar that more than one host answers
- * into.
+ * caller falls back to its page's; an in-process or mock transport posts to a
+ * relative path from a runtime with no location, so nothing there names the
+ * host. Without any of the three the jar is a single host's and refuses
+ * Domain cookies it cannot check (see LambderCookieJar), so give `host` (or
+ * the jar one) to any jar that more than one host answers into.
  *
- * Its own file rather than a passage inside the transport seam: it is a
- * transport like its three siblings, and it is the one of them that pulls in
+ * Its own file, like its three sibling transports, because it pulls in
  * tough-cookie, which a bundle that never carries a jar should be able to
  * drop.
  */

package/dist/shared/transport/lambderCookieJarTransport.js

@@ -3,23 +3,21 @@ import { resolveApiPathTarget } from "./LambderApiTransport.js";
 /**
  * Makes any transport carry a cookie jar the way a browser carries its
  * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
- * headers land in the jar, and, because a page's script reads the
- * non-HttpOnly CSRF cookie the same way, the request's `token` is filled
- * from the jar when the caller sent an empty one. This is how a session
- * survives between calls where there is no browser: in a Node test through
- * lambderHandlerTransport, or in the mock runtime's direct transport.
+ * headers land in the jar, and, as a page's script reads the non-HttpOnly
+ * CSRF cookie, the request's `token` is filled from the jar when the caller
+ * sent an empty one. This is how a session survives between calls without a
+ * browser: in a Node test through lambderHandlerTransport, or in the mock
+ * runtime's direct transport.
  *
  * The jar is only as scoped as the host it is told about. An absolute apiPath
  * carries one, `host` names one when the path is relative, and a browser's
- * caller falls back to its page's: an in-process or mock transport posts to a
- * relative path from a runtime with no location, so nothing there says which
- * host these cookies belong to. Without any of the three the jar is a single
- * host's, refusing Domain cookies it cannot check (see LambderCookieJar), so
- * give `host` (or the jar one) to any jar that more than one host answers
- * into.
+ * caller falls back to its page's; an in-process or mock transport posts to a
+ * relative path from a runtime with no location, so nothing there names the
+ * host. Without any of the three the jar is a single host's and refuses
+ * Domain cookies it cannot check (see LambderCookieJar), so give `host` (or
+ * the jar one) to any jar that more than one host answers into.
  *
- * Its own file rather than a passage inside the transport seam: it is a
- * transport like its three siblings, and it is the one of them that pulls in
+ * Its own file, like its three sibling transports, because it pulls in
  * tough-cookie, which a bundle that never carries a jar should be able to
  * drop.
  */
@@ -31,23 +29,23 @@ export const lambderCookieJarTransport = (inner, options) => {
         // through setSessionCookieKey.
         const csrfCookieKey = options.csrfCookieKey ?? request.csrfCookieKey ?? DEFAULT_SESSION_CSRF_COOKIE_KEY;
         // Where the call is going. An apiPath that names its own host is a
-        // fact about this request and outranks both the `host` option and the
-        // caller's siteHost: the option is the fallback for a relative path,
-        // where nothing says which host these cookies belong to, and siteHost
-        // is only the page the caller happens to be on. Read the other way
-        // round, a transport pinned to `host: "app.example.com"` sent
-        // app.example.com's session to an absolute cross-origin apiPath.
-        // siteHost is "" outside a browser, and an empty host would scope
-        // every cookie to nothing while claiming to scope it.
+        // fact about this request and outranks both the `host` option (the
+        // fallback for a relative path) and the caller's siteHost (only the
+        // page the caller is on). The other way round, a transport pinned to
+        // `host: "app.example.com"` would send that host's session to an
+        // absolute cross-origin apiPath. siteHost is "" outside a browser, and
+        // an empty host would scope every cookie to nothing while claiming to
+        // scope it.
         const target = resolveApiPathTarget(request.apiPath);
         const cookieScope = {
             host: target.host ?? options.host ?? (request.siteHost || undefined),
             path: target.path,
             ...(target.secure !== undefined ? { secure: target.secure } : {}),
         };
+        const postedToken = request.token || options.jar.get(csrfCookieKey, cookieScope) || "";
         const answer = await inner({
             ...request,
-            token: request.token || options.jar.get(csrfCookieKey, cookieScope) || "",
+            token: postedToken,
             cookies: [...(request.cookies ?? []), ...options.jar.cookiePairs(cookieScope)],
         });
         // The same scope the request was made under, so a Set-Cookie is judged
@@ -55,6 +53,9 @@ export const lambderCookieJarTransport = (inner, options) => {
         // plain-http target is one this jar could never send back.
         if (answer.setCookies?.length)
             options.jar.storeSetCookies(answer.setCookies, cookieScope);
-        return answer;
+        // The session lives in the jar, not in document.cookie, so the caller
+        // tells a sessionExpired about an older session (a poll sent before a
+        // login) by the jar's token, as a page does by its cookie.
+        return { ...answer, csrfTokens: { posted: postedToken, held: () => options.jar.get(csrfCookieKey, cookieScope) ?? "" } };
     };
 };

package/dist/shared/util/LambderCallAbort.d.ts

@@ -5,10 +5,9 @@
  * Both give a call a `timeoutMs`, both let the site pass its own AbortSignal,
  * and both have to answer the same three questions: which signal does the
  * transport get, has the call already been given up on before it is sent, and
- * did the answer arrive after it was given up on. Written twice, the two
- * drifted: the browser caller learned not to believe a late answer and the
- * invoke caller did not, so a 20ms timeoutMs there reported `ok: true` at
- * 300ms and the call site acted on data it had already abandoned.
+ * did the answer arrive after it was given up on. One implementation keeps
+ * the two from drifting apart: a caller that believed a late answer would
+ * report `ok: true` for a call its site had already abandoned.
  *
  * The listener on an external signal is removed in detach() rather than left
  * to `once`: a site's signal usually outlives the call (one controller per
@@ -53,7 +52,8 @@ export declare const createCallAbort: (options: {
  * the callee runs to completion either way, and what the caller's timeout
  * buys is its own answer. Used by lambderHandlerTransport and by
  * LambderInvokeCaller.localTransport, whose in-process calls are the two
- * places a signal has nothing to cancel.
+ * transports a signal has nothing to cancel, and by the crash reporter's
+ * time bound (LambderCrashHandling), where the app's report runs on.
  *
  * The listener is detached on either outcome, for the reason createCallAbort
  * detaches its own.

package/dist/shared/util/LambderCallAbort.js

@@ -5,10 +5,9 @@
  * Both give a call a `timeoutMs`, both let the site pass its own AbortSignal,
  * and both have to answer the same three questions: which signal does the
  * transport get, has the call already been given up on before it is sent, and
- * did the answer arrive after it was given up on. Written twice, the two
- * drifted: the browser caller learned not to believe a late answer and the
- * invoke caller did not, so a 20ms timeoutMs there reported `ok: true` at
- * 300ms and the call site acted on data it had already abandoned.
+ * did the answer arrive after it was given up on. One implementation keeps
+ * the two from drifting apart: a caller that believed a late answer would
+ * report `ok: true` for a call its site had already abandoned.
  *
  * The listener on an external signal is removed in detach() rather than left
  * to `once`: a site's signal usually outlives the call (one controller per
@@ -64,7 +63,8 @@ export const createCallAbort = (options) => {
  * the callee runs to completion either way, and what the caller's timeout
  * buys is its own answer. Used by lambderHandlerTransport and by
  * LambderInvokeCaller.localTransport, whose in-process calls are the two
- * places a signal has nothing to cancel.
+ * transports a signal has nothing to cancel, and by the crash reporter's
+ * time bound (LambderCrashHandling), where the app's report runs on.
  *
  * The listener is detached on either outcome, for the reason createCallAbort
  * detaches its own.