zuplo 6.67.32 → 6.68.0

package/docs/articles/github-deployment-testing.mdx

@@ -0,0 +1,101 @@
+---
+title: Testing GitHub Deployments
+sidebar_label: Testing Deployments
+---
+
+Run your test suite automatically after every Zuplo deployment without replacing
+the built-in GitHub integration. This approach uses GitHub's `deployment_status`
+event to trigger tests after Zuplo finishes deploying.
+
+## Why This Approach?
+
+Zuplo's GitHub integration already handles deployments perfectly — every push
+deploys automatically with status checks in GitHub. Rather than replacing this
+with custom CI/CD, you can extend it by running tests after each deployment
+completes.
+
+This gives you:
+
+- **Automatic deployments** — Keep the built-in integration
+- **Post-deploy testing** — Run tests against the live environment
+- **PR checks** — Tests block merging until they pass
+- **No duplicate deploys** — Tests run after Zuplo deploys, not instead of
+
+## Setup
+
+Create a workflow that triggers on the `deployment_status` event:
+
+```yaml title=".github/workflows/test.yaml"
+name: Test Deployment
+
+on:
+  deployment_status:
+
+jobs:
+  test:
+    # Only run when Zuplo deployment succeeds
+    if: |
+      github.event.deployment_status.state == 'success' &&
+      github.event.deployment_status.environment_url != ''
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests
+        run:
+          npx zuplo test --endpoint ${{
+          github.event.deployment_status.environment_url }}
+```
+
+## How It Works
+
+1. You push code to GitHub
+2. Zuplo's integration deploys automatically
+3. Zuplo reports deployment status back to GitHub
+4. The `deployment_status` event triggers your workflow
+5. Your tests run against the deployed environment URL
+6. Test results appear as a check on the commit/PR
+
+The `environment_url` from the deployment status contains your Zuplo environment
+URL, so tests always run against the correct environment.
+
+## Filtering by Environment
+
+To only test specific environments (like staging or production):
+
+```yaml
+jobs:
+  test:
+    if: |
+      github.event.deployment_status.state == 'success' &&
+      github.event.deployment_status.environment == 'production'
+    # ...
+```
+
+## Adding to PR Checks
+
+GitHub automatically shows deployment status checks on pull requests. Your test
+workflow results appear alongside them, giving reviewers confidence that both
+deployment and tests succeeded.
+
+## When to Use Custom CI/CD Instead
+
+This approach works great when you want to:
+
+- Keep automatic deployments
+- Run tests after deploy
+- Add PR checks
+
+Consider [custom GitHub Actions](./custom-ci-cd-github.mdx) if you need:
+
+- Approval gates before production
+- Multi-stage deployments (staging → production)
+- Tests that must pass before any deployment
+- Tag-based or release-based deployments

package/docs/articles/gke-with-upstream-auth-policy.mdx

@@ -0,0 +1,192 @@
+---
+title: Secure a GCP Backend with Zuplo Upstream Auth
+sidebar_label: GCP Backend with Upstream Auth
+---
+
+When using any API gateway as your API's entry point, it's critical that only
+traffic that originates from the Gateway is allowed to call your backend. There
+are [many way to this](./securing-your-backend.mdx) depending on your
+requirements and how your backend is hosted. This article will explain how to
+use Google IAM to secure a GKE cluster so that only requests made through your
+Zuplo API Gateway will be allowed to call your GKE ingress.
+
+Using GCP IAM to authorize your Zuplo Gateway to make requests to your backend
+utilizes Googles core IAM system known as
+"[Identity Aware Proxy](https://cloud.google.com/iap)" to secure public IP
+address from unauthorized access. When correctly configured, this will ensure
+that no unauthorized access makes it to your application.
+
+While it's also possible to enforce authorization within your application
+itself - for example using JWT Authentication. The key difference is that by
+using your Cloud providers identity and authorization system, you are ensuring
+that unauthorized requests are blocked before they even touch your backend. This
+provides protection from any potential security vulnerabilities in your core,
+web server, or operating system.
+
+:::note
+
+This article uses GKE as the example backend, but any GCP service that can be
+set up behind an HTTP Load Balancer can be used.
+
+:::
+
+The diagram below shows how the end-to-end system interacts. The important steps
+to this process are:
+
+1. The client makes a request to your Zuplo API Gateway
+1. The Zuplo API Gateway enforces any policies (for example authentication,
+   authorization, rate limiting)
+1. The Zuplo API Gateway proxies the request to the public IP address of your
+   GCP Load Balancer. Zuplo adds authorization information to the request that
+   identify the request as coming from Zuplo
+1. GCP Identity Aware proxy validates that the request comes from an authorized
+   Service Account identity. Unauthorized requests are rejected.
+1. Authorized requests are forwarded on through your GKE ingress to your
+   backend.
+
+![GKE diagram](../../public/media/gke-with-upstream-auth-policy/diagram.svg)
+
+## Zuplo Gateway Identity
+
+Requests that are proxied from Zuplo to your GCP Load Balancer use the
+[Upstream GCP Service Auth Policy](../policies/upstream-gcp-service-auth-inbound.mdx)
+to authenticate the request via a
+[GCP Service Account](https://cloud.google.com/iam/docs/service-account-overview).
+The policy appends an `authorization` header to the request that the GCP
+Identity Aware Proxy uses to determine if the request is authorized or not.
+
+Using this system means that you can uniquely identify requests that come from
+Zuplo as a their own identity. This means all request logs can be identified by
+their source - for example your Zuplo Gateway, another system also using a GCP
+Service account, a developer testing an internal system, etc.
+
+:::tip{title="Multiple Service Account"}
+
+While not normally needed, it's possible to configure multiple Upstream GCP
+Service Auth Inbound policies in order to provide fine-grain authorization to
+your internal resources by Service Account. For example, if you had two Zuplo
+projects - one for external users and one for internal users - each could use
+its own identity.
+
+:::
+
+For instructions on how to configure upstream GCP IAM auth, see the
+[Upstream GCP Service Auth Policy document](../policies/upstream-gcp-service-auth-inbound.mdx)
+
+## GCP Configuration
+
+Documentation on configuring GCP Identity Aware Proxy can be found on Google's
+documentation. Below are a few links on how to configure the proxy with several
+common backends.
+
+- [Enabling IAP for Compute Engine](https://cloud.google.com/iap/docs/enabling-compute-howto)
+- [Enabling IAP for GKE](https://cloud.google.com/iap/docs/enabling-kubernetes-howto)
+- [Enabling IAP for Cloud Run](https://cloud.google.com/iap/docs/enabling-cloud-run)
+
+:::tip{title="Cloud Run"}
+
+Cloud Run doesn't need to use IAP in all cases. It's possible to restrict Cloud
+Run to
+[require IAM authentication in order to invoke the service](https://cloud.google.com/run/docs/securing/managing-access).
+
+:::
+
+## Example
+
+To see how this works in action, follow the steps in Google's document
+_[Set up an external Application Load Balancer with Ingress](https://cloud.google.com/kubernetes-engine/docs/tutorials/http-balancer)_.
+This will configure a GKE cluster with a simple "hello world" web application
+behind an HTTP Load Balancer. At the end of the tutorial, you should have a
+public IP address that serves a simple web application.
+
+You can test the request with a simple curl command.
+
+```shell
+curl http://34.111.91.10/
+Hello, world!
+Version: 1.0.0
+Hostname: web-58756b54cc-7hdcw
+```
+
+In order to securely proxy traffic from Zuplo to GCP, you'll need to secure your
+traffic over an SSL connection. Navigate to the GCP portal to manage your
+[load balancer](https://console.cloud.google.com/net-services/loadbalancing/list/loadBalancers)
+and select the load balancer that was created previously. Click, **Edit** on the
+load balancer.
+
+![Edit load balancer](../../public/media/gke-with-upstream-auth-policy/770db332-ad94-41c6-a6f8-1498578fb78c.png)
+
+Next, click **ADD FRONTEND IP AND PORT**. Enter the name and select **HTTPS** as
+the protocol.
+
+![Add new frontend IP and port](../../public/media/gke-with-upstream-auth-policy/cd0b20d3-c109-4775-9fa0-1b3e391bcb84.png)
+
+Then click **Add a Certificate**. Select Google-managed Certificate and enter
+your domain name.
+
+![Add a certificate](../../public/media/gke-with-upstream-auth-policy/49760fbb-6eb4-46f9-a638-ac078fe85aab.png)
+
+Next, select **Host and path rules** and enter the domain and associate it with
+the backend.
+
+![Host and path rules configuration](../../public/media/gke-with-upstream-auth-policy/307e9026-d77e-4efd-9fc1-4c45ead963f1.png)
+
+Click **Done** and then **Update** to update your Load Balancer. It will take a
+few minutes to issue the SSL certificate for the domain.
+
+After the Load Balancer updates you should be able to request your site using
+the configured domain via HTTPS.
+
+```shell
+curl https://api.example.com
+Hello, world!
+Version: 1.0.0
+Hostname: web-58756b54cc-7hdcw
+```
+
+:::tip{title="Checkpoint"}
+
+At this point, your backend on GKE is exposed on the public internet via a GCP
+HTTP Load Balancer via HTTP and HTTPS. For this demo, we won't go through the
+changes, but in production you shouldn't expose an HTTP endpoint on your API.
+
+:::
+
+### Enabling Identity Aware Proxy
+
+To enable Identity Aware Proxy on your Load Balancer, follow googles document
+_[Enabling IAP for GKE](https://cloud.google.com/iap/docs/enabling-kubernetes-howto)_
+
+After you have enabled IAP, if you try to open your example API in the browser
+you will now be prompted to authenticate using your Google Account. If you do so
+you be shown a screen that blocks access to the application.
+
+![You don't have access](../../public/media/gke-with-upstream-auth-policy/a2ee889a-54c1-4e00-953b-1053c619ce52.png)
+
+Your API is now completely inaccessible to unauthorized requests.
+
+In order to allow your Zuplo Gateway access you need to
+[grant its service account permission](https://cloud.google.com/iap/docs/managing-access)
+to call the IAP protected API.
+
+![Add principals](../../public/media/gke-with-upstream-auth-policy/ecadec32-753b-4716-afb5-fafa69c91499.png)
+
+### Authorize Zuplo to Call the API
+
+The last thing required is to configure Zuplo with a service account and policy
+so that it can securely call your API. Follow the instructions on the
+[Upstream GCP Service Auth Policy document](../policies/upstream-gcp-service-auth-inbound.mdx)
+to set up the policy.
+
+With the policy setup, create a route in your Zuplo portal that points to your
+API. When you make a request you will once again see a successful response.
+
+```shell
+curl https://zuplo-gateway.example.com
+Hello, world!
+Version: 1.0.0
+Hostname: web-58756b54cc-7hdcw
+```
+
+You can now add additional policies on Zuplo in order to authenticate requests,
+add rate limiting, etc.

package/docs/articles/graphql-security.mdx

@@ -0,0 +1,180 @@
+---
+title: Secure your GraphQL API with Zuplo
+sidebar_label: Secure your GraphQL API
+description:
+  Learn how to secure your GraphQL API using Zuplo's security policies to
+  prevent DoS attacks and protect schema information.
+tags:
+  - authentication
+  - backends
+---
+
+**Secure your GraphQL API with Zuplo**
+
+GraphQL is a powerful query language for your APIs. While it offers great
+flexibility for clients, it also exposes potential security risks. Fortunately,
+with Zuplo, you can secure your GraphQL API by implementing various policies.
+This article walks you through our security policies:
+[GraphQL Complexity Limit](/docs/policies/graphql-complexity-limit-inbound), and
+[GraphQL Disable Introspection](/docs/policies/graphql-disable-introspection-inbound).
+
+## 1. Understanding the Risks
+
+### a. Deeply Nested Queries
+
+Without restrictions, a client can send deeply nested queries that could
+potentially overwhelm your server, resulting in a Denial of Service (DoS)
+attack. This is because deeply nested queries can cause the server to process a
+huge amount of data and operations. While this might be a planned attack, it
+could also be a mistake by a client who is unaware of the query depth limit.
+
+### b. Query Complexity
+
+Even without deep nesting, a query can be crafted to be very complex. This could
+force your server to execute resource-intensive operations, potentially slowing
+down the system or causing a DoS.
+
+### c. Introspection
+
+GraphQL allows clients to introspect your schema. While this is beneficial
+during development, it can expose detailed schema information to potential
+attackers in production.
+
+## 2. Add your GraphQL API & setting up Policies
+
+### Set Up POST Endpoint
+
+If you didn't already do so, you need to set up a POST endpoint in your API.
+This endpoint will be used to send the GraphQL queries to your API. The
+urlRewriteHandler to rewrite the request to your GraphQL API. For this example
+let's assume your GraphQL API is hosted at `https://api.example.com/graphql`.
+
+To do so, add the following to your `config/routes.oas.json`
+
+```json
+{
+  "post": {
+    "summary": "GraphQL Query",
+    "description": "The endpoint for GraphQL queries.",
+    "x-zuplo-route": {
+      "corsPolicy": "none",
+      "handler": {
+        "export": "urlRewriteHandler",
+        "module": "$import(@zuplo/runtime)",
+        "options": {
+          "rewritePattern": "https://api.example.com/graphql"
+        }
+      },
+      "policies": {
+        "inbound": [
+          "graphql-complexity-limit-policy",
+          "graphql-disable-introspection-policy"
+        ]
+      }
+    },
+    "operationId": "52bdf225-eaa7-441c-afb9-b7df046a142e"
+  }
+}
+```
+
+For all the risks mentioned above, Zuplo offers policies that can be configured
+to protect your GraphQL API. These policies can be configured for Zuplo. We'll
+create the configuration for the three policies `graphql-depth-limit`,
+`graphql-complexity-points` and `graphql-disable-introspection-policy` next.
+
+### a. GraphQL Depth Limit
+
+This policy limits how deep a query can be nested. Check our
+[detailed policy documentation](/docs/policies/graphql-complexity-limit-inbound)
+for more information.
+
+Add this into your `config/policies.json`
+
+```json
+{
+  "policies": [
+    {
+      "name": "graphql-complexity-limit-policy",
+      "policyType": "graphql-complexity-limit-inbound",
+      "handler": {
+        "export": "GraphQLComplexityLimitInboundPolicy",
+        "module": "$import(@zuplo/graphql)",
+        "options": {
+          "useDepthLimit": {
+            "depthLimit": 20
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+By limiting the query depth, you prevent malicious or mistakenly deep queries
+from consuming excessive server resources.
+
+### b. GraphQL Complexity Limit
+
+We can extend the same policy to also check for complexity. By defining a max
+for each type of operation, and then it limits the total complexity a query can
+have. In order to use the Complexity Limit you need to allow introspection in
+your GraphQL API.
+
+```json
+{
+  "policies": [
+    {
+      "name": "graphql-complexity-limit-policy",
+      "policyType": "graphql-complexity-limit-inbound",
+      "handler": {
+        "export": "GraphQLComplexityLimitInboundPolicy",
+        "module": "$import(@zuplo/graphql)",
+        "options": {
+          "useDepthLimit": {
+            "depthLimit": 20
+          },
+          "useComplexityLimit": {
+            "complexityLimit": 50,
+            "endpointUrl": "https://api.example.com/graphql"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+The complexity limit ensures that a potential attacker can't overload the system
+by sending overly complicated queries.
+
+### c. GraphQL Disable Introspection
+
+Disable introspection in production environments to hide schema details.
+
+```json
+{
+  "policies": [
+    {
+      "name": "graphql-disable-introspection-policy",
+      "policyType": "graphql-disable-introspection-inbound",
+      "handler": {
+        "export": "GraphQLDisableIntrospectionInboundPolicy",
+        "module": "$import(@zuplo/graphql)",
+        "options": {}
+      }
+    }
+  ]
+}
+```
+
+By disabling introspection in production, you prevent attackers from gaining
+insights into your GraphQL schema, thereby reducing potential attack vectors.
+
+## 4. Example Repository
+
+For those who prefer a hands-on approach or wish to see these configurations in
+action, there is a GitHub repository with everything set up. This repository
+offers a comprehensive example of how to configure and secure a GraphQL API
+using Zuplo. Check out the
+[GraphQL API with Zuplo example repository](https://github.com/zuplo/zuplo-graphql-example)
+to dive deeper.

package/docs/articles/handling-form-data.mdx

@@ -0,0 +1,61 @@
+---
+title: Handling FormData
+description:
+  Learn how to parse multipart/form-data uploads and process file content in
+  Zuplo runtime using function handlers.
+tags:
+  - request-handling
+  - backends
+---
+
+Zuplo supports working with `FormData` including `multipart/form-data`. In this
+simple example we show how you can parse a multipart entry and read the stream
+into memory for use in the Zuplo runtime.
+
+In this case, we upload a JSON file as a multipart/form-data entry using
+Insomnia, with a key `foo`
+
+![Insomnia multipart/form-data](../../public/media/handling-form-data/2d372851-af24-429b-8eeb-cb880589f30d.png)
+
+We can then handle this programmatically inside Zuplo using a function handler.
+We also modify the JSON before forwarding on to the target backend server.
+
+```ts
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+// FormData can return different types in different circumstances
+// use this function to convert both to strings
+async function readFileOrStringContent(data: unknown) {
+  if (data.constructor.name === "File") {
+    return await (data as File).text();
+  }
+  return data as string;
+}
+
+export default async function (request: ZuploRequest, context: ZuploContext) {
+  const formData = await request.formData();
+
+  // read the form-data entry as a 'Blob' type
+  const blob = formData.get("foo");
+
+  // stream the body into memory
+  const json = await readFileOrStringContent(blob);
+
+  // parse the JSON document
+  const object = JSON.parse(json);
+
+  // Modify the document somehow before forwarding on to the backend
+  object.newKey = "newValue";
+
+  // Make a standard POST to a backend with a JSON body
+  const response = fetch("https://backend-origin.com/example", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+    },
+    body: JSON.stringify(object, null, 2),
+  });
+
+  return response;
+}
+```

package/docs/articles/health-checks.mdx

@@ -0,0 +1,109 @@
+---
+title: Health Check Handler
+sidebar_label: Health Checks
+description:
+  Learn how to set up health check endpoints to monitor your API Gateway and
+  backend services.
+tags:
+  - observability
+  - backends
+---
+
+Part of running a reliable API Gateway is ensuring that the service is healthy
+and available. With Zuplo, it's easy to set up a health check endpoint that can
+be used to ensure the health of both your Zuplo Gateway and your backend (as
+well as the connectivity between them).
+
+A typical health check endpoint on your API Gateway will exercise some of the
+most important policies (such as authentication) and then make a simple request
+to your backend to ensure that it's reachable and functioning.
+
+## Setting up a Health Check Handler
+
+To set up a health check handler, you will need to create a new route in your
+Zuplo Gateway. This route will be used to handle health check requests.
+
+You'll create a new route with the path `/health` and the method `GET`. In your
+OpenAPI file this would look like:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/health": {
+      "get": {
+        "summary": "Health Check",
+        "description": "Checks the health of the API Gateway and backend.",
+        "responses": {
+          "200": {
+            "description": "OK"
+          },
+          "503": {
+            "description": "Service Unavailable"
+          }
+        },
+        "x-zuplo-route": {
+          "corsPolicy": "anything-goes",
+          "handler": {
+            "export": "default",
+            "module": "$import(./modules/health)"
+          },
+          "policies": {
+            "inbound": ["my-auth-policy"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Next, you'll create a custom handler module that will be used to process the
+health check requests. This module will make a simple request to your backend to
+ensure that it's reachable and functioning. If you have multiple backend
+services you can check each of them.
+
+```ts title="modules/health.ts"
+import { ZuploContext, ZuploRequest, ZuploResponse } from "@zuplo/runtime";
+
+export default async function handler(
+  request: ZuploRequest,
+  context: ZuploContext,
+): Promise<ZuploResponse> {
+  try {
+    // Make a simple request to the backend to check its health
+    const responses = await Promise.allSettled([
+      fetch("https://backend-1.example.com/health", {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+        },
+      }),
+      fetch("https://backend-2.example.com/health", {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json",
+        },
+      }),
+    ]);
+    const backendResponse = responses.find(
+      (res) => res.status === "fulfilled",
+    ) as PromiseFulfilledResult<Response> | undefined;
+    if (!backendResponse) {
+      context.log.error("All backend health checks failed", { responses });
+      return new ZuploResponse("Service Unavailable", { status: 503 });
+    } else {
+      const failedResponses = responses.filter(
+        (res) => res.status === "rejected",
+      ) as PromiseRejectedResult[];
+      context.log.error("Backend health check failed", {
+        statuses: failedResponses.map((res) => res.reason.status),
+        statusText: failedResponses.map((res) => res.reason.statusText),
+      });
+      return new ZuploResponse("Service Unavailable", { status: 503 });
+    }
+  } catch (error) {
+    context.log.error("Error during health check", { error });
+    return new ZuploResponse("Service Unavailable", { status: 503 });
+  }
+}
+```