zuplo 6.67.32 → 6.68.0

package/docs/handlers/openapi.mdx

@@ -0,0 +1,78 @@
+---
+title: OpenAPI Spec Handler
+sidebar_label: OpenAPI Spec Handler
+---
+
+The OpenAPI Spec handler serves a public version of your OpenAPI specification
+file. The handler strips Zuplo gateway configuration (such as `x-zuplo-*`
+extensions) and enriches the spec with data based on the gateway implementation.
+For example, if a route uses API key authentication, the handler automatically
+documents the `Authorization` header in the generated OpenAPI spec.
+
+## Setup via Portal
+
+The OpenAPI Spec Handler can be added to any route using the Route Designer.
+Open the **Route Designer** by navigating to the **Code** tab then click
+**routes.oas.json**. Inside any route, select **OpenAPI Spec** from the
+**Request Handlers** drop-down.
+
+The handler defaults to the OpenAPI file currently open, but you can change it
+to serve a different OpenAPI file via the dropdown.
+
+## Setup via routes.oas.json
+
+Add the OpenAPI Spec handler manually to the **routes.oas.json** file with the
+following route configuration:
+
+```json
+"paths": {
+  "/openapi": {
+    "get": {
+      "summary": "OpenAPI Specification",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "openApiSpecHandler",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "openApiFilePath": "./config/routes.oas.json"
+          }
+        },
+        "policies": {
+          "inbound": []
+        }
+      }
+    }
+  }
+}
+```
+
+## Options
+
+The OpenAPI Spec handler accepts the following options:
+
+- **`openApiFilePath`** (required): The file path of an OpenAPI file within the
+  `config` folder.
+  - Type: `string`
+  - The file name must end with `.oas.json`.
+  - Example: `"./config/routes.oas.json"`
+
+## How It Works
+
+When a request hits the route with this handler, the handler:
+
+1. Reads the specified OpenAPI file from the project configuration.
+2. Removes all Zuplo-specific extensions (`x-zuplo-*` properties) that are not
+   relevant to API consumers.
+3. Enriches the spec with information derived from the gateway configuration,
+   such as authentication requirements inferred from applied policies.
+4. Returns the cleaned and enriched OpenAPI spec as a JSON response.
+
+## Common Use Cases
+
+- **Developer portal integration**: Serve the OpenAPI spec at a known endpoint
+  for developer portals or documentation tools to consume.
+- **Client SDK generation**: Provide an endpoint that CI/CD pipelines or
+  developers can use to generate client SDKs from the latest API spec.
+- **API discovery**: Expose the spec so that API consumers can explore available
+  endpoints and their requirements.

package/docs/handlers/redirect.mdx

@@ -0,0 +1,115 @@
+---
+title: Redirect Handler
+sidebar_label: Redirect
+---
+
+The Redirect Handler sends a redirect HTTP response to the client. Use it to
+redirect traffic from one URL to another, such as directing users from a
+deprecated endpoint to its replacement or redirecting a root path to
+documentation.
+
+## Setup via Portal
+
+The Redirect Handler can be added to any route using the Route Designer. Open
+the **Route Designer** by navigating to the **Code** tab then click
+**routes.oas.json**. Inside any route, select **Redirect** from the **Request
+Handlers** drop-down.
+
+In the text box enter the URL location for the redirect.
+
+## Setup in routes.oas.json
+
+Configure the Redirect Handler directly in the **routes.oas.json** file. The
+following example redirects requests at the root of a domain to a docs page at
+`/docs`:
+
+```json
+"paths": {
+  "/redirect-test": {
+    "x-zuplo-path": {
+      "pathMode": "open-api"
+    },
+    "get": {
+      "summary": "Testing rewrite handler",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "module": "$import(@zuplo/runtime)",
+          "export": "redirectHandler",
+          "options": {
+            "location": "/docs"
+          }
+        }
+      },
+      "policies": {
+        "inbound": []
+      }
+    }
+  }
+}
+```
+
+## Options
+
+The Redirect Handler accepts the following options:
+
+- **`location`** (required): The URL or path to redirect the client to.
+  - Type: `string`
+  - Supports absolute URLs (e.g., `https://example.com/docs`) and relative paths
+    (e.g., `/docs`)
+
+- **`status`** (optional): The HTTP status code for the redirect response.
+  - Type: `number`
+  - Default: `302`
+  - Common values:
+    - `301` - Permanent redirect. Browsers and search engines cache this
+      redirect. Use for endpoints that have permanently moved.
+    - `302` - Temporary redirect (default). The client should continue using the
+      original URL for future requests.
+    - `307` - Temporary redirect that preserves the HTTP method. Unlike `302`,
+      the client must use the same method (POST, PUT, etc.) when following the
+      redirect.
+    - `308` - Permanent redirect that preserves the HTTP method. Like `301`, but
+      the client must use the same method when following the redirect.
+
+### Examples
+
+**Permanent redirect to an external URL:**
+
+```json
+{
+  "handler": {
+    "module": "$import(@zuplo/runtime)",
+    "export": "redirectHandler",
+    "options": {
+      "location": "https://newapi.example.com/v2",
+      "status": 301
+    }
+  }
+}
+```
+
+**Temporary redirect preserving the HTTP method:**
+
+```json
+{
+  "handler": {
+    "module": "$import(@zuplo/runtime)",
+    "export": "redirectHandler",
+    "options": {
+      "location": "/maintenance",
+      "status": 307
+    }
+  }
+}
+```
+
+## Common Use Cases
+
+- **API versioning**: Redirect requests from an old API version to the current
+  version using a `301` permanent redirect.
+- **Documentation entry point**: Redirect the root path (`/`) to a documentation
+  page or developer portal.
+- **Deprecated endpoints**: Redirect traffic from removed endpoints to their
+  replacements.
+- **Domain migration**: Redirect requests from a legacy domain to a new domain.

package/docs/handlers/system-handlers.mdx

@@ -0,0 +1,41 @@
+---
+title: Internal Route Handlers
+sidebar_label: Internal Route Handlers
+---
+
+The Zuplo Runtime automatically registers certain routes on your gateway to
+provide enhanced functionality. Requests to these routes may appear in your
+Analytics page. Below is a list of reserved routes:
+
+| Name                    | Method  | Path                              | Description                                                 |
+| ----------------------- | ------- | --------------------------------- | ----------------------------------------------------------- |
+| cors-preflight          | OPTIONS | `/(.*)`                           | Handles CORS preflight requests.                            |
+| developer-portal        | GET     | User configured, default: `/docs` | Handles serving the legacy Developer Portal.                |
+| developer-portal-legacy | GET     | `/__zuplo/dev-portal`             | Legacy path for the Developer Portal.                       |
+| ping                    | GET     | `/__zuplo/ping`                   | Used to check liveness of deployments.                      |
+| unmatched-path          | All     | `/(.*)`                           | Handles requests to endpoints that haven't been configured. |
+
+## Behavior Details
+
+### cors-preflight
+
+This handler automatically responds to CORS preflight (`OPTIONS`) requests based
+on the CORS policy configured for each route. It runs before any user-defined
+route handlers.
+
+### ping
+
+The `/__zuplo/ping` endpoint returns a simple response that indicates the
+deployment is live and accepting requests. Use this endpoint for health checks
+and uptime monitoring.
+
+### unmatched-path
+
+When a request does not match any configured route, this handler returns a
+`404 Not Found` response. It acts as a catch-all for undefined paths.
+
+:::note
+
+Internal routes are reserved by the Zuplo runtime.
+
+:::

package/docs/handlers/url-forward.mdx

@@ -0,0 +1,204 @@
+---
+title: URL Forward Handler
+sidebar_label: URL Forward
+---
+
+The URL Forward handler proxies requests to a different API without writing any
+code. It appends the incoming path section of the URL onto the specified
+`baseUrl` property, making it ideal for creating API gateways and backend
+proxying.
+
+:::tip
+
+Use TypeScript for an enhanced development experience with full type checking
+and IntelliSense support when configuring handlers.
+
+:::
+
+## How It Works
+
+If you have an incoming request with URL:
+`https://my-gateway.com/pizza/cheese/size/large`
+
+And a URL forward handler with `baseUrl` of `https://my-backend.com/folder`, the
+gateway makes a request to:
+`https://my-backend.com/folder/pizza/cheese/size/large`
+
+By default, query parameters are forwarded automatically.
+
+## Setup via Portal
+
+The Forward Handler can be added to any route using the Route Designer. Open the
+**Route Designer** by navigating to the **Code** tab then click
+**routes.oas.json**. Inside any route, select **URL Forward** from the **Request
+Handlers** drop-down.
+
+In the text box enter the URL to rewrite the request. Values can be mixed into
+the URL string using JavaScript string interpolation syntax. For example:
+
+```txt
+https://${env.BASE_HOST_NAME}/${method}/${params.productId}
+```
+
+The following objects are available for substitution:
+
+- `env` - the environment object, to access
+  [Environment Variables](../articles/environment-variables.mdx)
+- `request: ZuploRequest` - the full
+  [`ZuploRequest`](../programmable-api/zuplo-request.mdx) object
+- `context: ZuploContext` - the
+  [`ZuploContext`](../programmable-api/zuplo-context.mdx) object without
+  functions.
+- `params: Record<string, string>` - The parameters of the route. For example,
+  `params.productId` would be the value of `:productId` in a route.
+- `query: Record<string, string>` - The query parameters of the route. For
+  example, `query.filterBy` would be the value of `?filterBy=VALUE`.
+- `headers: Headers` - the incoming request's
+  [headers object](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+- `url: string` - The full incoming request as a string
+- `host: string` - The
+  [`host`](https://developer.mozilla.org/en-US/docs/Web/API/URL/host) portion of
+  the incoming URL
+- `hostname: string` - The
+  [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
+  portion of the incoming URL
+- `pathname: string` - The
+  [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname)
+  portion of the incoming URL
+- `port: string` - The
+  [`port`](https://developer.mozilla.org/en-US/docs/Web/API/URL/port) portion of
+  the incoming URL
+- `search` - The
+  [`search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/search)
+  portion of the incoming URL
+
+Use the following methods to encode portions of the URL:
+
+- `encodeURIComponent`: The
+  [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
+  function encodes a URI by replacing each instance of certain characters with
+  escape sequences.
+- `e`: An alias to `encodeURIComponent` to help keep URLs more readable. Can be
+  used like `${e(params.productId)}`
+
+### Example Values
+
+A few examples of the values of various substitutions.
+
+- `${headers.get("content-type")}` - `"application/json"`
+- `${host}` - `"example.com:8080"`
+- `${hostname}` - `"example.com"`
+- `${method}` - `"GET"`
+- `${origin}` - `"https://example.com"`
+- `${params.productId}` - `":productId"`
+- `${pathname}` - `"/v1/products/:productId"`
+- `${port}` - `"8080"`
+- `${protocol}` - `"https:"`
+- `${query.category}` - `"cars"`
+- `${search}` - `"?category=cars"`
+- `${url}` - `"https://example.com:8080/v1/products/:productId?category=cars"`
+- `${env.BASE_URL}` - `"https://example.com"`
+
+## Setup via routes.oas.json
+
+The URL Forward handler can also be added manually to the **routes.oas.json**
+file with the following route configuration.
+
+```json
+"paths": {
+  "/forward-test": {
+    "x-zuplo-path": {
+      "pathMode": "open-api"
+    },
+    "get": {
+      "summary": "Testing forward handler",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "urlForwardHandler",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "baseUrl": "${env.BASE_URL}"
+          }
+        },
+        "policies": {
+          "inbound": []
+        }
+      }
+    }
+  }
+}
+```
+
+## Options
+
+The URL Forward handler accepts the following options:
+
+- **`baseUrl`** (required): The base URL where the incoming pathname will be
+  appended
+  - Type: `string`
+  - Supports template interpolation with environment variables and request
+    properties
+  - Example: `"https://api.example.com"` or `"${env.BACKEND_URL}"`
+
+- **`forwardSearch`** (optional): Controls whether query parameters are
+  forwarded
+  - Type: `boolean`
+  - Default: `true`
+  - When `true`, query string is automatically included in forwarded URL
+
+- **`followRedirects`** (optional): Controls redirect handling behavior
+  - Type: `boolean`
+  - Default: `false`
+  - When `false`, redirects aren't followed - status and `location` header are
+    returned as received
+  - When `true`, redirects are automatically followed
+
+### Complete Example
+
+```json
+// routes.oas.json handler configuration
+{
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "baseUrl": "${env.BACKEND_URL}",
+      "forwardSearch": true,
+      "followRedirects": false
+    }
+  }
+}
+```
+
+## Different Backends per Environment
+
+It's common to want a different backend for your production, staging and preview
+environments. This can be achieved by using
+[environment variables](../articles/environment-variables.mdx) to specify the
+origin of the backend.
+
+For example,
+
+```js
+${env.BASE_PATH}
+```
+
+A URL rewrite like this will combine the `BASE_PATH` environment variable, say
+`https://example.com`
+
+```txt
+https://example.com/foo/bar
+```
+
+## Related Documentation
+
+- [URL Rewrite Handler](./url-rewrite.mdx) - For more complex URL
+  transformations
+- [Custom Handler](./custom-handler.mdx) - Building custom request handlers
+- [Environment Variables](../articles/environment-variables.mdx) - Configuration
+  management
+- [ZuploRequest](../programmable-api/zuplo-request.mdx) - Request object
+  reference
+- [ZuploContext](../programmable-api/zuplo-context.mdx) - Context object
+  reference

package/docs/handlers/url-rewrite.mdx

@@ -0,0 +1,224 @@
+---
+title: URL Rewrite Handler
+sidebar_label: URL Rewrite
+---
+
+The URL Rewrite handler proxies and rewrites requests to different APIs without
+writing any code. It provides powerful URL transformation capabilities, allowing
+you to map request data and parameters to custom URL patterns on other hosts.
+
+:::tip
+
+Combine the URL Rewrite handler with policies such as the Change Method Inbound
+policy to modify virtually any aspect of your request.
+
+:::
+
+## Setup via Portal
+
+The Rewrite Handler can be added to any route using the Route Designer. Open the
+**Route Designer** by navigating to the **Code** tab then click
+**routes.oas.json**. Inside any route, select **URL Rewrite** from the **Request
+Handlers** drop-down.
+
+![URL Rewrite Handler selection](../../public/media/url-rewrite-handler-selection.png)
+
+In the text box enter the URL to rewrite the request. Values can be mixed into
+the URL string using JavaScript string interpolation syntax. For example:
+
+```txt
+https://echo.zuplo.io/${method}/${params.productId}
+```
+
+The following objects are available for substitution:
+
+- `env` - the environment object, to access
+  [Environment Variables](../articles/environment-variables.mdx)
+- `request: ZuploRequest` - the full
+  [`ZuploRequest`](../programmable-api/zuplo-request.mdx) object
+- `context: ZuploContext` - the
+  [`ZuploContext`](../programmable-api/zuplo-context.mdx) object without
+  functions.
+- `params: Record<string, string>` - The parameters of the route. For example,
+  `params.productId` would be the value of `:productId` in a route.
+- `query: Record<string, string>` - The query parameters of the route. For
+  example, `query.filterBy` would be the value of `?filterBy=VALUE`.
+- `headers: Headers` - the incoming request's
+  [headers object](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+- `url: string` - The full incoming request as a string
+- `host: string` - The
+  [`host`](https://developer.mozilla.org/en-US/docs/Web/API/URL/host) portion of
+  the incoming URL
+- `hostname: string` - The
+  [`hostname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/hostname)
+  portion of the incoming URL
+- `pathname: string` - The
+  [`pathname`](https://developer.mozilla.org/en-US/docs/Web/API/URL/pathname)
+  portion of the incoming URL
+- `port: string` - The
+  [`port`](https://developer.mozilla.org/en-US/docs/Web/API/URL/port) portion of
+  the incoming URL
+- `search` - The
+  [`search`](https://developer.mozilla.org/en-US/docs/Web/API/URL/search)
+  portion of the incoming URL
+
+Use the following methods to encode portions of the URL:
+
+- `encodeURIComponent`: The
+  [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
+  function encodes a URI by replacing each instance of certain characters with
+  escape sequences.
+- `e`: An alias to `encodeURIComponent` to help keep URLs more readable. Can be
+  used like `${e(params.productId)}`
+
+### Example Values
+
+A few examples of the values of various substitutions.
+
+- `${headers.get("content-type")}` - `"application/json"`
+- `${host}` - `"example.com:8080"`
+- `${hostname}` - `"example.com"`
+- `${method}` - `"GET"`
+- `${origin}` - `"https://example.com"`
+- `${params.productId}` - `":productId"`
+- `${pathname}` - `"/v1/products/:productId"`
+- `${port}` - `"8080"`
+- `${protocol}` - `"https:"`
+- `${query.category}` - `"cars"`
+- `${search}` - `"?category=cars"`
+- `${url}` - `"https://example.com:8080/v1/products/:productId?category=cars"`
+- `${env.BASE_URL}` - `"https://example.com"`
+
+## Setup via routes.oas.json
+
+The URL Rewrite handler can also be added manually to the **routes.oas.json**
+file with the following route configuration.
+
+```json
+"paths": {
+  "/rewrite-test": {
+    "summary": "Proxy Welcome API",
+    "description": "This Route will proxy the welcome.zuplo.io api",
+    "x-zuplo-path": {
+      "pathMode": "open-api"
+    },
+    "get": {
+      "summary": "Testing rewrite handler",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "urlRewriteHandler",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "rewritePattern": "https://welcome.zuplo.io"
+          }
+        },
+        "policies": {
+          "inbound": []
+        }
+      }
+    }
+  }
+}
+```
+
+## Options
+
+The URL Rewrite handler can be configured via `options` to support common
+use-cases.
+
+- **`rewritePattern`** (required): The URL pattern template for rewriting
+  requests
+  - Type: `string`
+  - Supports JavaScript template interpolation with request context
+  - Available variables: `env`, `request`, `context`, `params`, `query`,
+    `headers`, `url`, `host`, `hostname`, `pathname`, `port`, `search`
+  - Example: `"https://api-${params.version}.example.com/users/${params.id}"`
+
+- **`forwardSearch`** (optional): Controls whether query parameters are
+  forwarded
+  - Type: `boolean`
+  - Default: `true`
+  - When `true`, query string is automatically included in rewritten URL
+
+- **`followRedirects`** (optional): Controls redirect handling behavior
+  - Type: `boolean`
+  - Default: `false`
+  - When `false`, redirects aren't followed - status and `location` header are
+    returned as received
+  - When `true`, redirects are automatically followed
+
+### Examples
+
+```json
+// Version-based routing with parameters
+{
+  "handler": {
+    "export": "urlRewriteHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rewritePattern": "https://api-${params.version}.example.com${pathname}",
+      "forwardSearch": true,
+      "followRedirects": false
+    }
+  }
+}
+
+// Environment-based backend selection
+{
+  "handler": {
+    "export": "urlRewriteHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rewritePattern": "${env.BACKEND_URL}/api${pathname}${search}",
+      "forwardSearch": false,
+      "followRedirects": true
+    }
+  }
+}
+
+// Complex parameter mapping with encoding
+{
+  "handler": {
+    "export": "urlRewriteHandler",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rewritePattern": "https://backend.com/v2/users/${encodeURIComponent(params.userId)}/data?type=${query.format}",
+      "forwardSearch": false
+    }
+  }
+}
+```
+
+## Different Backends per Environment
+
+It's common to want a different backend for your production, staging and preview
+environments. This can be achieved by using
+[environment variables](../articles/environment-variables.mdx) to specify the
+origin of the backend.
+
+For example,
+
+```json
+${env.BASE_PATH}${pathname}
+```
+
+A URL rewrite like this will combine the `BASE_PATH` environment variable, say
+`https://example.com` with the incoming path, for example, `/foo/bar` to create
+a re-written URL:
+
+```json
+https://example.com/foo/bar
+```
+
+## Related Documentation
+
+- [URL Forward Handler](./url-forward.mdx) - Simple URL forwarding without
+  transformation
+- [Custom Handler](./custom-handler.mdx) - Building custom request handlers
+- [Environment Variables](../articles/environment-variables.mdx) - Configuration
+  management
+- [ZuploRequest](../programmable-api/zuplo-request.mdx) - Request object
+  reference
+- [ZuploContext](../programmable-api/zuplo-context.mdx) - Context object
+  reference