feat: Image Optimizer support (#1224)

Author: TartanLlama

.github/workflows/main.yml

@@ -11,7 +11,7 @@ defaults:
     shell: bash
 env:
   # Note: when updated, also update version in ensure-cargo-installs
-  viceroy_version: 0.12.2
+  viceroy_version: 0.15.0
   # Note: when updated, also update version in ensure-cargo-installs ! AND ! release-please.yml
   wasm-tools_version: 1.216.0
   fastly-cli_version: 10.19.0
@@ -46,7 +46,7 @@ jobs:
       matrix:
         include:
           - crate: viceroy
-            version: 0.12.2 # Note: workflow-level env vars can't be used in matrix definitions
+            version: 0.15.0 # Note: workflow-level env vars can't be used in matrix definitions
             options: ""
           - crate: wasm-tools
             version: 1.216.0 # Note: workflow-level env vars can't be used in matrix definitions

documentation/docs/globals/fetch.mdx

@@ -76,6 +76,7 @@ fetch(resource, options)
       - *Fastly-specific*
     - `cacheOverride` _**Fastly-specific**_
     - `cacheKey` _**Fastly-specific**_
+    - `imageOptimizerOptions` _**Fastly-specific**_, see [`imageOptimizerOptions`](../../fastly:image-optimizer/imageOptimizerOptions.mdx).
     - `fastly` _**Fastly-specific**_
       - `decompressGzip`_: boolean_ _**optional**_
         - Whether to automatically gzip decompress the Response or not.

documentation/docs/image-optimizer/Auto.mdx

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Auto`
+
+Enumerator options for [`imageOptimizerOptions.auto`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `AVIF` (`"avif"`) If the browser's Accept header indicates compatibility, deliver an AVIF image.
+- `WEBP` (`"webp"`)	If the browser's Accept header indicates compatibility, deliver a WebP image.
+
+## Examples
+
+```js
+import { Auto, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      auto: Auto.AVIF
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/BWAlgorithm.mdx

@@ -0,0 +1,34 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `BWAlgorithm`
+
+Enumerator options for [`imageOptimizerOptions.bw`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Threshold` (`"threshold"`) Uses a luminance threshold to convert the image to black and white.
+- `Atkinson` (`"atkinson"`)	Uses [Atkinson dithering](https://en.wikipedia.org/wiki/Atkinson_dithering) to convert the image to black and white.
+
+
+## Examples
+
+```js
+import { Region, BWAlgorithm } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      bw: BWAlgorithm.Threshold
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/CropMode.mdx

@@ -0,0 +1,36 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `CropMode`
+
+Enumerator options for [`imageOptimizerOptions.crop.mode`](./imageOptimizerOptions.mdx) and `imageOptimizerOptions.precrop.mode`.
+
+## Constants
+
+- `Smart` (`"smart"`) Enables content-aware algorithms to attempt to crop the image to the desired aspect ratio while intelligently focusing on the most important visual content, including the detection of faces.
+- `Safe` (`"safe"`)	Allow cropping out-of-bounds regions.
+
+## Examples
+
+```js
+import { CropMode, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      crop: {
+        size: { ratio: { width: 4, height: 3 } },
+        mode: CropMode.Smart,
+      }
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/Disable.mdx

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Disable`
+
+Enumerator options for [`imageOptimizerOptions.disable`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Upscale` (`"upscale"`) Prevent images being resized such that the output image's dimensions are larger than the source image.
+
+## Examples
+
+```js
+import { Disable, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      width: 2560,
+      disable: Disable.Upscale
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/Enable.mdx

@@ -0,0 +1,33 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Enable`
+
+Enumerator options for [`imageOptimizerOptions.enable`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Upscale` (`"upscale"`) Allow images to be resized such that the output image's dimensions are larger than the source image.
+
+## Examples
+
+```js
+import { Enable, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      width: 2560,
+      enable: Enable.Upscale
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/Fit.mdx

@@ -0,0 +1,36 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Fit`
+
+Enumerator options for [`imageOptimizerOptions.fit`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Bounds` (`"bounds"`) Resize the image to fit entirely within the specified region, making one dimension smaller if needed.
+- `Cover` (`"cover"`) Resize the image to entirely cover the specified region, making one dimension larger if needed.
+- `Crop` (`"crop"`) Resize and crop the image centrally to exactly fit the specified region.
+
+## Examples
+
+```js
+import { Fit, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      width: 150,
+      height; 150,
+      fit: Fit.Bounds
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/Format.mdx

@@ -0,0 +1,46 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Format`
+
+Enumerator options for [`imageOptimizerOptions.format`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Auto` (`"auto"`) Automatically use the best format based on browser support and image/transform characteristics
+- `AVIF` (`"avif"`) AVIF
+- `BJPG` (`"bjpg"`) Baseline JPEG 
+- `GIF` (`"gif"`) Graphics Interchange Format
+- `JPG` (`"jpg"`) JPEG 
+- `JXL` (`"jxl"`) JPEGXL 
+- `MP4` (`"mp4"`) MP4 (H.264)
+- `PJPG` (`"pjpg"`) Progressive JPEG 
+- `PJXL` (`"pjxl"`) Progressive JPEGXL
+- `PNG` (`"png"`) Portable Network Graphics
+- `PNG8` (`"png8"`) Portable Network Graphics palette image with 256 colors and 8-bit transparency
+- `SVG` (`"svg"`) Scalable Vector Graphics
+- `WEBP` (`"webp"`) WebP
+- `WEBPLL` (`"webpll"`) WebP (Lossless)
+- `WEBPLY` (`"webply"`) WebP (Lossy)
+
+## Examples
+
+```js
+import { Format, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      format: Format.PNG
+    },
+    backend: 'w3'
+  });
+}
+```

documentation/docs/image-optimizer/Metadata.mdx

@@ -0,0 +1,34 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# `Metadata`
+
+Enumerator options for [`imageOptimizerOptions.metadata`](./imageOptimizerOptions.mdx).
+
+## Constants
+
+- `Copyright` (`"copyright"`) Preserve [copyright notice](https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata#copyright-notice), creator, credit line, licensor, and web statement of rights fields.
+- `C2PA` (`"c2pa"`) Preserve the [C2PA manifest](https://c2pa.org/) and add any transformations performed by Fastly Image Optimizer.
+- `CopyRightAndC2PA` (`"copyright,c2pa"`) Resize and crop the image centrally to exactly fit the specified region.
+
+## Examples
+
+```js
+import { Metadata, Region } from 'fastly:image-optimizer';
+
+addEventListener("fetch", (event) => event.respondWith(handleRequest(event)));
+
+async function handleRequest(event) {
+  return await fetch('https://www.w3.org/Graphics/PNG/text2.png', {
+    imageOptimizerOptions: {
+      region: Region.UsEast,
+      metadata: Metadata.Copyright
+    },
+    backend: 'w3'
+  });
+}
+```