@speedkit/cli 4.38.0 → 4.39.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,19 @@
1
+ # [4.39.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.38.1...v4.39.0) (2026-10-02)
2
+
3
+
4
+ ### Features
5
+
6
+ * **document-handler:** route the vm console through the CLI ([1cf03b9](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/1cf03b98cfb5af2537736882687a31f8000948e3))
7
+ * **onboarding:** hint to start the pre-renderer when SSR cannot reach it ([46cd19e](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/46cd19ef19ff6c53289cccc3002bb519d235d25d))
8
+ * **onboarding:** report a failed pre-render as an error in one line ([e1880b8](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/e1880b8d85227ecfd7d4d9ec1214542c236ddf7d))
9
+
10
+ ## [4.38.1](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.38.0...v4.38.1) (2026-10-02)
11
+
12
+
13
+ ### Bug Fixes
14
+
15
+ * **onboarding:** adapt errors regarding missing serverConfig ([aa0694b](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/aa0694b852030673bdbe32e92900004d730e4e02))
16
+
1
17
  # [4.38.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.37.0...v4.38.0) (2026-10-02)
2
18
 
3
19
 
@@ -56,3 +56,47 @@ export declare const ABORT_SERVER_TIMING = "errorcode;desc=303";
56
56
  * @param error - Error to classify.
57
57
  */
58
58
  export declare function isDocumentHandlerAbort(error?: Error): boolean;
59
+ /**
60
+ * Port the Document Handler posts SSR requests to when neither `NATS_URL` nor
61
+ * `preRender.lambdaUrl` is set (`requestViaLocal` in the document-handler's
62
+ * `SsrService.ts`). Locally that is the puppeteer-lambda pre-renderer.
63
+ */
64
+ export declare const LOCAL_PRERENDERER_PORT = 3001;
65
+ /**
66
+ * Whether an error is a refused connection to the local pre-renderer — the `TypeError:
67
+ * fetch failed` that `fetch` throws when nothing listens on {@link LOCAL_PRERENDERER_PORT}.
68
+ * The refused connection sits in the error's `cause`. The error comes from the `vm`
69
+ * context, so it is matched by shape, not by class.
70
+ *
71
+ * @param error - Any value; only an error with that cause matches.
72
+ */
73
+ export declare function isRefusedByLocalPrerenderer(error: unknown): boolean;
74
+ /**
75
+ * Whether an abort means SSR could not reach the local pre-renderer at all.
76
+ *
77
+ * The Document Handler wraps a failed SSR fetch as `Abort(error.toString(), { url,
78
+ * variation, error })`, so the fetch error is the abort's `data.error`.
79
+ *
80
+ * @param error - Error the Document Handler run failed with.
81
+ */
82
+ export declare function isLocalPrerendererUnreachable(error?: Error): boolean;
83
+ /** The payload of the abort the Document Handler throws when the pre-renderer answers non-200. */
84
+ export interface PrerenderFailure {
85
+ url: string;
86
+ variation: string;
87
+ /** Status the pre-renderer answered with. */
88
+ status: number;
89
+ /** The pre-renderer's `x-render-error`, e.g. a selector it waited for in vain. */
90
+ detailMessage: string | null;
91
+ }
92
+ /**
93
+ * The pre-renderer's failure, when an abort means it ran but could not render the page.
94
+ *
95
+ * `handleSSRResponse` in the document-handler's `SsrService.ts` throws
96
+ * `Abort(detailMessage, { url, variation, status, detailMessage })` for a non-200
97
+ * answer, and the SSR step re-throws it unchanged. Matched by shape, like every
98
+ * error from the `vm`.
99
+ *
100
+ * @param error - Error the Document Handler run failed with, or a value it logged.
101
+ */
102
+ export declare function prerenderFailure(error: unknown): PrerenderFailure | undefined;
@@ -64,3 +64,51 @@ export function isDocumentHandlerAbort(error) {
64
64
  }
65
65
  return (error.name === "Abort" || error.isAbort === true);
66
66
  }
67
+ /**
68
+ * Port the Document Handler posts SSR requests to when neither `NATS_URL` nor
69
+ * `preRender.lambdaUrl` is set (`requestViaLocal` in the document-handler's
70
+ * `SsrService.ts`). Locally that is the puppeteer-lambda pre-renderer.
71
+ */
72
+ export const LOCAL_PRERENDERER_PORT = 3001;
73
+ /**
74
+ * Whether an error is a refused connection to the local pre-renderer — the `TypeError:
75
+ * fetch failed` that `fetch` throws when nothing listens on {@link LOCAL_PRERENDERER_PORT}.
76
+ * The refused connection sits in the error's `cause`. The error comes from the `vm`
77
+ * context, so it is matched by shape, not by class.
78
+ *
79
+ * @param error - Any value; only an error with that cause matches.
80
+ */
81
+ export function isRefusedByLocalPrerenderer(error) {
82
+ const cause = error?.cause;
83
+ return (cause?.code === "ECONNREFUSED" && cause?.port === LOCAL_PRERENDERER_PORT);
84
+ }
85
+ /**
86
+ * Whether an abort means SSR could not reach the local pre-renderer at all.
87
+ *
88
+ * The Document Handler wraps a failed SSR fetch as `Abort(error.toString(), { url,
89
+ * variation, error })`, so the fetch error is the abort's `data.error`.
90
+ *
91
+ * @param error - Error the Document Handler run failed with.
92
+ */
93
+ export function isLocalPrerendererUnreachable(error) {
94
+ return isRefusedByLocalPrerenderer(error?.data?.error);
95
+ }
96
+ /**
97
+ * The pre-renderer's failure, when an abort means it ran but could not render the page.
98
+ *
99
+ * `handleSSRResponse` in the document-handler's `SsrService.ts` throws
100
+ * `Abort(detailMessage, { url, variation, status, detailMessage })` for a non-200
101
+ * answer, and the SSR step re-throws it unchanged. Matched by shape, like every
102
+ * error from the `vm`.
103
+ *
104
+ * @param error - Error the Document Handler run failed with, or a value it logged.
105
+ */
106
+ export function prerenderFailure(error) {
107
+ const data = error?.data;
108
+ if (typeof data?.url !== "string" ||
109
+ typeof data.status !== "number" ||
110
+ !("detailMessage" in data)) {
111
+ return undefined;
112
+ }
113
+ return data;
114
+ }
@@ -0,0 +1,45 @@
1
+ import { CliServiceInterface } from "../cli/index.js";
2
+ /**
3
+ * The `console` the customer's Document Handler sees inside the `vm`.
4
+ *
5
+ * Output goes through the CLI, prefixed with where it came from. `warn` and `error`
6
+ * are always shown; everything else only with `--verboseLevel`. Without a console of
7
+ * its own, a `vm` context falls back to V8's, which writes only to an attached
8
+ * inspector — so a Document Handler warning used to vanish unless `-v` was set.
9
+ *
10
+ * The Document Handler's own SSR warnings are dropped when the abort that follows
11
+ * reports the same failure in one line: a refused connection to the local
12
+ * pre-renderer, or a pre-renderer that could not render the page. The warning would
13
+ * add a full stack trace on every page.
14
+ */
15
+ export declare class DocumentHandlerConsole {
16
+ private readonly cli;
17
+ private readonly prefix;
18
+ private readonly verbose;
19
+ /**
20
+ * @param cli - Where the output goes.
21
+ * @param prefix - Marks the source of each line, e.g. `documentHandler`.
22
+ * @param verbose - Whether `log`, `info`, `debug` and the rest are shown.
23
+ */
24
+ constructor(cli: CliServiceInterface, prefix: string, verbose?: boolean);
25
+ error: (...logArguments: unknown[]) => void;
26
+ warn: (...logArguments: unknown[]) => void;
27
+ log: (...logArguments: unknown[]) => void;
28
+ info: (...logArguments: unknown[]) => void;
29
+ debug: (...logArguments: unknown[]) => void;
30
+ trace: (...logArguments: unknown[]) => void;
31
+ dir: (...logArguments: unknown[]) => void;
32
+ table: (...logArguments: unknown[]) => void;
33
+ time: (...logArguments: unknown[]) => void;
34
+ timeEnd: (...logArguments: unknown[]) => void;
35
+ timeLog: (...logArguments: unknown[]) => void;
36
+ count: (...logArguments: unknown[]) => void;
37
+ countReset: (...logArguments: unknown[]) => void;
38
+ group: (...logArguments: unknown[]) => void;
39
+ groupCollapsed: (...logArguments: unknown[]) => void;
40
+ groupEnd: (...logArguments: unknown[]) => void;
41
+ assert: (...logArguments: unknown[]) => void;
42
+ private native;
43
+ private isKnownNoise;
44
+ private format;
45
+ }
@@ -0,0 +1,81 @@
1
+ import { format } from "node:util";
2
+ import { isRefusedByLocalPrerenderer, prerenderFailure, } from "./document-handler-abort.js";
3
+ /**
4
+ * The `console` the customer's Document Handler sees inside the `vm`.
5
+ *
6
+ * Output goes through the CLI, prefixed with where it came from. `warn` and `error`
7
+ * are always shown; everything else only with `--verboseLevel`. Without a console of
8
+ * its own, a `vm` context falls back to V8's, which writes only to an attached
9
+ * inspector — so a Document Handler warning used to vanish unless `-v` was set.
10
+ *
11
+ * The Document Handler's own SSR warnings are dropped when the abort that follows
12
+ * reports the same failure in one line: a refused connection to the local
13
+ * pre-renderer, or a pre-renderer that could not render the page. The warning would
14
+ * add a full stack trace on every page.
15
+ */
16
+ export class DocumentHandlerConsole {
17
+ cli;
18
+ prefix;
19
+ verbose;
20
+ /**
21
+ * @param cli - Where the output goes.
22
+ * @param prefix - Marks the source of each line, e.g. `documentHandler`.
23
+ * @param verbose - Whether `log`, `info`, `debug` and the rest are shown.
24
+ */
25
+ constructor(cli, prefix, verbose = false) {
26
+ this.cli = cli;
27
+ this.prefix = prefix;
28
+ this.verbose = verbose;
29
+ }
30
+ error = (...logArguments) => {
31
+ if (!this.isKnownNoise(logArguments)) {
32
+ this.cli.writeError(this.format(logArguments));
33
+ }
34
+ };
35
+ warn = (...logArguments) => {
36
+ if (!this.isKnownNoise(logArguments)) {
37
+ this.cli.writeWarning(this.format(logArguments));
38
+ }
39
+ };
40
+ log = (...logArguments) => {
41
+ if (this.verbose) {
42
+ this.cli.write(this.format(logArguments));
43
+ }
44
+ };
45
+ info = this.log;
46
+ debug = (...logArguments) => {
47
+ if (this.verbose) {
48
+ this.cli.comment(this.format(logArguments));
49
+ }
50
+ };
51
+ trace = this.debug;
52
+ dir = this.debug;
53
+ table = this.log;
54
+ // Counters, timers and groups only make sense on the real console; they are
55
+ // accepted so a Document Handler calling them does not throw, and only take
56
+ // effect with `--verboseLevel`.
57
+ time = this.native("time");
58
+ timeEnd = this.native("timeEnd");
59
+ timeLog = this.native("timeLog");
60
+ count = this.native("count");
61
+ countReset = this.native("countReset");
62
+ group = this.native("group");
63
+ groupCollapsed = this.native("groupCollapsed");
64
+ groupEnd = this.native("groupEnd");
65
+ assert = this.native("assert");
66
+ native(method) {
67
+ return (...logArguments) => {
68
+ if (this.verbose) {
69
+ // eslint-disable-next-line no-console -- timers and groups keep their state on the real console
70
+ console[method](...logArguments);
71
+ }
72
+ };
73
+ }
74
+ isKnownNoise(logArguments) {
75
+ return logArguments.some((argument) => isRefusedByLocalPrerenderer(argument) ||
76
+ prerenderFailure(argument) !== undefined);
77
+ }
78
+ format(logArguments) {
79
+ return `[${this.prefix}]: ${format(...logArguments)}`;
80
+ }
81
+ }
@@ -8,6 +8,7 @@ import fetch from "node-fetch";
8
8
  import { Request } from "./server/request.js";
9
9
  import { DocumentHandlerResponse } from "./server/document-handler-response.js";
10
10
  import { DocumentHandlerAbort } from "./document-handler-abort.js";
11
+ import { DocumentHandlerConsole } from "./document-handler-console.js";
11
12
  import { safe } from "../../helpers/safe.js";
12
13
  import { VmEmptyResponseError } from "../onboarding/error/vm-empty-response-error.js";
13
14
  import { DocumentHandlerTransformError } from "../onboarding/error/document-handler-transform-error.js";
@@ -144,26 +145,7 @@ export class DocumentHandlerServer {
144
145
  return contextVariables;
145
146
  }
146
147
  async createDataBaseMock() {
147
- const vmConsole = {
148
- log: (...logArguments) => {
149
- // eslint-disable-next-line @typescript-eslint/no-unused-expressions
150
- this.verboseLevel
151
- ? this.cli.write(`[documentHandler.dbLog]: ${JSON.stringify(logArguments)}`)
152
- : "";
153
- },
154
- info: (...logArguments) => {
155
- // eslint-disable-next-line @typescript-eslint/no-unused-expressions
156
- this.verboseLevel
157
- ? this.cli.writeWarning(`[documentHandler.dbLog]: ${JSON.stringify(logArguments)}`)
158
- : "";
159
- },
160
- error: (...logArguments) => {
161
- // eslint-disable-next-line @typescript-eslint/no-unused-expressions
162
- this.verboseLevel
163
- ? this.cli.writeError(`[documentHandler.dbLog]: ${JSON.stringify(logArguments)}`)
164
- : "";
165
- },
166
- };
148
+ const vmConsole = new DocumentHandlerConsole(this.cli, "documentHandler.dbLog", this.verboseLevel);
167
149
  if (!this.database) {
168
150
  const dataBaseMock = new DatabaseMock();
169
151
  const databaseCode = dataBaseMock.render(dataBaseMock.create(this.customerConfig.origins[0], this.customerConfig.app));
@@ -193,10 +175,8 @@ export class DocumentHandlerServer {
193
175
  TextEncoder,
194
176
  TextDecoder,
195
177
  module: { exports: {} },
178
+ console: new DocumentHandlerConsole(this.cli, "documentHandler", this.verboseLevel),
196
179
  };
197
- if (this.verboseLevel) {
198
- context["console"] = console;
199
- }
200
180
  return context;
201
181
  }
202
182
  /**
@@ -1,6 +1,6 @@
1
1
  import { expect } from "chai";
2
2
  import { describe, it } from "mocha";
3
- import { ABORT_ERROR_CODE, ABORT_SERVER_TIMING, ABORT_STATUS_CODE, DocumentHandlerAbort, isDocumentHandlerAbort, } from "../document-handler-abort.js";
3
+ import { ABORT_ERROR_CODE, ABORT_SERVER_TIMING, ABORT_STATUS_CODE, DocumentHandlerAbort, isDocumentHandlerAbort, isLocalPrerendererUnreachable, LOCAL_PRERENDERER_PORT, prerenderFailure, } from "../document-handler-abort.js";
4
4
  import { DocumentHandlerTransformError } from "../../onboarding/error/document-handler-transform-error.js";
5
5
  /**
6
6
  * Mirrors the service worker's `parseServerTimingHeader`, so the header this module
@@ -64,6 +64,62 @@ describe("DocumentHandlerTransformError", () => {
64
64
  expect(isDocumentHandlerAbort(wrapped)).to.equal(false);
65
65
  });
66
66
  });
67
+ /**
68
+ * Builds the abort the Document Handler's `SsrService` throws when its SSR fetch fails.
69
+ */
70
+ function ssrFetchAbort(cause) {
71
+ const error = new TypeError("fetch failed", { cause });
72
+ return new DocumentHandlerAbort(error.toString(), {
73
+ url: "https://www.example.com/",
74
+ variation: "default",
75
+ error,
76
+ });
77
+ }
78
+ describe("isLocalPrerendererUnreachable", () => {
79
+ const refused = {
80
+ code: "ECONNREFUSED",
81
+ address: "127.0.0.1",
82
+ port: LOCAL_PRERENDERER_PORT,
83
+ };
84
+ it("recognises a refused connection to the local pre-renderer", () => {
85
+ expect(isLocalPrerendererUnreachable(ssrFetchAbort(refused))).to.equal(true);
86
+ });
87
+ it("still recognises it once the abort is wrapped on its way out of the vm", () => {
88
+ const wrapped = new DocumentHandlerTransformError(ssrFetchAbort(refused));
89
+ expect(isLocalPrerendererUnreachable(wrapped)).to.equal(true);
90
+ });
91
+ it("ignores a refused connection to another port", () => {
92
+ expect(isLocalPrerendererUnreachable(ssrFetchAbort({ ...refused, port: 443 }))).to.equal(false);
93
+ });
94
+ it("ignores other SSR failures and other aborts", () => {
95
+ expect(isLocalPrerendererUnreachable(ssrFetchAbort({ ...refused, code: "ETIMEDOUT" }))).to.equal(false);
96
+ expect(isLocalPrerendererUnreachable(new DocumentHandlerAbort("blacklisted"))).to.equal(false);
97
+ expect(isLocalPrerendererUnreachable(new Error("boom"))).to.equal(false);
98
+ expect(isLocalPrerendererUnreachable(undefined)).to.equal(false);
99
+ });
100
+ });
101
+ describe("prerenderFailure", () => {
102
+ const failure = {
103
+ url: "https://www.example.com/sale/",
104
+ variation: "default",
105
+ status: 500,
106
+ detailMessage: "TimeoutError: Waiting for selector `.grid` failed",
107
+ };
108
+ it("reads the failure from the abort a non-200 pre-render throws", () => {
109
+ const abort = new DocumentHandlerAbort(failure.detailMessage, failure);
110
+ expect(prerenderFailure(abort)).to.deep.equal(failure);
111
+ });
112
+ it("still reads it once the abort is wrapped on its way out of the vm", () => {
113
+ const wrapped = new DocumentHandlerTransformError(new DocumentHandlerAbort(failure.detailMessage, failure));
114
+ expect(prerenderFailure(wrapped)).to.deep.equal(failure);
115
+ });
116
+ it("ignores a failed SSR fetch, other aborts and plain errors", () => {
117
+ expect(prerenderFailure(ssrFetchAbort({ code: "ECONNREFUSED", port: LOCAL_PRERENDERER_PORT }))).to.equal(undefined);
118
+ expect(prerenderFailure(new DocumentHandlerAbort("blacklisted", { url: "/a" }))).to.equal(undefined);
119
+ expect(prerenderFailure(new Error("boom"))).to.equal(undefined);
120
+ expect(prerenderFailure(undefined)).to.equal(undefined);
121
+ });
122
+ });
67
123
  describe("ABORT_SERVER_TIMING", () => {
68
124
  it("sends the error code under the metric name Baqend uses", () => {
69
125
  const metrics = parseServerTiming(ABORT_SERVER_TIMING);
@@ -0,0 +1,97 @@
1
+ import { expect } from "chai";
2
+ import { describe, it } from "mocha";
3
+ import * as vm from "node:vm";
4
+ import { DocumentHandlerConsole } from "../document-handler-console.js";
5
+ import { DocumentHandlerAbort, LOCAL_PRERENDERER_PORT, } from "../document-handler-abort.js";
6
+ /** A CLI that records every line it is asked to print, tagged with its level. */
7
+ function recordingCli() {
8
+ const lines = [];
9
+ const record = (level) => (message) => lines.push(`${level} ${message}`);
10
+ const cli = {
11
+ write: record("write"),
12
+ comment: record("comment"),
13
+ writeWarning: record("warning"),
14
+ writeError: record("error"),
15
+ };
16
+ return { lines, cli };
17
+ }
18
+ function refusedByPrerenderer() {
19
+ return new TypeError("fetch failed", {
20
+ cause: { code: "ECONNREFUSED", port: LOCAL_PRERENDERER_PORT },
21
+ });
22
+ }
23
+ describe("DocumentHandlerConsole", () => {
24
+ it("always shows warnings and errors, prefixed", () => {
25
+ const { lines, cli } = recordingCli();
26
+ const vmConsole = new DocumentHandlerConsole(cli, "documentHandler");
27
+ vmConsole.warn("slow", 12);
28
+ vmConsole.error("broken");
29
+ expect(lines).to.deep.equal([
30
+ "warning [documentHandler]: slow 12",
31
+ "error [documentHandler]: broken",
32
+ ]);
33
+ });
34
+ it("shows log, info and debug only when verbose", () => {
35
+ const quiet = recordingCli();
36
+ const quietConsole = new DocumentHandlerConsole(quiet.cli, "dh");
37
+ quietConsole.log("a");
38
+ quietConsole.info("b");
39
+ quietConsole.debug("c");
40
+ const verbose = recordingCli();
41
+ const verboseConsole = new DocumentHandlerConsole(verbose.cli, "dh", true);
42
+ verboseConsole.log("a");
43
+ verboseConsole.info("b");
44
+ verboseConsole.debug("c");
45
+ expect(quiet.lines).to.deep.equal([]);
46
+ expect(verbose.lines).to.deep.equal([
47
+ "write [dh]: a",
48
+ "write [dh]: b",
49
+ "comment [dh]: c",
50
+ ]);
51
+ });
52
+ it("drops the SSR warning about a refused pre-renderer connection", () => {
53
+ const { lines, cli } = recordingCli();
54
+ const vmConsole = new DocumentHandlerConsole(cli, "dh", true);
55
+ vmConsole.warn("SSR errored after 0.04s of default - https://www.example.com/", refusedByPrerenderer());
56
+ expect(lines).to.deep.equal([]);
57
+ });
58
+ it("drops the SSR warning about a page the pre-renderer could not render", () => {
59
+ const { lines, cli } = recordingCli();
60
+ const vmConsole = new DocumentHandlerConsole(cli, "dh");
61
+ const detailMessage = "TimeoutError: Waiting for selector `.grid` failed";
62
+ vmConsole.warn("SSR errored after 8.566s of default - https://www.example.com/sale/", new DocumentHandlerAbort(detailMessage, {
63
+ url: "https://www.example.com/sale/",
64
+ variation: "default",
65
+ status: 500,
66
+ detailMessage,
67
+ }));
68
+ expect(lines).to.deep.equal([]);
69
+ });
70
+ it("keeps a refused connection to any other port", () => {
71
+ const { lines, cli } = recordingCli();
72
+ const vmConsole = new DocumentHandlerConsole(cli, "dh");
73
+ vmConsole.warn(new TypeError("fetch failed", {
74
+ cause: { code: "ECONNREFUSED", port: 443 },
75
+ }));
76
+ expect(lines).to.have.length(1);
77
+ expect(lines[0]).to.match(/^warning \[dh\]: TypeError: fetch failed/);
78
+ });
79
+ it("does not throw on the rest of the console API", () => {
80
+ const { cli } = recordingCli();
81
+ const vmConsole = new DocumentHandlerConsole(cli, "dh");
82
+ expect(() => {
83
+ vmConsole.time("t");
84
+ vmConsole.timeEnd("t");
85
+ vmConsole.group("g");
86
+ vmConsole.groupEnd();
87
+ vmConsole.table([{ a: 1 }]);
88
+ vmConsole.assert(true);
89
+ }).not.to.throw();
90
+ });
91
+ it("is what Document Handler code reaches as console inside the vm", () => {
92
+ const { lines, cli } = recordingCli();
93
+ const vmConsole = new DocumentHandlerConsole(cli, "documentHandler");
94
+ vm.runInNewContext("console.warn('from the vm')", { console: vmConsole });
95
+ expect(lines).to.deep.equal(["warning [documentHandler]: from the vm"]);
96
+ });
97
+ });
@@ -5,5 +5,7 @@ export declare class DocumentHandlerTransformError extends Error {
5
5
  * original prototype, so the flag has to be carried explicitly.
6
6
  */
7
7
  readonly isAbort: boolean;
8
+ /** The abort payload, carried over so the caller can tell why the Document Handler stopped. */
9
+ readonly data?: unknown;
8
10
  constructor(error: Error);
9
11
  }
@@ -6,10 +6,13 @@ export class DocumentHandlerTransformError extends Error {
6
6
  * original prototype, so the flag has to be carried explicitly.
7
7
  */
8
8
  isAbort;
9
+ /** The abort payload, carried over so the caller can tell why the Document Handler stopped. */
10
+ data;
9
11
  constructor(error) {
10
12
  super(error.message);
11
13
  this.stack = error.stack;
12
14
  this.cause = error.cause;
13
15
  this.isAbort = isDocumentHandlerAbort(error);
16
+ this.data = error.data;
14
17
  }
15
18
  }
@@ -267,6 +267,9 @@ export class OnboardingServiceFactory {
267
267
  const serverConfigResult = await safe(configApi.getServerConfig());
268
268
  if (serverConfigResult.success !== true) {
269
269
  cli.failAction("ONBOARDING:FETCH:RUNTIME_CONFIG");
270
+ // Everything the runtime config alone carries is gone for this session, including any
271
+ // override of a device variation. Those still resolve, from their built-in defaults only.
272
+ cli.writeWarning("without the runtime config, origin fetches carry no basic auth, no custom variation and no configured override of default, mobile or tablet — those fall back to the built-in defaults. Are you logged in?");
270
273
  return;
271
274
  }
272
275
  cli.successAction("ONBOARDING:FETCH:RUNTIME_CONFIG");
@@ -45,11 +45,31 @@ describe("Crawler.fetchRemote", () => {
45
45
  expect(result).to.not.equal(undefined);
46
46
  expect(await result.response.text()).to.equal("origin");
47
47
  });
48
- it("fetches an origin when no runtime config loaded at all", async () => {
48
+ it("stays quiet about a device variation without a runtime config", async () => {
49
49
  const { cli, warnings } = stubCli();
50
+ // default, mobile and tablet fall back to their built-in defaults, so the fetch still
51
+ // resolves. Any override the runtime config would carry for them is lost, but the failed
52
+ // config load reports that itself.
50
53
  const result = await new Crawler(cli, undefined).fetchRemote(url, "DEFAULT");
51
54
  expect(await result.response.text()).to.equal("origin");
52
- expect(warnings.join(" ")).to.contain("no variations available");
55
+ expect(warnings).to.deep.equal([]);
56
+ });
57
+ it("names the defined variations when a custom one is missing", async () => {
58
+ const { cli, warnings } = stubCli();
59
+ const serverConfig = {
60
+ speedKit: { variations: { "*": { headers: {} }, "store-de": {} } },
61
+ };
62
+ const crawler = new Crawler(cli, serverConfig);
63
+ await crawler.fetchRemote(url, "store-ch");
64
+ await crawler.fetchRemote(url, "store-ch");
65
+ expect(warnings).to.have.lengthOf(1);
66
+ expect(warnings[0]).to.contain("variation store-ch is not defined");
67
+ expect(warnings[0]).to.contain("defined are: *, store-de");
68
+ });
69
+ it("says the runtime config defines no variations at all", async () => {
70
+ const { cli, warnings } = stubCli();
71
+ await new Crawler(cli, undefined).fetchRemote(url, "store-ch");
72
+ expect(warnings.join(" ")).to.contain("it defines no variations at all");
53
73
  });
54
74
  describe("a runtime config that sets Accept-Language to null", () => {
55
75
  const withVariations = (variations) => ({ speedKit: { variations } });
@@ -21,8 +21,10 @@ export declare class Crawler {
21
21
  * templates with their `${group}` substitution, and the query params.
22
22
  *
23
23
  * Two things stay local: origin basic auth, which no variation carries, and tolerance for a
24
- * variation the config does not define — the server rejects that request, but failing a whole
25
- * onboarding session over it would be unhelpful, so it falls back to the base headers and warns.
24
+ * custom variation the config does not define — the server rejects that request, but failing a
25
+ * whole onboarding session over it would be unhelpful, so it falls back to the base headers and
26
+ * warns once. A missing runtime config is not reported here; the fetch that failed to load it
27
+ * says what it costs.
26
28
  */
27
29
  private prepareOriginRequest;
28
30
  private prepareAuthRequest;
@@ -42,24 +42,29 @@ export class Crawler {
42
42
  * templates with their `${group}` substitution, and the query params.
43
43
  *
44
44
  * Two things stay local: origin basic auth, which no variation carries, and tolerance for a
45
- * variation the config does not define — the server rejects that request, but failing a whole
46
- * onboarding session over it would be unhelpful, so it falls back to the base headers and warns.
45
+ * custom variation the config does not define — the server rejects that request, but failing a
46
+ * whole onboarding session over it would be unhelpful, so it falls back to the base headers and
47
+ * warns once. A missing runtime config is not reported here; the fetch that failed to load it
48
+ * says what it costs.
47
49
  */
48
50
  prepareOriginRequest(originUrl, variationParameter) {
49
51
  const variations = this.speedKitServerConfig?.speedKit?.variations ?? {};
50
- // An empty map means the runtime config never loaded, so no fetch can carry variation headers.
51
- // Say that once, rather than blaming each variation for being undefined.
52
- if (!Object.keys(variations).length) {
53
- this.warnOnce("no-runtime-config", "no variations available from the runtime config, so origin fetches carry the base headers only — the cached document may differ from production. Are you logged in?");
54
- }
55
52
  let resolved;
56
53
  try {
57
54
  resolved = resolveRequest(variations, originUrl, variationParameter);
58
55
  }
59
56
  catch (error) {
57
+ // Only a custom variation reaches this branch: a device variation (default, mobile, tablet)
58
+ // never throws. It starts from its built-in default, and an entry for it in the runtime
59
+ // config is applied on top, so a configured user agent or header still wins.
60
60
  if (!(error instanceof UndefinedVariationError))
61
61
  throw error;
62
- this.warnOnce(`undefined-variation:${variationParameter}`, `${error.message} Falling back to the base headers.`);
62
+ const defined = Object.keys(variations);
63
+ this.warnOnce(`undefined-variation:${variationParameter}`, `variation ${variationParameter} is not defined in the runtime config — ` +
64
+ (defined.length
65
+ ? `defined are: ${defined.join(", ")}. `
66
+ : "it defines no variations at all. ") +
67
+ "Falling back to the base headers.");
63
68
  resolved = resolveRequest({}, originUrl);
64
69
  }
65
70
  const init = { headers: { ...resolved.headers } };
@@ -15,6 +15,7 @@ export declare class VirtualOrestesApp {
15
15
  private developmentToolsMessages;
16
16
  private removeContentSecurityPolicy;
17
17
  private localCacheErrors;
18
+ private prerendererHintShown;
18
19
  constructor(customerConfig: CustomerConfig, crawler: Crawler, documentHandler: DocumentHandlerServer, cache: Cache, cli: CliServiceInterface, developmentToolsMessages: DevtoolsExtensionApi, removeContentSecurityPolicy?: boolean);
19
20
  fetchAssetResponse(event: Protocol.Fetch.RequestPausedEvent): Promise<Partial<Protocol.Fetch.FulfillRequestRequest> | AbortResponse>;
20
21
  /**
@@ -60,6 +61,8 @@ export declare class VirtualOrestesApp {
60
61
  * the page as an infrastructure failure and disconnect Speed Kit.
61
62
  */
62
63
  private returnAbortResponse;
64
+ private reportAbort;
65
+ private warnPrerendererUnreachable;
63
66
  /**
64
67
  * Answers an origin error the way the Asset API answers it, instead of caching it.
65
68
  *
@@ -1,5 +1,5 @@
1
1
  import { BaqendResponse } from "../browser/baqend-response.js";
2
- import { ABORT_SERVER_TIMING, ABORT_STATUS_CODE, isDocumentHandlerAbort, } from "../../document-handler-runtime/document-handler-abort.js";
2
+ import { ABORT_SERVER_TIMING, ABORT_STATUS_CODE, isDocumentHandlerAbort, isLocalPrerendererUnreachable, LOCAL_PRERENDERER_PORT, prerenderFailure, } from "../../document-handler-runtime/document-handler-abort.js";
3
3
  import { isBlockedOriginStatus, ORIGIN_ERROR_STATUS_CODE, originErrorCauseName, originErrorCode, originErrorServerTiming, } from "./origin-error-cause.js";
4
4
  import { safe } from "../../../helpers/safe.js";
5
5
  import { META_CONTENT_TYPE_REGEX, } from "../onboarding-model.js";
@@ -34,6 +34,8 @@ export class VirtualOrestesApp {
34
34
  // can surface an "error for this URL" affordance in the Causes & sources
35
35
  // card. Cleared per-URL on the next successful transform.
36
36
  localCacheErrors = new Map();
37
+ // The hint to start the pre-renderer is shown once; every later page gets one line.
38
+ prerendererHintShown = false;
37
39
  constructor(customerConfig, crawler, documentHandler, cache, cli, developmentToolsMessages, removeContentSecurityPolicy = false) {
38
40
  this.customerConfig = customerConfig;
39
41
  this.crawler = crawler;
@@ -250,10 +252,33 @@ export class VirtualOrestesApp {
250
252
  */
251
253
  returnAbortResponse(customResponse, customHeaders) {
252
254
  const message = customResponse.error;
253
- this.cli.writeWarning(`[VirtualOrestes]: Document Handler aborted: ${message}`);
255
+ this.reportAbort(message, customResponse.errorObj);
254
256
  customHeaders.push({ name: "x-error", value: message }, { name: "server-timing", value: ABORT_SERVER_TIMING });
255
257
  return new BaqendResponse(message, null, customHeaders, ABORT_STATUS_CODE);
256
258
  }
259
+ reportAbort(message, error) {
260
+ if (isLocalPrerendererUnreachable(error)) {
261
+ this.warnPrerendererUnreachable();
262
+ return;
263
+ }
264
+ const failure = prerenderFailure(error);
265
+ if (failure) {
266
+ this.cli.writeError(`[DocumentHandler:local]: SSR failed for ${failure.url} (${failure.variation}): ` +
267
+ `${failure.detailMessage ?? "no error message"}`);
268
+ return;
269
+ }
270
+ this.cli.writeWarning(`[DocumentHandler:local]: ${message}`);
271
+ }
272
+ warnPrerendererUnreachable() {
273
+ const unreachable = `no pre-renderer is listening on localhost:${LOCAL_PRERENDERER_PORT}`;
274
+ if (this.prerendererHintShown) {
275
+ this.cli.writeWarning(`[DocumentHandler:local]: SSR failed, ${unreachable}`);
276
+ return;
277
+ }
278
+ this.prerendererHintShown = true;
279
+ this.cli.writeWarning(`[DocumentHandler:local]: SSR is configured, but ${unreachable}.\n` +
280
+ "Start the pre-renderer in puppeteer-lambda (`npm run run:dev`), then reload the page.");
281
+ }
257
282
  /**
258
283
  * Answers an origin error the way the Asset API answers it, instead of caching it.
259
284
  *
@@ -23,6 +23,16 @@ describe("asset variations", () => {
23
23
  expect(resolutionPath).to.equal("template");
24
24
  expect(appliedKeys).to.deep.equal(["*", "desktop-fmarkt-variant"]);
25
25
  });
26
+ it("lets a configured device variation override its built-in default", () => {
27
+ const { appliedKeys, headers } = resolveRequest({
28
+ mobile: {
29
+ headers: { "user-agent": "custom-mobile-agent", "x-device": "m" },
30
+ },
31
+ }, "https://www.example.com/plp", "mobile");
32
+ expect(appliedKeys).to.deep.equal(["device-default:mobile", "mobile"]);
33
+ expect(headers["user-agent"]).to.equal("custom-mobile-agent");
34
+ expect(headers["x-device"]).to.equal("m");
35
+ });
26
36
  it("matches a template only against the whole variation, and rejects what matches nothing", () => {
27
37
  // The desktop template cannot match a mobile variation, and the server does not fall back to
28
38
  // the "mobile" device default by substring — that is the pre-renderer's rule, not the server's.
@@ -1746,5 +1746,5 @@
1746
1746
  ]
1747
1747
  }
1748
1748
  },
1749
- "version": "4.38.0"
1749
+ "version": "4.39.0"
1750
1750
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@speedkit/cli",
3
3
  "description": "Speed Kit CLI",
4
- "version": "4.38.0",
4
+ "version": "4.39.0",
5
5
  "author": {
6
6
  "name": "Baqend.com",
7
7
  "email": "info@baqend.com"