@speedkit/cli 4.26.0 → 4.27.1

package/dist/services/query-builder/queries/query-model.js

@@ -0,0 +1,19 @@
+/** How far back a query looks, per query type. */
+export const DEFAULT_QUERY_DAYS = {
+    parameter: 30,
+    pops: 7,
+    prewarm: 10,
+};
+/** Today, as `YYYY-MM-DD` — the format of the `date` partition column. */
+export function today(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/**
+ * The day the query starts at, `days` before now, as `YYYY-MM-DD` — the
+ * format of the `date` partition column.
+ */
+export function sinceDate(days, now = new Date()) {
+    const window = Math.max(1, Math.floor(days));
+    const since = new Date(now.getTime() - window * 24 * 60 * 60 * 1000);
+    return since.toISOString().slice(0, 10);
+}

package/dist/services/query-builder/queries/spec/golden-configs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Config shapes the query builder has to get right, each one standing for a
+ * class of real customer configs.
+ *
+ * These feed the golden queries in `golden.spec.ts`: the whole emitted SQL and
+ * the whole accounting are checked in next to them, so any change to the
+ * builder shows up as a reviewable diff instead of as a surprise in a
+ * pre-warm run.
+ */
+export interface GoldenConfig {
+    /** The evaluated `window.speedKit` of a customer config. */
+    readonly config: Record<string, unknown>;
+    /** Why this shape is here. */
+    readonly describes: string;
+    readonly hosts: readonly string[];
+    readonly name: string;
+}
+export declare const GOLDEN_CONFIGS: readonly GoldenConfig[];

package/dist/services/query-builder/queries/spec/golden-configs.js

@@ -0,0 +1,116 @@
+export const GOLDEN_CONFIGS = [
+    {
+        config: {
+            blacklist: [
+                {
+                    pathname: [
+                        // Guards for pages `enabledSites` never allowed — the bulk of a
+                        // real blacklist, and all reducible.
+                        /^\/checkout/i,
+                        /^\/cart/i,
+                        /^\/account/i,
+                        // These can hit an enabled page and have to survive.
+                        /\.pdf/i,
+                        /paypal/i,
+                    ],
+                },
+                { contentType: ["image", "script"], pathname: [/\/media\//i] },
+                { host: ["tracking.example.com"] },
+            ],
+            disabledScopes: ["/checkout", "/cart"],
+            disabledSites: [{ pathname: [/^\/search/i] }],
+            enabledSites: [
+                {
+                    host: ["www.shop.de"],
+                    pathname: [/^\/$/, /^\/p\//i, /^\/c\//i],
+                },
+            ],
+            ruleSetConfig: { version: 2 },
+            stripQueryParams: [{ params: ["gclid", /^utm[_-]/i] }],
+            whitelist: [{ contentType: ["navigate"], host: ["www.shop.de"] }],
+        },
+        describes: "the recommended shape: version 2, enabledSites, and a blacklist most of which cannot fire",
+        hosts: ["www.shop.de"],
+        name: "enabled-sites-v2",
+    },
+    {
+        config: {
+            blacklist: [{ pathname: ["/login", "/warenkorb"] }],
+            disabledSites: [{ pathname: [/\/kasse/i] }],
+            // No ruleSetConfig: version 1, where a string is a prefix and a
+            // pathname pattern is matched against the query string as well.
+            stripQueryParams: ["utm", /session$/i],
+            whitelist: [{ host: ["www.shop.de", "m.shop.de"] }],
+        },
+        describes: "a version 1 config without enabledSites, where every page is enabled unless disabled",
+        hosts: ["www.shop.de", "m.shop.de"],
+        name: "disabled-sites-v1",
+    },
+    {
+        config: {
+            enabledSites: [
+                { host: ["www.shop.de"], pathname: [/^\/de\//i] },
+                { host: ["www.shop.fr"], pathname: [/^\/fr\//i] },
+            ],
+            ruleSetConfig: { version: 2 },
+            whitelist: [{ host: ["www.shop.de", "www.shop.fr"] }],
+        },
+        describes: "one market per rule, which only works if host and pathname stay together",
+        hosts: ["www.shop.de", "www.shop.fr"],
+        name: "multi-market",
+    },
+    {
+        config: {
+            enabledSites: [{ pathname: [/^\/p\//i, /^\/c\//i] }],
+            ruleSetConfig: { version: 2 },
+            stripQueryParams: [
+                { params: ["gclid"] },
+                // Only stripped on product pages.
+                { enabledSites: [{ pathname: [/^\/p\//i] }], params: ["size"] },
+                // Only stripped on images, which a page impression never is.
+                { params: ["width"], rules: [{ contentType: ["image"] }] },
+            ],
+            whitelist: [{ host: ["www.shop.de"] }],
+        },
+        describes: "parameters stripped only on certain pages or resources",
+        hosts: ["www.shop.de"],
+        name: "scoped-strip-params",
+    },
+    {
+        config: {
+            blacklist: [
+                // A real shape: the hosts are only blacklisted for browsers without
+                // WebP, and the evaluated config carries the empty branch. Read as
+                // "any host" this rule would exclude every page.
+                { host: [] },
+                { pathname: [/^\/checkout/i] },
+            ],
+            enabledSites: [{ pathname: [/^\/$/, /^\/p\//i] }],
+            ruleSetConfig: { version: 2 },
+            whitelist: [{ host: ["www.shop.de"] }],
+        },
+        describes: "a condition that is an empty list, which matches nothing",
+        hosts: ["www.shop.de"],
+        name: "empty-condition",
+    },
+    {
+        config: {
+            blacklist: [
+                { contentType: ["fetch"] },
+                { url: ["www.googletagmanager.com/gtm.js"] },
+                // A word boundary has no automaton, so no reduction may touch it.
+                { pathname: [/\bprint\b/i] },
+            ],
+            disabledSites: [
+                { cookie: /loggedIn=true/ },
+                { mobile: true, pathname: [/^\/app\//i] },
+            ],
+            enabledSites: [{ pathname: [/^\//i] }],
+            ruleSetConfig: { version: 2 },
+            whitelist: [],
+        },
+        describes: "rules the query cannot express literally: a cookie, a device, a pattern with no automaton",
+        hosts: ["www.shop.de"],
+        name: "unexpressible",
+    },
+];

package/dist/services/query-builder/queries/spec/golden.spec.d.ts

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

package/dist/services/query-builder/queries/spec/golden.spec.js

@@ -0,0 +1,161 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { parseRuleSets } from "../../rules/index.js";
+import { buildParameterQuery } from "../parameter-query.js";
+import { buildPopsQuery } from "../pops-query.js";
+import { buildPrewarmQuery } from "../prewarm-query.js";
+import { GOLDEN_CONFIGS } from "./golden-configs.js";
+/**
+ * The queries these configs produce, in full, checked in beside them.
+ *
+ * A unit test states one property; a golden query states all of them at once,
+ * which is what a reviewer needs for a change that rewrites SQL. Run with
+ * `UPDATE_GOLDEN=1 npm test` to write the files, then read the diff — an
+ * unexplained line there is a bug, and the diff is the review.
+ */
+const DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), "golden");
+/** A fixed day, so a window never makes a golden query go stale. */
+const NOW = new Date("2026-09-04T09:30:00Z");
+const APP = "shop-de";
+function goldenText(query) {
+    const notes = [
+        ...query.findings.map(({ reason, source }) => `finding: ${source} ${reason}`),
+        ...query.dropped.map(({ reason, source }) => `dropped: ${source} — ${reason}`),
+        ...query.approximated.map(({ reason, source }) => `approximated: ${source} — ${reason}`),
+        ...query.reduced.map(({ reason, source }) => `reduced: ${source} — ${reason}`),
+        ...query.warnings.map((warning) => `warning: ${warning}`),
+    ];
+    return [
+        query.sql.trim(),
+        "",
+        "-- accounting",
+        ...(notes.length > 0
+            ? notes.map((note) => `-- ${note}`)
+            : ["-- nothing left out, reduced or approximated"]),
+        "",
+    ].join("\n");
+}
+/** Compares against the checked-in file, or writes it when asked to. */
+function expectGolden(name, text) {
+    const file = join(DIRECTORY, `${name}.sql`);
+    if (process.env.UPDATE_GOLDEN) {
+        mkdirSync(DIRECTORY, { recursive: true });
+        writeFileSync(file, text, "utf8");
+        return;
+    }
+    let expected;
+    try {
+        expected = readFileSync(file, "utf8");
+    }
+    catch {
+        throw new Error(`No golden query at ${file}. Run UPDATE_GOLDEN=1 npm test to write it.`);
+    }
+    expect(text).to.equal(expected);
+}
+/** The prewarm query for one of the golden configs, with options on top. */
+function prewarmQueryFor(name, options) {
+    const { config, hosts } = GOLDEN_CONFIGS.find((candidate) => candidate.name === name);
+    return buildPrewarmQuery({
+        app: APP,
+        days: 10,
+        hosts,
+        now: NOW,
+        ruleSets: parseRuleSets(config),
+        ...options,
+    });
+}
+describe("golden queries", () => {
+    for (const { config, describes, hosts, name } of GOLDEN_CONFIGS) {
+        describe(`${name} — ${describes}`, () => {
+            const input = {
+                app: APP,
+                days: 10,
+                hosts,
+                now: NOW,
+                ruleSets: parseRuleSets(config),
+            };
+            it("should build the same prewarm query", () => {
+                expectGolden(`${name}.prewarm`, goldenText(buildPrewarmQuery(input)));
+            });
+            it("should build the same parameter query", () => {
+                expectGolden(`${name}.parameter`, goldenText(buildParameterQuery({ ...input, days: 30 })));
+            });
+        });
+    }
+    describe("match — a prewarm query narrowed by --match", () => {
+        it("should build the same prewarm query", () => {
+            expectGolden("enabled-sites-v2.match.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                match: ["^/p/", "(?i)^/c/[^?]*sale", "[?&]size="],
+            })));
+        });
+    });
+    describe("device — a prewarm list split by device class", () => {
+        it("should carry the variation and still judge urls", () => {
+            // Every url-level cut at once: the limit, the threshold and the 404 rule
+            // all belong to the inner `urls` relation, never to the pairs.
+            expectGolden("enabled-sites-v2.device.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                devices: ["desktop", "mobile"],
+                excludeNotFound: true,
+                limit: 5000,
+                minHits: 2,
+            })));
+        });
+        it("should split a list whose urls are reduced to a cache key", () => {
+            expectGolden("scoped-strip-params.device.prewarm", goldenText(prewarmQueryFor("scoped-strip-params", {
+                devices: ["desktop", "mobile", "tablet"],
+            })));
+        });
+    });
+    describe("variation — a prewarm list paired with custom variations", () => {
+        it("should cross every url with every variation", () => {
+            expectGolden("enabled-sites-v2.variation.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                variations: ["desktop-pdp-a", "mobile-pdp-a", "break"],
+            })));
+        });
+        it("should pair urls that were reduced to a cache key", () => {
+            expectGolden("scoped-strip-params.variation.prewarm", goldenText(prewarmQueryFor("scoped-strip-params", {
+                limit: 5000,
+                variations: ["men", "women"],
+            })));
+        });
+    });
+    describe("count — how large the list is, instead of what is in it", () => {
+        it("should count the list every other flag leaves", () => {
+            expectGolden("enabled-sites-v2.count.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                count: true,
+                excludeNotFound: true,
+                limit: 5000,
+                minHits: 2,
+            })));
+        });
+        it("should count a split list per device class, plus a total", () => {
+            expectGolden("enabled-sites-v2.device.count.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                count: true,
+                devices: ["desktop", "mobile"],
+            })));
+        });
+        it("should count custom variations as a product, not as rows", () => {
+            expectGolden("enabled-sites-v2.variation.count.prewarm", goldenText(prewarmQueryFor("enabled-sites-v2", {
+                count: true,
+                variations: ["desktop-pdp-a", "mobile-pdp-a", "break"],
+            })));
+        });
+    });
+    describe("pops — the same query for every app", () => {
+        it("should build the same pops query", () => {
+            const { parameters, sql } = buildPopsQuery({ app: APP, now: NOW });
+            expectGolden("pops", [sql.trim(), "", `-- parameters: ${parameters.join(", ")}`, ""].join("\n"));
+        });
+        it("should build the same pops query from rum", () => {
+            const { parameters, sql } = buildPopsQuery({
+                app: APP,
+                now: NOW,
+                useRum: true,
+            });
+            expectGolden("pops.rum", [sql.trim(), "", `-- parameters: ${parameters.join(", ")}`, ""].join("\n"));
+        });
+    });
+});

package/dist/services/query-builder/queries/spec/pops-query.spec.d.ts

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

package/dist/services/query-builder/queries/spec/pops-query.spec.js

@@ -0,0 +1,58 @@
+import { expect } from "chai";
+import { describe, it } from "mocha";
+import { buildPopsQuery } from "../pops-query.js";
+import { sinceDate, today } from "../query-model.js";
+describe("buildPopsQuery", () => {
+    it("should read the request log, not the page impressions", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("from fastly.logs");
+        expect(sql).to.not.contain("rum.pi");
+    });
+    it("should pass the window and the app as parameters, in order", () => {
+        const { parameters, sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("where date between ? and ?");
+        expect(sql).to.contain("and app = ?");
+        expect(parameters).to.deep.equal([sinceDate(7), today(), "shop-de"]);
+    });
+    it("should look back a week by default", () => {
+        const [start, end] = buildPopsQuery({ app: "shop-de" }).parameters;
+        const days = (Date.parse(String(end)) - Date.parse(String(start))) / 86_400_000;
+        expect(days).to.equal(7);
+    });
+    it("should take the window from the caller", () => {
+        const { parameters } = buildPopsQuery({ app: "shop-de", days: 30 });
+        expect(parameters[0]).to.equal(sinceDate(30));
+    });
+    it("should count Speed Kit's own asset requests by default", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("and isassetrequest");
+        expect(sql).to.contain("and isnavigaterequest");
+        expect(sql).to.not.contain("ispibeacon");
+    });
+    it("should count beacons instead when there is no accelerated traffic", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de", useRum: true });
+        expect(sql).to.contain("and ispibeacon");
+        expect(sql).to.not.contain("isassetrequest");
+    });
+    it("should exclude bots and unknown origins", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("and client.bot is null");
+        expect(sql).to.contain("and origin not in ('Unknown', '')");
+    });
+    it("should keep the locale prefix of an origin", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("regexp_extract(url_extract_path(asseturl)");
+        expect(sql).to.contain(String.raw `(?i)((/\w+)?/[a-z]{2}([-/_][a-z]{2})*/)`);
+    });
+    it("should aggregate per region, pop and origin", () => {
+        const { sql } = buildPopsQuery({ app: "shop-de" });
+        expect(sql).to.contain("coalesce(originWithPrefix, origin) as origin");
+        expect(sql).to.contain("count() as hits");
+        expect(sql).to.contain("group by grouping sets (");
+        expect(sql).to.contain("having originWithPrefix is null or originWithPrefix <> 'Unknown'");
+    });
+    it("should project only what the aggregation reads", () => {
+        // `select *` would carry every column of the log through the CTE.
+        expect(buildPopsQuery({ app: "shop-de" }).sql).to.not.contain("select *");
+    });
+});

package/dist/services/query-builder/queries/spec/queries.spec.d.ts

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