feat(webhooks): auto-decompress proxy response body and simplify body handling in scripts

Author: azasypkin

Cargo.lock

@@ -21,6 +21,7 @@ actix-web-httpauth = "0.8.2"
 addr = { version = "0.15.6", default-features = false }
 anyhow = "1.0.101"
 async-stream = "0.3.6"
+brotli = "8.0.2"
 byte-unit = "5.2.0"
 bytes = "1.11.1"
 chrono = { version = "0.4.43", default-features = false }
@@ -33,6 +34,7 @@ deno_error = "0.7.3"
 directories = "6.0.0"
 dotenvy = "0.15.7"
 figment = "0.10.19"
+flate2 = "1.1.9"
 futures = "0.3.31"
 handlebars = "6.4.0"
 hex = "0.4.3"
@@ -73,6 +75,7 @@ url = "2.5.8"
 urlencoding = "2.1.3"
 uuid = "1.20.0"
 zip = { version = "7.4.0", default-features = false }
+zstd = "0.13.3"
 
 [dev-dependencies]
 ctor = "0.6.3"

Cargo.toml

@@ -40,18 +40,19 @@ const bytes = Deno.core.encode('Hello, world!');
 // Uint8Array(13) [72, 101, 108, 108, 111, 44, 32, 119, 111, 114, 108, 100, 33]
 ```
 
-Use it whenever a script needs to return a binary body:
+Use it whenever a script needs to explicitly encode a string to binary:
 
 ```javascript
 (() => {
-  return {
-    body: Deno.core.encode(
-      JSON.stringify({ status: 'ok' })
-    )
-  };
+  const bytes = Deno.core.encode('raw binary payload');
+  return { body: bytes };
 })();
 ```
 
+:::tip
+Scripts can also return `body` as a plain string, object, or array - the runtime auto-converts them. See [Body auto-conversion](#body-auto-conversion) below.
+:::
+
 ### `Deno.core.decode(buffer)`
 
 Decodes a `Uint8Array` back into a JavaScript string using **UTF-8**:
@@ -134,9 +135,7 @@ function fromBase64(base64) {
 (() => {
   const payload = JSON.stringify({ user: 'alice', role: 'admin' });
   const encoded = toBase64(payload);
-  return {
-    body: Deno.core.encode(encoded)
-  };
+  return { body: encoded };
 })();
 ```
 
@@ -154,7 +153,7 @@ Returns the **UTF-8 byte length** of a string without allocating a `Uint8Array`.
       'Content-Type': 'application/json',
       'Content-Length': String(Deno.core.byteLength(body)),
     },
-    body: Deno.core.encode(body),
+    body,
   };
 })();
 ```
@@ -260,6 +259,9 @@ interface ProxyRequest {
   // Clamped to the server-configured maximum (default: 30 000 ms).
   // If omitted, the server default timeout applies.
   timeout?: number;
+  // Automatically decompress the response body based on the Content-Encoding
+  // header (gzip, deflate, br, zstd). Defaults to true.
+  decompress?: boolean;
 }
 ```
 
@@ -271,7 +273,7 @@ interface ProxyResponse {
   statusCode: number;
   // HTTP response headers from the upstream server.
   headers: Record<string, string>;
-  // Response body as an array of bytes.
+  // Response body as an array of bytes (decompressed by default).
   body: number[];
 }
 ```
@@ -284,13 +286,35 @@ Basic example:
     url: 'https://api.example.com/data',
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
-    body: Array.from(Deno.core.encode(JSON.stringify({ key: 'value' }))),
+    body: Deno.core.encode(JSON.stringify({ key: 'value' })),
   });
   // resp.statusCode, resp.headers, resp.body are available
   return resp;
 })()
 ```
 
+#### Transparent decompression
+
+When the upstream server returns a compressed response (e.g. `Content-Encoding: gzip`), `op_proxy_request` **automatically decompresses** the body before returning it to the script. Supported encodings: `gzip`, `x-gzip`, `deflate`, `br` (Brotli), and `zstd` (Zstandard).
+
+After decompression, the original transport headers are preserved under renamed keys so you can still see what the upstream sent:
+
+| Original header    | Renamed to                    |
+|--------------------|-------------------------------|
+| `content-encoding` | `x-original-content-encoding` |
+| `content-length`   | `x-original-content-length`   |
+
+This means scripts can always work with the decompressed body directly (e.g. `JSON.parse(Deno.core.decode(new Uint8Array(resp.body)))`) regardless of whether the upstream compresses its responses.
+
+To **opt out** of automatic decompression (e.g. to forward compressed bytes as-is), pass `decompress: false`:
+
+```javascript
+const resp = await Deno.core.ops.op_proxy_request({
+  url: 'https://upstream/api',
+  decompress: false, // body stays compressed, content-encoding header is preserved
+});
+```
+
 **Error handling.** When the upstream request fails, the op throws a JavaScript error with a descriptive message. Scripts can catch these errors and return a custom response:
 
 ```javascript
@@ -301,25 +325,26 @@ Basic example:
     return {
       statusCode: 502,
       headers: { 'Content-Type': 'text/plain' },
-      body: Array.from(Deno.core.encode(`Proxy error: ${e.message}`)),
+      body: `Proxy error: ${e.message}`,
     };
   }
 })()
 ```
 
 Possible error messages include:
 
-| Error                                     | Meaning                                                                               |
-|-------------------------------------------|---------------------------------------------------------------------------------------|
-| `Invalid URL '…': …`                      | The `url` field could not be parsed.                                                  |
-| `URL not allowed (non-public address): …` | SSRF protection blocked the URL because it resolves to a private/internal IP address. |
-| `Invalid HTTP method: '…'`                | The `method` value is not a valid HTTP method token.                                  |
-| `Invalid header name: '…'`                | A key in `headers` is not a valid HTTP header name.                                   |
-| `Invalid header value for '…'`            | A value in `headers` contains invalid characters.                                     |
-| `Upstream request timed out: …`           | The upstream server did not respond within the configured timeout.                    |
-| `Failed to connect to upstream: …`        | Could not establish a TCP connection to the upstream server.                          |
-| `Upstream request failed: …`              | A general upstream request failure (DNS, TLS, etc.).                                  |
-| `Upstream response body too large: …`     | The response body exceeded the configured size limit.                                 |
+| Error                                             | Meaning                                                                               |
+|---------------------------------------------------|---------------------------------------------------------------------------------------|
+| `Invalid URL '…': …`                              | The `url` field could not be parsed.                                                  |
+| `URL not allowed (non-public address): …`         | SSRF protection blocked the URL because it resolves to a private/internal IP address. |
+| `Invalid HTTP method: '…'`                        | The `method` value is not a valid HTTP method token.                                  |
+| `Invalid header name: '…'`                        | A key in `headers` is not a valid HTTP header name.                                   |
+| `Invalid header value for '…'`                    | A value in `headers` contains invalid characters.                                     |
+| `Upstream request timed out: …`                   | The upstream server did not respond within the configured timeout.                    |
+| `Failed to connect to upstream: …`                | Could not establish a TCP connection to the upstream server.                          |
+| `Upstream request failed: …`                      | A general upstream request failure (DNS, TLS, etc.).                                  |
+| `Upstream response body too large: …`             | The response body exceeded the configured size limit.                                 |
+| `Failed to decompress gzip/deflate/brotli/zstd …` | The response body claimed a content-encoding but the data was invalid.                |
 
 :::caution Security
 By default, `op_proxy_request` only allows requests to **publicly routable** IP addresses. URLs that resolve to private or loopback addresses (e.g. `127.0.0.1`, `10.x.x.x`, `192.168.x.x`) are rejected to prevent [Server-Side Request Forgery (SSRF)](https://owasp.org/www-community/attacks/Server-Side_Request_Forgery). This restriction can be relaxed per subscription tier for local development scenarios.
@@ -332,3 +357,44 @@ Each responder has a maximum number of concurrent proxy requests it can handle s
 :::tip Response tracking
 When using `op_proxy_request`, you can store the upstream response alongside the tracked request by returning `trackResponse: true` in your script result. This is especially useful for debugging proxy issues. See [Track responses](/docs/guides/webhooks#track-responses) for details.
 :::
+
+## Body auto-conversion {#body-auto-conversion}
+
+Responder scripts can return `body` as several types - not just `Uint8Array`. The runtime automatically converts the value before sending the response:
+
+| Script returns                           | Conversion                      | Result                            |
+|------------------------------------------|---------------------------------|-----------------------------------|
+| `Uint8Array` or `ArrayBuffer`            | None (pass-through)             | Raw bytes                         |
+| `string`                                 | UTF-8 encode                    | UTF-8 bytes of the string         |
+| Plain object (e.g. `{ key: "value" }`)   | `JSON.stringify` + UTF-8 encode | UTF-8 bytes of the JSON           |
+| Array of non-numbers (e.g. `[{ a: 1 }]`) | `JSON.stringify` + UTF-8 encode | UTF-8 bytes of the JSON array     |
+| Array of numbers (e.g. `[72, 101]`)      | `new Uint8Array(arr)`           | Raw bytes (backward compatible)   |
+| `number` or `boolean`                    | `JSON.stringify` + UTF-8 encode | UTF-8 bytes of `"42"` or `"true"` |
+| `null` or `undefined`                    | Skipped                         | Uses the responder's default body |
+
+Examples:
+
+```javascript
+// Return a JSON object directly - no Deno.core.encode needed.
+(() => ({
+  headers: { 'Content-Type': 'application/json' },
+  body: { status: 'ok', count: 42 },
+}))();
+```
+
+```javascript
+// Return a plain text string.
+(() => ({ body: 'Hello, world!' }))();
+```
+
+```javascript
+// Modify a proxied JSON response and return the object.
+(async () => {
+  const resp = await Deno.core.ops.op_proxy_request({
+    url: 'https://api.example.com/data',
+  });
+  const data = JSON.parse(Deno.core.decode(new Uint8Array(resp.body)));
+  data._proxied = true;
+  return { ...resp, body: data };
+})()
+```

components/secutils-docs/docs/guides/platform/deno_runtime.mdx

@@ -83,12 +83,14 @@ In responder scripts, secrets are available through the `context.secrets` object
 ```javascript
 (async () => {
   const apiKey = context.secrets.MY_API_KEY;
-  const resp = await fetch('https://api.example.com/data', {
-    headers: { 'Authorization': `Bearer ${apiKey}` }
+  const resp = await Deno.core.ops.op_proxy_request({
+    url: 'https://api.example.com/data',
+    headers: { 'Authorization': `Bearer ${apiKey}` },
   });
+  const data = JSON.parse(Deno.core.decode(new Uint8Array(resp.body)));
   return {
     headers: { 'Content-Type': 'application/json' },
-    body: Deno.core.encode(JSON.stringify(await resp.json()))
+    body: data
   };
 })();
 ```

components/secutils-docs/docs/guides/platform/secrets.mdx

@@ -174,10 +174,7 @@ The script should be provided in the form of an [Immediately Invoked Function Ex
                 <tr><td><b>Headers</b></td><td><CodeBlock language="http">Content-Type: text/html; charset=utf-8</CodeBlock></td></tr>
                 <tr><td><b>Script</b></td><td><CodeBlock language="javascript">{`(async () => {
     return {
-      // Encode body as binary data.
-      body: Deno.core.encode(
-        context.query.arg ?? 'Query string does not include \`arg\` parameter'
-      )
+      body: context.query.arg ?? 'Query string does not include \`arg\` parameter'
     };
 })();`}</CodeBlock></td></tr>
                 </tbody>
@@ -240,28 +237,28 @@ interface ScriptResult {
   // Optional HTTP headers of the response. If not specified, the default headers of responder are used.
   headers?: Record<string, string>;
   // Optional HTTP body of the response. If not specified, the default body of responder is used.
-  body?: Uint8Array;
+  // Accepts Uint8Array, string, object, or array - see Body auto-conversion.
+  body?: Uint8Array | string | object;
   // When true, the request is not recorded in the responder's tracked request history.
   skipRequest?: boolean;
   // When true, the response sent to the client is also stored alongside the tracked request.
   trackResponse?: boolean;
 }
 ```
 
+:::tip Body auto-conversion
+The `body` field accepts multiple types: `Uint8Array` for raw bytes, a **string** (auto-encoded to UTF-8), a **plain object or array** (auto-serialized to JSON), or a **number/boolean** (auto-stringified). See [Body auto-conversion](/docs/guides/platform/deno_runtime#body-auto-conversion) for the full conversion table.
+:::
+
 ### Override response properties
 The script overrides the responder's response with a custom status code, headers, and body:
 
 ```javascript
 (async () => {
   return {
     statusCode: 201,
-    headers: {
-      "Content-Type": "application/json"
-    },
-    // Encode body as binary data.
-    body: Deno.core.encode(
-      JSON.stringify({ a: 1, b: 2 })
-    )
+    headers: { "Content-Type": "application/json" },
+    body: { a: 1, b: 2 },
   };
 })();
 ```
@@ -278,7 +275,7 @@ This script inspects the incoming request properties and returns them as a JSON
 
   // Override response with a custom HTML body.
   return {
-    body: Deno.core.encode(`
+    body: `
       <h2>Request headers</h2>
       <table>
         <tr><th>Header</th><th>Value</th></tr>
@@ -303,7 +300,7 @@ This script inspects the incoming request properties and returns them as a JSON
 
       <h2>Request body</h2>
       <pre>${JSON.stringify(parsedJsonBody, null, 2)}</pre>
-    `)
+    `
   };
 })();
 ```
@@ -316,7 +313,7 @@ This script reads a user secret and includes it in the response. Secrets are man
   const apiKey = context.secrets.THIRD_PARTY_API_KEY ?? 'not-set';
   return {
     headers: { 'Content-Type': 'application/json' },
-    body: Deno.core.encode(JSON.stringify({ apiKey }))
+    body: { apiKey }
   };
 })();
 ```
@@ -340,7 +337,7 @@ Responder scripts can forward incoming requests to a real backend using `Deno.co
 })()
 ```
 
-**Transform the response** - e.g. inject a field into JSON responses:
+**Transform the response** - e.g., inject a field into JSON responses. Compressed responses (gzip, deflate, Brotli) are automatically decompressed, so `JSON.parse` works regardless of the upstream's `Content-Encoding`:
 
 ```javascript
 (async () => {
@@ -354,11 +351,7 @@ Responder scripts can forward incoming requests to a real backend using `Deno.co
   if (resp.headers['content-type']?.includes('application/json')) {
     const body = JSON.parse(Deno.core.decode(new Uint8Array(resp.body)));
     body._proxied = true;
-    return {
-      statusCode: resp.statusCode,
-      headers: resp.headers,
-      body: Array.from(Deno.core.encode(JSON.stringify(body))),
-    };
+    return { statusCode: resp.statusCode, headers: resp.headers, body };
   }
 
   return resp;
@@ -377,10 +370,7 @@ Responder scripts can forward incoming requests to a real backend using `Deno.co
       body: context.body,
     });
   }
-  return {
-    statusCode: 200,
-    body: Array.from(Deno.core.encode(JSON.stringify({ mock: true }))),
-  };
+  return { statusCode: 200, body: { mock: true } };
 })()
 ```
 
@@ -394,10 +384,7 @@ By default every incoming request is recorded in the responder's tracked history
 (async () => {
   // Only track non-health-check requests.
   const skip = context.path === '/healthz' || context.path === '/readyz';
-  return {
-    body: Deno.core.encode('ok'),
-    skipRequest: skip,
-  };
+  return { body: 'ok', skipRequest: skip };
 })();
 ```