zuplo 6.67.32 → 6.68.0

package/docs/articles/performance-testing.mdx

@@ -0,0 +1,304 @@
+---
+title: Performance Testing Your API Gateway
+sidebar_label: Performance Testing
+---
+
+<!-- vale Vale.Spelling["Blazemeter","JMeter","wrk"] = NO -->
+
+Performance testing is critical for understanding the real-world performance of
+your API when using an API gateway like Zuplo. This guide helps you create fair
+and accurate performance tests that properly measure latency and throughput.
+
+## Creating Fair Comparison Tests
+
+When evaluating API gateway performance, it's essential to ensure your tests
+accurately reflect real-world conditions and provide a fair comparison between
+direct backend calls and calls through your gateway.
+
+### Test Location Matters
+
+One of the most common mistakes in performance testing is running tests from
+within the same cloud provider network as your backend. This creates
+artificially low latency results that don't reflect real-world usage.
+
+:::warning
+
+Never run performance tests from the same cloud provider as your backend. If
+your backend runs on AWS, don't test from AWS. The same applies to GCP, Azure,
+or any other provider. If you are using a third-party tool such as K8 or
+Blazemeter, be sure to check where their test nodes are located.
+
+:::
+
+**Why this matters:** When traffic stays within a cloud provider's network,
+latency is dramatically reduced and more consistent, especially within the same
+geographical region. Intra-cloud network latency benefits from:
+
+- Dedicated high-speed interconnects between data centers
+- Optimized routing within the provider's backbone
+- Minimal network hops
+- Consistent, predictable performance with low jitter
+
+You can see real-world latency differences using tools like:
+
+- [AWS CloudPing](https://www.cloudping.co/) - Shows inter-region latency for
+  AWS
+- [Google Cloud Network Intelligence Center](https://cloud.google.com/network-intelligence-center/docs/performance-dashboard/how-to/view-google-cloud-latency) -
+  Provides detailed GCP network performance metrics
+
+The difference is stark: intra-cloud latency within the same region (for
+example, within North America) can be 50-70% lower than traffic traversing the
+public internet or between different cloud providers. Additionally, internet
+traffic experiences significantly higher jitter (variance), making response
+times less predictable.
+
+This artificial performance boost from testing within the same cloud provider
+can make it appear that an API gateway adds substantially more latency than it
+actually does in real-world scenarios where traffic crosses network boundaries.
+
+### Ensure Test Equality
+
+Fair comparisons require testing under identical conditions. Here are the key
+factors to consider:
+
+#### Authentication Methods
+
+Different authentication methods have different performance characteristics. If
+you're testing:
+
+- **Backend with IAM/JWT:** Processing time varies but is typically minimal for
+  JWT validation
+- **Zuplo with API Key authentication:** Adds approximately 5-10ms for key
+  validation
+
+To ensure fair testing, use the same authentication method for both tests, or
+account for the difference in your analysis.
+
+#### Request Parameters and Payloads
+
+Always use identical:
+
+- Request headers
+- Query parameters
+- Request body size and complexity
+- Response size expectations
+
+#### Scaling Patterns
+
+Test both your backend and gateway-fronted API with the same:
+
+- Ramp-up patterns
+- Concurrent connection counts
+- Request rates
+- Test duration
+
+### Account for Additional Layers
+
+Your architecture may include additional layers that affect performance:
+
+- **CDN (CloudFlare, Fastly, etc.):** Adds 5-15ms for cache misses
+- **WAF (Web Application Firewall):** Adds 10-20ms depending on rule complexity
+- **DDoS Protection:** Usually minimal impact (1-5ms) unless under attack
+- **Load Balancers:** Adds 1-5ms
+
+Include these layers in both test scenarios or explicitly account for their
+impact in your analysis.
+
+## Understanding Gateway Latency
+
+API gateways necessarily add some latency to process requests. For Zuplo:
+
+- **Base latency:** Approximately 20-30ms with no policies
+- **Per policy:** Most policies add 1-5ms each
+- **Complex policies:** Authentication, rate limiting, or custom code can add
+  5-15ms
+
+This latency is the trade-off for the benefits an API gateway provides:
+
+- Centralized authentication and authorization
+- Rate limiting and quota management
+- Request/response transformation
+- Analytics and monitoring
+- Developer portal and documentation
+
+## Policy Impact on Performance
+
+Different policies have varying performance impacts:
+
+### Low Impact (0-3ms)
+
+- Header manipulation
+- Simple request validation
+- Basic routing rules
+- Response caching (for cache hits)
+
+### Medium Impact (3-10ms)
+
+- API key authentication (Varies depending on cache hits/replication)
+- Rate limiting checks (0ms with asynchronous mode)
+- Request/response logging
+- Simple transformations
+
+### Higher Impact (10-20ms)
+
+- Large payload transformations
+- Custom code that makes external calls
+
+:::tip
+
+For optimal performance, order your policies from least to most expensive, and
+use early-exit conditions where possible. For example, validate API keys before
+performing complex transformations.
+
+:::
+
+## Performance Testing Best Practices
+
+### 1. Choose the Right Testing Tool
+
+Use professional load testing tools that can:
+
+- Generate consistent load patterns
+- Measure percentile latencies (p50, p95, p99)
+- Handle connection pooling properly
+- Report detailed metrics
+
+Recommended tools:
+
+- [k6](https://k6.io/) - Modern load testing tool with excellent reporting
+- [Apache JMeter](https://jmeter.apache.org/) - Comprehensive but complex
+- [Gatling](https://gatling.io/) - High-performance testing framework
+- [wrk](https://github.com/wg/wrk) - Simple but powerful for basic tests
+
+### 2. Test from Multiple Locations
+
+Run tests from various geographic locations to understand global performance:
+
+- Use cloud providers different from your backend
+- Test from regions where your users are located
+- Consider using distributed load testing services
+
+### 3. Measure the Right Metrics
+
+Focus on metrics that matter:
+
+- **Latency percentiles:** p50, p95, p99 (not just averages)
+- **Throughput:** Requests per second at various concurrency levels
+- **Error rates:** Both 4xx and 5xx responses
+- **Time to first byte (TTFB)**
+- **Total request time**
+
+### 4. Test Realistic Scenarios
+
+Design tests that reflect actual usage:
+
+- Mix of different endpoints
+- Realistic payload sizes
+- Actual authentication flows
+- Expected traffic patterns (steady, burst, ramp-up)
+
+## Interpreting Results
+
+When analyzing your performance test results:
+
+1. **Compare percentiles, not averages:** p95 and p99 latencies better represent
+   user experience
+2. **Account for geographic distribution:** Users farther from your
+   infrastructure will see higher latency
+3. **Look for anomalies:** Sudden spikes might indicate rate limiting or
+   capacity issues
+
+:::note
+
+Remember that Zuplo's edge deployment means your API is served from locations
+globally, which can actually reduce latency for geographically distributed users
+compared to a single-region backend.
+
+:::
+
+## Optimizing for Intra-Cloud Traffic
+
+If your primary use case involves API traffic that stays within a particular
+cloud provider's network, consider Zuplo's
+[Managed Dedicated deployment](/docs/dedicated/overview.mdx) options. With
+Managed Dedicated, Zuplo can be deployed directly to:
+
+- Your chosen cloud provider (AWS, GCP, Azure, etc.)
+- Your specific regions
+- Your VPC or private network configurations
+
+This deployment model provides:
+
+- **Minimal latency:** Your API gateway runs in the same cloud network as your
+  backend
+- **Predictable performance:** Consistent sub-10ms latency for intra-region
+  traffic
+- **Network isolation:** Traffic never leaves your cloud provider's backbone
+- **Compliance benefits:** Data remains within your controlled infrastructure
+
+Managed Dedicated is ideal for organizations with:
+
+- High-volume internal API traffic
+- Strict latency requirements for service-to-service communication
+- Regulatory requirements for data locality
+- Existing investments in specific cloud providers
+
+:::tip
+
+For most use cases, where API traffic comes from multiple providers, networks,
+and geographic locations (mobile apps, web applications, third-party
+integrations), Zuplo's edge-deployed instances typically provide better overall
+performance. Edge deployment ensures your API is served from locations closest
+to your users globally, reducing latency for the majority of real-world traffic
+patterns.
+
+:::
+
+## Cold Starts (Managed Edge Deployments Only)
+
+:::note
+
+This section applies only to Zuplo's managed edge (serverless) deployment. If
+you're running Zuplo in a dedicated environment, cold starts don't apply.
+
+:::
+
+Zuplo's serverless platform automatically scales to handle any load, from zero
+to billions of requests. However, the first requests after a period of
+inactivity may experience "cold starts."
+
+### Understanding Cold Starts
+
+- **Initial latency:** First request may be 100-200ms slower
+- **Node lifecycle:** Once warm, nodes can serve requests for hours or days
+- **Scaling behavior:** New nodes spin up automatically based on traffic
+
+### Testing with Cold Starts
+
+To accurately test performance:
+
+1. **Run a warm-up phase:** Send 100-1000 requests before measuring
+2. **Measure steady-state:** After warm-up, measure consistent performance
+3. **Test scaling:** Gradually increase load to observe scaling behavior
+4. **Account for real-world patterns:** Most production APIs stay warm during
+   business hours
+
+:::tip
+
+For APIs with predictable traffic patterns, consider implementing a simple
+keep-warm strategy using scheduled synthetic requests during low-traffic
+periods.
+
+:::
+
+## Summary
+
+Creating fair performance tests requires careful attention to test conditions,
+understanding of network topology, and realistic expectations about API gateway
+overhead. By following these guidelines, you'll get accurate measurements that
+help you make informed decisions about your API architecture.
+
+Remember: Zuplo typically adds only 20-30ms of latency for basic request
+processing, with additional small increments for some policies. This overhead is
+often offset by the operational benefits and can even result in better global
+performance due to edge deployment.

package/docs/articles/plugin-akamai-api-security.mdx

@@ -0,0 +1,76 @@
+---
+title: Akamai API Security (AKA NONAME) plugin
+sidebar_label: Akamai API Security
+---
+
+This plugin pushes request/response data to Akamai API Security, formerly known
+as "NONAME" API Security. It can also pull data from Akamai API Security to
+actively block traffic based on the blocklist rules provided by Akamai API
+Security; known as "Protection".
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+To get started, you'll need to configure the Zuplo Integration in Akamai API
+Security. Once this step is completed you'll have a 'key' to allow us to connect
+to Akamai API Security on your behalf.
+
+In Zuplo you configure the plugin in the
+[Runtime Extensions](../programmable-api/runtime-extensions.mdx) file
+`zuplo.runtime.ts`, as follows:
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  environment,
+  AkamaiApiSecurityPlugin,
+  RuntimeExtensions,
+  ZuploContext,
+  ZuploRequest,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new AkamaiApiSecurityPlugin({
+      hostname: "your-akamai-api-security-hostname.com",
+      // index, provided by Akamai API Security
+      index: 1,
+      // Key provided by Akamai API Security
+      key: environment.AKAMAI_API_SECURITY_KEY,
+      // Enable the active prevention/protection feature
+      enableProtection: true,
+    }),
+  );
+}
+```
+
+It's recommended to store your key in an
+[Environment Variable](./environment-variables.mdx) shown in the example above
+`AKAMAI_API_SECURITY_KEY`. If you want the active protection feature enabled,
+set `enableProtection` to `true`.
+
+The plugin also supports an optional `shouldLog` parameter which is a function
+that returns true or false and, if false, stops the request/response from
+logging to Akamai API Security.
+
+```ts
+runtime.addPlugin(
+  new AkamaiApiSecurityPlugin({
+    hostname: "your-akamai-api-security-hostname.com",
+    // index, provided by Akamai API Security
+    index: 1,
+    // Key provided by Akamai API Security
+    key: environment.AKAMAI_API_SECURITY_KEY,
+    // Enable the active prevention/protection feature
+    enableProtection: true,
+    // optional filter function to exclude requests
+    shouldLog: async (request: ZuploRequest, context: ZuploContext) => {
+      if (request.headers.get("content-type") !== "application/json") {
+        return false;
+      }
+
+      return true;
+    },
+  }),
+);
+```

package/docs/articles/plugin-azure-blob.mdx

@@ -0,0 +1,73 @@
+---
+title: Azure Blob Plugin
+sidebar_label: Azure Blob
+---
+
+This plugin pushes request/response logs to Azure Blob Storage. This can be used
+to save request data generated by your API Gateway to use for monitoring,
+analytics, auditing, or debugging purposes.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+You can define the fields created in the CSV by creating a custom type in
+TypeScript and a function to extract the field data from the `Response`,
+`ZuploRequest`, and `ZuploContext`.
+
+The plugin is configured in the
+[Runtime Extensions](../programmable-api/runtime-extensions.mdx) file
+`zuplo.runtime.ts`:
+
+```ts title="modules/zuplo.runtime.ts"
+// The interface that describes the rows
+// in the output
+interface AzureBlobLogEntry {
+  timestamp: string;
+  method: string;
+  url: string;
+  status: number;
+  statusText: string;
+  sub: string | null;
+  contentLength: string | null;
+}
+
+// Add the plugin - use a SAS URL
+runtime.addPlugin(
+  new AzureBlobPlugin<AzureBlobLogEntry>({
+    sasUrl:
+      "https://YOUR_ACCOUNT.blob.core.windows.net/YOUR_CONTAINER?sv=2022-11-02&ss=b&srt=co&sp=wactfx&se=2045-11-17T13:50:53Z&st=2024-11-17T05:50:53Z&spr=https&sig=YOUR_SIG",
+    batchPeriodSeconds: 1,
+    generateLogEntry: (
+      response: Response,
+      request: ZuploRequest,
+      context: ZuploContext,
+    ) => ({
+      // You can customize the log entry here by adding new fields
+      timestamp: new Date().toISOString(),
+      url: request.url,
+      method: request.method,
+      status: response.status,
+      statusText: response.statusText,
+      sub: request.user?.sub ?? null,
+      contentLength: request.headers.get("content-length"),
+    }),
+  }),
+);
+```
+
+The plugin writes Block Blobs using SAS signatures. Ensure that your SAS URL has
+the correct structure and contains the container name, and the SAS has the
+appropriate permissions.
+
+## Writing the response or request
+
+Writing the full request or response body can be expensive but is supported.
+Alternatively, you may want to parse the body for a particular property to log,
+in this case it's important that the request or response is cloned so that the
+stream is available for the response.
+
+Also, note that the `generateLogEntry` function will be called **after** the
+request stream has been read. So if you need to read the request, you will need
+to store the cloned response before it reaches the request handler and store it,
+ideally using [ContextData](../programmable-api/context-data.mdx).

package/docs/articles/plugin-azure-event-hubs.mdx

@@ -0,0 +1,64 @@
+---
+title: Azure Event Hubs Request Logger Plugin
+sidebar_label: Azure Event Hubs
+---
+
+This plugin pushes request/response logs to Azure Event Hubs. This can be used
+to stream the request data generated by your API Gateway to use for monitoring,
+analytics, auditing, or debugging purposes.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+You can define the fields created in the JSON object by creating a custom type
+in TypeScript and a function to extract the field data from the `Response`,
+`ZuploRequest`, and `ZuploContext`.
+
+The plugin is configured in the
+[Runtime Extensions](../programmable-api/runtime-extensions.mdx) file
+`zuplo.runtime.ts`: git sta
+
+```ts title="modules/zuplo.runtime.ts"
+// The interface that describes the rows
+// in the output
+interface LogEntry {
+  timestamp: string;
+  method: string;
+  url: string;
+  status: number;
+  statusText: string;
+  sub: string | null;
+  contentLength: string | null;
+}
+
+// Add the plugin
+runtime.addPlugin(
+  new AzureEventHubsRequestLoggerPlugin<LogEntry>({
+    connectionString: environment.AZURE_EVENT_HUBS_CONNECTION_STRING,
+    // for example "Endpoint=sb://your-namespace.servicebus.windows.net/;SharedAccessKeyName=key-name;SharedAccessKey=YOUR_SHARED_ACCESS_KEY"
+    batchPeriodSeconds: 1,
+    entityPath: "your-event-hub-name",
+    generateLogEntry: (response: Response, request: ZuploRequest) => ({
+      // You can customize the log entry here by adding new fields
+      timestamp: new Date().toISOString(),
+      url: request.url,
+      method: request.method,
+      status: response.status,
+      statusText: response.statusText,
+      sub: request.user?.sub ?? null,
+      contentLength: request.headers.get("content-length"),
+    }),
+  }),
+);
+```
+
+The configuration requires a `connectionString` which you can get from the Azure
+portal "Shared access policies" section in Event Hubs. If the connection string
+contains an EntityPath property the separate `entityPath` option to define the
+event hub's name isn't required.
+
+Entries will be batched and sent as an array, they will be sent every
+`batchPeriodSeconds`. If not specified it will be sent very frequently (~every
+10ms) to avoid data loss. Note that `batchPeriodSeconds` can be specified as a
+fraction, for example `0.1` for every 100ms.

package/docs/articles/plugin-hydrolix-traffic-peak.mdx

@@ -0,0 +1,147 @@
+---
+title: Hydrolix / Akamai Traffic Peak Plugin
+sidebar_label: Hydrolix / Traffic Peak
+---
+
+This plugin pushes request/response logs to Hydrolix AKA Akamai Traffic Peak.
+
+<EnterpriseFeature name="Custom logging" />
+
+## Setup
+
+You can define the fields created in the JSON object by creating a custom type
+in TypeScript and a function to extract the field data from the `Response`,
+`ZuploRequest`, and `ZuploContext`.
+
+The plugin is configured in the
+[Runtime Extensions](../programmable-api/runtime-extensions.mdx) file
+`zuplo.runtime.ts`:
+
+This logger includes a default type and function that logs the following fields:
+
+- **deploymentName** <CodeType>string</CodeType> - The name of the deployment.
+- **timestamp** <CodeType>string</CodeType> - The time the log was created.
+- **requestId** <CodeType>string</CodeType> - The UUID of the request (the value
+  of the `zp-rid` header).
+- **routePath** <CodeType>string</CodeType> - The path of the route.
+- **operationId** <CodeType>string | undefined</CodeType> - The operation ID.
+- **url** <CodeType>string | undefined</CodeType> - The URL of the request.
+- **statusCode** <CodeType>number | undefined</CodeType> - The status code of
+  the response.
+- **durationMs** <CodeType>number | undefined</CodeType> - The duration of the
+  request in milliseconds.
+- **method** <CodeType>string</CodeType> - The HTTP method of the request.
+- **userSub** <CodeType>string | undefined</CodeType> - The user sub.
+- **instanceId** <CodeType>string | undefined</CodeType> - The instance ID.
+- **colo** <CodeType>string | undefined</CodeType> - The data center of the
+  request.
+- **city** <CodeType>string | undefined</CodeType> - The city the request
+  origin.
+- **country** <CodeType>string | undefined</CodeType> - The country the request
+  origin.
+- **continent** <CodeType>string | undefined</CodeType> - The continent the
+  request origin.
+- **latitude** <CodeType>string | undefined</CodeType> - The latitude of the
+  request origin.
+- **longitude** <CodeType>string | undefined</CodeType> - The longitude of the
+  request origin.
+- **postalCode** <CodeType>string | undefined</CodeType> - The postal code of
+  the request origin.
+- **metroCode** <CodeType>string | undefined</CodeType> - The metro code of the
+  request origin.
+- **region** <CodeType>string | undefined</CodeType> - The region of the request
+  origin.
+- **regionCode** <CodeType>string | undefined</CodeType> - The region code of
+  the request origin.
+- **timezone** <CodeType>string | undefined</CodeType> - The timezone of the
+  request origin.
+- **asn** <CodeType>string | undefined</CodeType> - The ASN of the request
+  origin.
+- **asOrganization** <CodeType>string | undefined</CodeType> - The AS
+  organization of the request origin.
+- **clientIP** <CodeType>string | undefined</CodeType> - The client IP of the
+  requester.
+- **zuploUserAgent** <CodeType>string | undefined</CodeType> - The Zuplo user
+  agent.
+
+To use this default setup add the following code to your `zuplo.runtime.ts`
+file:
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  defaultGenerateHydrolixEntry,
+  environment,
+  HydrolixDefaultEntry,
+  HydrolixRequestLoggerPlugin,
+  RuntimeExtensions,
+} from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new HydrolixRequestLoggerPlugin<HydrolixDefaultEntry>({
+      hostname: "your-hydrolix-hostname.com",
+      username: "your-hydrolix-username",
+      password: environment.HYDROLIX_PASSWORD,
+      token: environment.HYDROLIX_TOKEN,
+      table: "your-table.name",
+      transform: "your-transform-name",
+      generateLogEntry: defaultGenerateHydrolixEntry,
+    }),
+  );
+}
+```
+
+Note, the `token` (HYDROLIX_TOKEN above) is a
+[Streaming Auth Token](https://docs.hydrolix.io/docs/stream-authentication).
+
+If you want to customize the data written to Hydrolix, you can define the fields
+and entry generation function yourself as follows:
+
+```ts title="modules/zuplo.runtime.ts"
+import {
+  ZuploRequest,
+  HydrolixRequestLoggerPlugin,
+  environment,
+} from "@zuplo/runtime";
+
+// The interface that describes the rows
+// in the output
+interface LogEntry {
+  timestamp: string;
+  method: string;
+  url: string;
+  status: number;
+  statusText: string;
+  sub: string | null;
+  contentLength: string | null;
+}
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new HydrolixRequestLoggerPlugin<LogEntry>({
+      hostname: "your-hydrolix-hostname.com",
+      username: "your-hydrolix-username",
+      password: environment.HYDROLIX_PASSWORD,
+      token: environment.HYDROLIX_TOKEN,
+      table: "your-table.name",
+      transform: "your-transform-name",
+      batchPeriodSeconds: 0.1,
+      generateLogEntry: (response: Response, request: ZuploRequest) => ({
+        // You can customize the log entry here by adding new fields
+        timestamp: new Date().toISOString(),
+        url: request.url,
+        method: request.method,
+        status: response.status,
+        statusText: response.statusText,
+        sub: request.user?.sub ?? null,
+        contentLength: request.headers.get("content-length"),
+      }),
+    }),
+  );
+}
+```
+
+Entries will be batched and sent as an array, they will be sent every
+`batchPeriodSeconds`. If not specified the will be dispatched very frequently
+(~every 10ms) to avoid data loss. Note that `batchPeriodSeconds` can be
+specified as a fraction, for example `0.1` for every 100ms.

package/docs/articles/policies.mdx

@@ -0,0 +1,33 @@
+---
+title: Policy Fundamentals
+---
+
+Policies are modules that can intercept an incoming request or outgoing
+response. You can have multiple policies and apply them to multiple routes.
+There are built-in policies but of course, being a developer-focused platform
+you can easily create custom policies.
+
+## How policies work
+
+![How Policies Work](../../public/media/policies/103f37f8-9801-4f37-8962-d516b9e12fbd.png)
+
+An `inbound` policy can intercept a request and modify the request before it
+reaches the request handler (or the next policy). It can also short-circuit the
+whole request lifecycle and immediately respond to the client.
+
+An `outbound` policy intercepts the response from your request handler, allowing
+you to transform your response, or return a new one entirely.
+
+## Built-In Policies
+
+Zuplo includes many built-in policies that make it easy to handle things like
+authentication, validation, and request modification.
+
+Explore the navigation to see all of the built-in policies.
+
+## Custom Policies
+
+The ability to write custom policies that run in-process of your Gateway is at
+the core of what makes Zuplo the Programmable API Gateway. You can write
+policies to handle virtually any task. To learn more about
+[writing custom policies see the documentation](../policies/custom-code-inbound.mdx).