@speedkit/cli 4.22.1 → 4.23.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [4.23.1](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.23.0...v4.23.1) (2026-08-21)
+
+
+### Bug Fixes
+
+* **cli:** resolve IPv4 addresses before IPv6 ([057fa59](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/057fa59bb06f3d49af5b8631681e7850a062d585))
+* **onboarding:** allow one hour Shopify staleness for local runs ([4e31124](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/4e31124aa3c217f698ef3bb48a51c83fb5395ca4))
+
+# [4.23.0](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.22.1...v4.23.0) (2026-08-21)
+
+
+### Bug Fixes
+
+* **onboarding:** fetch origin exactly as the server does ([8da54b0](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/8da54b0ac0ffa04671cb3c7e97988e8ac871f2c5))
+
+
+### Features
+
+* **origin-request:** simulate the server's origin request for a variation ([dc414e0](https://gitlab.orestes.info/baqend/speed-kit-cli/commit/dc414e03142cab154c8f179cdb67f58922a6d38b))
+
 ## [4.22.1](https://gitlab.orestes.info/baqend/speed-kit-cli/compare/v4.22.0...v4.22.1) (2026-08-21)
 
 

package/README.md

@@ -21,7 +21,7 @@ $ npm install -g @speedkit/cli
 $ sk COMMAND
 running command...
 $ sk (--version)
-@speedkit/cli/4.22.1 linux-x64 node-v22.23.2
+@speedkit/cli/4.23.1 linux-x64 node-v22.23.2
 $ sk --help [COMMAND]
 USAGE
   $ sk COMMAND
@@ -88,6 +88,7 @@ By either...
 * [`sk help [COMMAND]`](#sk-help-command)
 * [`sk login [APP]`](#sk-login-app)
 * [`sk onboarding CUSTOMERPATH`](#sk-onboarding-customerpath)
+* [`sk origin-request CUSTOMERPATH PAGEURL`](#sk-origin-request-customerpath-pageurl)
 * [`sk param-diff PAGEURL`](#sk-param-diff-pageurl)
 * [`sk prewarm APP PATH`](#sk-prewarm-app-path)
 * [`sk pull CUSTOMERPATH`](#sk-pull-customerpath)
@@ -620,6 +621,41 @@ EXAMPLES
   $ sk onboarding customers/decathlon.de -c production -d www.decathlon.de
 ```
 
+## `sk origin-request CUSTOMERPATH PAGEURL`
+
+Request a page from origin with the exact headers Speed Kit's server sends for a cache variation, using the app's deployed runtime config
+
+```
+USAGE
+  $ sk origin-request CUSTOMERPATH PAGEURL [-c <value>] [-v <value>] [--host <value>] [--body <value>] [--grep
+    <value>] [--json] [--variations <value>]
+
+ARGUMENTS
+  CUSTOMERPATH  The customer config path
+  PAGEURL       Page to request from origin
+
+FLAGS
+  -c, --configName=<value>  [default: production] The costumer config name
+  -v, --variation=<value>   Cache variation to simulate, e.g. desktop-fmarkt-variant-e_1907090. Omitted means the
+                            default variation
+      --body=<value>        Write the response body to this file
+      --grep=<value>        Print body lines matching this regex, case-insensitive
+      --host=<value>        Send this Host header, emulating an origin-map host override
+      --json                Machine-readable output
+      --variations=<value>  Simulate against a runtime config in a local file instead of the app's deployed one
+
+DESCRIPTION
+  Request a page from origin with the exact headers Speed Kit's server sends for a cache variation, using the app's
+  deployed runtime config
+
+EXAMPLES
+  $ sk origin-request <customerPath> <pageUrl>
+
+  $ sk origin-request customers/decathlon.de https://www.decathlon.de/ -v mobile
+
+  $ sk origin-request customers/decathlon.de https://www.decathlon.de/ --grep "storeId" --body /tmp/origin.html
+```
+
 ## `sk param-diff PAGEURL`
 
 Shows difference in documents with query parameters on/off

package/dist/commands/origin-request.d.ts

@@ -0,0 +1,21 @@
+import { Command } from "@oclif/core";
+export default class OriginRequest extends Command {
+    static description: string;
+    static args: {
+        pageUrl: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        customerPath: import("@oclif/core/interfaces").Arg<string, {
+            exists?: boolean;
+        }>;
+    };
+    static flags: {
+        variation: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        host: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        body: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        grep: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        variations: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        configName: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/origin-request.js

@@ -0,0 +1,49 @@
+import { Args, Command, Flags } from "@oclif/core";
+import { CLI_CONFIG_NAME, CLI_CUSTOMER_CONFIG, CLIParameters, CLIParametersChar, CLIParametersExample, } from "../models/cli-parameters.js";
+import { CliConfig } from "../helpers/cli-config.js";
+import { OriginRequestContext, OriginRequestServiceFactory, } from "../services/origin-request/index.js";
+export default class OriginRequest extends Command {
+    static description = "Request a page from origin with the exact headers Speed Kit's server sends for a cache variation, using the app's deployed runtime config";
+    static args = {
+        ...CLI_CUSTOMER_CONFIG,
+        [CLIParameters.PageUrl]: Args.string({
+            name: CLIParameters.PageUrl,
+            required: true,
+            description: "Page to request from origin",
+            example: CLIParametersExample.PageUrl,
+        }),
+    };
+    static flags = {
+        ...CLI_CONFIG_NAME,
+        [CLIParameters.Variation]: Flags.string({
+            char: CLIParametersChar.Variation,
+            description: "Cache variation to simulate, e.g. desktop-fmarkt-variant-e_1907090. Omitted means the default variation",
+        }),
+        host: Flags.string({
+            description: "Send this Host header, emulating an origin-map host override",
+        }),
+        body: Flags.string({
+            description: "Write the response body to this file",
+        }),
+        grep: Flags.string({
+            description: "Print body lines matching this regex, case-insensitive",
+        }),
+        json: Flags.boolean({
+            description: "Machine-readable output",
+        }),
+        variations: Flags.string({
+            description: "Simulate against a runtime config in a local file instead of the app's deployed one",
+        }),
+    };
+    static examples = [
+        `$ sk origin-request <${CLIParameters.CustomerPath}> <${CLIParameters.PageUrl}>`,
+        `$ sk origin-request ${CLIParametersExample.CustomerPath} ${CLIParametersExample.PageUrl} -${CLIParametersChar.Variation} mobile`,
+        `$ sk origin-request ${CLIParametersExample.CustomerPath} ${CLIParametersExample.PageUrl} --grep "storeId" --body /tmp/origin.html`,
+    ];
+    async run() {
+        const { args: { customerPath, pageUrl }, flags: { configName, variation, host, body, grep, json, variations }, } = await this.parse(OriginRequest);
+        const context = new OriginRequestContext(customerPath, configName, pageUrl, variation, host, body, grep, json, variations);
+        const service = await new OriginRequestServiceFactory(context, new CliConfig(this.config).load()).buildService();
+        await service.run();
+    }
+}

package/dist/hooks/init/dns-result-order.d.ts

@@ -0,0 +1,12 @@
+import { Hook } from "@oclif/core";
+/**
+ * Puts IPv4 addresses first for every lookup the CLI makes. This is the runtime equivalent of
+ * `NODE_OPTIONS=--dns-result-order=ipv4first`, so no entrypoint has to export that variable.
+ *
+ * Node resolves `localhost` to `::1` first. WSL in mirrored networking mode shares `localhost`
+ * between Windows and Linux, but Chrome's remote debugging port and the local dev server both
+ * listen on IPv4 only. A lookup that answers `::1` therefore never reaches the listener on the
+ * other side of the boundary, and the connection fails instead of crossing over.
+ */
+declare const hook: Hook<"init">;
+export default hook;

package/dist/hooks/init/dns-result-order.js

@@ -0,0 +1,14 @@
+import { setDefaultResultOrder } from "node:dns";
+/**
+ * Puts IPv4 addresses first for every lookup the CLI makes. This is the runtime equivalent of
+ * `NODE_OPTIONS=--dns-result-order=ipv4first`, so no entrypoint has to export that variable.
+ *
+ * Node resolves `localhost` to `::1` first. WSL in mirrored networking mode shares `localhost`
+ * between Windows and Linux, but Chrome's remote debugging port and the local dev server both
+ * listen on IPv4 only. A lookup that answers `::1` therefore never reaches the listener on the
+ * other side of the boundary, and the connection fails instead of crossing over.
+ */
+const hook = async () => {
+    setDefaultResultOrder("ipv4first");
+};
+export default hook;

package/dist/hooks/init/dns-result-order.spec.d.ts

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

package/dist/hooks/init/dns-result-order.spec.js

@@ -0,0 +1,15 @@
+import { expect } from "chai";
+import { after, describe, it } from "mocha";
+import { getDefaultResultOrder, setDefaultResultOrder } from "node:dns";
+import hook from "./dns-result-order.js";
+describe("dns-result-order hook", () => {
+    const previousOrder = getDefaultResultOrder();
+    after(() => {
+        setDefaultResultOrder(previousOrder);
+    });
+    it("puts IPv4 addresses first", async () => {
+        setDefaultResultOrder("verbatim");
+        await hook.call(null, {});
+        expect(getDefaultResultOrder()).to.equal("ipv4first");
+    });
+});

package/dist/services/document-handler-runtime/context/document-handler-runtime-context.d.ts

@@ -6,6 +6,7 @@ export declare const LOCAL_DYNAMIC_FETCHER_CONFIG = "config_dynamicBlocks";
 export declare const LOCAL_STYLES = "config_dynamicStyles";
 export declare const LATEST_DOCUMENT_HANDLER_URL = "https://www.baqend.com/speed-kit-handler/latest/DocumentHandler.js";
 export declare const LATEST_DYNAMIC_FETCHER_URL = "https://www.baqend.com/speed-kit/latest/dynamic-fetcher.js";
+export declare const LOCAL_TRIGGERED_BY = "STREAM:QA";
 export declare const TEST_DOCUMENT_HANDLER_FILE_NAME = "testDocumentHandler";
 export declare const TEST_DATABASE_MOCK_FILE_NAME = "database-mock";
 export declare const TEST_ORESTES_MOCK_FILE_NAME = "orestes-mock";

package/dist/services/document-handler-runtime/context/document-handler-runtime-context.js

@@ -6,6 +6,10 @@ export const LOCAL_DYNAMIC_FETCHER_CONFIG = "config_dynamicBlocks";
 export const LOCAL_STYLES = "config_dynamicStyles";
 export const LATEST_DOCUMENT_HANDLER_URL = "https://www.baqend.com/speed-kit-handler/latest/DocumentHandler.js";
 export const LATEST_DYNAMIC_FETCHER_URL = "https://www.baqend.com/speed-kit/latest/dynamic-fetcher.js";
+// Local runs have no persistent cache, so an origin HTML is served straight to the developer and may
+// legitimately be older than the default five minutes. STREAM:QA relaxes the document handler's
+// Shopify staleness check to one hour, see ONE_HOUR_STALENESS_TRIGGERS in document-handler.
+export const LOCAL_TRIGGERED_BY = "STREAM:QA";
 export const TEST_DOCUMENT_HANDLER_FILE_NAME = "testDocumentHandler";
 export const TEST_DATABASE_MOCK_FILE_NAME = "database-mock";
 export const TEST_ORESTES_MOCK_FILE_NAME = "orestes-mock";

package/dist/services/document-handler-runtime/server/request.d.ts

@@ -2,6 +2,7 @@ interface query {
     url: string;
     variation: string;
     headers: string;
+    triggeredBy: string;
 }
 export declare class Request {
     query: query;

package/dist/services/document-handler-runtime/server/request.js

@@ -1,9 +1,15 @@
+import { LOCAL_TRIGGERED_BY } from "../context/document-handler-runtime-context.js";
 export class Request {
     query;
     body;
     headers;
     constructor(url, body, variation, originalHeaders, requestHeaders = {}) {
-        this.query = { variation, headers: JSON.stringify(originalHeaders), url };
+        this.query = {
+            variation,
+            headers: JSON.stringify(originalHeaders),
+            url,
+            triggeredBy: LOCAL_TRIGGERED_BY,
+        };
         this.body = body;
         this.headers = {};
         for (const key of Object.keys(requestHeaders)) {

package/dist/services/document-handler-runtime/templates/execute-document-handler.js

@@ -1,4 +1,5 @@
 import AbstractTemplate from "./abstract-template.js";
+import { LOCAL_TRIGGERED_BY } from "../context/document-handler-runtime-context.js";
 export default class ExecuteDocumentHandler extends AbstractTemplate {
     buildContext(domain, file) {
         return { domain, file };
@@ -35,6 +36,7 @@ async function run(iterator) {
             variation: item.variation || 'DEFAULT',
             headers: item?.headers ? item.headers : JSON.stringify(DEFAULT_HEADERS),
             url: item.url,
+            triggeredBy: '${LOCAL_TRIGGERED_BY}',
         }
         let req = {
             query, body: file

package/dist/services/document-handler-runtime/templates/orestes-mock.js

@@ -1,4 +1,5 @@
 import AbstractTemplate from "./abstract-template.js";
+import { LOCAL_TRIGGERED_BY } from "../context/document-handler-runtime-context.js";
 export default class OrestesMock extends AbstractTemplate {
     buildContext() {
         return {};
@@ -79,6 +80,7 @@ const server = http.createServer(async function (request, response) {
         variation: UrlObject.searchParams.has('bqvariation')?UrlObject.searchParams.get('bqvariation'):'DEFAULT',
         headers: '',
         url: url,
+        triggeredBy: '${LOCAL_TRIGGERED_BY}',
       }
       let req = {query, body}
       const output =  await documentHandler.transform(database,req)

package/dist/services/document-handler-runtime/templates/test.js

@@ -1,4 +1,5 @@
 import AbstractTemplate from "./abstract-template.js";
+import { LOCAL_TRIGGERED_BY } from "../context/document-handler-runtime-context.js";
 export default class Test extends AbstractTemplate {
     buildContext(domain, name, timeout = 2000) {
         return { domain, name, timeout };
@@ -25,6 +26,7 @@ describe(\`documentHandler run on \${file}\`, function () {
         variation: 'DEFAULT',
         headers: JSON.stringify(DEFAULT_HEADERS),
         url: url,
+        triggeredBy: '${LOCAL_TRIGGERED_BY}',
     }
 
     let req = {query, body}
@@ -42,6 +44,7 @@ describe(\`create files to diff for \${file}\`,function (){
       variation: 'DEFAULT',
       headers: JSON.stringify(DEFAULT_HEADERS),
       url: url,
+      triggeredBy: '${LOCAL_TRIGGERED_BY}',
     }
 
     let req = {query, body}

package/dist/services/onboarding/virtual-orestes-app/crawler.d.ts

@@ -5,58 +5,27 @@ export declare class Crawler {
     private cli;
     private agentConfig;
     private speedKitServerConfig?;
+    /** Warnings already shown, so a per-fetch condition is reported once per session. */
+    private readonly warned;
     constructor(cli: CliService, agentConfig: Agent, speedKitServerConfig?: SpeedKitServerConfig);
+    private warnOnce;
     fetchRemote(originUrl: string, variation: string): Promise<{
         response: Response;
         url: string;
     } | undefined>;
-    private setDefaultUserAgent;
     /**
-     * Mirrors how the Baqend asset server applies the `variations` block from
-     * the Speed Kit server config to outgoing origin fetches. The cookie /
-     * user-agent / etc. headers configured per variation must reach the origin
-     * so that the response matches what the variation is supposed to represent
-     * (e.g. a logged-in user, a specific store, a mobile device).
+     * Builds the origin request exactly as the Baqend asset server builds it, so a locally cached
+     * document matches what production would cache for the same variation.
      *
-     * Resolution order (matches Orestes server behavior):
-     *   1. The wildcard `"*"` variation (if any) — its headers always apply.
-     *   2. First-match-wins iteration over the remaining variations: for each
-     *      entry in declaration order, try an exact key match against
-     *      `variationParameter` first, then fall back to its Java-style
-     *      `regex` (e.g. `(?i)desktop-fmarkt-variant-(?<storeId>.*)`). The
-     *      first variation that matches by either means is applied — exact
-     *      matches do NOT take priority over regex matches in earlier
-     *      entries. When matched via regex, named capture groups are
-     *      substituted into header values via `${name}` placeholders, so a
-     *      cookie like `fmarktcookie=${storeId}` becomes
-     *      `fmarktcookie=2879130`.
-     *   3. Origin-level basic auth fallback (only if no variation matched).
+     * The resolution itself lives in `services/origin-request` and is shared with
+     * `sk origin-request`, so there is one owner for it and one place the server's behaviour is
+     * pinned by specs. That covers the base headers, the wildcard-then-variation order, the regex
+     * templates with their `${group}` substitution, and the query params.
      *
-     * Returns the (query-param-augmented) origin URL alongside the request init,
-     * so query-param variations like `Sortierung=${sort}` reach the origin.
+     * Two things stay local: origin basic auth, which no variation carries, and tolerance for a
+     * variation the config does not define — the server rejects that request, but failing a whole
+     * onboarding session over it would be unhelpful, so it falls back to the base headers and warns.
      */
     private prepareOriginRequest;
-    /**
-     * Applies a matched variation: merges its headers into `init` and appends its
-     * `queryParams` onto `url`, substituting regex named groups (`${name}`) — so
-     * `Sortierung=${sort}` with `{ sort: "3" }` becomes `Sortierung=3`.
-     */
-    private applyVariation;
-    /**
-     * Replaces `${name}` placeholders in each header value with the matching
-     * named capture group from a regex match. Used by `prepareOriginRequest`
-     * to materialize parameterized variation headers — e.g. given:
-     *
-     *   headers = { cookie: "fmarktcookie=${storeId}" }
-     *   groups  = { storeId: "2879130" }
-     *
-     * the result is `{ cookie: "fmarktcookie=2879130" }`.
-     *
-     * Placeholders that don't match a captured group are left intact rather
-     * than replaced with `undefined`, so a misconfigured variation still
-     * produces a recognisable header value instead of a silent corruption.
-     * Non-string header values are passed through unchanged.
-     */
-    private substituteNamedGroups;
     private prepareAuthRequest;
 }

package/dist/services/onboarding/virtual-orestes-app/crawler.js

@@ -1,26 +1,27 @@
-import { USER_AGENT } from "../onboarding-model.js";
 import { safe } from "../../../helpers/safe.js";
-import { javaRegexToJs } from "../../../helpers/java-regex.js";
+import { resolveRequest, UndefinedVariationError, } from "../../origin-request/index.js";
 import { randomUUID } from "node:crypto";
 export class Crawler {
     cli;
     agentConfig;
     speedKitServerConfig;
+    /** Warnings already shown, so a per-fetch condition is reported once per session. */
+    warned = new Set();
     constructor(cli, agentConfig, speedKitServerConfig) {
         this.cli = cli;
         this.agentConfig = agentConfig;
         this.speedKitServerConfig = speedKitServerConfig;
     }
+    warnOnce(key, message) {
+        if (this.warned.has(key))
+            return;
+        this.warned.add(key);
+        this.cli.writeWarning(message);
+    }
     async fetchRemote(originUrl, variation) {
-        const userAgent = this.setDefaultUserAgent(variation);
-        const headers = {
-            "User-Agent": userAgent,
-        };
         // origin URL with the variation's query params applied — returned so callers compare it
         // (not the bare originUrl) against response.url for redirect detection
-        const { url, init } = this.prepareOriginRequest(originUrl, variation, {
-            headers,
-        });
+        const { url, init } = this.prepareOriginRequest(originUrl, variation);
         const requestInit = {
             ...init,
             agent: this.agentConfig,
@@ -36,138 +37,46 @@ export class Crawler {
         this.cli.writeError(fetchResponse.error);
         this.cli.writeError(JSON.stringify(fetchResponse.errorObj));
     }
-    setDefaultUserAgent(variation) {
-        if (/^mobile$/is.test(variation)) {
-            return USER_AGENT.MOBILE;
-        }
-        if (/^tablet$/is.test(variation)) {
-            return USER_AGENT.TABLET;
-        }
-        return USER_AGENT.DESKTOP;
-    }
     /**
-     * Mirrors how the Baqend asset server applies the `variations` block from
-     * the Speed Kit server config to outgoing origin fetches. The cookie /
-     * user-agent / etc. headers configured per variation must reach the origin
-     * so that the response matches what the variation is supposed to represent
-     * (e.g. a logged-in user, a specific store, a mobile device).
+     * Builds the origin request exactly as the Baqend asset server builds it, so a locally cached
+     * document matches what production would cache for the same variation.
      *
-     * Resolution order (matches Orestes server behavior):
-     *   1. The wildcard `"*"` variation (if any) — its headers always apply.
-     *   2. First-match-wins iteration over the remaining variations: for each
-     *      entry in declaration order, try an exact key match against
-     *      `variationParameter` first, then fall back to its Java-style
-     *      `regex` (e.g. `(?i)desktop-fmarkt-variant-(?<storeId>.*)`). The
-     *      first variation that matches by either means is applied — exact
-     *      matches do NOT take priority over regex matches in earlier
-     *      entries. When matched via regex, named capture groups are
-     *      substituted into header values via `${name}` placeholders, so a
-     *      cookie like `fmarktcookie=${storeId}` becomes
-     *      `fmarktcookie=2879130`.
-     *   3. Origin-level basic auth fallback (only if no variation matched).
+     * The resolution itself lives in `services/origin-request` and is shared with
+     * `sk origin-request`, so there is one owner for it and one place the server's behaviour is
+     * pinned by specs. That covers the base headers, the wildcard-then-variation order, the regex
+     * templates with their `${group}` substitution, and the query params.
      *
-     * Returns the (query-param-augmented) origin URL alongside the request init,
-     * so query-param variations like `Sortierung=${sort}` reach the origin.
-     */
-    prepareOriginRequest(originUrl, variationParameter, init) {
-        const url = new URL(originUrl);
-        if (!this.speedKitServerConfig) {
-            return { url: url.toString(), init };
-        }
-        const variations = this.speedKitServerConfig.speedKit.variations;
-        // Wildcard variation applies to every request, regardless of which
-        // specific variation (if any) is requested.
-        if (variations?.["*"]) {
-            this.applyVariation(url, init, variations["*"], undefined);
-        }
-        if (!variationParameter) {
-            return { url: url.toString(), init };
-        }
-        // First-match-wins over the variations in declaration order. Each entry
-        // can match by exact key or by its Java-style `regex` field; whichever
-        // entry matches first applies its headers + query params and short-circuits.
-        for (const variationKey in variations) {
-            if (variationKey === "*") {
-                continue;
-            }
-            const variationConfig = variations[variationKey];
-            if (variationParameter === variationKey) {
-                this.applyVariation(url, init, variationConfig, undefined);
-                return { url: url.toString(), init };
-            }
-            if (!variationConfig.regex) {
-                continue;
-            }
-            const regex = javaRegexToJs(variationConfig.regex);
-            if (!regex) {
-                // Unsupported Java regex construct — skip rather than crash so later
-                // variations still get a chance to match.
-                continue;
-            }
-            const match = variationParameter.match(regex);
-            if (!match) {
-                continue;
-            }
-            this.applyVariation(url, init, variationConfig, match.groups);
-            return { url: url.toString(), init };
-        }
-        // No variation matched: fall back to origin basic auth if configured.
-        const authentication = this.prepareAuthRequest(originUrl);
-        if (authentication) {
-            init.headers["Authorization"] = authentication;
-        }
-        return { url: url.toString(), init };
-    }
-    /**
-     * Applies a matched variation: merges its headers into `init` and appends its
-     * `queryParams` onto `url`, substituting regex named groups (`${name}`) — so
-     * `Sortierung=${sort}` with `{ sort: "3" }` becomes `Sortierung=3`.
+     * Two things stay local: origin basic auth, which no variation carries, and tolerance for a
+     * variation the config does not define — the server rejects that request, but failing a whole
+     * onboarding session over it would be unhelpful, so it falls back to the base headers and warns.
      */
-    applyVariation(url, init, variationConfig, groups) {
-        init.headers = {
-            ...init.headers,
-            ...this.substituteNamedGroups(variationConfig.headers, groups),
-        };
-        for (const queryParam of variationConfig.queryParams ?? []) {
-            const substituted = groups
-                ? queryParam.replace(/\$\{(\w+)}/g, (match, name) => groups[name] ?? match)
-                : queryParam;
-            const eq = substituted.indexOf("=");
-            const key = eq === -1 ? substituted : substituted.slice(0, eq);
-            const value = eq === -1 ? "" : substituted.slice(eq + 1);
-            url.searchParams.set(key, value);
+    prepareOriginRequest(originUrl, variationParameter) {
+        const variations = this.speedKitServerConfig?.speedKit?.variations ?? {};
+        // An empty map means the runtime config never loaded, so no fetch can carry variation headers.
+        // Say that once, rather than blaming each variation for being undefined.
+        if (!Object.keys(variations).length) {
+            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?");
         }
-    }
-    /**
-     * Replaces `${name}` placeholders in each header value with the matching
-     * named capture group from a regex match. Used by `prepareOriginRequest`
-     * to materialize parameterized variation headers — e.g. given:
-     *
-     *   headers = { cookie: "fmarktcookie=${storeId}" }
-     *   groups  = { storeId: "2879130" }
-     *
-     * the result is `{ cookie: "fmarktcookie=2879130" }`.
-     *
-     * Placeholders that don't match a captured group are left intact rather
-     * than replaced with `undefined`, so a misconfigured variation still
-     * produces a recognisable header value instead of a silent corruption.
-     * Non-string header values are passed through unchanged.
-     */
-    substituteNamedGroups(headers, groups) {
-        if (!headers) {
-            return {};
+        let resolved;
+        try {
+            resolved = resolveRequest(variations, originUrl, variationParameter);
         }
-        if (!groups) {
-            return { ...headers };
+        catch (error) {
+            if (!(error instanceof UndefinedVariationError))
+                throw error;
+            this.warnOnce(`undefined-variation:${variationParameter}`, `${error.message} Falling back to the base headers.`);
+            resolved = resolveRequest({}, originUrl);
         }
-        const result = {};
-        for (const [key, value] of Object.entries(headers)) {
-            result[key] =
-                typeof value === "string"
-                    ? value.replace(/\$\{(\w+)}/g, (match, name) => groups[name] ?? match)
-                    : value;
+        const init = { headers: { ...resolved.headers } };
+        // Only a request that matched no specific variation falls back to origin basic auth. The
+        // wildcard applies to every request, so it does not count as a match.
+        const matchedSpecificVariation = resolved.appliedKeys.some((key) => key !== "*" && !key.startsWith("device-default:"));
+        if (!matchedSpecificVariation) {
+            const authentication = this.prepareAuthRequest(originUrl);
+            if (authentication)
+                init.headers["Authorization"] = authentication;
         }
-        return result;
+        return { url: resolved.url, init };
     }
     prepareAuthRequest(originUrl) {
         if (!this.speedKitServerConfig ||

package/dist/services/origin-request/asset-variations.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Port of the server's variation resolution, so a request can be reproduced locally with the exact
+ * headers Speed Kit would send.
+ *
+ * Mirrors two pieces of server behaviour:
+ *   - `AssetVariations.getVariations()` — which variation configs apply and in which order
+ *     (orestes: `orestes-common/.../typesystem/AssetVariations.kt`)
+ *   - `AssetClient.newRequest()` / `createRequest()` — base headers, last-writer-wins merging,
+ *     urlPrefix and queryParams (orestes: `orestes-server/.../asset/AssetClient.kt`)
+ *
+ * Keep this file free of I/O so the resolution stays unit-testable.
+ */
+/** A single variation entry of the runtime config's `speedKit.variations`. */
+export interface AssetVariation {
+    headers?: Record<string, string | null>;
+    urlPrefix?: string;
+    encodePrefixedUrl?: boolean;
+    queryParams?: string[];
+    regex?: string | null;
+    /** Which config key produced this entry. Set during resolution, for reporting. */
+    matchedKey?: string;
+}
+export type AssetVariationMap = Record<string, AssetVariation>;
+export interface ResolvedRequest {
+    /** Keys of the applied configs, in the order the server applies them. */
+    appliedKeys: string[];
+    /** `template` when a regex entry matched, otherwise `named`. */
+    resolutionPath: "template" | "named";
+    url: string;
+    headers: Record<string, string>;
+}
+export declare const DEFAULT_TYPE = "default";
+/** User agents the server falls back to. Keep in sync with AssetVariations.kt. */
+export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.6 Safari/605.1.15 (compatible; SpeedKit/1.0)";
+/** Thrown where the server would throw UndefinedVariationException. */
+export declare class UndefinedVariationError extends Error {
+    constructor(variationType: string);
+}
+/**
+ * Resolves which variation configs apply, in server order. The template path returns
+ * `[wildcard, template]` and skips the device defaults; otherwise `[default, wildcard, named]`.
+ */
+export declare function getVariations(custom: AssetVariationMap, variationType?: string): AssetVariation[];
+/** Resolves a variation into the concrete request the server would send. */
+export declare function resolveRequest(custom: AssetVariationMap, url: string, variationType?: string, hostOverride?: string): ResolvedRequest;
+/** Renders the resolved request as a curl command, for pasting into a bug report. */
+export declare function toCurl(url: string, headers: Record<string, string>): string;