zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/memory-zone-read-through-cache.mdx

@@ -0,0 +1,96 @@
+---
+title: MemoryZoneReadThroughCache
+sidebar_label: MemoryZoneReadThroughCache
+---
+
+The `MemoryZoneReadThroughCache` class provides an in-memory caching solution
+with automatic read-through capabilities. This cache stores data in memory for
+fast access and automatically handles cache misses.
+
+## Constructor
+
+```ts
+new MemoryZoneReadThroughCache<T = unknown>(name: string, context: ZuploContext)
+```
+
+Creates a new instance of the memory cache with read-through capabilities.
+
+- `name` - A unique identifier for the cache instance
+- `context` - The [ZuploContext](./zuplo-context.mdx) object
+- `T` - The type of data stored in the cache (defaults to `unknown`)
+
+## Methods
+
+**`get`**
+
+Retrieves a value from the cache by its key. Returns `undefined` if not found.
+
+```ts
+get(key: string): Promise<T | undefined>
+```
+
+**`put`**
+
+Stores a value in the cache with a time-to-live (TTL) in seconds.
+
+```ts
+put(key: string, data: T, ttlSeconds: number): void
+```
+
+**`delete`**
+
+Removes a value from the cache.
+
+```ts
+delete(key: string): Promise<void>
+```
+
+## Example
+
+```ts
+import {
+  MemoryZoneReadThroughCache,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Create a cache instance for user data
+  const userCache = new MemoryZoneReadThroughCache<{
+    name: string;
+    email: string;
+  }>("user-cache", context);
+
+  // Try to get user from cache
+  const userId = "user-123";
+  let user = await userCache.get(userId);
+
+  if (!user) {
+    // User not in cache, fetch from database
+    user = await fetchUserFromDatabase(userId);
+
+    // Cache the user data for 5 minutes (300 seconds)
+    userCache.put(userId, user, 300);
+  }
+
+  return new Response(JSON.stringify(user));
+}
+```
+
+## Best Practices
+
+- Use descriptive cache names to avoid collisions between different cache
+  instances
+- Set appropriate TTL values based on your data freshness requirements
+- Consider memory usage when caching large objects
+- The cache is scoped to the current worker instance and not shared across
+  instances
+
+## See Also
+
+- [ZoneCache](./zone-cache.mdx) - For distributed caching across zones
+- [StreamingZoneCache](./streaming-zone-cache.mdx) - For caching streaming data
+- [BackgroundLoader](./background-loader.mdx) - For automatic cache population

package/docs/programmable-api/node-modules.mdx

@@ -0,0 +1,67 @@
+---
+title: Node Modules
+sidebar_label: Node Modules
+---
+
+Zuplo itself doesn't run Node.js, but instead runs a custom JavaScript engine
+that's designed to be fast and secure. However, the Zuplo engine is compatible
+with certain node modules that don't use native code or certain Node.js specific
+features like the file system.
+
+## Custom Modules
+
+If you would like to use a node module, you can bundle modules inside of your
+own project. This process is straightforward using standard tools like
+[ESBuild](https://esbuild.github.io/) or [TSDown](https://tsdown.dev) to bundle
+your code along with any dependencies into a single file that's included in your
+Zuplo project.
+
+You can find a complete example of how to bundle your own node modules in the
+[Bundling Custom Node Modules example](https://github.com/zuplo/zuplo/tree/main/examples/custom-module).
+
+The process is typically as quick as running the following commands:
+
+```bash
+npm install your-package-name
+npx tsdown ./node_modules/your-package-name --format esm --platform browser --out-dir ./modules/third-party/your-package-name
+```
+
+The module can then be imported and used in your Zuplo project like so:
+
+```ts
+import { YourPackage } from "./modules/third-party/your-package-name.mjs";
+```
+
+Be sure to test your bundled code thoroughly to ensure it works as expected in
+the Zuplo environment.
+
+## Bundled Node Modules
+
+:::danger{title="Deprecated"}
+
+Using the bundled node modules is no longer recommended. As these modules are
+used by multiple customers, they may not be the version you need or may not work
+as you expect. Instead, we recommend bundling your own node modules inside of
+your project. See the section on [custom modules](#custom-modules)
+
+:::
+
+Below are the currently installed modules.
+
+:::caution{title="Test Carefully"}
+
+It's important to test your use of any node module carefully. Zuplo doesn't run
+Node.js, it runs a custom JavaScript engine that's designed to be fast and
+secure. This means that these modules may not work as you expect or certain
+functionality in these modules may not work at all. Even when we say a module is
+"Working", that doesn't guarantee it will work in your specific use case. Test
+your code thoroughly before deploying it to production.
+
+:::
+
+When developing in the Zuplo portal using the bundled modules, you will see a
+red underline on the module types. We do not provide type definitions for these
+modules. You can ignore these editor errors as this won't impact the build
+(assuming the modules are used correctly).
+
+<BundlesTable />

package/docs/programmable-api/not-found-handler.mdx

@@ -0,0 +1,47 @@
+---
+title: Custom Not Found Handler
+---
+
+By default, Zuplo will return a 404 (using
+[problem details](./http-problems.mdx)) if no matching `path/method` combination
+is found. You can override this behavior by adding code to the
+`zuplo.runtime.ts` file (see [runtime extensions](./runtime-extensions.mdx)).
+
+For example - a custom not found handler can be used to return a
+`405 - Method Not Allowed` if a matching path is found, but no matching METHOD,
+here is an example function that would implement this behavior:
+
+```ts
+import { HttpProblems, RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  //add a custom not found handler
+  runtime.notFoundHandler = async (request, context, notFoundOptions) => {
+    if (notFoundOptions.routesMatchedByPathOnly.length > 0) {
+      // It's required to have an 'Allow' header with a 405 response
+      // Generate a string of allowed methods
+      const allowedMethods = notFoundOptions.routesMatchedByPathOnly
+        .map((route) => route.methods)
+        .reduce((acc, val) => acc.concat(val), [])
+        .join(", ");
+
+      return HttpProblems.methodNotAllowed(
+        request,
+        context,
+        {},
+        { allow: allowedMethods },
+      );
+    }
+
+    return HttpProblems.notFound(request, context);
+  };
+}
+```
+
+:::warning
+
+An error in your `zuplo.runtime.ts` can break your gateway for all requests. Be
+sure to carefully review any custom code in this file and add generous error
+handling where appropriate.
+
+:::

package/docs/programmable-api/oauth-protected-resource-plugin.mdx

@@ -0,0 +1,46 @@
+---
+title: OAuth Protected Resource Plugin
+---
+
+The `OAuthProtectedResourcePlugin` allows you to configure your Zuplo gateway to
+support OAuth protected resources through the
+`.well-known/oauth-protected-resource` endpoint. See
+[RFC9728](https://datatracker.ietf.org/doc/rfc9728/) for more details.
+
+This is particularly useful when building an MCP Server on Zuplo. See the
+[MCP Server Handler docs](../handlers/mcp-server.mdx#oauth-authentication) for
+more details.
+
+## Usage
+
+This runtime plugin will register the `.well-known/oauth-protected-resource`
+route on your behalf. If you configure an
+[OAuth Policy](../articles/oauth-authentication.mdx) on a route with the
+`oAuthResourceMetadataEnabled` option set to `true`, then the OAuth policy will
+automatically add the necessary `WWW-Authenticate` header to 401 responses, with
+the `resource_metadata` parameter set to the URL of the
+`.well-known/oauth-protected-resource` endpoint.
+
+```ts
+import {
+  RuntimeExtensions,
+  OAuthProtectedResourcePlugin,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OAuthProtectedResourcePlugin({
+      authorizationServers: ["https://your-auth0-domain.us.auth0.com"],
+      resourceName: "My MCP OAuth Resource",
+    }),
+  );
+}
+```
+
+As per the MCP OAuth specification, you _must_ use the canonical URL of your
+authorization server as the `authorizationServers` value. The `resourceName` is
+a human readable name for the resource.
+
+Note that the `.well-known/oauth-protected-resource` endpoint explicitly has a
+CORS policy of `anything-goes` since this is a public endpoint that should be
+accessible to anyone to check the server's OAuth configuration.

package/docs/programmable-api/overview.mdx

@@ -0,0 +1,213 @@
+---
+title: Programmable API
+sidebar_label: Overview
+description:
+  "This section provides a comprehensive index of all public APIs available in
+  the Zuplo runtime. The APIs are organized by category for easy reference."
+---
+
+This section provides a comprehensive index of all public APIs available in the
+Zuplo runtime. The APIs are organized by category for easy reference.
+
+## Core Request/Response APIs
+
+### ZuploRequest
+
+- **Status**: Documented ([ZuploRequest](./zuplo-request.mdx))
+- **Description**: Extended Request class with additional properties for
+  parameters, query, and user data
+- **Key Features**: Type-safe parameters and query access, user authentication
+  data
+
+### ZuploContext
+
+- **Status**: Documented ([ZuploContext](./zuplo-context.mdx))
+- **Description**: Context object available in all handlers and policies
+- **Key Features**: Request ID, logging, route information, event hooks
+
+### HttpProblems
+
+- **Status**: Documented ([HttpProblems](./http-problems.mdx))
+- **Description**: Utility class for generating RFC 7807 compliant problem
+  responses
+- **Methods**: Static methods for all HTTP status codes (for example,
+  `badRequest`, `unauthorized`, `notFound`)
+
+### HttpStatusCode
+
+- **Status**: Documented ([HttpProblems](./http-problems.mdx))
+- **Description**: All standard HTTP status codes
+
+### ProblemResponseFormatter
+
+- **Status**: Documented
+  ([ProblemResponseFormatter](./problem-response-formatter.mdx))
+- **Description**: Utility class for formatting RFC 7807 compliant problem
+  responses
+- **Methods**: `format` - Formats problem details into standard responses
+
+## Handlers
+
+See the [Handlers documentation](../handlers/url-forward.mdx) for information
+about built-in request handlers.
+
+### Available Handlers
+
+- `awsLambdaHandler` - [AWS Lambda Handler](/docs/handlers/aws-lambda)
+- `mcpServerHandler` - [MCP Server Handler](/docs/handlers/mcp-server)
+- `openApiSpecHandler` - [OpenAPI Spec Handler](/docs/handlers/openapi)
+- `redirectHandler` - [Redirect Handler](/docs/handlers/redirect)
+- `urlForwardHandler` - [URL Forward Handler](/docs/handlers/url-forward)
+- `urlRewriteHandler` - [URL Rewrite Handler](/docs/handlers/url-rewrite)
+- `webSocketHandler` - [WebSocket Handler](/docs/handlers/websocket-handler)
+- Custom handlers - [Function Handler](/docs/handlers/custom-handler)
+
+## Caching APIs
+
+### ZoneCache
+
+- **Status**: Documented ([Zone Cache](./zone-cache.mdx))
+- **Description**: Key-value cache with zone-level storage
+- **Key Methods**: `get`, `put`, `delete`
+
+### MemoryZoneReadThroughCache
+
+- **Status**: Documented
+  ([Memory Zone Read Through Cache](./memory-zone-read-through-cache.mdx))
+- **Description**: In-memory cache with automatic loading
+- **Key Methods**: `get`, `put`
+
+### StreamingZoneCache
+
+- **Status**: Documented ([Streaming Zone Cache](./streaming-zone-cache.mdx))
+- **Description**: Cache for streaming responses
+- **Key Methods**: `get`, `put`, `delete`
+
+## Data Management
+
+### ContextData
+
+- **Status**: Documented ([Context Data](./context-data.mdx))
+- **Description**: Type-safe context data storage
+- **Key Methods**: `get`, `set`
+
+### BackgroundLoader
+
+- **Status**: Documented ([Background Loader](./background-loader.mdx))
+- **Description**: Background data loading with caching
+- **Key Methods**: `get`
+
+### BackgroundDispatcher
+
+- **Status**: Documented ([Background Dispatcher](./background-dispatcher.mdx))
+- **Description**: Batch processing for background tasks
+- **Key Methods**: `enqueue`
+
+## Runtime Extensions
+
+### RuntimeExtensions
+
+- **Status**: Documented ([Runtime Extensions](./runtime-extensions.mdx))
+- **Description**: API for extending runtime behavior
+- **Key Features**: Plugin support, request/response hooks, custom error
+  handling
+
+### RuntimeError
+
+- **Status**: Documented ([Runtime Errors](./runtime-errors.mdx))
+- **Description**: Base error class for runtime errors
+
+### ConfigurationError
+
+- **Status**: Documented ([Runtime Errors](./runtime-errors.mdx))
+- **Description**: Error class for configuration issues
+
+## Plugins
+
+### AuditLogPlugin
+
+- **Status**: Documented ([Audit Log](./audit-log.mdx))
+- **Description**: Comprehensive request/response logging
+- **Key Features**: Configurable request/response capture, custom output
+  providers
+
+### Logging Plugins
+
+See [Logging documentation](/docs/articles/logging.mdx) for details on logging
+plugins:
+
+- `AWSLoggingPlugin` - AWS CloudWatch logging
+- `DataDogLoggingPlugin` - Datadog logging
+- `DynaTraceLoggingPlugin` - Dynatrace logging
+- `GoogleCloudLoggingPlugin` - Google Cloud logging
+- `LokiLoggingPlugin` - Grafana Loki logging
+- `NewRelicLoggingPlugin` - New Relic logging
+- `SplunkLoggingPlugin` - Splunk logging
+- `SumoLogicLoggingPlugin` - Sumo Logic logging
+- `VMWareLogInsightLoggingPlugin` - VMware Log Insight logging
+
+### Metrics Plugins
+
+See [Metrics documentation](/docs/articles/metrics-plugins.mdx) for details on
+metrics plugins:
+
+- `DataDogMetricsPlugin` - Datadog metrics
+- `DynatraceMetricsPlugin` - Dynatrace metrics
+- `NewRelicMetricsPlugin` - New Relic metrics
+
+### Storage Plugins
+
+- `AzureBlobPlugin` - Azure Blob Storage integration
+- `AzureEventHubsRequestLoggerPlugin` - Azure Event Hubs logging
+- `HydrolixRequestLoggerPlugin` - Hydrolix data platform integration
+
+### Special Plugins
+
+- `AkamaiApiSecurityPlugin` - Akamai API security integration
+- `StripeMonetizationPlugin` - Stripe billing integration
+
+## Utility APIs
+
+### environment
+
+- **Status**: Documented ([Environment Variables](./environment.mdx))
+- **Description**: Access to environment variables
+
+### ZuploServices
+
+- **Status**: Documented ([Zuplo ID Token](./zuplo-id-token.mdx))
+- **Description**: Zuplo platform services
+
+## Types and Interfaces
+
+### RequestUser
+
+- **Status**: Documented ([Request User](./request-user.mdx))
+- **Description**: User data structure for authenticated requests
+
+### Logger
+
+- **Status**: Documented ([Logger](./logger.mdx))
+- **Description**: Structured logging interface
+
+### ContextData
+
+- **Status**: Documented ([Context Data](./context-data.mdx))
+- **Description**: Type-safe context data storage
+
+### CorsPolicyConfiguration
+
+- **Status**: Documented ([Custom CORS Policy](./custom-cors-policy.mdx))
+- **Description**: CORS policy configuration
+
+## Hooks and Events
+
+### ZuploContextHooks
+
+- **Status**: Documented ([Hooks](./hooks.mdx))
+- **Description**: Request/response lifecycle hooks
+
+---
+
+This index provides an overview of the runtime APIs available in Zuplo. For
+detailed information about each API, follow the documentation links provided.

package/docs/programmable-api/problem-response-formatter.mdx

@@ -0,0 +1,183 @@
+---
+title: ProblemResponseFormatter
+sidebar_label: ProblemResponseFormatter
+---
+
+The `ProblemResponseFormatter` class provides a way to customize the format of
+problem responses in your API. This allows you to maintain consistent error
+response formats across your API while adhering to the
+[RFC 7807 Problem Details](https://httpproblems.com/) specification.
+
+## Overview
+
+The `ProblemResponseFormatter` class works in conjunction with the
+`HttpProblems` helper to format error responses. It can be used to customize how
+problem details are serialized and presented to API consumers.
+
+## Static Methods
+
+### format
+
+Formats a problem response with the provided details.
+
+```typescript
+static format(
+  problemDetails: ProblemResponseDetails,
+  request: ZuploRequest,
+  context: ZuploContext
+): Promise<Response>
+```
+
+#### Parameters
+
+- **problemDetails**: `ProblemResponseDetails` - The problem details to format
+- **request**: `ZuploRequest` - The current request object
+- **context**: `ZuploContext` - The current context object
+
+#### Returns
+
+A `Promise<Response>` containing the formatted problem response.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import {
+  ProblemResponseFormatter,
+  ZuploRequest,
+  ZuploContext,
+} from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  try {
+    // Your handler logic
+  } catch (error) {
+    const problemDetails = {
+      type: "https://example.com/errors/validation-failed",
+      title: "Validation Failed",
+      status: 400,
+      detail: "The request body contains invalid fields",
+      instance: request.url,
+    };
+
+    return ProblemResponseFormatter.format(problemDetails, request, context);
+  }
+}
+```
+
+### Custom Error Handler
+
+```typescript
+import {
+  ProblemResponseFormatter,
+  RuntimeExtensions,
+  ProblemResponseDetails,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addErrorHandler(async (error, request, context) => {
+    // Map errors to problem details
+    const problemDetails: ProblemResponseDetails = {
+      type: "https://api.example.com/errors/internal",
+      title: "Internal Server Error",
+      status: 500,
+      detail: error.message,
+      instance: request.url,
+      // Add custom extensions
+      extensions: {
+        errorId: crypto.randomUUID(),
+        timestamp: new Date().toISOString(),
+      },
+    };
+
+    return ProblemResponseFormatter.format(problemDetails, request, context);
+  });
+}
+```
+
+## Problem Response Details Interface
+
+The `ProblemResponseDetails` interface defines the structure of problem details:
+
+```typescript
+interface ProblemResponseDetails {
+  type?: string; // URI reference for the problem type
+  title: string; // Short, human-readable summary
+  status: number; // HTTP status code
+  detail?: string; // Human-readable explanation
+  instance?: string; // URI reference for the specific occurrence
+  extensions?: Record<string, any>; // Additional problem-specific details
+}
+```
+
+## Integration with HttpProblems
+
+The `ProblemResponseFormatter` is used internally by the `HttpProblems` helper
+class. When you use `HttpProblems` methods, they utilize
+`ProblemResponseFormatter` to ensure consistent formatting:
+
+```typescript
+// This internally uses ProblemResponseFormatter
+return HttpProblems.badRequest(request, context, {
+  detail: "Invalid request parameters",
+});
+```
+
+## Custom Formatting Example
+
+You can extend problem responses with custom fields:
+
+```typescript
+import { ProblemResponseFormatter } from "@zuplo/runtime";
+
+export async function customErrorHandler(
+  error: Error,
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const problemDetails = {
+    type: "https://api.example.com/errors/business-rule",
+    title: "Business Rule Violation",
+    status: 422,
+    detail: error.message,
+    instance: request.url,
+    // Custom extensions
+    extensions: {
+      code: "BRV_001",
+      timestamp: new Date().toISOString(),
+      requestId: context.requestId,
+      supportUrl: "https://support.example.com",
+    },
+  };
+
+  return ProblemResponseFormatter.format(problemDetails, request, context);
+}
+```
+
+## Response Format
+
+The formatter produces responses in the standard Problem Details format:
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-failed",
+  "title": "Validation Failed",
+  "status": 400,
+  "detail": "The 'email' field is invalid",
+  "instance": "/api/users",
+  "code": "VAL_001",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "requestId": "req_123abc"
+}
+```
+
+## See Also
+
+- [HttpProblems](./http-problems.mdx)
+- [Runtime Extensions](./runtime-extensions.mdx)
+- [Runtime Errors](./runtime-errors.mdx) - Error handling with RuntimeError and
+  ConfigurationError