zuplo 6.67.32 → 6.68.0

package/docs/policies/xml-to-json-outbound/schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/auth0-jwt-auth-inbound.json",
+  "type": "object",
+  "title": "XML to JSON Outbound",
+  "isDeprecated": false,
+  "isPaidAddOn": false,
+  "isEnterprise": false,
+  "isInternal": false,
+  "isBeta": false,
+  "isHidden": false,
+  "products": ["api-gateway"],
+  "description": "Parses XML and converts it to JSON.",
+  "deprecatedMessage": "",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "XmlToJsonOutboundPolicy",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(@zuplo/runtime)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "title": "XmlToJsonPolicyOptions",
+          "type": "object",
+          "description": "The options for this policy.",
+          "additionalProperties": false,
+          "required": [],
+          "properties": {
+            "removeNSPrefix": {
+              "type": "boolean",
+              "default": true,
+              "description": "Remove namespace string from tag and attribute names."
+            },
+            "ignoreProcessingInstructions": {
+              "type": "boolean",
+              "default": true,
+              "description": "Ignore processing instruction tags. i.e. `<?elementnames <fred>, <bert>, <harry> ?>`."
+            },
+            "ignoreDeclarations": {
+              "type": "boolean",
+              "default": true,
+              "description": "Ignore declarations. i.e. `<?xml version=\"1.0\"?>`."
+            },
+            "ignoreAttributes": {
+              "type": "boolean",
+              "default": true,
+              "description": "Ignore tag attributes."
+            },
+            "stopNodes": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "examples": [["root.a", "*.accounts"]],
+              "description": "At particular point, if you don't want to parse a tag and it's nested tags then you can set their path in stopNodes. You can also set tags which should not be processed irrespective of their path using \\* as the wildcard."
+            },
+            "attributeNamePrefix": {
+              "type": "string",
+              "default": "@_",
+              "description": "The prefix of attribute names in the resulting JS object."
+            },
+            "textNodeName": {
+              "type": "string",
+              "default": "#text",
+              "description": "Text value of a tag is parsed to \\#text property by default."
+            },
+            "trimValues": {
+              "type": "boolean",
+              "default": true,
+              "description": "Remove surrounding whitespace from tag or attribute value."
+            },
+            "parseOnStatusCodes": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "number"
+                  }
+                }
+              ],
+              "description": "A list of status codes and ranges \"200-299, 304\" that should the XML parser should run on. If not set, the parser will run on all status codes.",
+              "examples": ["200-299"]
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "XmlToJsonOutboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "attributeNamePrefix": "@_",
+            "ignoreAttributes": true,
+            "ignoreDeclarations": true,
+            "ignoreProcessingInstructions": true,
+            "parseOnStatusCodes": "200-299",
+            "removeNSPrefix": true,
+            "stopNodes": ["root.a", "*.accounts"],
+            "textNodeName": "#text",
+            "trimValues": true
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/programmable-api/audit-log.mdx

@@ -0,0 +1,74 @@
+---
+title: Audit Log Feature
+sidebar_label: Audit Log
+---
+
+Zuplo has a built-in auditing feature that can write output to a selection of
+data sinks.
+
+If enabled, the Audit Log feature logs full details of
+
+- The request including URL, headers (optional), and full body (optional)
+- The response including status, headers (optional) and full body (optional)
+
+These can then be written to a configured Audit Log Output Provider of your
+choosing, like AstraDB by DataStax. Contact
+[support@zuplo.com](mailto:support@zuplo.com) to request a new provider.
+
+:::note
+
+While you can use it on any tier in working-copy, the Audit Log capability is an
+**enterprise** feature. Contact us to have Audit Logging enabled for your
+enterprise deployment. [Pricing](https://zuplo.com/pricing)
+
+:::
+
+## Configuring Audit Log
+
+Audit Logging is enabled via a plugin that's registered in the
+`zuplo.runtime.ts` runtime extensions module;
+[learn more about runtime extensions](./runtime-extensions.mdx). The following
+example configures Audit Log to write to a DataStax Astra DB collection.
+
+Note you must provide the full URL to the collection, for example
+`https://<id-and-region>.apps.astra.datastax.com/api/rest/v2/namespaces/<namespace>/collections/<collection>`
+
+```ts
+import {
+  AuditLogDataStaxProvider,
+  AuditLogPlugin,
+  RuntimeExtensions,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new AuditLogPlugin(
+      new AuditLogDataStaxProvider({
+        url: "THE_FULL_URL_TO_YOUR_COLLECTION_HERE",
+        xCassandraToken: "YOUR_API_KEY_HERE",
+      }),
+      {
+        include: {
+          request: {
+            body: false,
+          },
+          response: {
+            headers: false,
+          },
+        },
+      },
+    ),
+  );
+}
+```
+
+Note the use of options to disable capture of the full request body and full
+response headers.
+
+:::tip
+
+This feature logs API request and response data. For account-level activity
+tracking (project changes, team management, deployments), see
+[Account Audit Logs](../articles/accounts/audit-logs.mdx).
+
+:::

package/docs/programmable-api/background-dispatcher.mdx

@@ -0,0 +1,124 @@
+---
+title: BackgroundDispatcher
+sidebar_label: BackgroundDispatcher
+---
+
+The BackgroundDispatcher class batches outbound transmissions for efficient
+processing. It's ideal for logging and analytics calls to external services
+where you don't need 1:1 transmission with incoming requests. The dispatcher
+groups entries and invokes your callback with batches at regular intervals.
+
+## Constructor
+
+```ts
+new BackgroundDispatcher<T>(
+  dispatchFunction: (entries: T[]) => Promise<void>,
+  options: { msDelay: number }
+)
+```
+
+Creates a new background dispatcher instance.
+
+- `dispatchFunction` - Asynchronous function called with batched entries
+- `options.msDelay` - Milliseconds between dispatch calls (required, non-zero)
+- `T` - The type of entries being batched
+
+## Methods
+
+**`enqueue`**
+
+Adds an entry to the batch queue for later dispatch.
+
+```ts
+enqueue(entry: T, context: ZuploContext): void
+```
+
+## Example
+
+```ts
+import {
+  ZuploContext,
+  ZuploRequest,
+  BackgroundDispatcher,
+  environment,
+} from "@zuplo/runtime";
+
+// The type that identifies the entries
+// to be batched
+interface ExampleEntry {
+  message: string;
+}
+
+// The dispatch function that will be invoked by the
+// BatchDispatcher at most every 'n' milliseconds
+const dispatchFunction = async (entries: ExampleEntry[]) => {
+  // consider implementing a retry or backup call
+  // if the data being transmitted is important
+  await fetch(`https://example-logging-service.com/`, {
+    method: "POST",
+    headers: {
+      "api-key": environment.MY_LOGGING_API_KEY,
+    },
+    body: JSON.stringify(entries),
+  });
+};
+
+// The dispatcher is typically initiated at the module level
+// so it can be shared by requests. Note that the msDelay is set
+// to 100ms.
+const backgroundDispatcher = new BackgroundDispatcher<ExampleEntry>(
+  dispatchFunction,
+  { msDelay: 100 },
+);
+
+// This is an example Request Handler that used the component, a simple
+// "Hello World" handler.
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  backgroundDispatcher.enqueue(
+    {
+      message: `new request on '${request.url}' with id ${context.requestId}`,
+    },
+    context,
+  );
+
+  return "Hello World!";
+}
+```
+
+The dispatcher invokes the dispatch function with batched records at most every
+'n' milliseconds (as configured) when items are enqueued. If no items are
+enqueued, the function won't be invoked.
+
+:::tip
+
+There are no automatic retries for failed dispatch functions. Implement retry
+logic in your dispatch function if needed.
+
+:::
+
+## Best Practices
+
+### Module-Level Initialization
+
+Initialize the dispatcher at the module level so it can be shared across
+multiple requests:
+
+```ts
+// Create at module level
+const dispatcher = new BackgroundDispatcher<LogEntry>(dispatchFunction, {
+  msDelay: 100,
+});
+
+// Or use a Map for multiple dispatchers
+const dispatchers = new Map<string, BackgroundDispatcher<any>>();
+```
+
+### Choosing the Right Delay
+
+The longer the delay, the larger your batches will get and the less frequently
+you'll send batched information. However, on a busy server this could build up a
+lot of memory and potentially cause an OOM (out-of-memory) situation.
+
+The shorter the delay, the more frequently you'll send smaller batches. We
+typically recommend 10ms for very high traffic gateways and 100ms for lower
+traffic gateways.

package/docs/programmable-api/background-loader.mdx

@@ -0,0 +1,104 @@
+---
+title: BackgroundLoader
+sidebar_label: BackgroundLoader
+---
+
+The BackgroundLoader class provides asynchronous loading of configuration data
+while minimizing gateway latency. It's ideal for critical configuration that
+powers your gateway for smart routing or similar use cases.
+
+The BackgroundLoader optimizes performance by:
+
+- Immediately returning cached data when available
+- Asynchronously refreshing data in the background
+- Only blocking when cache is empty or expired
+
+## Constructor
+
+```ts
+new BackgroundLoader<T>(
+  loader: (key: string) => Promise<T>,
+  options: BackgroundLoaderOptions
+)
+```
+
+Creates a new background loader instance.
+
+- `loader` - Asynchronous function that loads data for a given key
+- `options` - Configuration options including TTL and timeout
+- `T` - The type of data being loaded
+
+## Options
+
+```ts
+interface BackgroundLoaderOptions {
+  // (Required) Time to live for cache entries in seconds
+  ttlSeconds: number;
+  // (Optional) Timeout for the loader function in seconds
+  loaderTimeoutSeconds?: number;
+}
+```
+
+## Methods
+
+**`get`**
+
+Retrieves data for the specified key. Returns immediately if cached, otherwise
+blocks while loading.
+
+```ts
+get(key: string): Promise<T>
+```
+
+## Example
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { BackgroundLoader } from "@zuplo/runtime";
+
+const loaderFunction = async (key: string) => {
+  // Add error handling and validation as needed for your use case
+  const result = await fetch(`https://example-config-service.com/${key}`);
+  const data = await result.json();
+  return data;
+};
+
+// Create an instance of the component at the module level
+// Here with a cache expiry of 60s
+//
+const backgroundLoader = new BackgroundLoader(loaderFunction, {
+  ttlSeconds: 60,
+  loaderTimeoutSeconds: 10,
+});
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  // once an entry is cached this will return immediately. It will only block
+  // if the cache is empty or has expired.
+  const data = await backgroundLoader.get(request.params.loaderId);
+  return data;
+}
+```
+
+The BackgroundLoader will ensure that only one request per 'key' is active at
+any one time to avoid overloading your destination services.
+
+The BackgroundLoader has the following options. In the above example, we set
+`ttlSeconds`:
+
+```ts
+interface BackgroundLoaderOptions {
+  // (Required) The time to live for the cache entry in seconds
+  ttlSeconds: number;
+  // (Optional) The timeout for the loader -- error out if the load takes longer than this. Useful to prevent hanging background requests.
+  loaderTimeoutSeconds?: number;
+}
+```
+
+:::warning
+
+You can't return a `Response` created by the BackgroundLoader as a response from
+a policy or handler. Responses can't be re-used in this way - they're associated
+with the originating request and results from the BackgroundLoader can be shared
+across requests.
+
+:::

package/docs/programmable-api/cache.mdx

@@ -0,0 +1,186 @@
+---
+title: Cache
+sidebar_label: Cache
+draft: false
+---
+
+The [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache) provides
+a persistent storage mechanism for Request / Response object pairs that are
+cached in long lived memory.
+
+:::tip
+
+Only a subset of the standard Cache API is supported. Below are the interfaces
+and methods that are supported and known limitations.
+
+:::
+
+## CacheStorage
+
+The `CacheStorage` is exposed as the `caches` global object. This object allows
+you to open instances of a `Cache`. When calling `caches.open` if the named
+cache doesn't exist it will be created, otherwise the existing cache will be
+returned.
+
+**Definition**
+
+```ts
+interface CacheStorage {
+  open(cacheName: string): Promise<Cache>;
+}
+```
+
+**Example**
+
+```ts
+const cache = await caches.open("MY_CACHE");
+```
+
+## Cache
+
+The `Cache` object stores `Request` and `Response` objects based on header
+values.
+
+**Definition**
+
+```ts
+interface Cache {
+  put(request: RequestInfo, response: Response): Promise<void>;
+  match(
+    request: RequestInfo,
+    options?: CacheQueryOptions,
+  ): Promise<Response | undefined>;
+  delete(request: RequestInfo, options?: CacheQueryOptions): Promise<boolean>;
+}
+
+interface CacheQueryOptions {
+  /**
+   * Not supported in development environments
+   */
+  ignoreMethod: boolean;
+  /**
+   * Always ignored
+   */
+  ignoreSearch: boolean;
+  /**
+   * Always ignored
+   */
+  ignoreVary: boolean;
+}
+```
+
+:::warning
+
+At this time, the `options` parameter will be ignored entirely when running in a
+developer environment (for example working copy). In non-developer environments,
+the `ignoreMethod` property is supported. All other properties will be ignored.
+
+:::
+
+### Put
+
+```ts
+await cache.put(request, response);
+```
+
+The `put()` method of the `Cache` interface allows key/value pairs to be added
+to the current Cache object.
+
+### Match
+
+```ts
+const response = await cache.match(request);
+```
+
+The `match()` method of the `Cache` interface returns a Promise that resolves to
+the Response associated with the first matching request in the Cache object. If
+no match is found, the Promise resolves to `undefined`.
+
+### Delete
+
+```ts
+await cache.delete(request);
+```
+
+The delete() method of the Cache interface finds the Cache entry whose key is
+the request, and if found, deletes the Cache entry and returns a Promise that
+resolves to true. If no Cache entry is found, it resolves to false.
+
+## Headers
+
+The following headers can be used to control the cache when adding a response
+using the `put()` method.
+
+- `Cache-Control`: Controls caching directives.
+  [More info](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
+- `ETag`: Allows cache.match() to evaluate conditional requests with
+  If-None-Match.
+- `Expires`: A string that specifies when the resource becomes invalid.
+- `Last-Modified`: Allows cache.match() to evaluate conditional requests with
+  If-Modified-Since.
+
+## Examples
+
+The below example shows how to use a cached response and populate the cache in
+the event there is no response already cached.
+
+```ts
+const request = new Request(`https://echo.zuplo.io`);
+const cache = await caches.open("MY_CACHE");
+let response = await cache.match(request);
+if (!response) {
+  response = await fetch(request);
+  await cache.put(request, response);
+}
+
+const data = await response.json();
+```
+
+If you just want to store the value, just create a new simple Response and set
+the `Cache-Control` header.
+
+```ts
+const request = new Request(`https://echo.zuplo.io`);
+const cache = await caches.open("MY_CACHE");
+const response = await fetch(request);
+
+// Create a new response and set new headers
+const cachedResponse = new Response(response, {
+  headers: {
+    "Cache-Control": "max-age=604800",
+  },
+});
+
+// Add the response to the cache
+await cache.put(request, cachedResponse);
+```
+
+When adding to the cache, headers are used to control how long resources are
+stored. If you are reusing the response headers, make sure to account for
+additional cache headers that may have been sent.
+
+```ts
+const request = new Request(`https://echo.zuplo.io`);
+const cache = await caches.open("MY_CACHE");
+const response = await fetch(request);
+
+// Create a new Headers object and add existing response headers
+const headers = new Headers(response.headers);
+
+// Set the cache max age
+headers.set("Cache-Control", "max-age=604800");
+
+// Just in case the original response included other cache
+// headers, remove them
+headers.delete("Expires");
+headers.delete("ETag");
+headers.delete("Last-Modified");
+
+// Create a new request with the cache headers
+const cachedResponse = new Response(response, {
+  headers,
+});
+
+// Add the response to the cache
+await cache.put(request, cachedResponse);
+```