zuplo 6.67.32 → 6.68.0

package/docs/articles/openapi.mdx

@@ -0,0 +1,130 @@
+---
+title: OpenAPI Support in Zuplo
+sidebar_label: OpenAPI
+---
+
+Zuplo natively supports the OpenAPI 3.1 (and is compatible with 3.0)
+specification standard as the core way to configure the gateway.
+
+When you create a new project you will see a `routes.oas.json` file. This is
+your default OpenAPI routing file. The file extension `.oas.json` indicates that
+this is an OpenAPI document used for routing.
+
+![routes.oas.json](../../public/media/open-api/image.png)
+
+You can use the Route Designer to build your routes, which will be creating an
+OpenAPI document in the background for you (check it out in the **JSON View**).
+
+You can also **import an OpenAPI** document by clicking the **Open API** tab.
+
+![Import Open API](../../public/media/open-api/image-1.png)
+
+This will merge your imported file with any routes you already have in your
+.oas.json file. By default, operations will be merged by path & method - but you
+can choose to merge on `operationId` instead if you prefer.
+
+## OpenAPI Workflow
+
+Having a source of truth when embracing design-first and OpenAPI is critical.
+Zuplo offers the best workflow for OpenAPI friendly businesses because its
+support for OpenAPI is native.
+
+You can start your OpenAPI document in Zuplo and export that to other sources,
+or you can generate your OpenAPI elsewhere (by hand, using
+[stoplight.io](https://stoplight.io), etc.) and sync your changes into Zuplo
+using our import feature.
+
+The import feature will merge changes from an external source-of-truth OpenAPI
+document and will keep your Zuplo settings intact, while overwriting everything
+else from your imported OpenAPI docs. This creates a great workflow, whatever
+toolset you use.
+
+![Import OpenAPI dialog](../../public/media/open-api/28512107-8c41-4974-8319-c9ec50734331.png)
+
+What's more, you can now have more confidence that your OpenAPI represents the
+truth of your API implementation - because it now drives the configuration of
+your gateway.
+
+## Zuplo extensions
+
+Zuplo extends the OpenAPI spec using **vendor extensions**. You will see two
+vendor extensions:
+
+### x-zuplo-path
+
+`x-zuplo-path` is used to specify the type of
+[path matching mode](./routing.mdx) you want to use; **open-api** is the default
+and uses the standard OpenAPI slugs for tokens (for example `/pizza/{size}`).
+You can change the `pathMode` to `url-pattern` to use the web standards
+[URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern)
+approach to path matching which is much more powerful and supports regular
+expressions.
+
+This extension is defined below the **path** property:
+
+```json
+"paths": {
+    "/path-0": {
+        "x-zuplo-path": {
+            "pathMode": "url-pattern"
+        },
+    }
+}
+```
+
+### x-zuplo-route
+
+`x-zuplo-route` is where all of your route settings are configured, including
+[policies](/docs/policies), [handlers](/docs/handlers/openapi.mdx),
+[CORS](../programmable-api/custom-cors-policy.mdx) and more.
+
+This extension is defined inside the operation, below the method:
+
+```json
+"get": {
+    "summary": "New Route",
+    "description": "Lorem ipsum dolor sit amet, **consectetur adipiscing** elit, sed do `eiusmod tempor` incididunt ut labore et dolore magna aliqua.",
+    "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+                "baseUrl": "https://echo.zuplo.io"
+            }
+        },
+        "policies": {
+            "inbound": []
+        }
+    },
+    "operationId": "e73d0713-b894-494d-8796-2c50b8634d47"
+}
+```
+
+## Other Supported Extensions
+
+Zuplo also supports other popular extensions in order to better integrate with
+your existing tooling.
+
+### x-internal
+
+```json
+"get": {
+    "summary": "Internal Route",
+    "x-internal": true,
+    "x-zuplo-route": {
+        //...
+    },
+}
+```
+
+You can set this property to `true` in order to hide a route from the Developer
+Portal. If you are using the [OpenAPI Spec Handler](../handlers/openapi.mdx),
+internal routes won't be present in the generated OpenAPI file.
+
+## Multiple File Support
+
+You can have multiple `.oas.json` files if you wish to break up your route
+definitions. Note that routes will be executed in document order, based on the
+`.oas.json` files being sorted alphabetically. For more details see
+[routing](./routing.mdx).

package/docs/articles/opentelemetry.mdx

@@ -0,0 +1,250 @@
+---
+title: Zuplo OpenTelemetry
+sidebar_label: OpenTelemetry
+---
+
+Zuplo ships with an OpenTelemetry plugin that allows you to collect and export
+telemetry data from your Zuplo API. The OpenTelemetry plugin supports tracing
+and logging. Metrics support is planned for future releases.
+
+<EnterpriseFeature name="OpenTelemetry" />
+
+## Tracing
+
+Tracing enables you to monitor performance, identify bottlenecks, and
+troubleshoot issues in your Zuplo API. The OpenTelemetry plugin automatically
+instruments your API to collect trace data. You can send trace data any
+OpenTelemetry service such as [Honeycomb](https://honeycomb.io),
+[Middleware](https://middleware.io/), [Dynatrace](https://dynatrace.com),
+[Jaeger](https://www.jaegertracing.io/), and
+[many more](https://opentelemetry.io/ecosystem/).
+
+With tracing enabled on your Zuplo API you will see timings for each request as
+well as spans for plugins, handlers, and policies. The OpenTelemetry plugin
+supports trace propagation (W3C headers by default) so you can trace requests
+all the way from the client to your backend.
+
+![Trace visualization](../../public/media/opentelemetry/image-1.png)
+
+### What's Traced?
+
+By default, when the OpenTelemetry plugin is enabled, the following is traced:
+
+- Request: The entire request lifecycle is traced, including the time taken to
+  process the request and send the response.
+- Inbound Policies: The time taken to execute all inbound policies as well as
+  each policy is traced.
+- Handler: The request handler is traced
+- Outbound Policies: The time taken to execute all outbound policies as well as
+  each policy is traced.
+- Subrequests: Any use of `fetch` within your custom policies or handlers will
+  be traced.
+
+### Limitations
+
+One important limitation to keep in mind is that the clock will only increment
+when performing I/O operations (for example when calling `fetch`, using the
+Cache APIs, etc.). This is a limitation imposed as a security measure due
+Zuplo's serverless, multi-tenant architecture. In practice this shouldn't impact
+your ability to trace as virtually any code that isn't I/O bound is fast.
+
+### Custom Tracing
+
+You can add custom tracing to your Zuplo API by using the OpenTelemetry API. The
+example below shows how to implement tracing in a custom policy.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+import { trace } from "@opentelemetry/api";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  const tracer = trace.getTracer("my-tracer");
+  return tracer.startActiveSpan("my-span", async (span) => {
+    span.setAttribute("key", "value");
+
+    try {
+      const results = await Promise.all([
+        fetch("https://api.example.com/hello"),
+        fetch("https://api.example.com/world"),
+      ]);
+      // ...
+
+      return request;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+This will result in a span that has the following spans:
+
+```txt
+|--- my-policy
+|    |
+|    |--- my-span
+|    |    |
+|    |    |--- GET https://api.example.com/hello
+|    |    |
+|    |    |--- GET https://api.example.com/world
+```
+
+## Logging
+
+Logging can be enabled by configuring the `logUrl` property in the OpenTelemetry
+plugin configuration, as shown in
+[Tracing and Logging Configuration](#tracing-and-logging-configuration). When
+enabled, logs will be exported to the specified endpoint in OpenTelemetry
+format.
+
+To add OpenTelemetry logs in your Zuplo handlers and policies, you can use the
+`context.log` object as shown below:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.log.info("Hello World");
+  return request;
+}
+```
+
+You can also set additional custom log properties using
+`context.log.setLogProperties!`:
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+) {
+  context.log.setLogProperties!({ customProperty: "value" });
+  context.log.info("Hello World");
+  return request;
+}
+```
+
+After setting a custom property, all subsequent log messages will include that
+property.
+
+These logs will be exported to the configured log endpoint in OpenTelemetry
+format. The log message will be in the `message` field and the custom properties
+will be in the `attributes` field.
+
+## Setup
+
+Adding OpenTelemetry to your Zuplo API is done by adding the
+`OpenTelemetryPlugin` in the `zuplo.runtime.ts` file as shown below.
+
+:::warning{title="OpenTelemetry Protocol"}
+
+The Zuplo OpenTelemetry plugin only supports sending data in JSON format. Not
+all OpenTelemetry services support the JSON format. If you are using a service
+that doesn't support JSON, you will need to use a tool like the
+[OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) that can
+convert the JSON format to the format required by your service.
+
+:::
+
+### Basic Tracing Configuration
+
+For most providers you will set values for `exporter.url` and
+`exporter.headers`. It's common for providers to use a header for authorization.
+
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      exporter: {
+        url: "https://otel-collector.example.com/v1/traces",
+        headers: {
+          "api-key": environment.OTEL_API_KEY,
+        },
+      },
+      service: {
+        name: "my-api",
+        version: "1.0.0",
+      },
+    }),
+  );
+}
+```
+
+### Advanced Tracing Configuration
+
+The OpenTelemetry plugin supports additional configuration options for advanced
+use cases, including sampling and post-processing of spans.
+
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      exporter: {
+        url: "https://otel-collector.example.com/v1/traces",
+        headers: { "api-key": environment.OTEL_API_KEY },
+      },
+      service: {
+        name: "my-api",
+        version: "1.0.0",
+      },
+      // Optional post processor to modify spans before export
+      postProcessor: (spans) => {
+        for (const span of spans) {
+          (
+            span as unknown as { attributes: Record<string, unknown> }
+          ).attributes["post.processed"] = true;
+        }
+        return spans;
+      },
+      sampling: {
+        headSampler: {
+          ratio: 0.1, // Sample 10% of requests
+        },
+      },
+    }),
+  );
+}
+```
+
+### Tracing and Logging Configuration
+
+Logging is only enabled when specifically configured with its own endpoint using
+the `logUrl` property. When using both tracing and logging, you can configure
+them with separate endpoints.
+
+```ts title="zuplo.runtime.ts"
+import { OpenTelemetryPlugin } from "@zuplo/otel";
+import { RuntimeExtensions, environment } from "@zuplo/runtime";
+
+export function runtimeInit(runtime: RuntimeExtensions) {
+  runtime.addPlugin(
+    new OpenTelemetryPlugin({
+      logUrl: "https://otel-collector.example.com/v1/logs",
+      traceUrl: "https://otel-collector.example.com/v1/traces",
+      headers: { "api-key": environment.OTEL_API_KEY },
+      service: {
+        name: "my-api",
+        version: "1.0.0",
+      },
+      sampling: {
+        headSampler: {
+          ratio: 0.1, // Sample 10% of requests
+        },
+      },
+    }),
+  );
+}
+```

package/docs/articles/per-user-rate-limits-using-db.mdx

@@ -0,0 +1,112 @@
+---
+title: Per user rate-limiting using a database and the ZoneCache
+sidebar_label: "Per-User Rate Limits"
+description:
+  Learn how to implement advanced dynamic rate limiting with database lookups
+  and ZoneCache for improved performance.
+tags:
+  - rate-limiting
+  - caching
+---
+
+In this example we show a more advanced implementation of
+[dynamic rate limiting](../articles/per-user-rate-limits-using-db.mdx). It uses
+a database lookup to get the customer details and combines that with the
+ZoneCache to improve performance, reduce latency and lower the load on the
+database.
+
+In this example we use [Supabase](https://supabase.com) as the database but you
+could use your own API, [Xata](https://xata.io),
+[Firebase](https://firebase.com) etc. The implementation will be similar for
+all.
+
+If you haven't already, check out the
+[rate-limiting policy](../policies/rate-limit-inbound.mdx) and the
+[dynamic rate limiting quickstart](../articles/per-user-rate-limits-using-db.mdx).
+Then you should be oriented to how dynamic rate limiting works.
+
+Below is a full implementation of a custom rate limiting function. In our
+example this is a module called `per-user-rate-limiting.ts`.
+
+```ts
+import {
+  CustomRateLimitDetails,
+  ZoneCache,
+  ZuploContext,
+  ZuploRequest,
+  environment,
+} from "@zuplo/runtime";
+import { createClient } from "@supabase/supabase-js";
+
+const CACHE_NAME = "rate-limit-requests-allowed-cache";
+const SB_URL = "https://YOUR_SUPABASE_URL.supabase.co";
+const SB_SERVICE_ROLE_KEY = environment.SB_SERVICE_ROLE_KEY;
+const FALLBACK_REQUESTS_ALLOWED = 100;
+
+export async function rateLimitKey(
+  request: ZuploRequest,
+  context: ZuploContext,
+  policyName: string,
+): Promise<CustomRateLimitDetails> {
+  // We'll get the customer ID from the user data.
+  // This might be from a JWT or API Key metadata
+  const customerId = request.user.data.customerId;
+
+  // We don't want to hit the database on every request
+  // So we'll use the fast zone cache to cache this data
+  const cache = new ZoneCache(CACHE_NAME, context);
+  let requestsAllowed = await cache.get(customerId);
+
+  // If we didn't get a value, we'll need to go to the database
+  // In this example we're using supabase, but you could use your
+  // own API, Xata, etc.
+  if (requestsAllowed === undefined) {
+    // create the supabase client and read the customer's
+    const supabase = createClient(SB_URL, SB_SERVICE_ROLE_KEY);
+    let { data, error } = await supabase
+      .from("customer_rate_limits")
+      .select("requestsAllowed")
+      .eq("customerId", customerId);
+
+    // If something goes wrong, we probably want to log an
+    // error and assume a default, vs go down
+    if (error) {
+      context.log.error(error);
+      requestsAllowed = FALLBACK_REQUESTS_ALLOWED;
+    } else {
+      context.log.info(data);
+      requestsAllowed = data[0].requestsAllowed;
+    }
+    // store the read value in the ZoneCache
+    // do this asynchronously to improve performance
+    cache
+      .put(customerId, requestsAllowed, 60)
+      .catch((err) => context.log.error(err));
+  }
+
+  return {
+    key: customerId,
+    requestsAllowed: requestsAllowed,
+    timeWindowMinutes: 1,
+  };
+}
+```
+
+The above function can be applied to a rate limiter with the following
+configuration in policies
+
+```json
+{
+  "export": "RateLimitInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "rateLimitBy": "function",
+    "requestsAllowed": 2,
+    "timeWindowMinutes": 1,
+    "identifier": {
+      "export": "rateLimitKey",
+      "module": "$import(./modules/per-user-rate-limiting)"
+    }
+  }
+}
+```