@drupflare/spool 0.1.0 → 0.2.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/README.md +193 -1
- package/dist/cdn/manifest.json +1 -1
- package/dist/media/embeds.d.ts +59 -0
- package/dist/media/embeds.js +120 -0
- package/dist/media/headers.d.ts +13 -0
- package/dist/media/headers.js +44 -0
- package/dist/media/html.d.ts +27 -0
- package/dist/media/html.js +93 -0
- package/dist/media/image.d.ts +222 -0
- package/dist/media/image.js +413 -0
- package/dist/media/index.d.ts +6 -0
- package/dist/media/index.js +6 -0
- package/dist/media/lazy.d.ts +26 -0
- package/dist/media/lazy.js +74 -0
- package/dist/media/responsive.d.ts +45 -0
- package/dist/media/responsive.js +98 -0
- package/dist/media/video.d.ts +30 -0
- package/dist/media/video.js +75 -0
- package/dist/proxy/dictionary.d.ts +58 -0
- package/dist/proxy/dictionary.js +197 -0
- package/dist/proxy/index.d.ts +1 -0
- package/dist/proxy/index.js +1 -0
- package/dist/proxy/proxy.d.ts +47 -0
- package/dist/proxy/proxy.js +132 -13
- package/dist/report/derive.d.ts +2 -0
- package/dist/report/derive.js +6 -2
- package/dist/report/index.d.ts +1 -0
- package/dist/report/index.js +1 -0
- package/dist/report/ledger.d.ts +169 -0
- package/dist/report/ledger.js +278 -0
- package/dist/report/measurement.d.ts +1 -1
- package/dist/report/measurement.js +4 -1
- package/dist/trim/tokens.d.ts +4 -0
- package/dist/trim/tokens.js +1 -1
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -36,6 +36,7 @@ has no runtime dependencies. A site with no server code can load it from two fil
|
|
|
36
36
|
- [Shadow Mode](#-shadow-mode)
|
|
37
37
|
- [Proxy Mode](#-proxy-mode)
|
|
38
38
|
- [Trimmed Stylesheets](#-trimmed-stylesheets)
|
|
39
|
+
- [Images and Video](#-images-and-video)
|
|
39
40
|
- [Out of Scope](#-out-of-scope)
|
|
40
41
|
- [Browser Support](#-browser-support)
|
|
41
42
|
- [Subpath Exports](#-subpath-exports)
|
|
@@ -1419,7 +1420,8 @@ in the instance: a restart forgets them, and each instance of a scaled-out proxy
|
|
|
1419
1420
|
A whole page is a large artifact, and the provisioning rule declines one that costs more than the
|
|
1420
1421
|
priors say it saves, so set `provision` on the spool for large pages. A `Content-Security-Policy`
|
|
1421
1422
|
that allows only nonce or hash scripts blocks the injected client tag. A URL with a query string
|
|
1422
|
-
always goes to the origin. [Trimmed Stylesheets](#-trimmed-stylesheets) covers the `trim` option
|
|
1423
|
+
always goes to the origin. [Trimmed Stylesheets](#-trimmed-stylesheets) covers the `trim` option
|
|
1424
|
+
and [Images and Video](#-images-and-video) the `images` and `video` options.
|
|
1423
1425
|
|
|
1424
1426
|
---
|
|
1425
1427
|
|
|
@@ -1475,6 +1477,195 @@ seen, never to a repeat or local view, and it is not part of the per-view headli
|
|
|
1475
1477
|
|
|
1476
1478
|
---
|
|
1477
1479
|
|
|
1480
|
+
## 🎬 Images and Video
|
|
1481
|
+
|
|
1482
|
+
A browser that has fetched an image cannot make it smaller, so conversion happens where the file is
|
|
1483
|
+
served. `@drupflare/spool/media` gives `spoolProxy` three options, each off until set. `images`
|
|
1484
|
+
converts a JPEG or PNG response to WebP for a browser whose `Accept` lists it. `video` rewrites
|
|
1485
|
+
the `<video>` tags of an HTML response, such as adding `preload="none"`. `embeds` swaps a YouTube
|
|
1486
|
+
or Vimeo iframe for a link that loads the player on click.
|
|
1487
|
+
|
|
1488
|
+
```ts
|
|
1489
|
+
import { type ImageEncoder } from '@drupflare/spool/media';
|
|
1490
|
+
import { spoolProxy } from '@drupflare/spool/proxy';
|
|
1491
|
+
import { memoryStore } from '@drupflare/spool/stores';
|
|
1492
|
+
|
|
1493
|
+
export function mediaProxy(encoder: ImageEncoder) {
|
|
1494
|
+
return spoolProxy({
|
|
1495
|
+
origin: 'https://origin.example.edu',
|
|
1496
|
+
spool: { store: memoryStore() },
|
|
1497
|
+
images: { encoder, width: { fallback: 1600 } },
|
|
1498
|
+
video: { preload: 'none', autoplay: 'defer', when: 'slow' }
|
|
1499
|
+
});
|
|
1500
|
+
}
|
|
1501
|
+
```
|
|
1502
|
+
|
|
1503
|
+
An `ImageEncoder` takes the origin's bytes and `{ format: 'webp', quality, width }` and returns
|
|
1504
|
+
`{ bytes }`. It never upscales, so `width` is a ceiling, and it throws on input it cannot decode.
|
|
1505
|
+
spool has no runtime dependencies and ships an adapter for [tinyimg](https://tinyimg.gmitch215.dev),
|
|
1506
|
+
which decodes and encodes inside WebAssembly:
|
|
1507
|
+
|
|
1508
|
+
```js
|
|
1509
|
+
import { readFile } from 'node:fs/promises';
|
|
1510
|
+
import { TinyImgModule, transform } from '@gmitch215/tinyimg';
|
|
1511
|
+
import { tinyimgEncoder } from '@drupflare/spool/media';
|
|
1512
|
+
|
|
1513
|
+
const wasm = new URL(import.meta.resolve('@gmitch215/tinyimg/tinyimg.wasm'));
|
|
1514
|
+
const module = await TinyImgModule.loadBytes(await readFile(wasm));
|
|
1515
|
+
|
|
1516
|
+
export const encoder = tinyimgEncoder({ module, transform });
|
|
1517
|
+
```
|
|
1518
|
+
|
|
1519
|
+
Use tinyimg 1.1.1 or later. Version 1.1.0 and earlier drop the EXIF orientation tag without
|
|
1520
|
+
rotating the pixels, so a phone photo comes out sideways. `tinyimgEncoder` throws when the module
|
|
1521
|
+
reports an older version.
|
|
1522
|
+
|
|
1523
|
+
Quality is 80, 65 for `Save-Data: on` and 70 for an `ECT` of `slow-2g`, `2g` or `3g`. The width
|
|
1524
|
+
comes from `Sec-CH-Width`, then `Sec-CH-Viewport-Width` times `Sec-CH-DPR`, then
|
|
1525
|
+
`width.fallback`. The proxy converts a `GET` that matches `paths` (JPEG and PNG names by default),
|
|
1526
|
+
has no `Range` or `Authorization`, and gets a `200` JPEG or PNG without a cookie between
|
|
1527
|
+
`minBytes` (4096) and `maxBytes` (15,000,000). Anything else, and any file the encoder cannot
|
|
1528
|
+
shrink, goes out as the origin sent it. The proxy fetches the origin for every request, so a
|
|
1529
|
+
visitor only gets bytes the origin sent that visitor.
|
|
1530
|
+
|
|
1531
|
+
A converted response carries `Vary` for `Accept`, `Save-Data`, `Sec-CH-Width`, `Sec-CH-DPR`,
|
|
1532
|
+
`Sec-CH-Viewport-Width` and `ECT`, a weak `ETag` and `X-Spool-Image`. HTML responses gain
|
|
1533
|
+
`Accept-CH` for the three size hints and `ECT` unless `hints` is false, and the browser then
|
|
1534
|
+
sends them with later image requests to the same origin.
|
|
1535
|
+
|
|
1536
|
+
`maxWidth` (2560) is the width for a request that carries no hint, and `false` removes it. `png`
|
|
1537
|
+
is `'lossy'` by default. `'lossless'` encodes every PNG without loss, and `'auto'` encodes a PNG
|
|
1538
|
+
under 200 KB both ways and serves the smaller file, which suits screenshots and flat graphics.
|
|
1539
|
+
Requests for the same file, quality and width share one encoder call while it runs. The proxy
|
|
1540
|
+
waits `timeoutMs` (10,000) for the encoder and then serves the origin's file, and the late result
|
|
1541
|
+
is cached for the next request. `timeoutMs: false` waits without limit.
|
|
1542
|
+
|
|
1543
|
+
Drupal's video formatter has no `preload` setting, and `preload="none"` does not stop `autoplay`.
|
|
1544
|
+
`autoplay: 'defer'` removes the attribute, adds `controls` and marks the tag
|
|
1545
|
+
`data-spool-autoplay`. With `when: 'always'` the page the spool keeps carries the rewrite. With
|
|
1546
|
+
`'save-data'` or `'slow'` the rewritten page is private to that visitor: it gets `private` in
|
|
1547
|
+
`Cache-Control` and `Save-Data, ECT` in `Vary`, and the spool does not keep it. A device's stored
|
|
1548
|
+
copy of that page keeps the origin's tags.
|
|
1549
|
+
|
|
1550
|
+
`proxy.images` counts `converted`, `bytesIn` and `bytesOut` (converted responses only),
|
|
1551
|
+
`cacheHits`, `coalesced`, `lazied`, `responsive`, and `skipped` by reason. `proxy.video` counts
|
|
1552
|
+
`pages` and `rewritten`. Read the saving as `bytesIn - bytesOut` over real traffic on the site. A
|
|
1553
|
+
request for any other path counts under `skipped.path`, so that key follows total traffic.
|
|
1554
|
+
[docs/security.md](docs/security.md#images-and-video) covers the decoder.
|
|
1555
|
+
|
|
1556
|
+
### Page Rewrites
|
|
1557
|
+
|
|
1558
|
+
Three options change the HTML the origin sends. Each edits start tags only and leaves every other
|
|
1559
|
+
byte as it was, and a rewritten page gets a weak `ETag`.
|
|
1560
|
+
|
|
1561
|
+
```ts
|
|
1562
|
+
import { type ImageEncoder } from '@drupflare/spool/media';
|
|
1563
|
+
import { spoolProxy } from '@drupflare/spool/proxy';
|
|
1564
|
+
import { memoryStore } from '@drupflare/spool/stores';
|
|
1565
|
+
|
|
1566
|
+
export function rewriteProxy(encoder: ImageEncoder) {
|
|
1567
|
+
return spoolProxy({
|
|
1568
|
+
origin: 'https://origin.example.edu',
|
|
1569
|
+
spool: { store: memoryStore() },
|
|
1570
|
+
images: {
|
|
1571
|
+
encoder,
|
|
1572
|
+
png: 'auto',
|
|
1573
|
+
maxWidth: 1920,
|
|
1574
|
+
timeoutMs: 5000,
|
|
1575
|
+
lazy: { skip: 3 },
|
|
1576
|
+
responsive: { widths: [480, 960, 1440], sizes: '(min-width: 60em) 50vw, 100vw' }
|
|
1577
|
+
},
|
|
1578
|
+
embeds: { providers: ['youtube'], thumbnail: false }
|
|
1579
|
+
});
|
|
1580
|
+
}
|
|
1581
|
+
```
|
|
1582
|
+
|
|
1583
|
+
`lazy` adds `loading="lazy"` and `decoding="async"` to each `<img>` after the first `skip` (2 by
|
|
1584
|
+
default), and `iframes: true` does the same for `<iframe>`. It leaves a tag that has `loading`,
|
|
1585
|
+
`fetchpriority` or a lazy-loading library's `data-src`, a tag inside a `<header>` or `<noscript>`,
|
|
1586
|
+
and an image that a `<link rel="preload" as="image">` names. A browser that defers the largest
|
|
1587
|
+
image of a page paints it later, so `skip` is the only guard and the option is off until set. In a
|
|
1588
|
+
crawl of 70 pages per profile on 16 sites, the default `skip` of 2 made the largest image lazy on 2
|
|
1589
|
+
of 23 desktop pages and 2 of 20 phone pages that had an image as their largest element, and no
|
|
1590
|
+
`skip` from 2 to 4 reached zero on both profiles.
|
|
1591
|
+
|
|
1592
|
+
`responsive` adds a `srcset` of `?spool-w=<width>` variants to a same-origin `<img>` that has none,
|
|
1593
|
+
one per entry of `widths` (320, 480, 640, 960, 1280 and 1920 by default), and a `sizes` of `100vw`
|
|
1594
|
+
unless the tag has one. The proxy removes `spool-w` before it asks the origin, answers only widths
|
|
1595
|
+
from the list and never sends a file larger than the origin's. Firefox and Safari send no
|
|
1596
|
+
`Sec-CH-Width`, and this is how they get a resized file. Name the layout width in `sizes`, since
|
|
1597
|
+
`100vw` makes the browser pick the widest candidate it can use. A tag with `srcset` or `data-src`,
|
|
1598
|
+
and any tag inside `<picture>`, stays as it is.
|
|
1599
|
+
|
|
1600
|
+
`embeds` replaces a server-rendered YouTube or Vimeo `<iframe>` with one whose `srcdoc` holds a
|
|
1601
|
+
link to the player. YouTube shows its thumbnail (`thumbnail: false` shows a plain frame) and the
|
|
1602
|
+
player loads on click. A page that sends `Content-Security-Policy` is left alone unless
|
|
1603
|
+
`ignoreCsp` is true, and so is an embed with `enablejsapi=1`. `proxy.embeds` counts `pages`,
|
|
1604
|
+
`rewritten` and `skipped`. [docs/security.md](docs/security.md#embed-facades) covers the rules.
|
|
1605
|
+
|
|
1606
|
+
### Dictionary Transport
|
|
1607
|
+
|
|
1608
|
+
A visitor who holds an earlier stylesheet or script of a directory can fetch the next one as the
|
|
1609
|
+
difference from it. `dictionary` implements this for Chromium 130 and later
|
|
1610
|
+
([RFC 9842](https://www.rfc-editor.org/rfc/rfc9842)). The proxy marks public `.css` and `.js`
|
|
1611
|
+
responses with `Use-As-Dictionary` and answers a request that names one of them with
|
|
1612
|
+
`Content-Encoding: dcz`. spool has no compression library, so the caller supplies the `encoder`,
|
|
1613
|
+
and Node's `zlib` does zstd:
|
|
1614
|
+
|
|
1615
|
+
```ts
|
|
1616
|
+
import { promisify } from 'node:util';
|
|
1617
|
+
import { zstdCompress } from 'node:zlib';
|
|
1618
|
+
import { spoolProxy } from '@drupflare/spool/proxy';
|
|
1619
|
+
import { memoryStore } from '@drupflare/spool/stores';
|
|
1620
|
+
|
|
1621
|
+
const compress = promisify(zstdCompress);
|
|
1622
|
+
|
|
1623
|
+
export const proxy = spoolProxy({
|
|
1624
|
+
origin: 'https://origin.example.edu',
|
|
1625
|
+
spool: { store: memoryStore() },
|
|
1626
|
+
dictionary: {
|
|
1627
|
+
encoder: async (dictionary, input) => new Uint8Array(await compress(input, { dictionary }))
|
|
1628
|
+
}
|
|
1629
|
+
});
|
|
1630
|
+
```
|
|
1631
|
+
|
|
1632
|
+
The `encoder` gets the dictionary, the new file and the coding (`'dcz'`, or `'dcb'` when `formats`
|
|
1633
|
+
lists it) and returns the compressed stream. spool adds the coding's header. An encoder that
|
|
1634
|
+
throws, or whose output is no smaller, leaves the plain file. Only responses the proxy would keep
|
|
1635
|
+
as public ones, with no cookie, ever become dictionaries. `proxy.dictionary` counts `registered`,
|
|
1636
|
+
`encoded`, `bytesIn`, `bytesOut` and `skipped`.
|
|
1637
|
+
[docs/security.md](docs/security.md#dictionary-transport) covers the exposure.
|
|
1638
|
+
|
|
1639
|
+
`base` names the files that register as dictionaries, as a function of the pathname, a regular
|
|
1640
|
+
expression or a list of them. Without it the browser holds the latest file of each directory it
|
|
1641
|
+
fetched, and the sizing in [docs/impact.md](docs/impact.md#savings-today-and-at-maximum) shows that
|
|
1642
|
+
choice recovers little. With it the browser holds only the files you name, one per directory, and
|
|
1643
|
+
every other file of the directory is encoded against the base the request names.
|
|
1644
|
+
`scripts/measure/dictionary-size.ts` records the best base of each directory of a site.
|
|
1645
|
+
|
|
1646
|
+
### Defaults
|
|
1647
|
+
|
|
1648
|
+
Every option is absent by default. The table shows what a feature does once its parent option is
|
|
1649
|
+
set and how to change it.
|
|
1650
|
+
|
|
1651
|
+
| Feature | Option | Default once the parent is set | Leave or enter |
|
|
1652
|
+
| ------------------------------------------ | ------------------- | ------------------------------------------- | ----------------------------------------------------- |
|
|
1653
|
+
| WebP conversion, `304` and `X-Spool-Image` | `images` | on, needs an `encoder` | leave `images` out |
|
|
1654
|
+
| `Accept-CH` hints and `Vary` | `images.hints` | on | `hints: false` |
|
|
1655
|
+
| Quality by `Save-Data` and `ECT` | `images.quality` | 80, 65 and 70 | give all three one number |
|
|
1656
|
+
| Width ceiling for a request with no width | `images.maxWidth` | 2560 | `maxWidth: false`, or another number |
|
|
1657
|
+
| Shared encodes and the encoder time limit | `images.timeoutMs` | 10,000 ms, identical encodes share one call | `timeoutMs: false` removes the limit |
|
|
1658
|
+
| PNG mode | `images.png` | `'lossy'` | `'auto'` or `'lossless'` |
|
|
1659
|
+
| `loading="lazy"` on images and iframes | `images.lazy` | off | `lazy: {}` or `{ skip, iframes }` |
|
|
1660
|
+
| `srcset` variants | `images.responsive` | off | `responsive: {}` or `{ widths, sizes }` |
|
|
1661
|
+
| `preload="none"` on video | `video.preload` | `'none'` | `preload: false` |
|
|
1662
|
+
| Video autoplay deferral | `video.autoplay` | off | `autoplay: 'defer'` |
|
|
1663
|
+
| YouTube and Vimeo facades | `embeds` | off | `embeds: {}` or `{ providers, thumbnail, ignoreCsp }` |
|
|
1664
|
+
| Dictionary transport | `dictionary` | off | `dictionary: { encoder }` |
|
|
1665
|
+
| Which files become dictionaries | `dictionary.base` | every `.css` and `.js` response | `base: /\/base\.js$/`, a list or a function |
|
|
1666
|
+
|
|
1667
|
+
---
|
|
1668
|
+
|
|
1478
1669
|
## 🚫 Out of Scope
|
|
1479
1670
|
|
|
1480
1671
|
- spool never authorises on the client. The device holds only what the server already sent that
|
|
@@ -1520,6 +1711,7 @@ loads per view and reports the view as such.
|
|
|
1520
1711
|
| `@drupflare/spool/client` | `register` and the page handle |
|
|
1521
1712
|
| `@drupflare/spool/report` | the energy model |
|
|
1522
1713
|
| `@drupflare/spool/trim` | `buildTrimManifest`, `trimCss` and `guardPage` |
|
|
1714
|
+
| `@drupflare/spool/media` | `tinyimgEncoder`, `imageVariant` and `rewriteVideo` |
|
|
1523
1715
|
|
|
1524
1716
|
---
|
|
1525
1717
|
|
package/dist/cdn/manifest.json
CHANGED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/** the embed hosts `embeds` knows */
|
|
2
|
+
export type EmbedProvider = 'youtube' | 'vimeo';
|
|
3
|
+
/**
|
|
4
|
+
* What `spoolProxy({ embeds })` does to a server-rendered `<iframe>` of a YouTube or Vimeo embed:
|
|
5
|
+
* it becomes an iframe whose `srcdoc` is one link to the real embed, so the player loads when the
|
|
6
|
+
* visitor clicks. `providers` defaults to both. `thumbnail` shows YouTube's `hqdefault.jpg` in the
|
|
7
|
+
* link; default true, and Vimeo always gets a plain placeholder. A page that sends a
|
|
8
|
+
* `Content-Security-Policy` header is left alone, because the facade needs an inline style and the
|
|
9
|
+
* thumbnail host, unless `ignoreCsp` is true.
|
|
10
|
+
*/
|
|
11
|
+
export type EmbedOptions = {
|
|
12
|
+
providers?: readonly EmbedProvider[];
|
|
13
|
+
thumbnail?: boolean;
|
|
14
|
+
ignoreCsp?: boolean;
|
|
15
|
+
};
|
|
16
|
+
/** `EmbedOptions` with every default applied */
|
|
17
|
+
export type ResolvedEmbedOptions = {
|
|
18
|
+
providers: ReadonlySet<EmbedProvider>;
|
|
19
|
+
thumbnail: boolean;
|
|
20
|
+
ignoreCsp: boolean;
|
|
21
|
+
};
|
|
22
|
+
/** what the proxy counted for `embeds`: pages with a rewritten embed, the embeds, and the ones left alone by reason (`csp`, `jsapi`) */
|
|
23
|
+
export type EmbedStats = {
|
|
24
|
+
pages: number;
|
|
25
|
+
rewritten: number;
|
|
26
|
+
skipped: Record<string, number>;
|
|
27
|
+
};
|
|
28
|
+
/** applies the defaults to `options` */
|
|
29
|
+
export declare function resolveEmbedOptions(options?: EmbedOptions): ResolvedEmbedOptions;
|
|
30
|
+
/** the provider and id of an embed URL, with the URL made absolute, or null for any other address */
|
|
31
|
+
export declare function embedOf(src: string): {
|
|
32
|
+
provider: EmbedProvider;
|
|
33
|
+
id: string;
|
|
34
|
+
url: URL;
|
|
35
|
+
} | null;
|
|
36
|
+
/** the document a facade iframe carries in `srcdoc`, before it is escaped for the attribute */
|
|
37
|
+
export declare function facadeDocument(embed: {
|
|
38
|
+
provider: EmbedProvider;
|
|
39
|
+
id: string;
|
|
40
|
+
url: URL;
|
|
41
|
+
}, title: string, thumbnail: boolean): string;
|
|
42
|
+
/**
|
|
43
|
+
* Replaces each server-rendered YouTube or Vimeo `<iframe src>` in `html` with a facade, as
|
|
44
|
+
* `options` allow, and says how many it replaced and how many it left alone. Only an `https`,
|
|
45
|
+
* `http` or protocol-relative `src` on a known embed host and path, with an id of 6 to 64 letters,
|
|
46
|
+
* digits, `-` and `_`, is touched. An iframe inside an HTML comment or `<noscript>`, one that has
|
|
47
|
+
* `srcdoc`, and one whose URL sets `enablejsapi=1` (the page's script expects the real player) stay
|
|
48
|
+
* as they are; the last is counted as `jsapi`. With `page.csp` set, and no `ignoreCsp`, every
|
|
49
|
+
* matching iframe is left alone and counted as `csp`. The facade keeps `width`, `height`, `title`,
|
|
50
|
+
* `class`, `style`, `allow`, `allowfullscreen`, `loading`, `id`, `sandbox` and `referrerpolicy`.
|
|
51
|
+
* Everything outside the replaced start tags stays byte for byte.
|
|
52
|
+
*/
|
|
53
|
+
export declare function rewriteEmbeds(html: string, options?: EmbedOptions | ResolvedEmbedOptions, page?: {
|
|
54
|
+
csp: boolean;
|
|
55
|
+
}): {
|
|
56
|
+
html: string;
|
|
57
|
+
rewritten: number;
|
|
58
|
+
skipped: Record<string, number>;
|
|
59
|
+
};
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
import { decodeEntities, tagsOf } from '../trim/tokens.js';
|
|
2
|
+
import { applyEdits, commentRanges, find, noscriptRanges, within } from './html.js';
|
|
3
|
+
/** applies the defaults to `options` */
|
|
4
|
+
export function resolveEmbedOptions(options = {}) {
|
|
5
|
+
return {
|
|
6
|
+
providers: new Set(options.providers ?? ['youtube', 'vimeo']),
|
|
7
|
+
thumbnail: options.thumbnail !== false,
|
|
8
|
+
ignoreCsp: options.ignoreCsp === true
|
|
9
|
+
};
|
|
10
|
+
}
|
|
11
|
+
const HOSTS = {
|
|
12
|
+
'youtube.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
|
|
13
|
+
'www.youtube.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
|
|
14
|
+
'youtube-nocookie.com': { provider: 'youtube', path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/ },
|
|
15
|
+
'www.youtube-nocookie.com': {
|
|
16
|
+
provider: 'youtube',
|
|
17
|
+
path: /^\/embed\/([A-Za-z0-9_-]{6,64})\/?$/
|
|
18
|
+
},
|
|
19
|
+
'player.vimeo.com': { provider: 'vimeo', path: /^\/video\/([A-Za-z0-9_-]{6,64})\/?$/ }
|
|
20
|
+
};
|
|
21
|
+
/** the provider and id of an embed URL, with the URL made absolute, or null for any other address */
|
|
22
|
+
export function embedOf(src) {
|
|
23
|
+
const text = decodeEntities(src).trim();
|
|
24
|
+
if (!/^(?:https?:)?\/\//i.test(text))
|
|
25
|
+
return null;
|
|
26
|
+
let url;
|
|
27
|
+
try {
|
|
28
|
+
url = new URL(text.startsWith('//') ? `https:${text}` : text);
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
const host = HOSTS[url.hostname.toLowerCase()];
|
|
34
|
+
const id = host?.path.exec(url.pathname)?.[1];
|
|
35
|
+
// the playlist embed is `/embed/videoseries?list=...` and has no single video id
|
|
36
|
+
if (!host || !id || id === 'videoseries')
|
|
37
|
+
return null;
|
|
38
|
+
return { provider: host.provider, id, url };
|
|
39
|
+
}
|
|
40
|
+
const escape = (text) => text.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
41
|
+
const KEPT = new Set([
|
|
42
|
+
'width',
|
|
43
|
+
'height',
|
|
44
|
+
'title',
|
|
45
|
+
'class',
|
|
46
|
+
'style',
|
|
47
|
+
'allow',
|
|
48
|
+
'allowfullscreen',
|
|
49
|
+
'loading',
|
|
50
|
+
'id',
|
|
51
|
+
'sandbox',
|
|
52
|
+
'referrerpolicy'
|
|
53
|
+
]);
|
|
54
|
+
const STYLE = 'html,body{margin:0;height:100%;background:#000}a{position:relative;display:block;height:100%;color:#fff;font:14px/1.2 sans-serif;text-decoration:none}' +
|
|
55
|
+
'img{position:absolute;top:0;left:0;width:100%;height:100%;object-fit:cover}' +
|
|
56
|
+
'.g{position:absolute;top:0;right:0;bottom:0;left:0;margin:auto;width:64px;height:44px;border-radius:12px;background:rgba(0,0,0,.7);text-align:center;font-size:26px;line-height:44px}' +
|
|
57
|
+
'.t{position:absolute;left:0;right:0;bottom:0;padding:8px 12px;background:rgba(0,0,0,.6);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}';
|
|
58
|
+
/** the document a facade iframe carries in `srcdoc`, before it is escaped for the attribute */
|
|
59
|
+
export function facadeDocument(embed, title, thumbnail) {
|
|
60
|
+
const link = new URL(embed.url);
|
|
61
|
+
link.searchParams.set('autoplay', '1');
|
|
62
|
+
const label = escape(title);
|
|
63
|
+
const picture = thumbnail && embed.provider === 'youtube'
|
|
64
|
+
? `<img src="https://i.ytimg.com/vi/${embed.id}/hqdefault.jpg" alt="">`
|
|
65
|
+
: '';
|
|
66
|
+
return (`<!doctype html><meta charset=utf-8><style>${STYLE}</style>` +
|
|
67
|
+
`<a href="${escape(link.href)}" aria-label="${label}">${picture}` +
|
|
68
|
+
`<span class=g>▶</span><span class=t>${label}</span></a>`);
|
|
69
|
+
}
|
|
70
|
+
function facadeTag(html, tag, embed, o) {
|
|
71
|
+
const kept = tag.attributes
|
|
72
|
+
.filter((a) => KEPT.has(a.name))
|
|
73
|
+
.map((a) => html.slice(a.start, a.end));
|
|
74
|
+
const title = decodeEntities(find(tag, 'title')?.value ?? '').trim() || 'Play video';
|
|
75
|
+
const doc = escape(facadeDocument(embed, title, o.thumbnail));
|
|
76
|
+
return `<iframe ${[...kept, `srcdoc="${doc}"`].join(' ')}>`;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Replaces each server-rendered YouTube or Vimeo `<iframe src>` in `html` with a facade, as
|
|
80
|
+
* `options` allow, and says how many it replaced and how many it left alone. Only an `https`,
|
|
81
|
+
* `http` or protocol-relative `src` on a known embed host and path, with an id of 6 to 64 letters,
|
|
82
|
+
* digits, `-` and `_`, is touched. An iframe inside an HTML comment or `<noscript>`, one that has
|
|
83
|
+
* `srcdoc`, and one whose URL sets `enablejsapi=1` (the page's script expects the real player) stay
|
|
84
|
+
* as they are; the last is counted as `jsapi`. With `page.csp` set, and no `ignoreCsp`, every
|
|
85
|
+
* matching iframe is left alone and counted as `csp`. The facade keeps `width`, `height`, `title`,
|
|
86
|
+
* `class`, `style`, `allow`, `allowfullscreen`, `loading`, `id`, `sandbox` and `referrerpolicy`.
|
|
87
|
+
* Everything outside the replaced start tags stays byte for byte.
|
|
88
|
+
*/
|
|
89
|
+
export function rewriteEmbeds(html, options = {}, page = { csp: false }) {
|
|
90
|
+
const resolved = options.providers instanceof Set
|
|
91
|
+
? options
|
|
92
|
+
: resolveEmbedOptions(options);
|
|
93
|
+
const tags = tagsOf(html);
|
|
94
|
+
const comments = commentRanges(html);
|
|
95
|
+
const noscripts = noscriptRanges(html, tags);
|
|
96
|
+
const edits = [];
|
|
97
|
+
const skipped = {};
|
|
98
|
+
for (const tag of tags) {
|
|
99
|
+
if (tag.name !== 'iframe' || html[tag.end] !== '>')
|
|
100
|
+
continue;
|
|
101
|
+
if (within(comments, tag.start) || within(noscripts, tag.start))
|
|
102
|
+
continue;
|
|
103
|
+
const src = find(tag, 'src')?.value;
|
|
104
|
+
if (src === undefined || find(tag, 'srcdoc'))
|
|
105
|
+
continue;
|
|
106
|
+
const embed = embedOf(src);
|
|
107
|
+
if (!embed || !resolved.providers.has(embed.provider))
|
|
108
|
+
continue;
|
|
109
|
+
if (embed.url.searchParams.get('enablejsapi') === '1') {
|
|
110
|
+
skipped.jsapi = (skipped.jsapi ?? 0) + 1;
|
|
111
|
+
continue;
|
|
112
|
+
}
|
|
113
|
+
if (page.csp && !resolved.ignoreCsp) {
|
|
114
|
+
skipped.csp = (skipped.csp ?? 0) + 1;
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
edits.push({ at: tag.start, to: tag.end + 1, text: facadeTag(html, tag, embed, resolved) });
|
|
118
|
+
}
|
|
119
|
+
return { html: applyEdits(html, edits), rewritten: edits.length, skipped };
|
|
120
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/** what a request says about the visitor's connection */
|
|
2
|
+
export type MediaSignals = {
|
|
3
|
+
/** `Save-Data: on` */
|
|
4
|
+
saveData: boolean;
|
|
5
|
+
/** `ECT` of `slow-2g`, `2g` or `3g` */
|
|
6
|
+
slow: boolean;
|
|
7
|
+
};
|
|
8
|
+
/** the connection signals in a request's `Save-Data` and `ECT` headers */
|
|
9
|
+
export declare function signalsOf(headers: Headers): MediaSignals;
|
|
10
|
+
/** adds each name to a comma-separated header, skipping any it already lists in any case */
|
|
11
|
+
export declare function mergeList(headers: Headers, name: string, additions: readonly string[]): void;
|
|
12
|
+
/** makes `Cache-Control` private: `public` becomes `private`, and a header with none gets `private, max-age=0` */
|
|
13
|
+
export declare function makePrivate(headers: Headers): void;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/** the connection signals in a request's `Save-Data` and `ECT` headers */
|
|
2
|
+
export function signalsOf(headers) {
|
|
3
|
+
const ect = (headers.get('ect') ?? '').trim().toLowerCase();
|
|
4
|
+
return {
|
|
5
|
+
saveData: (headers.get('save-data') ?? '').trim().toLowerCase() === 'on',
|
|
6
|
+
slow: ect === 'slow-2g' || ect === '2g' || ect === '3g'
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
/** adds each name to a comma-separated header, skipping any it already lists in any case */
|
|
10
|
+
export function mergeList(headers, name, additions) {
|
|
11
|
+
const current = headers.get(name);
|
|
12
|
+
const have = (current ?? '')
|
|
13
|
+
.split(',')
|
|
14
|
+
.map((part) => part.trim())
|
|
15
|
+
.filter((part) => part !== '');
|
|
16
|
+
if (have.includes('*'))
|
|
17
|
+
return;
|
|
18
|
+
const lower = new Set(have.map((part) => part.toLowerCase()));
|
|
19
|
+
const added = additions.filter((part) => !lower.has(part.toLowerCase()));
|
|
20
|
+
if (added.length === 0)
|
|
21
|
+
return;
|
|
22
|
+
headers.set(name, [...have, ...added].join(', '));
|
|
23
|
+
}
|
|
24
|
+
/** makes `Cache-Control` private: `public` becomes `private`, and a header with none gets `private, max-age=0` */
|
|
25
|
+
export function makePrivate(headers) {
|
|
26
|
+
const value = headers.get('cache-control');
|
|
27
|
+
if (!value) {
|
|
28
|
+
headers.set('cache-control', 'private, max-age=0');
|
|
29
|
+
return;
|
|
30
|
+
}
|
|
31
|
+
const parts = value
|
|
32
|
+
.split(',')
|
|
33
|
+
.map((part) => part.trim())
|
|
34
|
+
.filter((part) => part !== '');
|
|
35
|
+
const names = parts.map((part) => (part.split('=')[0] ?? '').trim().toLowerCase());
|
|
36
|
+
if (names.includes('private'))
|
|
37
|
+
return;
|
|
38
|
+
const at = names.indexOf('public');
|
|
39
|
+
if (at >= 0)
|
|
40
|
+
parts[at] = 'private';
|
|
41
|
+
else
|
|
42
|
+
parts.unshift('private');
|
|
43
|
+
headers.set('cache-control', parts.join(', '));
|
|
44
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { type Attribute, type Tag } from '../trim/tokens.js';
|
|
2
|
+
/** one replacement in an HTML string: the text from `at` to `to` becomes `text` */
|
|
3
|
+
export type Edit = {
|
|
4
|
+
at: number;
|
|
5
|
+
to: number;
|
|
6
|
+
text: string;
|
|
7
|
+
};
|
|
8
|
+
/** the `[start, end)` ranges of the HTML comments in `html`; a comment that never closes runs to the end */
|
|
9
|
+
export declare function commentRanges(html: string): Array<[number, number]>;
|
|
10
|
+
/** the ranges of every `<noscript>` element, from its start tag to its end tag or the end of the HTML */
|
|
11
|
+
export declare function noscriptRanges(html: string, tags: readonly Tag[]): Array<[number, number]>;
|
|
12
|
+
/** the ranges of the outermost elements called `name`, from the start tag to the matching end tag or the end of the HTML */
|
|
13
|
+
export declare function elementRanges(html: string, tags: readonly Tag[], name: string): Array<[number, number]>;
|
|
14
|
+
/** the range of `<head>`, from its start tag to the first `<body>` or `</head>`, or null without one */
|
|
15
|
+
export declare function headRange(html: string, tags: readonly Tag[]): [number, number] | null;
|
|
16
|
+
/** whether `at` falls inside any of `ranges` */
|
|
17
|
+
export declare const within: (ranges: ReadonlyArray<[number, number]>, at: number) => boolean;
|
|
18
|
+
/** the first attribute of `tag` called `name`, whose name is already lowercase */
|
|
19
|
+
export declare const find: (tag: Tag, name: string) => Attribute | undefined;
|
|
20
|
+
/** the edit that gives the attribute `a` the value `value`, keeping its quote style */
|
|
21
|
+
export declare function setValue(html: string, a: Attribute, value: string): Edit;
|
|
22
|
+
/** the edit that adds `attributes` (such as `preload="none"`) to the end of `tag`, before a closing slash */
|
|
23
|
+
export declare function appendAttributes(html: string, tag: Tag, attributes: readonly string[]): Edit;
|
|
24
|
+
/** `html` with `edits` applied; they may arrive in any order and must not overlap */
|
|
25
|
+
export declare function applyEdits(html: string, edits: readonly Edit[]): string;
|
|
26
|
+
/** the start tags of `html` that are named `name`, close with `>` and sit outside comments */
|
|
27
|
+
export declare function tagsNamed(html: string, name: string, tags?: readonly Tag[]): Tag[];
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { tagsOf } from '../trim/tokens.js';
|
|
2
|
+
/** the `[start, end)` ranges of the HTML comments in `html`; a comment that never closes runs to the end */
|
|
3
|
+
export function commentRanges(html) {
|
|
4
|
+
const ranges = [];
|
|
5
|
+
let at = html.indexOf('<!--');
|
|
6
|
+
while (at >= 0) {
|
|
7
|
+
const close = html.indexOf('-->', at + 4);
|
|
8
|
+
const end = close < 0 ? html.length : close + 3;
|
|
9
|
+
ranges.push([at, end]);
|
|
10
|
+
at = html.indexOf('<!--', end);
|
|
11
|
+
}
|
|
12
|
+
return ranges;
|
|
13
|
+
}
|
|
14
|
+
/** the ranges of every `<noscript>` element, from its start tag to its end tag or the end of the HTML */
|
|
15
|
+
export function noscriptRanges(html, tags) {
|
|
16
|
+
const ranges = [];
|
|
17
|
+
for (const tag of tags) {
|
|
18
|
+
if (tag.name !== 'noscript')
|
|
19
|
+
continue;
|
|
20
|
+
const after = html.slice(tag.end).search(/<\/noscript\s*>/i);
|
|
21
|
+
ranges.push([tag.start, after < 0 ? html.length : tag.end + after]);
|
|
22
|
+
}
|
|
23
|
+
return ranges;
|
|
24
|
+
}
|
|
25
|
+
/** the ranges of the outermost elements called `name`, from the start tag to the matching end tag or the end of the HTML */
|
|
26
|
+
export function elementRanges(html, tags, name) {
|
|
27
|
+
const ranges = [];
|
|
28
|
+
let open = -1;
|
|
29
|
+
for (const tag of tags) {
|
|
30
|
+
if (tag.name !== name || tag.start < open)
|
|
31
|
+
continue;
|
|
32
|
+
const pattern = new RegExp(`<(/?)${name}\\b[^>]*>`, 'gi');
|
|
33
|
+
pattern.lastIndex = tag.end;
|
|
34
|
+
let depth = 1;
|
|
35
|
+
let end = html.length;
|
|
36
|
+
for (let hit = pattern.exec(html); hit; hit = pattern.exec(html)) {
|
|
37
|
+
depth += hit[1] ? -1 : 1;
|
|
38
|
+
if (depth === 0) {
|
|
39
|
+
end = hit.index + hit[0].length;
|
|
40
|
+
break;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
ranges.push([tag.start, end]);
|
|
44
|
+
open = end;
|
|
45
|
+
}
|
|
46
|
+
return ranges;
|
|
47
|
+
}
|
|
48
|
+
/** the range of `<head>`, from its start tag to the first `<body>` or `</head>`, or null without one */
|
|
49
|
+
export function headRange(html, tags) {
|
|
50
|
+
const head = tags.find((tag) => tag.name === 'head');
|
|
51
|
+
if (!head)
|
|
52
|
+
return null;
|
|
53
|
+
const rest = html.slice(head.end);
|
|
54
|
+
const stop = rest.search(/<\/head\s*>|<body[\s>]/i);
|
|
55
|
+
return [head.start, stop < 0 ? html.length : head.end + stop];
|
|
56
|
+
}
|
|
57
|
+
/** whether `at` falls inside any of `ranges` */
|
|
58
|
+
export const within = (ranges, at) => ranges.some(([start, end]) => at >= start && at < end);
|
|
59
|
+
/** the first attribute of `tag` called `name`, whose name is already lowercase */
|
|
60
|
+
export const find = (tag, name) => tag.attributes.find((a) => a.name === name);
|
|
61
|
+
/** the edit that gives the attribute `a` the value `value`, keeping its quote style */
|
|
62
|
+
export function setValue(html, a, value) {
|
|
63
|
+
const raw = html.slice(a.start, a.end);
|
|
64
|
+
const prefix = /^[^=\s]+\s*=\s*/.exec(raw);
|
|
65
|
+
if (!prefix)
|
|
66
|
+
return { at: a.end, to: a.end, text: `="${value}"` };
|
|
67
|
+
const quote = raw[prefix[0].length];
|
|
68
|
+
const q = quote === '"' || quote === "'" ? quote : '';
|
|
69
|
+
return { at: a.start + prefix[0].length, to: a.end, text: `${q}${value}${q}` };
|
|
70
|
+
}
|
|
71
|
+
/** the edit that adds `attributes` (such as `preload="none"`) to the end of `tag`, before a closing slash */
|
|
72
|
+
export function appendAttributes(html, tag, attributes) {
|
|
73
|
+
const floor = tag.attributes.at(-1)?.end ?? tag.start + 1 + tag.name.length;
|
|
74
|
+
const slash = html[tag.end - 1] === '/' && floor < tag.end;
|
|
75
|
+
const at = slash ? tag.end - 1 : tag.end;
|
|
76
|
+
const gap = /\s/.test(html[at - 1]) ? '' : ' ';
|
|
77
|
+
return { at, to: at, text: `${gap}${attributes.join(' ')}` };
|
|
78
|
+
}
|
|
79
|
+
/** `html` with `edits` applied; they may arrive in any order and must not overlap */
|
|
80
|
+
export function applyEdits(html, edits) {
|
|
81
|
+
let out = '';
|
|
82
|
+
let from = 0;
|
|
83
|
+
for (const edit of [...edits].sort((a, b) => a.at - b.at)) {
|
|
84
|
+
out += html.slice(from, edit.at) + edit.text;
|
|
85
|
+
from = edit.to;
|
|
86
|
+
}
|
|
87
|
+
return out + html.slice(from);
|
|
88
|
+
}
|
|
89
|
+
/** the start tags of `html` that are named `name`, close with `>` and sit outside comments */
|
|
90
|
+
export function tagsNamed(html, name, tags = tagsOf(html)) {
|
|
91
|
+
const comments = commentRanges(html);
|
|
92
|
+
return tags.filter((tag) => tag.name === name && html[tag.end] === '>' && !within(comments, tag.start));
|
|
93
|
+
}
|