zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/runtime-extensions.mdx

@@ -0,0 +1,340 @@
+---
+title: Runtime Extensions
+---
+
+While most configuration in your Zuplo gateway is set on a per-route or
+per-policy basis, there are times when behaviors need to be modified globally.
+To plug into the global initialization of your gateway, create a file called
+`zuplo.runtime.ts` in the `modules` folder with the following code.
+
+:::warning
+
+Any error thrown in the `runtimeInit` method will prevent the gateway from
+starting and yield a 500 error for all requests. Be sure to add only reliable
+code here and use `try/catch` as appropriate to handle any recoverable
+exceptions.
+
+:::
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  // Extensions go here
+}
+```
+
+:::note
+
+The name of the export must be `runtimeInit` and must conform to the above
+function signature.
+
+:::
+
+## Custom Problem (Error) Response Formatter
+
+Zuplo includes built-in error handling that returns errors in the format of the
+[Problem Details for HTTP APIs](http://httpproblems.com/) proposed standard.
+This means that HTTP errors (or other exceptions) will return responses that
+look like the following.
+
+```json
+{
+  "type": "https://httpproblems.com/http-status/404",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Not Found",
+  "instance": "/not-a-path",
+  "trace": {
+    "timestamp": "2023-03-14T15:49:38.581Z",
+    "requestId": "05968b6d-6f82-4ae3-8e13-f92e0d0499c5",
+    "buildId": "a9b200a3-734c-413a-a1ae-ce171d53e5a7",
+    "rayId": "7a7daaf3bac2f325"
+  }
+}
+```
+
+If you want to customize this format, you can configure the
+`problemResponseFormat` function and return a `Response` in the format of your
+choice.
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.problemResponseFormat = (
+    { problem, statusText, additionalHeaders },
+    request,
+    context,
+  ) => {
+    // Build the response body
+    const body = JSON.stringify(problem, null, 2);
+
+    // Send the response with headers and status
+    return new Response(body, {
+      status: problem.status,
+      statusText,
+      headers: {
+        ...additionalHeaders,
+        "content-type": "application/problem+json",
+      },
+    });
+  };
+}
+```
+
+## Hooks
+
+Hooks allow code to be run as part of the request/response pipeline. Hooks can
+be created at the API level in `zuplo.runtime.ts` as shown below or can be added
+[via a plugin](./hooks.mdx).
+
+:::tip
+
+All hooks can be either synchronous or asynchronous. To make your hook
+asynchronous simply add the `async` keyword on the function.
+
+:::
+
+The following hooks can be set globally in the `zuplo.runtime.ts`:
+
+### Hook: OnPreRouting
+
+Runs before the request is matched to a route. This is useful if you want to
+customize the routing behavior. Example use cases include:
+
+- Routing to a different URL based on a header value
+- Normalizing URLs to be all lowercase
+- Request preprocessing before route matching
+
+**Type Definition:**
+
+```ts
+interface PreRoutingHook {
+  (request: Request): Promise<Request> | Request;
+}
+```
+
+**Example:**
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPreRoutingHook(async (request) => {
+    // Normalize URL to lowercase
+    const nr = new Request(request.url.toLowerCase(), request);
+    return nr;
+  });
+
+  // Header-based routing
+  runtime.addPreRoutingHook((request) => {
+    const version = request.headers.get("API-Version");
+    if (version === "v2") {
+      const url = new URL(request.url);
+      url.pathname = `/v2${url.pathname}`;
+      return new Request(url.toString(), request);
+    }
+    return request;
+  });
+}
+```
+
+### Hook: OnRequest
+
+Runs when a request is received, before any plugins or handlers. This hook can
+modify the request or return a response to short-circuit the pipeline.
+
+**Type Definition:**
+
+```ts
+interface OnRequestHook {
+  (
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<ZuploRequest | Response> | (ZuploRequest | Response);
+}
+```
+
+**Example:**
+
+```ts
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addRequestHook(async (request, context) => {
+    // Add correlation ID
+    const correlationId = crypto.randomUUID();
+    context.custom.correlationId = correlationId;
+
+    const headers = new Headers(request.headers);
+    headers.set("X-Correlation-ID", correlationId);
+
+    // Can return a request or a response. If a response is returned the
+    // pipeline stops and the response is returned.
+    return new ZuploRequest(request, { headers });
+  });
+
+  // Example: Early response for maintenance mode
+  runtime.addRequestHook((request, context) => {
+    if (environment.MAINTENANCE_MODE === "true") {
+      return new Response("Service temporarily unavailable", {
+        status: 503,
+        headers: { "Retry-After": "3600" },
+      });
+    }
+    return request;
+  });
+}
+```
+
+### Hook: OnResponseSending
+
+Runs before a response is sent. Response can be modified. Multiple hooks execute
+in the order they were added.
+[More details.](/docs/programmable-api/hooks#hook-onresponsesending)
+
+**Type Definition:**
+
+```ts
+interface OnResponseSendingHook {
+  (
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<Response> | Response;
+}
+```
+
+**Example:**
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addResponseSendingHook((response, request, context) => {
+    // Add security headers
+    const headers = new Headers(response.headers);
+    headers.set("X-Content-Type-Options", "nosniff");
+    headers.set("X-Frame-Options", "DENY");
+    headers.set("X-XSS-Protection", "1; mode=block");
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  });
+}
+```
+
+### Hook: OnResponseSendingFinal
+
+Runs before a response is sent. The response can't be modified. Ideal for
+logging, analytics, and monitoring.
+[More details.](/docs/programmable-api/hooks#hook-onresponsesendingfinal)
+
+**Type Definition:**
+
+```ts
+interface OnResponseSendingFinalHook {
+  (
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<void> | void;
+}
+```
+
+**Example:**
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addResponseSendingFinalHook(async (response, request, context) => {
+    // Log response metrics
+    const processingTime = Date.now() - context.custom.startTime;
+
+    context.log.info("Request completed", {
+      method: request.method,
+      url: request.url,
+      status: response.status,
+      processingTime,
+      correlationId: context.custom.correlationId,
+    });
+
+    // Send metrics to external service (non-blocking)
+    const sendMetrics = async () => {
+      await fetch("https://metrics.example.com/api/log", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          timestamp: new Date().toISOString(),
+          method: request.method,
+          status: response.status,
+          processingTime,
+        }),
+      });
+    };
+
+    context.waitUntil(sendMetrics());
+  });
+}
+```
+
+## Custom Not Found Handler
+
+You can customize how Zuplo handles requests that don't match any route by
+setting a custom `notFoundHandler`:
+
+```ts
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.notFoundHandler = async (request, context, notFoundOptions) => {
+    // Custom 404 handling
+    const customResponse = {
+      error: "Route not found",
+      message: `The requested path '${new URL(request.url).pathname}' wasn't found`,
+      timestamp: new Date().toISOString(),
+      requestId: context.requestId,
+    };
+
+    return new Response(JSON.stringify(customResponse, null, 2), {
+      status: 404,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Custom-Handler": "true",
+      },
+    });
+  };
+}
+```
+
+## Plugin and Handler Extensions
+
+Built-in and custom plugins and handlers can expose their own extensibility. For
+example, [AWS Lambda handler](../handlers/aws-lambda.mdx) exposes the ability to
+customize the event that's sent when invoking the Lambda function.
+
+The example below shows how to use a route's custom property to set the path on
+the outgoing event to a custom value.
+
+```ts
+import {
+  AwsLambdaHandlerExtensions,
+  RuntimeExtensions,
+  ContextData,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  AwsLambdaHandlerExtensions.addSendingAwsLambdaEventHook(
+    async (request, context, event: AwsLambdaEventV1) => {
+      const lambdaPath = ContextData.get(context, "lambdaPath");
+      event.path = lambdaPath ?? event.path;
+      return event;
+    },
+  );
+}
+```

package/docs/programmable-api/safely-clone-a-request-or-response.mdx

@@ -0,0 +1,57 @@
+---
+title: Safely clone a request or response
+sidebar_label: Clone Request/Response
+---
+
+We often want to read the body of a request or response before forwarding it on
+to the downwind service or back to the client respectively.
+
+![Lifecycle](../../public/media/safely-clone-a-request-or-response/f70d62c0-8bdd-4476-9fd6-fe2dad7ae3a2.png)
+
+When doing this inside the Zuplo gateway in a
+[Request Handler](../handlers/custom-handler.mdx), be careful to clone the
+request or response to avoid causing a `body-used` exception.
+
+A `body-used` exception occurs when a `.body` property of a request or response,
+which is of type `ReadableStream`, has already been read. These properties can
+only be read once and if we pass that same object to `fetch` (for the downwind
+call) or return it from a request handler - you’ll get that exception.
+
+> Note - you can check to see if a body has already been used by looking at the
+> `.bodyUsed` property of `ZuploRequest` and `Response`.
+
+## How to clone the request and response
+
+Let’s imagine we want to log both the request body and response body of a
+proxied call to a downwind service
+
+```ts
+export default async function (req: ZuploRequest, ctx: ZuploContext) {
+  // pretend we want to log the request and response body
+  const reqClone = req.clone();
+  const reqBody = await reqClone.text();
+  ctx.log.debug(reqBody);
+
+  // we can now safely re-use this body to call the downstream
+  // service
+  const response = await fetch("https://downwind-url.com/foo/bar", {
+    method: req.method,
+    body: req.body,
+  });
+
+  const resClone = response.clone();
+  const resBody = await resClone.text();
+  ctx.log.debug(resBody);
+
+  // we can now safely use the original response
+  return response;
+}
+```
+
+If you don’t need to read the body - we recommend against cloning the request or
+response as it will make your gateway more memory efficient and increase
+performance.
+
+> Note - in [policies](../policies/overview.mdx), if you need to read the body
+> we always recommend using `.clone()` first, as you don’t know what the end
+> request handler might want to do with the originals.

package/docs/programmable-api/streaming-zone-cache.mdx

@@ -0,0 +1,155 @@
+---
+title: StreamingZoneCache
+sidebar_label: StreamingZoneCache
+---
+
+The `StreamingZoneCache` class provides a distributed caching solution optimized
+for streaming data. It allows you to cache `ReadableStream` objects across
+Zuplo's edge network.
+
+:::note{title="Beta Feature"}
+
+This API is in Beta - please use with care and provide feedback to the team if
+you encounter any issues.
+
+:::
+
+## Constructor
+
+```ts
+new StreamingZoneCache(name: string, context: ZuploContext)
+new StreamingZoneCache(name: string, options: CacheOptions)
+```
+
+Creates a new streaming cache instance.
+
+- `name` - A unique identifier for the cache instance
+- `context` - The [ZuploContext](./zuplo-context.mdx) object
+- `options` - Cache configuration options (alternative to context)
+
+## Methods
+
+**`get`**
+
+Retrieves a stream from the cache. Returns `undefined` if not found.
+
+```ts
+get(key: string): Promise<ReadableStream<Uint8Array> | undefined>
+```
+
+**`put`**
+
+Stores a stream in the cache with a time-to-live (TTL) in seconds.
+
+```ts
+put(key: string, stream: ReadableStream<Uint8Array>, ttlSeconds: number): Promise<void>
+```
+
+**`delete`**
+
+Removes a stream from the cache.
+
+```ts
+delete(key: string): Promise<void>
+```
+
+## Example
+
+```ts
+import { StreamingZoneCache, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const cache = new StreamingZoneCache("response-cache", context);
+  const cacheKey = `response:${request.url}`;
+
+  // Try to get cached response
+  const cachedStream = await cache.get(cacheKey);
+  if (cachedStream) {
+    return new Response(cachedStream, {
+      headers: { "X-Cache": "HIT" },
+    });
+  }
+
+  // Fetch from origin
+  const response = await fetch("https://api.example.com/large-file");
+
+  // Clone the response so we can cache it and return it
+  const [streamForCache, streamForResponse] = response.body!.tee();
+
+  // Cache the response for 1 hour (3600 seconds)
+  await cache.put(cacheKey, streamForCache, 3600);
+
+  return new Response(streamForResponse, {
+    headers: {
+      ...response.headers,
+      "X-Cache": "MISS",
+    },
+  });
+}
+```
+
+## Advanced Example: Caching Large Files
+
+```ts
+import { StreamingZoneCache, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const cache = new StreamingZoneCache("file-cache", context);
+  const fileId = request.params.fileId;
+  const cacheKey = `file:${fileId}`;
+
+  // Check cache first
+  const cachedFile = await cache.get(cacheKey);
+  if (cachedFile) {
+    context.log.info(`Cache hit for file ${fileId}`);
+    return new Response(cachedFile, {
+      headers: {
+        "Content-Type": "application/octet-stream",
+        "Cache-Control": "public, max-age=3600",
+      },
+    });
+  }
+
+  // Stream from storage service
+  const storageResponse = await fetch(
+    `https://storage.example.com/files/${fileId}`,
+  );
+
+  if (!storageResponse.ok) {
+    return new Response("File not found", { status: 404 });
+  }
+
+  // Use tee() to create two identical streams
+  const [cacheStream, responseStream] = storageResponse.body!.tee();
+
+  // Cache for 24 hours
+  context.waitUntil(cache.put(cacheKey, cacheStream, 86400));
+
+  return new Response(responseStream, {
+    headers: storageResponse.headers,
+  });
+}
+```
+
+## Best Practices
+
+- Use `tee()` to split streams when you need to both cache and return the same
+  stream
+- Use `context.waitUntil()` for non-blocking cache writes
+- Set appropriate TTL values based on your content update frequency
+- Consider the size of streams being cached to avoid memory issues
+- The cache is distributed across Zuplo's edge network for optimal performance
+
+## See Also
+
+- [ZoneCache](./zone-cache.mdx) - For caching JSON and other structured data
+- [MemoryZoneReadThroughCache](./memory-zone-read-through-cache.mdx) - For
+  in-memory caching
+- [Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) -
+  MDN documentation on streams