zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/compatibility-dates.mdx

@@ -0,0 +1,201 @@
+---
+title: Compatibility Dates
+---
+
+Zuplo is constantly shipping updates to the underlying runtime of projects.
+Occasionally, these updates aren't backwards compatible. In order to ensure that
+your project continues to build, deploy, and operate as you expect, you can set
+a compatibility date to lock in the behavior and APIs of the runtime.
+
+The compatibility date is set in the `zuplo.jsonc` file at the root of your
+project. The `zuplo.jsonc` file is created by default for new projects and
+contains the default configuration. For more information on the `zuplo.jsonc`
+file, see the [Zuplo Project Configuration](./zuplo-json.mdx) documentation.
+
+## 2026-03-01
+
+:::note
+
+This compatibility date is the default for projects created after March
+1st, 2026. Existing projects should update their `zuplo.jsonc` to take advantage
+of this change.
+
+:::
+
+### Chain Response Sending Hooks
+
+This compatibility date changes how response sending hooks behave when multiple
+hooks are registered. With this flag enabled, response sending hooks
+(`context.addResponseSendingHook` and `runtime.addResponseSendingHook`) chain
+properly, where each hook receives the response from the previous hook instead
+of the original response.
+
+**Before this flag:** All hooks received the **_original_** response, so only
+the last hook's output was used.
+
+**After this flag:** Hooks are chained properly, each receiving the **_previous
+hook's response_**. For example, if you register three hooks A, B, and C in a
+policy in that order, hook A's response passes to hook B, then hook B's response
+passes to hook C.
+
+This change enables more predictable behavior when composing multiple response
+transformations.
+
+### 501 for Unsupported HTTP Methods
+
+This compatibility date changes how unsupported HTTP methods are handled.
+Requests using non-standard HTTP methods such as WebDAV methods (`PROPFIND`,
+`MKCOL`, `COPY`, etc.) now return a proper `501 Not Implemented` response
+instead of a `500 Internal Server Error`.
+
+**Before this flag:** Unsupported HTTP methods returned a
+`500 Internal Server Error`.
+
+**After this flag:** Unsupported HTTP methods return a `501 Not Implemented`
+response with an [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807)
+`application/problem+json` body.
+
+## 2025-02-06
+
+This compatibility date introduces a number of breaking changes to improve the
+overall behavior of Zuplo APIs. This compatibility date is the default for any
+projects created after 2025-03-27.
+
+### Special Characters in OpenAPI Format URLs
+
+Previously, special characters that were included in URLs that used the
+`open-api` formatted URLs weren't escaped. This allowed an unintended behavior
+where the URL could include Regex patterns even though the OpenAPI format URLs
+doesn't allow regex. This has been fixed and now all special characters are
+escaped. This allows URLs with formats like:
+
+```
+/accounts/open({id})
+/accounts/:action
+```
+
+### Removed legacy Log Initialization
+
+Previously, several of the Zuplo log plugins could be enabled by setting
+undocumented environment variables. This was a legacy feature that was added
+before the current plugin system existed. This feature has been removed. Log
+plugins should be enabled using the
+[documented plugin system](../articles/logging.mdx).
+
+If you are setting any of the following environment variables, you should
+migrate to the log plugin initialization.
+
+```txt
+GCP_USER_LOG_NAME
+GCP_USER_LOG_SVC_ACCT_JSON
+ZUPLO_USER_LOGGER_DATA_DOG_URL
+```
+
+### Removed legacy Log Context
+
+Previously, several log plugins used special properties on `context.custom` to
+set global attributes on logs. This was a legacy feature that was added before
+the current plugin system existed. This feature has been removed. Log plugins
+should be enabled using the [documented plugin system](../articles/logging.mdx).
+
+If you are setting any of the following in your code, you should migrate to the
+plugin configuration instead.
+
+```ts
+context.custom["__ddtags"]; // Sets tags
+context.custom["__ddattr"]; // Sets fields
+```
+
+Migrate to the following:
+
+```ts
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new DataDogLoggingPlugin({
+      url: "https://http-intake.logs.datadoghq.com/api/v2/logs",
+      apiKey: environment.DATADOG_API_KEY,
+      source: "MyAPI", // Optional, defaults to "Zuplo"
+      tags: {
+        tag: "hello",
+      },
+      fields: {
+        field1: "value1",
+        field2: "value2",
+      },
+    }),
+  );
+}
+```
+
+### Improved Node.js Compatibility
+
+The Zuplo runtime doesn't run Node.js, but is compatible with a number of
+Node.js APIs. This compatibility date adds some additional support for Node.js
+specific APIs.
+
+### URL Forward Handler Redirects
+
+The `UrlForwardHandler` now supports the `followRedirects` option. Previously,
+this option wasn't supported on the forward handler. However, it was erroneously
+documented as supported. This property is behind a compatibility date in order
+to ensure that if existing projects were using the option that didn't work as
+expected, they wouldn't be broken by this change.
+
+## 2024-09-02
+
+The compatibility date allows the ability to call `fetch` to hosts with custom
+ports. Previously only the standard ports (80, 443) were allowed.
+
+## 2024-03-14
+
+This compatibility date doesn't include any breaking changes. However, Zuplo
+made a number of changes to the runtime build process. These changes will allow
+a number of future improvements. Out of an abundance of caution, these changes
+are only enabled for projects that have set their compatibility date to
+`2024-03-14`. This compatibility date is the default for any projects created
+after March 14th, 2024.
+
+Over time, the build changes will be enabled by default on all future
+deployments regardless of compatibility date. Existing customers are encouraged
+to update their compatibility date to `2024-03-14` and test their projects to
+ensure that they continue to operate as expected.
+
+This new build process has rolled out to all customers regardless of
+compatibility date.
+
+## 2024-01-15
+
+This compatibility date includes several breaking changes to improve the overall
+behavior of Zuplo APIs. This compatibility date is the default for any projects
+created after Jan. 15th, 2024.
+
+### Run Outbound Policies on All Responses
+
+Previously, outbound policies would only run on response status ranging from
+200-299. Now outbound policies will always run, regardless of the response code.
+
+### No Hooks on System Routes
+
+Previously runtime hooks such as `OnRequest` or `OnResponseSending` would run on
+system routes. For example, if you are using our Developer Portal and have it
+running on `/docs`, before this change you could write a hook that modified the
+output of the Developer Portal. This could result in unexpected behavior and is
+now disallowed.
+
+### Remove Cloudflare Location Headers
+
+On SaaS deployments, Zuplo routes all requests through Cloudflare. Cloudflare
+adds a number of headers to requests. Previously, some Cloudflare location
+headers (for example `cf-ipregion`) could be passed through your Zuplo gateway.
+Now these headers are always removed from the outbound request if they have been
+set. If you need access to geo-location data use
+[`context.incomingRequestProperties`](./zuplo-context.mdx) instead.
+
+### Remove Internal Zuplo Headers
+
+Zuplo uses several internal headers to send data between different layers of our
+systems. Previously, some of these headers where exposed in a way that they
+could be accessed directly. Examples were `zp-ipcity` and `zp-ipcountry`. These
+headers are now always removed from the outbound request if they have been set.
+If you need access this data use
+[`context.incomingRequestProperties`](./zuplo-context.mdx) instead.

package/docs/programmable-api/console-logging.mdx

@@ -0,0 +1,48 @@
+---
+title: Console Logging
+sidebar_label: Console Logging
+---
+
+Zuplo supports standard JavaScript console logging methods as a convenience for
+developers. These console methods map directly to the Zuplo context logger
+methods.
+
+## Supported Methods
+
+The following console methods are supported:
+
+- `console.log()` - Maps to `context.log.info()`
+- `console.info()` - Maps to `context.log.info()`
+- `console.warn()` - Maps to `context.log.warn()`
+- `console.error()` - Maps to `context.log.error()`
+- `console.debug()` - Maps to `context.log.debug()`
+
+## Usage
+
+You can use console methods anywhere in your Zuplo code:
+
+```ts
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  console.log("Processing request", request.url);
+
+  try {
+    const result = await processRequest(request);
+    console.info("Request processed successfully");
+    return result;
+  } catch (error) {
+    console.error("Error processing request:", error);
+    throw error;
+  }
+}
+```
+
+## Limitations
+
+- Only the standard logging methods listed above are supported
+- Other console methods (like `console.table()`, `console.time()`, etc.) are
+  no-ops and won't produce any output
+
+## See Also
+
+- [Logger](./logger.mdx) - Using the context logger
+- [Logging Guide](../articles/logging.mdx) - Detailed logging documentation

package/docs/programmable-api/context-data.mdx

@@ -0,0 +1,127 @@
+---
+title: ContextData - Sharing Request Data
+sidebar_label: ContextData
+---
+
+It's often useful to store data throughout the life of a single request. This
+data could be used on multiple policies, handlers, or for logging. However,
+because the Zuplo runtime is asynchronous, you can't simply create global
+variables and reference them in other modules if the value is unique across
+requests. Additionally, using a traditional data structure like a `Map` is also
+not recommended as it can build up memory over time.
+
+## ContextData
+
+The `ContextData` utility stores data that's tied to a specific request.
+Additionally, this utility ensures that data stored is garbage collected
+(removed from memory) when the request is complete.
+
+**`ContextData.set`**
+
+Static method to store data in the context.
+
+```ts
+ContextData.set(context, "my-data", { prop1: "hello world" });
+```
+
+**`ContextData.get`**
+
+Static method to retrieve data from the context.
+
+```ts
+const data = ContextData.get(context, "my-data");
+```
+
+**`set` (instance method)**
+
+Stores data in the context using an instance.
+
+```ts
+const myData = new ContextData("my-data");
+myData.set(context, { prop1: "hello world" });
+```
+
+**`get` (instance method)**
+
+Retrieves data from the context using an instance.
+
+```ts
+const myData = new ContextData("my-data");
+const data = myData.get(context);
+```
+
+### Typing
+
+The methods of `ContextData` support generics in order to support typing.
+
+```ts
+const myData = new ContextData<{ key: string }>("my-data");
+ContextData.get<{ key: string }>(context, "my-data");
+ContextData.set<{ key: string }>(context, "my-data", { key: "hello" });
+```
+
+## How NOT to Share Data
+
+Below are a few examples of how **NOT** to share data in your API.
+
+:::danger
+
+Don't write code like this in your API. It won't work reliably. These are
+examples of what NOT to do. See the next section for best practices.
+
+:::
+
+The first example uses a simple shared global variable called `currentRequestId`
+to store the current `requestId`. On the surface this looks straightforward.
+However, because the gateway is being shared among many requests who are all
+running at the same time, the value of `currentRequestId` is completely
+unpredictable when your API is under load.
+
+```ts title="/modules/policies.ts"
+let currentRequestId: string | undefined;
+
+export function myFirstPolicy(request: ZuploRequest, context: ZuploContext) {
+  currentRequestId = context.requestId;
+  context.log.info(`The current requestId is: ${currentRequestId}`);
+}
+
+export function mySecondPolicy(request: ZuploRequest, context: ZuploContext) {
+  currentRequestId = context.requestId;
+  context.log.info(`The current requestId is: ${currentRequestId}`);
+}
+```
+
+## Using ContextData
+
+Below you will find examples of how to use `ContextData` to safely share data
+throughout the lifecycle of a request.
+
+### Using static methods
+
+```ts
+import { ContextData, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export function myFirstPolicy(request: ZuploRequest, context: ZuploContext) {
+  ContextData.set(context, "currentRequestId", context.requestId);
+
+  const currentRequestId = ContextData.get(context, "currentRequestId");
+  context.log.info(`The current requestId is: ${currentRequestId}`);
+}
+```
+
+### Using Shared Variable
+
+Reusable class shared across modules The shared module allows other modules to
+access the same storage without passing the string name or type around.
+
+```ts
+export const myData = new ContextData<{ prop1: string }>("my-data");
+```
+
+Then use the class in another module.
+
+```ts
+import { myData } from "./my-module";
+const data = myData.get(context);
+myData.set(context, data);
+```

package/docs/programmable-api/custom-cors-policy.mdx

@@ -0,0 +1,64 @@
+---
+title: CORS Policy Configuration
+sidebar_label: CORS Policy Configuration
+---
+
+For a complete guide on configuring CORS including built-in policies, wildcard
+origin matching, environment variables, and troubleshooting, see the
+[Configuring CORS](../articles/cors.mdx) article.
+
+## CorsPolicyConfiguration
+
+Custom CORS policies are defined in the `corsPolicies` array in the
+`policies.json` file. Each policy has the following properties:
+
+| Property           | Type                   | Required | Description                                                                                                                        |
+| ------------------ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `name`             | `string`               | Yes      | A unique name used to reference this policy on routes.                                                                             |
+| `allowedOrigins`   | `string[]` or `string` | Yes      | Origins permitted to make cross-origin requests. Supports wildcards (see [Origin Matching](../articles/cors.mdx#origin-matching)). |
+| `allowedMethods`   | `string[]` or `string` | No       | HTTP methods allowed for cross-origin requests (e.g., `GET`, `POST`).                                                              |
+| `allowedHeaders`   | `string[]` or `string` | No       | Request headers the client can send. Use `*` to allow any header.                                                                  |
+| `exposeHeaders`    | `string[]` or `string` | No       | Response headers the browser can access from JavaScript.                                                                           |
+| `maxAge`           | `number`               | No       | Time in seconds the browser caches preflight results.                                                                              |
+| `allowCredentials` | `boolean`              | No       | Whether to include credentials (cookies, authorization headers) in cross-origin requests.                                          |
+
+## Built-in Policies
+
+Every route has a `corsPolicy` property in `x-zuplo-route` that can be set to
+one of the built-in values or the name of a custom policy:
+
+- **`none`** - Disables CORS. All CORS headers are stripped from responses. This
+  is the default.
+- **`anything-goes`** - Allows any origin, method, and header. Not recommended
+  for production.
+
+## Example
+
+```json title="config/policies.json"
+{
+  "corsPolicies": [
+    {
+      "name": "my-cors-policy",
+      "allowedOrigins": [
+        "https://app.example.com",
+        "https://admin.example.com"
+      ],
+      "allowedMethods": ["GET", "POST", "PUT", "DELETE"],
+      "allowedHeaders": ["Authorization", "Content-Type"],
+      "exposeHeaders": ["X-Request-Id"],
+      "maxAge": 3600,
+      "allowCredentials": true
+    }
+  ]
+}
+```
+
+```json title="config/routes.oas.json"
+"x-zuplo-route": {
+  "corsPolicy": "my-cors-policy",
+  "handler": {
+    "export": "urlForwardHandler",
+    "module": "$import(@zuplo/runtime)"
+  }
+}
+```