zuplo 6.67.32 → 6.68.0

package/docs/articles/troubleshooting-slow-responses.mdx

@@ -0,0 +1,301 @@
+---
+title: Troubleshooting Slow API Response Times
+sidebar_label: Troubleshooting Slow Responses
+description:
+  Diagnose and fix slow API response times through your Zuplo gateway. Covers
+  backend latency, cold starts, DNS, policy overhead, and geographic routing.
+---
+
+When API responses through your Zuplo gateway are slower than expected, a
+systematic approach helps you identify the root cause quickly. This guide walks
+you through diagnosing latency issues — whether the source is the gateway, your
+backend, the network, or something else entirely.
+
+## Understanding API Gateway Latency
+
+Every API gateway adds some processing overhead to requests. For Zuplo, this
+overhead is minimal:
+
+- **Base latency**: Approximately 20–30ms with no policies enabled
+- **Per policy**: Most policies add 1–5ms each
+- **Complex policies**: Authentication, rate limiting, or custom code that makes
+  external calls can add 5–15ms
+
+Zuplo runs at the edge across 300+ data centers worldwide, so requests are
+processed close to the caller. In many cases, edge deployment actually _reduces_
+total latency compared to routing all traffic to a single-region backend.
+
+If you're seeing response times significantly higher than your backend's
+response time plus the expected gateway overhead, something else is contributing
+to the latency. The sections below help you identify what.
+
+## Diagnostic Checklist
+
+Work through these steps in order. Each one helps narrow down the source of the
+slowness.
+
+### 1. Measure Your Backend Directly
+
+Before investigating the gateway, confirm your backend's baseline response time
+by calling it directly (bypassing Zuplo):
+
+```bash
+curl -o /dev/null -s -w "Total time: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\n" https://your-backend.example.com/endpoint
+```
+
+Record the total time and time-to-first-byte (TTFB). The gateway cannot respond
+faster than the backend — if your backend takes 2 seconds, the response through
+Zuplo takes at least 2 seconds plus gateway overhead.
+
+### 2. Measure the Same Request Through Zuplo
+
+Run the same curl command against your Zuplo endpoint:
+
+```bash
+curl -o /dev/null -s -w "Total time: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\n" -H "Authorization: Bearer YOUR_TOKEN" https://your-api.zuplo.app/endpoint
+```
+
+Compare the two results. If the difference is within 20–50ms, the gateway is
+performing normally. If the difference is hundreds of milliseconds or more,
+continue with the steps below.
+
+### 3. Check Whether the Slowness Is Consistent
+
+Run the request through Zuplo multiple times:
+
+```bash
+for i in {1..10}; do
+  curl -o /dev/null -s -w "Request $i: %{time_total}s\n" -H "Authorization: Bearer YOUR_TOKEN" https://your-api.zuplo.app/endpoint
+done
+```
+
+Look at the pattern:
+
+- **Only the first request is slow**: This likely indicates a
+  [cold start](#cold-starts).
+- **Every request is slow**: The issue is probably your backend, network path,
+  or policy configuration.
+- **Intermittent slowness**: This could be DNS resolution, backend variability,
+  or geographic routing differences.
+
+### 4. Test from Multiple Locations
+
+Your latency experience depends on where requests originate. A request from the
+same continent as your backend has a very different network path than one from
+across the globe. Use tools like
+[curl from different machines](https://www.whatsmydns.net/) or distributed
+testing services to confirm whether the slowness is location-specific.
+
+## Common Causes and Solutions
+
+### Backend Response Time
+
+The most common cause of slow responses through any API gateway is a slow
+backend. The gateway adds its processing time _on top of_ whatever the backend
+takes.
+
+**How to identify**: Compare direct backend response times with gateway response
+times. If both are slow, the issue is the backend.
+
+**Solution**: Optimize your backend endpoints. Consider using Zuplo's
+[Caching policy](../policies/caching-inbound.mdx) to cache responses for
+endpoints that don't change frequently:
+
+```json title="config/policies.json"
+{
+  "name": "my-caching-inbound-policy",
+  "policyType": "caching-inbound",
+  "handler": {
+    "export": "CachingInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "expirationSecondsTtl": 300,
+      "statusCodes": [200]
+    }
+  }
+}
+```
+
+For more fine-grained caching in custom code, use
+[ZoneCache](../programmable-api/zone-cache.mdx) to cache frequently accessed
+data like configuration or session information with low latency.
+
+### Geographic Distance Between Edge and Backend
+
+Zuplo processes requests at the edge location closest to the caller. If your
+backend is in a single region (for example, `us-east-1`), requests from users in
+Asia or Europe still need to travel to that region after reaching the nearest
+edge node.
+
+**How to identify**: Test from locations near your backend versus locations far
+from it. If latency scales with geographic distance, this is the cause.
+
+**Solutions**:
+
+- Deploy your backend in multiple regions
+- Use Zuplo's [Caching policy](../policies/caching-inbound.mdx) to serve cached
+  responses from the edge without reaching the backend
+- For internal or single-cloud traffic, consider
+  [Managed Dedicated](../dedicated/overview.mdx) deployment, which runs Zuplo
+  within your cloud provider's network for reduced latency by keeping traffic
+  within your infrastructure
+
+### DNS Resolution Delays
+
+Slow DNS resolution can add hundreds of milliseconds to request times,
+especially on the first request or when DNS records have short TTLs.
+
+**How to identify**: In the curl output, check the `time_namelookup` value. If
+it's over 100ms, DNS resolution is contributing to the latency.
+
+**Solution**: Ensure your backend's DNS records have reasonable TTL values (at
+least 60 seconds). If you're using a custom domain with Zuplo, verify the DNS
+configuration follows the [custom domains setup guide](./custom-domains.mdx).
+
+### Large Response Bodies
+
+Large response payloads take longer to transfer and serialize. A 10MB JSON
+response takes significantly longer than a 1KB response, regardless of the
+gateway.
+
+**How to identify**: Check the response body size of slow endpoints. If
+responses are consistently large (over 1MB), this may be a factor.
+
+**Solutions**:
+
+- Implement pagination in your API to return smaller response payloads
+- Use compression to reduce the size of response payloads over the network
+- Return only the fields the caller needs
+
+### Policy Execution Overhead
+
+While individual policies add minimal latency, a long chain of policies — or
+policies that make external API calls — can accumulate overhead.
+
+**How to identify**: Temporarily remove or disable policies one at a time and
+measure the response time after each change. If removing a specific policy
+significantly improves performance, that policy is the bottleneck.
+
+**Policy performance tiers**:
+
+- **Low impact (0–3ms)**: Header manipulation, simple validation, basic routing,
+  response caching (cache hits)
+- **Medium impact (3–10ms)**: API key authentication, rate limiting, request
+  logging, simple transformations
+- **Higher impact (10–20ms+)**: Large payload transformations, custom code with
+  external API calls
+
+:::tip
+
+Order your policies from least to most expensive, and use early-exit conditions
+where possible. For example, validate API keys before performing complex
+transformations. This way, unauthorized requests are rejected quickly without
+incurring the cost of downstream policies.
+
+:::
+
+### Cold Starts
+
+:::note
+
+Cold starts apply only to Zuplo's managed edge (serverless) deployment. If
+you're running Zuplo in a [Managed Dedicated](../dedicated/overview.mdx)
+environment, cold starts don't apply.
+
+:::
+
+On Zuplo's managed edge platform, the first request after a period of inactivity
+may experience a "cold start" — an additional 100–200ms of latency while a new
+worker initializes. After the first request, subsequent requests are served from
+warm workers with normal latency.
+
+**How to identify**: Only the first request (or first few requests) after a
+period of inactivity is slow. Subsequent requests are fast.
+
+**Solutions**:
+
+- **Keep-warm requests**: Send periodic synthetic requests to your API during
+  low-traffic periods to prevent workers from going cold. A simple scheduled
+  health check every few minutes is usually sufficient.
+- **Health check endpoints**: Set up a
+  [health check handler](./health-checks.mdx) and configure an external
+  monitoring service to ping it regularly. This keeps your gateway warm while
+  also monitoring availability.
+
+## Using Zuplo Observability Tools
+
+### Analytics Dashboard
+
+Zuplo's analytics dashboard provides at-a-glance visibility into your API's
+performance. Use it to:
+
+- Identify slow endpoints by reviewing request latency data
+- Filter by route, API key, or time period to isolate patterns
+- Spot error rate spikes that may correlate with latency issues
+- Track request volume trends that may indicate capacity-related slowness
+
+### Logging Integrations
+
+For deeper analysis, configure one of Zuplo's
+[logging integrations](./logging.mdx) to send request data to your preferred
+observability platform. Supported integrations include Datadog, New Relic,
+Splunk, AWS CloudWatch, Google Cloud Logging, and others.
+
+Each log entry includes the request ID (`zp-rid` header), which you can use to
+trace a specific request through the system. You can also measure and log
+execution time within custom policies to identify performance bottlenecks:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const start = Date.now();
+
+  // ... policy logic ...
+
+  const duration = Date.now() - start;
+  context.log.info(`Policy executed in ${duration}ms`);
+
+  return request;
+}
+```
+
+### Proactive Monitoring
+
+Set up [proactive monitoring](./monitoring-your-gateway.mdx) with health check
+endpoints for each backend and network configuration. Use an external monitoring
+service like Checkly, API Context, or Datadog Synthetics to continuously monitor
+response times and alert on degradation.
+
+## When to Contact Support
+
+If you've worked through the steps above and can't identify the source of
+latency, [contact Zuplo support](./support.mdx) with the following information:
+
+- **Your Zuplo project name and environment** (production, preview, etc.)
+- **The specific endpoint(s)** experiencing slow response times
+- **Curl output** showing both direct backend timing and timing through Zuplo
+  (use the curl commands from the [diagnostic checklist](#diagnostic-checklist)
+  above)
+- **Whether the issue is consistent or intermittent**, and if intermittent, any
+  patterns you've noticed (time of day, specific geographic regions, etc.)
+- **Your backend's geographic location** (cloud provider and region)
+- **The policies configured** on the affected route(s)
+
+This information helps the support team investigate efficiently and avoid
+back-and-forth diagnostic questions.
+
+## Related Resources
+
+- [Performance Testing Your API Gateway](./performance-testing.mdx) — How to
+  benchmark and compare gateway performance accurately
+- [Proactive Monitoring](./monitoring-your-gateway.mdx) — Setting up health
+  checks and monitoring for your gateway
+- [ZoneCache](../programmable-api/zone-cache.mdx) — Low-latency caching API for
+  frequently accessed data
+- [Caching Policy](../policies/caching-inbound.mdx) — Built-in response caching
+  to reduce backend load and improve response times
+- [Logging](./logging.mdx) — Configuring log integrations for observability

package/docs/articles/troubleshooting.md

@@ -0,0 +1,302 @@
+---
+title: Troubleshooting
+sidebar_label: Troubleshooting
+---
+
+This guide covers common errors you may encounter when building, deploying, and
+running your Zuplo API gateway, along with steps to diagnose and fix them.
+
+## Build errors
+
+Build errors prevent your project from compiling during deployment. The gateway
+returns a `BUILD_ERROR` when this happens.
+
+### TypeScript compilation errors
+
+Type mismatches, missing type definitions, or invalid syntax prevent the build
+from completing. Check the deployment logs for the file name, line number, and
+error description.
+
+**Fix:** Run the build locally before deploying to catch these errors early:
+
+```bash
+npx zuplo build
+```
+
+You can also add TypeScript to your project and run type checking directly:
+
+```bash
+npm install -D typescript
+npx tsc --noEmit
+```
+
+This catches type errors before you deploy and integrates with most editors for
+inline feedback.
+
+### Module resolution failures
+
+Imports that do not start with `./` or `../` and have no matching `paths`
+mapping in `tsconfig.json` fail to resolve.
+
+```ts
+// This fails if there is no paths mapping
+import { myFunction } from "modules/my-module";
+
+// Use a relative path instead
+import { myFunction } from "./modules/my-module";
+```
+
+**Fix:** Use relative paths for local modules, or configure
+`compilerOptions.paths` in your `tsconfig.json`. See
+[TypeScript Configuration](./tsconfig.mdx) for details.
+
+### Missing or incompatible packages
+
+Zuplo does not run Node.js and does not run `npm install` during deployment.
+Only npm packages that don't use native code or Node.js-specific APIs (like the
+filesystem or `child_process`) are compatible. Packages must be installed
+locally and their bundled output checked into source control.
+
+**Fix:** Install the package locally, verify it works with `zuplo dev`, and
+ensure the compiled output is committed to your repository. See
+[Node Modules](../programmable-api/node-modules.mdx) for details on package
+compatibility and limitations.
+
+### Invalid route configuration
+
+The `routes.oas.json` file contains syntax errors or references handlers and
+policies that do not exist.
+
+**Fix:** Validate that all `handler.module` and `handler.export` values in your
+route configuration match actual modules and exported functions. Check for typos
+in policy names referenced in the `policies.inbound` and `policies.outbound`
+arrays.
+
+## Deployment errors
+
+### FATAL_PROJECT_ERROR
+
+The gateway returns this error when the project has a critical configuration
+issue that prevents it from starting.
+
+**Fix:** Check the deployment logs in the Zuplo Portal for the specific error
+message. Common causes include invalid `zuplo.runtime.ts` configuration or
+broken runtime extensions.
+
+### MAIN_MOD_ERROR
+
+This error indicates that the main module failed to load at startup.
+
+**Fix:** Verify that your `zuplo.runtime.ts` file (if present) exports valid
+configuration and that all plugins are properly initialized. Check for runtime
+errors in module-level code that runs during startup.
+
+### NO_PROJECT_SET
+
+This error typically occurs in local development when trying to run a project
+that cannot build or is invalid.
+
+**Fix:** Verify that your project structure is correct and that the project
+builds successfully. See
+[Local Development Troubleshooting](./local-development-troubleshooting.mdx) for
+more details.
+
+## Runtime errors
+
+### Policy errors
+
+When a policy throws an unhandled error, the gateway returns a `500` response.
+Use `RuntimeError` or `ConfigurationError` from `@zuplo/runtime` to return
+structured error responses instead.
+
+```ts
+import { RuntimeError, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const apiKey = request.headers.get("x-api-key");
+  if (!apiKey) {
+    throw new RuntimeError("Missing API key", { status: 401 });
+  }
+  return request;
+}
+```
+
+See [Runtime Errors](../programmable-api/runtime-errors.mdx) for the full API.
+
+### Handler errors
+
+If a request handler throws an unhandled exception, the gateway returns a
+generic error response. Wrap handler logic in try/catch blocks and return
+meaningful error responses.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  try {
+    const response = await fetch("https://api.example.com/data");
+    if (!response.ok) {
+      context.log.error("Upstream request failed", {
+        status: response.status,
+      });
+      return new Response("Bad Gateway", { status: 502 });
+    }
+    return response;
+  } catch (err) {
+    context.log.error("Handler error", { error: String(err) });
+    return new Response("Internal Server Error", { status: 500 });
+  }
+}
+```
+
+### Timeout errors
+
+Requests to upstream services can time out if the backend is slow or
+unresponsive. The gateway enforces platform-level timeouts on outbound requests.
+
+**Fix:** Check that your upstream service is healthy and responding within
+acceptable timeframes. Add timeout handling in custom handlers using
+`AbortSignal.timeout()`:
+
+```ts
+const response = await fetch("https://api.example.com/data", {
+  signal: AbortSignal.timeout(5000), // 5 second timeout
+});
+```
+
+## Debugging with logs
+
+### Portal live logs
+
+The Zuplo Portal provides real-time log viewing for deployed environments.
+Navigate to your project in the portal and open the logs tab to see live request
+logs and any messages logged with `context.log`.
+
+### Using context.log
+
+The `context.log` object is available in all handlers and policies. It supports
+`debug`, `info`, `warn`, and `error` levels:
+
+```ts
+context.log.debug("Detailed debug information");
+context.log.info("Request received", { path: request.url });
+context.log.warn("Deprecated endpoint accessed");
+context.log.error("Failed to process request", { error: "Invalid input" });
+```
+
+You can also attach custom properties to all subsequent log entries for a
+request using `context.log.setLogProperties`:
+
+```ts
+context.log.setLogProperties({ customerId: "cust_123" });
+```
+
+### Log shipping
+
+For production observability, ship logs to an external provider by configuring a
+log plugin in your `zuplo.runtime.ts` file. Supported providers include AWS
+CloudWatch, Datadog, Dynatrace, Google Cloud Logging, Loki, New Relic, Splunk,
+and Sumo Logic.
+
+See [Logging](./logging.mdx) for setup instructions.
+
+## Request tracing with zp-rid
+
+Every request processed by Zuplo is assigned a unique request ID. This ID is
+returned in the `zp-rid` response header and is available in code as
+`context.requestId`.
+
+To trace a failed request:
+
+1. Copy the `zp-rid` value from the response headers.
+2. Search your log provider (Datadog, Loki, Splunk, etc.) for that `requestId`
+   value.
+3. All log entries for that request share the same `requestId`, so you can see
+   the full request lifecycle.
+
+You can also log the request ID explicitly for correlation:
+
+```ts
+context.log.info(`Processing request ${context.requestId}`);
+```
+
+Default log fields include `requestId`, `environment`, `environmentType`,
+`environmentStage`, `buildId`, and `rayId`, which you can use to filter and
+correlate across requests.
+
+## Common gotchas
+
+### Environment variables not set
+
+Environment variables are only applied on new deployments. If you change a
+variable value, you must redeploy the environment for the change to take effect.
+
+Variables return `undefined` if not set. Always validate required variables
+early:
+
+```ts
+import { environment, ConfigurationError } from "@zuplo/runtime";
+
+const apiKey = environment.API_KEY;
+if (!apiKey) {
+  throw new ConfigurationError("API_KEY environment variable is not set");
+}
+```
+
+See [Configuring Environment Variables](./environment-variables.mdx) for more
+details.
+
+### CORS misconfiguration
+
+Common CORS issues include:
+
+- **No CORS headers in response** - Verify the route has a `corsPolicy` set (not
+  `none`) and that the request `Origin` matches one of the `allowedOrigins`.
+- **Preflight returns 404** - Ensure the CORS policy is not set to `none` and
+  the request method matches a method configured on the route.
+- **Wildcard subdomain not matching** - The `*.` pattern only matches a single
+  subdomain level. `https://*.example.com` does not match
+  `https://v2.api.example.com` or `https://example.com`.
+- **Credentials not working** - Set `allowCredentials` to `true` in the CORS
+  policy.
+
+See [Configuring CORS](./cors.mdx) for the full configuration reference.
+
+### Rate limit surprises
+
+Rate limiting policies apply per-environment. Preview and development
+environments have their own rate limit counters separate from production.
+
+If requests are unexpectedly rate limited, check:
+
+- The rate limit policy configuration for the correct `requestsAllowed` and
+  `timeWindowMinutes` values.
+- Whether a per-user or per-IP rate limit is in use and the identifier is
+  resolving correctly.
+- Whether multiple rate limit policies are applied to the same route.
+
+See [Rate Limiting](../policies/rate-limit-inbound.mdx) for configuration
+details.
+
+### GET or HEAD requests with a body
+
+Sending a body with a `GET` or `HEAD` request results in a `GET_HEAD_BODY_ERROR`
+response. Some HTTP clients attach a body by default.
+
+**Fix:** Remove the request body for `GET` and `HEAD` requests, or change the
+HTTP method to `POST` or `PUT` if a body is required.
+
+## Getting help
+
+If you cannot resolve an issue using this guide:
+
+- Check the [Zuplo Errors](../errors.mdx) reference for detailed error
+  descriptions.
+- Reach out to support@zuplo.com or join the
+  [Zuplo Discord server](https://discord.gg/8QbEjr2MgZ).

package/docs/articles/tsconfig.mdx

@@ -0,0 +1,105 @@
+---
+title: TypeScript Configuration (tsconfig.json)
+sidebar_label: TypeScript Config
+---
+
+Zuplo projects use TypeScript for custom code. At the root of every project is a
+`tsconfig.json` file that specifies the configuration for the TypeScript
+compiler. This file is used by the TypeScript compiler to compile the TypeScript
+code into JavaScript.
+
+This file is automatically generated by Zuplo and shouldn't be modified. If you
+do modify the file, you will receive build warnings indicating the settings that
+have been changed.
+
+When developing in the Zuplo Portal or running the `zuplo dev` command locally,
+the build will automatically fix this file for you. If you were using
+unsupported settings, the modifications to this file may cause the build to
+fail. If this happens, we recommend that you fix your code instead of reverting
+the changes to the `tsconfig.json` file.
+
+The recommended `tsconfig.json` file is shown below.
+
+```json
+{
+  "include": ["modules/**/*", ".zuplo/**/*", "tests/**/*"],
+  "exclude": ["./node_modules", "./dist"],
+  "compilerOptions": {
+    "module": "ESNext",
+    "target": "ES2022",
+    "lib": ["ESNext", "WebWorker", "Webworker.Iterable"],
+    "preserveConstEnums": true,
+    "moduleResolution": "Bundler",
+    "useUnknownInCatchVariables": false,
+    "forceConsistentCasingInFileNames": true,
+    "importHelpers": true,
+    "removeComments": true,
+    "esModuleInterop": true,
+    "noEmit": true,
+    "strictNullChecks": true,
+    "experimentalDecorators": true
+  }
+}
+```
+
+## Updating the tsconfig.json File
+
+The `tsconfig.json` file isn't shown in the Zuplo Portal. If you need to update
+it you can do so connecting your project to
+[Source Control](./source-control.mdx) and editing the file in your source
+control provider or locally.
+
+## Troubleshooting
+
+This section contains common issues that you may encounter if you have used
+unsupported settings in the `tsconfig.json` file and are migrating to the
+recommended configuration.
+
+### Build Warning: This project's tsconfig.json wasn't set to the recommended settings. Custom settings may cause build issues.
+
+![Build Warning](../../public/media/tsconfig/image.png)
+
+This warning is shown when the `tsconfig.json` file isn't set to the recommended
+settings. If you see this warning, but your build is successful, then you aren't
+required to do anything. However, we still encourage you to update your
+`tsconfig.json` file to the recommended settings. This will ensure that your
+build continues to work in the future and that you don't encounter any issues.
+
+:::info{title="Note"}
+
+Depending on when your project was created, you might see this warning even if
+you never edited the `tsconfig.json` file. Older project templates used various
+different configurations in the tsconfig.json. This warning is just telling you
+that your settings are different from the **current** recommended settings.
+
+:::
+
+### Build Error: Couldn't resolve "modules/my-module"
+
+If you have a module that isn't being resolved and the module doesn't start with
+a path indicator like `./` or `../`, you either need to change the import to use
+the path indicator or add a `paths` setting to your `tsconfig.json` file.
+
+For example, if you have the following import:
+
+```typescript
+import { myFunction } from "modules/my-module";
+```
+
+You can either change the import to:
+
+```typescript
+import { myFunction } from "./modules/my-module";
+```
+
+Or add the `baseUrl` and `paths` setting to your `tsconfig.json` file:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "modules/*": ["./modules/*"]
+    }
+  }
+}
+```