@braidlabs/gateway 0.7.1 → 0.8.1

package/src/speculation.d.ts

@@ -0,0 +1,56 @@
+import type { FragmentManifest } from './registry.js';
+/**
+ * Speculation Rules (Chromium) built from the registry: the pages a fragment pierces, for the
+ * fragments that asked the browser to fetch or render them before a click.
+ *
+ * Nothing here is stored or configured beyond the manifests. The gateway already knows which URL
+ * patterns compose which fragment; the browser is told the same patterns, in the format it reads.
+ */
+export interface SpeculationRule {
+    source: 'document';
+    where: {
+        and: [
+            {
+                or: {
+                    href_matches: {
+                        pathname: string;
+                    };
+                    relative_to: 'document';
+                }[];
+            },
+            {
+                not: {
+                    selector_matches: string;
+                };
+            }
+        ];
+    };
+    eagerness: 'moderate';
+}
+/**
+ * Links never speculated, whatever they point at: ones the page marks as not to be followed (as
+ * user-generated content often is), and ones it opts out by name.
+ */
+export declare const SPECULATION_EXCLUDED_LINKS = "[rel~=\"nofollow\"], [data-braid-no-speculate]";
+export interface SpeculationRules {
+    prefetch?: SpeculationRule[];
+    prerender?: SpeculationRule[];
+}
+/**
+ * The rule set for these manifests: every pierce pattern of a bound fragment that sets
+ * `speculate`.
+ *
+ * Two kinds are left out, because their patterns describe pages the fragment does not own:
+ *
+ * - **An unbound fragment** is chrome — a header, a notifications panel — pierced into pages
+ *   that belong to someone else.
+ * - **A pattern that matches any path** (`/*`, `/:rest*`) would make every same-origin link on
+ *   every page speculative, `/logout` included.
+ */
+export declare function speculationRulesFor(manifests: readonly FragmentManifest[]): SpeculationRules;
+/**
+ * Whether a pierce pattern covers every page of the site rather than some of them: anything that
+ * is not a literal first segment (`/*`, `/:page`, `/(.*)`), or that matches a path nobody wrote.
+ * The home page alone (`/`) is a page like any other. Registry analysis judges it the same way.
+ */
+export declare function matchesAnyPath(pattern: string): boolean;

package/src/speculation.js

@@ -0,0 +1,85 @@
+/**
+ * Links never speculated, whatever they point at: ones the page marks as not to be followed (as
+ * user-generated content often is), and ones it opts out by name.
+ */
+export const SPECULATION_EXCLUDED_LINKS = '[rel~="nofollow"], [data-braid-no-speculate]';
+/**
+ * The rule set for these manifests: every pierce pattern of a bound fragment that sets
+ * `speculate`.
+ *
+ * Two kinds are left out, because their patterns describe pages the fragment does not own:
+ *
+ * - **An unbound fragment** is chrome — a header, a notifications panel — pierced into pages
+ *   that belong to someone else.
+ * - **A pattern that matches any path** (`/*`, `/:rest*`) would make every same-origin link on
+ *   every page speculative, `/logout` included.
+ */
+export function speculationRulesFor(manifests) {
+    const rules = {};
+    for (const action of ['prefetch', 'prerender']) {
+        const patterns = new Set();
+        for (const manifest of manifests) {
+            if (manifest.speculate !== action || manifest.bound === false)
+                continue;
+            for (const pattern of manifest.pierce ?? []) {
+                if (matchesAnyPath(pattern))
+                    continue;
+                patterns.add(pattern);
+                const toggled = slashToggled(pattern);
+                if (toggled)
+                    patterns.add(toggled);
+            }
+        }
+        if (patterns.size === 0)
+            continue;
+        rules[action] = [
+            {
+                source: 'document',
+                where: {
+                    and: [
+                        { or: [...patterns].map((pathname) => ({ href_matches: { pathname }, relative_to: 'document' })) },
+                        { not: { selector_matches: SPECULATION_EXCLUDED_LINKS } },
+                    ],
+                },
+                // on hover or pointerdown: early enough to feel instant, late enough not to fetch every link
+                eagerness: 'moderate',
+            },
+        ];
+    }
+    return rules;
+}
+/**
+ * Whether a pierce pattern covers every page of the site rather than some of them: anything that
+ * is not a literal first segment (`/*`, `/:page`, `/(.*)`), or that matches a path nobody wrote.
+ * The home page alone (`/`) is a page like any other. Registry analysis judges it the same way.
+ */
+export function matchesAnyPath(pattern) {
+    if (pattern === '/')
+        return false;
+    if (!/^\/[^:*({?+\\]/.test(pattern))
+        return true;
+    try {
+        const compiled = new URLPattern({ pathname: pattern });
+        return ['/__braid_probe', '/__braid_probe/deeper'].some((pathname) => compiled.test({ pathname }));
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The pattern that matches the trailing-slash twin of a URL this one matches.
+ *
+ * Pierce matching is slash-insensitive (`/checkout/*` also pierces `/checkout`), and a link the
+ * gateway would compose should be speculated too. URLPattern itself is strict, so the twin is
+ * listed alongside.
+ */
+function slashToggled(pattern) {
+    if (pattern === '/' || pattern === '/*')
+        return null;
+    if (pattern.endsWith('/*'))
+        return pattern.slice(0, -2);
+    if (pattern.endsWith('*'))
+        return null;
+    return pattern.endsWith('/') ? pattern.slice(0, -1) : `${pattern}/`;
+}
+//# sourceMappingURL=speculation.js.map

package/src/speculation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"speculation.js","sourceRoot":"","sources":["../../../../libs/braid-gateway/src/speculation.ts"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,8CAA8C,CAAC;AAOzF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAsC;IACxE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,KAAK,MAAM,MAAM,IAAI,CAAC,UAAU,EAAE,WAAW,CAAU,EAAE,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;QACnC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,QAAQ,CAAC,SAAS,KAAK,MAAM,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK;gBAAE,SAAS;YACxE,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;gBAC5C,IAAI,cAAc,CAAC,OAAO,CAAC;oBAAE,SAAS;gBACtC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;gBACtB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;gBACtC,IAAI,OAAO;oBAAE,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;YAAE,SAAS;QAClC,KAAK,CAAC,MAAM,CAAC,GAAG;YACd;gBACE,MAAM,EAAE,UAAU;gBAClB,KAAK,EAAE;oBACL,GAAG,EAAE;wBACH,EAAE,EAAE,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE;wBAClG,EAAE,GAAG,EAAE,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,EAAE;qBAC1D;iBACF;gBACD,6FAA6F;gBAC7F,SAAS,EAAE,UAAU;aACtB;SACF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAClC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,gBAAgB,EAAE,uBAAuB,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACrG,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC;AACtE,CAAC"}