ReviewOS

also looking at this

stacks/rpx

feat: imgx integration — on-the-fly image transforms from query params

#2264
Merged glennmichael123 wants to merge feat/imgx-integration into main
15 files +1118 -16
docs/features/imgx.mdadded+102-0
Changes to docs/features/imgx.md
@@ -0,0 +1,102 @@
1# Image Transforms (imgx)
2
3rpx can transform image responses on the fly, driven by imgix/meema-style query params — powered by the [imgx](https://github.com/stacksjs/ts-images) pure-TypeScript pipeline. Enable it and every image your proxy (or static route) serves understands URLs like:
4
5```txt
6https://app.localhost/hero.png?w=200&h=1200&q=80
7https://app.localhost/hero.png?w=640&fm=webp
8https://app.localhost/hero.png?w=400&h=400&fit=crop&crop=top
9```
10
11The upstream never sees anything but the original request — any dev server, static directory, or app gains image resizing for free.
12
13## Enabling
14
15```ts
16import { startProxy } from '@stacksjs/rpx'
17
18await startProxy({
19 from: 'localhost:5173',
20 to: 'my-app.localhost',
21 imgx: true, // defaults; or pass an options object
22})
23```
24
25Per-proxy in multi-proxy configs (overrides the shared setting):
26
27```ts
28await startProxy({
29 imgx: true,
30 proxies: [
31 { from: 'localhost:5173', to: 'app.localhost' },
32 { from: 'localhost:3000', to: 'api.localhost', imgx: false },
33 ],
34})
35```
36
37Or from the CLI:
38
39```bash
40rpx start --from localhost:5173 --to my-app.localhost --imgx
41```
42
43## Supported query params
44
45Sizing:
46
47| Param | Meaning |
48| --- | --- |
49| `w`, `h` | Output width/height in px, or a `0–1` fraction of the source dimension |
50| `fit` | `clip` (default, fit within preserving AR), `max` (clip, never enlarge), `crop` (fill + crop overflow), `min` (crop, never enlarge), `scale` (stretch), `fill` (letterbox with `bg`) |
51| `crop` | Crop anchor for `fit=crop`: `top`, `bottom`, `left`, `right`, or combos (`top,left`) |
52| `ar` | Aspect ratio (`16:9`) used to derive a missing dimension |
53| `dpr` | Device pixel ratio multiplier, `0–5` (default `1`) |
54
55Output:
56
57| Param | Meaning |
58| --- | --- |
59| `q` | Quality `1–100` (default `80`, configurable) |
60| `fm` / `format` | `jpeg`, `png`, `webp`, `avif`, `gif`, `bmp`, or `auto` |
61| `auto` | `format` (negotiate from `Accept`, prefers WebP), `compress` |
62| `lossless` | Lossless WebP/AVIF encoding |
63
64Adjustments:
65
66| Param | Meaning |
67| --- | --- |
68| `blur` | Gaussian blur, imgix `0–2000` scale |
69| `sharp` | Sharpen |
70| `greyscale` / `grayscale` | Convert to grayscale |
71| `bri`, `sat` | Brightness/saturation offset `−100..100` |
72| `hue` | Hue rotation in degrees |
73| `tint` | Tint color (`tint=ff0000`) |
74| `rot` | Rotate by degrees (`bg` fills the corners) |
75| `flip`, `flop` | Vertical / horizontal mirror |
76| `bg` | Background color for `fit=fill` and `rot` (hex or `white`/`black`/`transparent`) |
77
78## Options
79
80```ts
81await startProxy({
82 from: 'localhost:5173',
83 to: 'my-app.localhost',
84 imgx: {
85 quality: 80, // encode quality when the request has no `q`
86 maxWidth: 8192, // clamp on requested output width
87 maxHeight: 8192, // clamp on requested output height
88 maxInputBytes: 32 * 1024 * 1024, // larger responses pass through untouched
89 cache: true, // cache transformed variants in memory
90 cacheMaxBytes: 64 * 1024 * 1024, // total cache byte budget
91 cacheMaxEntries: 500, // max cached variants
92 },
93})
94```
95
96## Behavior notes
97
98- Only `GET` requests with a `200` image response (`jpeg`, `png`, `gif`, `bmp`, `webp`, `avif`) and at least one transform param are touched — everything else streams through untouched.
99- Transformed variants are cached in memory, keyed by path, params, and a hash of the upstream bytes: an unchanged image is never re-encoded twice, and a changed one misses naturally (no TTLs to tune). Cache state is visible in the `x-rpx-imgx: hit|miss` response header.
100- Any decode/encode failure falls back to serving the original bytes — the integration can slow an image down, but never break it.
101- Upstream `ETag`/`Last-Modified` headers are dropped from transformed responses (they described the original entity); `Cache-Control` is passed through. `auto=format` responses set `Vary: accept`.
102- WebP/AVIF encoding uses system `cwebp`/`avifenc` when available and falls back to the bundled pure-TS encoders; `auto=format` deliberately negotiates WebP (not AVIF) for that reason.