zuplo 6.67.32 → 6.68.0

package/docs/programmable-api/hooks.mdx

@@ -0,0 +1,569 @@
+---
+title: Request/Response Hooks
+sidebar_label: Hooks
+---
+
+Hooks allow you to run code at specific points in the request/response pipeline.
+They're accessible through the [ZuploContext](./zuplo-context.mdx) object and
+are commonly used for cross-cutting concerns like logging, tracing, and
+monitoring.
+
+:::tip
+
+All hooks can be either synchronous or asynchronous. To make your hook
+asynchronous, simply add the `async` keyword to the function.
+
+:::
+
+## Available Hooks
+
+Zuplo provides several hooks for different stages of the request/response
+pipeline:
+
+### Request Pipeline Hooks
+
+- **`addPreRoutingHook`** - Executes before route matching, can modify the
+  request URL or headers
+- **`addRequestHook`** - Executes after route matching but before handlers, can
+  return early responses
+
+### Response Pipeline Hooks
+
+- **`addResponseSendingHook`** - Executes before the response is sent and can
+  modify it
+- **`addResponseSendingFinalHook`** - Executes after all processing but can't
+  modify the response
+
+### Hook Types
+
+```ts
+// Pre-routing hook (available globally via runtime.addPreRoutingHook)
+interface PreRoutingHook {
+  (request: Request): Promise<Request> | Request;
+}
+
+// Request hook (available globally and per-context)
+interface OnRequestHook {
+  (
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<ZuploRequest | Response> | (ZuploRequest | Response);
+}
+
+// Response hooks (available globally and per-context)
+interface OnResponseSendingHook {
+  (
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<Response> | Response;
+}
+
+interface OnResponseSendingFinalHook {
+  (
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ): Promise<void> | void;
+}
+```
+
+## Hook: OnResponseSending
+
+The `addResponseSendingHook` method adds a hook that fires just before the
+response is sent to the client. This hook can modify the response by returning a
+new `Response` object. Multiple hooks execute in the order they were added.
+
+### Method Signature
+
+```ts
+context.addResponseSendingHook(
+  (response: Response, request: Request, context: ZuploContext) =>
+    Response | Promise<Response>,
+);
+```
+
+### Example: Adding Response Headers
+
+```ts
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.addResponseSendingHook(async (response, request) => {
+    // Add custom headers to all responses
+    response.headers.set("X-Request-ID", context.requestId);
+    response.headers.set(
+      "X-Processing-Time",
+      `${Date.now() - context.custom.startTime}ms`,
+    );
+
+    // Log response details
+    context.log.info({
+      status: response.status,
+      contentType: response.headers.get("content-type"),
+    });
+
+    return response;
+  });
+
+  return fetch(request);
+}
+```
+
+### Example: Tracing Policy
+
+This example shows a tracing policy that ensures trace headers are consistent
+between requests and responses:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export async function tracingPlugin(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+) {
+  // Get the trace header
+  let traceparent = request.headers.get("traceparent");
+
+  // If not set, add the header to the request
+  if (!traceparent) {
+    traceparent = crypto.randomUUID();
+    const headers = new Headers(request.headers);
+    headers.set("traceparent", traceparent);
+    return new ZuploRequest(request, { headers });
+  }
+
+  context.addResponseSendingHook((response, latestRequest, context) => {
+    // If the response doesn't have the trace header that matches, set it
+    if (response.headers.get("traceparent") !== traceparent) {
+      const headers = new Headers(response.headers);
+      headers.set("traceparent", traceparent);
+      return new Response(response.body, {
+        headers,
+      });
+    }
+    return response;
+  });
+
+  return request;
+}
+```
+
+## Hook: OnResponseSendingFinal
+
+The `addResponseSendingFinalHook` method adds a hook that fires immediately
+before the response is sent to the client. Unlike `OnResponseSending`, this hook
+can't modify the response - it's immutable at this point. This hook is ideal for
+logging, analytics, and monitoring tasks.
+
+### Method Signature
+
+```ts
+context.addResponseSendingFinalHook(
+  (response: Response, request: Request, context: ZuploContext) => void | Promise<void>
+)
+```
+
+### Example: Request Duration Logging
+
+This example logs the total request processing time:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const start = Date.now();
+
+  context.addResponseSendingFinalHook(async (response, latestRequest) => {
+    const end = Date.now();
+    const delta = end - start;
+    context.log.debug(`Request took ${delta}ms`);
+  });
+
+  return fetch(request);
+}
+```
+
+### Example: Asynchronous Analytics
+
+This hook can block the response. To run asynchronous tasks without blocking,
+use `context.waitUntil()` to ensure your async work completes after the response
+is sent:
+
+```ts
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Clone request before it's consumed by the handler
+  const requestClone = request.clone();
+
+  context.addResponseSendingFinalHook(async (response, latestRequest) => {
+    // Clone response to read the body without consuming it
+    const responseClone = response.clone();
+
+    const asyncAnalytics = async () => {
+      const requestBody = await requestClone.text();
+      const responseBody = await responseClone.text();
+
+      await fetch("https://analytics.example.com/log", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          requestId: context.requestId,
+          requestBody,
+          responseBody,
+          status: response.status,
+          timestamp: new Date().toISOString(),
+        }),
+      });
+    };
+
+    // Don't block the response
+    context.waitUntil(asyncAnalytics());
+  });
+
+  return fetch(request);
+}
+```
+
+## Best Practices
+
+### 1. Order Matters
+
+Hooks execute in the order they're added. Plan your hook order carefully:
+
+```ts
+// First hook adds authentication info
+context.addResponseSendingHook((response) => {
+  response.headers.set("X-User-ID", request.user?.sub || "anonymous");
+  return response;
+});
+
+// Second hook adds timing (sees the user header)
+context.addResponseSendingHook((response) => {
+  response.headers.set("X-Processing-Time", `${Date.now() - start}ms`);
+  return response;
+});
+```
+
+### 2. Clone Before Reading
+
+Always clone requests and responses before reading their bodies:
+
+```ts
+// ❌ Bad - consumes the original body
+const body = await response.text();
+
+// ✅ Good - preserves the original
+const clone = response.clone();
+const body = await clone.text();
+```
+
+### 3. Use `waitUntil` for Asynchronous Work
+
+For operations that shouldn't block the response:
+
+```ts
+context.addResponseSendingFinalHook((response) => {
+  const asyncWork = async () => {
+    // Long-running operation
+    await sendToAnalytics(response);
+  };
+
+  context.waitUntil(asyncWork());
+});
+```
+
+### 4. Handle Errors Gracefully
+
+Always handle errors in hooks to prevent response failures:
+
+```ts
+context.addResponseSendingHook(async (response) => {
+  try {
+    // Hook logic
+    response.headers.set("X-Custom", "value");
+  } catch (error) {
+    context.log.error("Hook failed", error);
+    // Return original response on error
+  }
+  return response;
+});
+```
+
+## Hook Registration
+
+Hooks can be registered in two ways:
+
+1. **In Handlers or Policies** - Add hooks directly in your code using
+   `context.addResponseSendingHook()` or `context.addResponseSendingFinalHook()`
+
+2. **Globally via Runtime Extensions** - Register hooks that apply to all
+   requests using [Runtime Extensions](./runtime-extensions.mdx)
+
+## Complete Hook Pipeline Example
+
+This example demonstrates how all hooks work together in a request/response
+lifecycle:
+
+```ts
+// In zuplo.runtime.ts - Global hooks
+import { RuntimeExtensions } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  // 1. Pre-routing hook - runs before route matching
+  runtime.addPreRoutingHook((request) => {
+    console.log("Pre-routing: Processing request", request.url);
+
+    // Normalize URL to lowercase
+    const url = new URL(request.url);
+    if (url.pathname !== url.pathname.toLowerCase()) {
+      url.pathname = url.pathname.toLowerCase();
+      return new Request(url.toString(), request);
+    }
+    return request;
+  });
+
+  // 2. Request hook - runs after routing but before handlers
+  runtime.addRequestHook(async (request, context) => {
+    console.log("Request hook: Adding correlation ID");
+
+    const correlationId = crypto.randomUUID();
+    context.custom.startTime = Date.now();
+    context.custom.correlationId = correlationId;
+
+    const headers = new Headers(request.headers);
+    headers.set("X-Correlation-ID", correlationId);
+
+    return new ZuploRequest(request, { headers });
+  });
+
+  // 3. Response sending hook - can modify response
+  runtime.addResponseSendingHook((response, request, context) => {
+    console.log("Response sending: Adding security headers");
+
+    const headers = new Headers(response.headers);
+    headers.set("X-Content-Type-Options", "nosniff");
+    headers.set("X-Frame-Options", "DENY");
+    headers.set("X-Correlation-ID", context.custom.correlationId);
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  });
+
+  // 4. Response sending final hook - for logging/analytics only
+  runtime.addResponseSendingFinalHook(async (response, request, context) => {
+    const duration = Date.now() - context.custom.startTime;
+    console.log(
+      `Request completed in ${duration}ms with status ${response.status}`,
+    );
+
+    // Non-blocking analytics
+    const sendAnalytics = async () => {
+      await fetch("https://analytics.example.com/track", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          correlationId: context.custom.correlationId,
+          method: request.method,
+          path: new URL(request.url).pathname,
+          status: response.status,
+          duration,
+          timestamp: new Date().toISOString(),
+        }),
+      });
+    };
+
+    context.waitUntil(sendAnalytics());
+  });
+}
+```
+
+```ts
+// In a handler - Local hooks that augment global ones
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  // Handler-specific response hook
+  context.addResponseSendingHook(async (response, request, context) => {
+    // Add handler-specific headers
+    const headers = new Headers(response.headers);
+    headers.set("X-Handler", "custom-api");
+    headers.set("X-Processing-Node", environment.REGION || "unknown");
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  });
+
+  // Your handler logic
+  const result = await processApiRequest(request);
+  return new Response(JSON.stringify(result), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+```
+
+### Hook Execution Order
+
+1. **Pre-routing hooks** (global only) - before route matching
+2. **Request hooks** (global first, then handler-specific) - after route
+   matching
+3. Handler execution
+4. **Response sending hooks** (global first, then handler-specific) - can modify
+   response
+5. **Response sending final hooks** (global first, then handler-specific) -
+   read-only
+
+## Creating Custom Plugins with Hooks
+
+You can create reusable plugins that register hooks automatically:
+
+```ts
+// In modules/custom-observability-plugin.ts
+import {
+  SystemRuntimePlugin,
+  RuntimeExtensions,
+  ZuploRequest,
+  ZuploContext,
+} from "@zuplo/runtime";
+
+interface ObservabilityOptions {
+  metricsEndpoint: string;
+  apiKey: string;
+  enableTracing?: boolean;
+}
+
+export class CustomObservabilityPlugin extends SystemRuntimePlugin {
+  constructor(private options: ObservabilityOptions) {
+    super();
+  }
+
+  async initialize(runtime: RuntimeExtensions): Promise<void> {
+    // Add correlation ID to all requests
+    runtime.addRequestHook(this.addCorrelationId.bind(this));
+
+    // Add trace headers to responses
+    if (this.options.enableTracing) {
+      runtime.addResponseSendingHook(this.addTraceHeaders.bind(this));
+    }
+
+    // Send metrics after each request
+    runtime.addResponseSendingFinalHook(this.sendMetrics.bind(this));
+  }
+
+  private addCorrelationId(request: ZuploRequest, context: ZuploContext) {
+    const correlationId =
+      request.headers.get("x-correlation-id") || crypto.randomUUID();
+
+    context.custom.correlationId = correlationId;
+    context.custom.startTime = Date.now();
+
+    if (!request.headers.get("x-correlation-id")) {
+      const headers = new Headers(request.headers);
+      headers.set("x-correlation-id", correlationId);
+      return new ZuploRequest(request, { headers });
+    }
+
+    return request;
+  }
+
+  private addTraceHeaders(
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ) {
+    const headers = new Headers(response.headers);
+    headers.set("x-correlation-id", context.custom.correlationId);
+    headers.set("x-trace-id", context.requestId);
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
+  private async sendMetrics(
+    response: Response,
+    request: ZuploRequest,
+    context: ZuploContext,
+  ) {
+    const duration = Date.now() - context.custom.startTime;
+
+    const metrics = {
+      timestamp: new Date().toISOString(),
+      correlationId: context.custom.correlationId,
+      method: request.method,
+      path: new URL(request.url).pathname,
+      status: response.status,
+      duration,
+      userAgent: request.headers.get("user-agent"),
+      contentLength: response.headers.get("content-length"),
+    };
+
+    // Send asynchronously to avoid blocking response
+    const sendToMetrics = async () => {
+      try {
+        await fetch(this.options.metricsEndpoint, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.options.apiKey}`,
+          },
+          body: JSON.stringify(metrics),
+        });
+      } catch (error) {
+        context.log.error("Failed to send metrics", error);
+      }
+    };
+
+    context.waitUntil(sendToMetrics());
+  }
+}
+```
+
+```ts
+// In zuplo.runtime.ts - Register the plugin
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+import { CustomObservabilityPlugin } from "./modules/custom-observability-plugin";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  const observabilityPlugin = new CustomObservabilityPlugin({
+    metricsEndpoint: "https://metrics.example.com/api/events",
+    apiKey: environment.METRICS_API_KEY,
+    enableTracing: true,
+  });
+
+  runtime.addPlugin(observabilityPlugin);
+}
+```
+
+This plugin demonstrates:
+
+- **Reusable functionality** encapsulated in a plugin class
+- **Multiple hook types** working together (request, response sending, response
+  final)
+- **Configurable behavior** through constructor options
+- **Error handling** and **non-blocking operations** with `waitUntil`
+- **Context data sharing** between hooks
+
+## See Also
+
+- [ZuploContext](./zuplo-context.mdx) - The context object that provides hook
+  methods
+- [Runtime Extensions](./runtime-extensions.mdx) - Global hook registration
+- [waitUntil](./zuplo-context.mdx#waituntil) - Extending request lifetime for
+  asynchronous operations