zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/request-user.mdx

@@ -0,0 +1,289 @@
+---
+title: RequestUser
+---
+
+The `RequestUser` interface represents authenticated user information attached
+to a [ZuploRequest](./zuplo-request.mdx). This interface is used when
+authentication policies validate and identify users.
+
+## Interface
+
+```ts
+interface RequestUser<TUserData> {
+  sub: string;
+  data: TUserData;
+}
+```
+
+## Properties
+
+**`sub`**
+
+The subject identifier (unique user ID) from the authentication token.
+
+```ts
+sub: string;
+```
+
+**`data`**
+
+Additional user data of generic type `TUserData`.
+
+```ts
+data: TUserData;
+```
+
+## Usage
+
+The `user` property is available on `ZuploRequest` after successful
+authentication:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Check if user is authenticated
+  if (!request.user) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  // Access user information
+  const userId = request.user.sub;
+  const userData = request.user.data;
+
+  context.log.info("Request from user", { userId });
+
+  return new Response(`Hello, user ${userId}!`);
+}
+```
+
+## Type-Safe User Data
+
+You can define custom types for user data:
+
+```ts
+import { ZuploContext, ZuploRequest, RequestUser } from "@zuplo/runtime";
+
+// Define your user data structure
+interface MyUserData {
+  email: string;
+  roles: string[];
+  organizationId: string;
+  permissions?: string[];
+}
+
+// Use typed request
+type MyRequest = ZuploRequest<{
+  UserData: MyUserData;
+}>;
+
+export default async function handler(
+  request: MyRequest,
+  context: ZuploContext,
+) {
+  if (!request.user) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  // TypeScript knows the shape of user.data
+  const { email, roles, organizationId } = request.user.data;
+
+  if (!roles.includes("admin")) {
+    return new Response("Forbidden: Admin role required", { status: 403 });
+  }
+
+  return new Response(`Welcome admin ${email} from org ${organizationId}`);
+}
+```
+
+## Common Authentication Patterns
+
+### JWT Authentication
+
+When using JWT authentication policies, the user data typically includes claims
+from the token:
+
+```ts
+// After JWT validation
+request.user = {
+  sub: "auth0|123456789",
+  data: {
+    email: "user@example.com",
+    name: "John Doe",
+    picture: "https://example.com/avatar.jpg",
+    // Custom claims
+    organization: "acme-corp",
+    roles: ["user", "admin"],
+  },
+};
+```
+
+### API Key Authentication
+
+For API key authentication, user data might include consumer information:
+
+```ts
+// After API key validation
+request.user = {
+  // The subject of the consumer
+  sub: "consumer-id-123",
+  data: {
+    // The metadata you set when creating the consumer
+    customerId: "123",
+    plan: "premium",
+  },
+};
+```
+
+## Working with User Data
+
+### Role-Based Access Control
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface UserWithRoles {
+  roles: string[];
+  permissions?: string[];
+}
+
+export function requireRole(role: string) {
+  return async function handler(
+    request: ZuploRequest<{ UserData: UserWithRoles }>,
+    context: ZuploContext,
+  ) {
+    if (!request.user) {
+      return new Response("Unauthorized", { status: 401 });
+    }
+
+    const { roles } = request.user.data;
+
+    if (!roles.includes(role)) {
+      context.log.warn("Access denied", {
+        userId: request.user.sub,
+        requiredRole: role,
+        userRoles: roles,
+      });
+
+      return new Response(`Forbidden: ${role} role required`, {
+        status: 403,
+      });
+    }
+
+    // User has required role, continue processing
+    return null; // Continue to next handler
+  };
+}
+
+// Usage in a route
+export const adminOnly = requireRole("admin");
+```
+
+### User Context in Logging
+
+```ts
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const userContext = request.user
+    ? {
+        userId: request.user.sub,
+        userEmail: request.user.data?.email,
+        organization: request.user.data?.organizationId,
+      }
+    : { userId: "anonymous" };
+
+  context.log.info("Processing request", {
+    ...userContext,
+    path: request.url,
+    method: request.method,
+  });
+
+  try {
+    const result = await processBusinessLogic(request, request.user);
+
+    context.log.info("Request completed", {
+      ...userContext,
+      success: true,
+    });
+
+    return new Response(JSON.stringify(result));
+  } catch (error) {
+    context.log.error("Request failed", {
+      ...userContext,
+      error: error.message,
+    });
+
+    throw error;
+  }
+}
+```
+
+### Passing User to Upstream Services
+
+```ts
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  if (!request.user) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  // Forward user information to upstream service
+  const upstreamRequest = new Request(request, {
+    headers: {
+      ...Object.fromEntries(request.headers),
+      "X-User-Id": request.user.sub,
+      "X-User-Email": request.user.data.email || "",
+      "X-User-Roles": JSON.stringify(request.user.data.roles || []),
+    },
+  });
+
+  return fetch("https://api.internal.example.com", upstreamRequest);
+}
+```
+
+## Authentication Policy Integration
+
+Authentication policies automatically populate the `user` property:
+
+```ts
+// In your routes configuration
+{
+  "path": "/api/protected",
+  "methods": ["GET"],
+  "handler": {
+    "export": "default",
+    "module": "$import(./modules/protected-handler)"
+  },
+  "policies": {
+    "inbound": ["jwt-auth-policy", "rate-limit-policy"]
+  }
+}
+```
+
+After the JWT authentication policy validates the token, it sets:
+
+```ts
+request.user = {
+  sub: tokenClaims.sub,
+  data: {
+    ...tokenClaims,
+    // Additional data from policy configuration
+  },
+};
+```
+
+## See Also
+
+- [ZuploRequest](./zuplo-request.mdx) - The request object that contains user
+  information
+- [API Key Authentication](../policies/api-key-inbound.mdx) - Built-in API key
+  authentication
+- [JWT Authentication](../policies/open-id-jwt-auth-inbound.mdx) - JWT/OpenID
+  authentication

package/docs/programmable-api/reusing-code.mdx

@@ -0,0 +1,26 @@
+---
+title: Share code across request handlers and policies with modules
+sidebar_label: Code Reuse
+---
+
+Sharing code across your request handlers and policies is easy with modules.
+Simply create a new module with exports and import them to your other files.
+Here's a module called `util.ts`:
+
+```ts
+//util.ts
+export function increment(n: number) {
+  return n + 1;
+}
+```
+
+Now in our request handler, we can import this and reuse this code
+
+```ts
+import { ZuploRequest, ZuploContext } from "@zuplo/runtime";
+import { increment } from "./util";
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  return increment(1);
+}
+```

package/docs/programmable-api/route-raw.mdx

@@ -0,0 +1,55 @@
+---
+title: Route Custom Data
+---
+
+Each route in your OpenAPI file allows for specifying custom properties on your
+route that can be referenced in code. Because the OpenAPI document allows
+extensibility by adding `x-` properties, you can add custom data as needed to
+your operations and then read that data in code.
+
+## Custom Data in OpenAPI File
+
+The example below shows how to add custom data and operation with a property
+`x-custom`.
+
+```json title="/config/routes.oas.json"
+{
+  "/my-route": {
+    "get": {
+      // highlight-start
+      "x-custom": {
+        "hello": "world"
+      },
+      // highlight-end
+      "operationId": "c18da63b-bd4d-433f-a634-1da9913958c0",
+      "x-zuplo-route": {
+        "handler": {
+          "module": "$import(@zuplo/runtime)",
+          "export": "urlForwardHandler",
+          "options": {
+            "baseUrl": "https://echo.zuplo.io",
+            "forwardSearch": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Custom Data in Code
+
+Custom data can be accessed through the `context.route.raw()` function. This
+gives you full access to the underlying data of the OpenAPI operation. By
+default this function returns `unknown`, but you can pass it a custom object or
+for the full OpenAPI operation, use `OpenAPIV3_1.OperationObject` exported from
+`openapi-types`
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export async function echo(request: ZuploRequest, context: ZuploContext) {
+  const data = context.route.raw<{ "x-custom": { hello: string } }>();
+  context.log.info(`My custom data: ${data["x-custom"].hello}`);
+}
+```

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

@@ -0,0 +1,25 @@
+---
+title: Runtime Behaviors
+---
+
+Zuplo's core gateway runtime is built on
+[open web-standards](./web-standard-apis.mdx). However, there are some cases
+where Zuplo either differentiates from the standard or where the standard
+doesn't apply due to Zuplo running server-side rather than in the browser. There
+are also some behaviors that are enforced in Zuplo that may be unfamiliar to
+developers coming from other systems. This document aims to outline behaviors
+that developers may encounter and suggested ways to handle these behaviors.
+
+Because some legacy APIs may require non-standard behavior, most of these
+behaviors can be modified for your particular deployment. Contact
+support@zuplo.com to discuss options.
+
+## Request.body
+
+The [standard](https://developer.mozilla.org/en-US/docs/Web/API/Request/body)
+for `Request.body` specifies that on `GET` and `HEAD` requests the value must be
+`null`. Different APIs, networks, and gateways follow this spec to varying
+degrees. In some cases they allow in others they don't.
+
+By default, Zuplo will return a 500 error in the event that a `GET` or `HEAD`
+request has a body.

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

@@ -0,0 +1,246 @@
+---
+title: Runtime Errors
+---
+
+Zuplo provides specialized error classes for handling runtime and configuration
+errors in your API gateway.
+
+## RuntimeError
+
+The `RuntimeError` class extends the standard JavaScript `Error` class and
+provides additional functionality for including extension members in error
+responses.
+
+### Constructor
+
+```ts
+new RuntimeError(message: string, options?: ErrorOptions)
+new RuntimeError(
+  info: {
+    message: string;
+    extensionMembers?: Record<string, unknown>
+  },
+  options?: ErrorOptions
+)
+```
+
+Creates a new runtime error with optional extension data.
+
+- `message` - The error message
+- `info` - Object containing message and optional extension members
+- `options` - Standard error options (for example `cause`)
+
+### Properties
+
+**`extensionMembers`**
+
+Additional data included with the error for context and debugging.
+
+```ts
+extensionMembers?: Record<string, unknown>
+```
+
+### Example
+
+```ts
+import { RuntimeError, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  try {
+    // Some operation that might fail
+    const result = await riskyOperation();
+    return new Response(JSON.stringify(result));
+  } catch (error) {
+    // Throw a RuntimeError with additional context
+    throw new RuntimeError(
+      {
+        message: "Failed to process request",
+        extensionMembers: {
+          requestId: context.requestId,
+          operation: "riskyOperation",
+          timestamp: new Date().toISOString(),
+        },
+      },
+      { cause: error },
+    );
+  }
+}
+```
+
+## ConfigurationError
+
+The `ConfigurationError` class extends `RuntimeError` and is specifically
+designed for configuration-related errors.
+
+### Constructor
+
+```ts
+new ConfigurationError(message: string, options?: ErrorOptions)
+```
+
+Creates a new configuration error.
+
+- `message` - The error message describing the configuration issue
+- `options` - Standard error options
+
+### Example
+
+```ts
+import {
+  ConfigurationError,
+  ZuploContext,
+  ZuploRequest,
+  environment,
+} from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const apiKey = environment.EXTERNAL_API_KEY;
+
+  if (!apiKey) {
+    throw new ConfigurationError(
+      "EXTERNAL_API_KEY environment variable isn't configured",
+    );
+  }
+
+  const maxRetries = parseInt(environment.MAX_RETRIES || "3");
+
+  if (isNaN(maxRetries) || maxRetries < 1) {
+    throw new ConfigurationError("MAX_RETRIES must be a positive integer");
+  }
+
+  // Continue with properly configured values
+  return fetch("https://api.example.com", {
+    headers: { "X-API-Key": apiKey },
+  });
+}
+```
+
+## Error Handling Best Practices
+
+### 1. Use Specific Error Types
+
+```ts
+import { ConfigurationError, RuntimeError } from "@zuplo/runtime";
+
+// For configuration issues
+if (!config.isValid()) {
+  throw new ConfigurationError(
+    "Invalid configuration: missing required fields",
+  );
+}
+
+// for runtime issues
+if (response.status === 503) {
+  throw new RuntimeError({
+    message: "Service temporarily unavailable",
+    extensionMembers: {
+      retryAfter: response.headers.get("Retry-After"),
+      service: "external-api",
+    },
+  });
+}
+```
+
+### 2. Include Helpful Context
+
+```ts
+throw new RuntimeError(
+  {
+    message: "Database query failed",
+    extensionMembers: {
+      query: "SELECT * FROM users WHERE id = ?",
+      parameters: [userId],
+      errorCode: "DB_CONNECTION_TIMEOUT",
+      suggestion: "Check database connection settings",
+    },
+  },
+  { cause: originalError },
+);
+```
+
+### 3. Use Error Boundaries in Policies
+
+```ts
+import { RuntimeError, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function customPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: any,
+  policyName: string,
+) {
+  try {
+    // Policy logic here
+    return request;
+  } catch (error) {
+    // Log the error
+    context.log.error("Policy execution failed", {
+      policyName,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    // Re-throw as RuntimeError with context
+    throw new RuntimeError(
+      {
+        message: `Policy '${policyName}' failed to execute`,
+        extensionMembers: {
+          policyName,
+          originalError: error instanceof Error ? error.message : String(error),
+        },
+      },
+      { cause: error },
+    );
+  }
+}
+```
+
+## Integration with Problem Details
+
+When using [HttpProblems](./http-problems.mdx), errors can be automatically
+converted to RFC 7807 Problem Details responses:
+
+```ts
+import {
+  RuntimeError,
+  HttpProblems,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  try {
+    // Your logic here
+  } catch (error) {
+    if (error instanceof ConfigurationError) {
+      return HttpProblems.internalServerError(request, context, {
+        detail: error.message,
+        instance: `/errors/${context.requestId}`,
+      });
+    }
+
+    if (error instanceof RuntimeError && error.extensionMembers) {
+      return HttpProblems.internalServerError(request, context, {
+        detail: error.message,
+        ...error.extensionMembers,
+      });
+    }
+
+    // Default error response
+    return HttpProblems.internalServerError(request, context);
+  }
+}
+```
+
+## See Also
+
+- [HttpProblems](./http-problems.mdx) - Creating standardized error responses
+- [ZuploContext](./zuplo-context.mdx) - Context object with logging capabilities