zuplo 6.67.32 → 6.68.0

package/docs/policies/archive-request-aws-s3-inbound/schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/archive-request-aws-s3-inbound.json",
+  "type": "object",
+  "title": "Archive Request to AWS S3",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Archive the incoming request body to AWS S3 storage",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": [],
+          "properties": {
+            "region": {
+              "type": "string",
+              "description": "The AWS region where the bucket is located"
+            },
+            "bucketName": {
+              "type": "string",
+              "description": "The name of the storage bucket"
+            },
+            "path": {
+              "type": "string",
+              "description": "The path where requests are stored"
+            },
+            "accessKeyId": {
+              "type": "string",
+              "description": "The Access Key ID of the account authorized to write to the bucket"
+            },
+            "accessKeySecret": {
+              "type": "string",
+              "description": "The Access Key Secret of the account authorized to write to the bucket"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "ArchiveResponseOutbound",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "region": "us-east-1",
+            "bucketName": "test-bucket-123.s3.amazonaws.com",
+            "path": "responses/",
+            "accessKeyId": "$env(AWS_ACCESS_KEY_ID)",
+            "accessKeySecret": "$env(AWS_ACCESS_KEY_SECRET)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/archive-request-azure-storage-inbound/doc.md

@@ -0,0 +1,31 @@
+## Using the Policy
+
+In order to use this policy, you'll need to setup Azure storage. You'll find
+instructions on how to do that below.
+
+### Setup Azure
+
+First, let's set up Azure. You'll need a container in Azure storage
+([docs](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal)).
+Once you have your container you'll need the URL - you can get it on the
+`properties` tab of your container as shown below.
+
+![Azure](../../public/media/guides/archiving-requests-to-storage/Untitled.png)
+
+This URL will be the `blobPath` in our policy options.
+
+Next, we'll need a SAS (Shared Access Secret) to authenticate with Azure. You
+can generate one of these on the `Shared access tokens` tab.
+
+Note, you should minimize the permissions - and select only the `Create`
+permission. Choose a sensible start and expiration time for your token. Note, we
+don't recommend restricting IP addresses because Zuplo runs at the edge in over
+200 data-centers world-wide.
+
+![Permissions](../../public/media/guides/archiving-requests-to-storage/Untitled_1.png)
+
+Then generate your SAS token - copy the token (not the URL) to the clipboard and
+enter it into a new environment variable in your API called `BLOB_CREATE_SAS`.
+You'll need another environment variable called `BLOB_CONTAINER_PATH`.
+
+![SAS token](../../public/media/guides/archiving-requests-to-storage/Untitled_2.png)

package/docs/policies/archive-request-azure-storage-inbound/intro.md

@@ -0,0 +1,4 @@
+In this example shows how you can archive the body of incoming requests to Azure
+Blob Storage. This can be useful for auditing, logging, or archival scenarios.
+Additionally, you could use this policy to save the body of a request and then
+enqueue some asynchronous work that uses this body.

package/docs/policies/archive-request-azure-storage-inbound/policy.ts

@@ -0,0 +1,54 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  blobContainerPath: string;
+  blobCreateSas: string;
+}
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+  policyName: string,
+) {
+  // NOTE: policy options should be validated, but to keep the sample short,
+  // we are skipping that here.
+
+  // because we will read the body, we need to
+  // create a clone of this request first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = request.clone();
+
+  // In this example we assume the body could be text, but you could also
+  // request the blob() to handle binary data types like images.
+  //
+  // This example loads the entire body into memory. This is fine for
+  // small payloads, but if you have a large payload you should instead
+  // save the body via streaming.
+  const body = await clone.text();
+
+  // generate a unique blob name based on the date and requestId
+  const blobName = `${Date.now()}-${context.requestId}.req.txt`;
+
+  const url = `${options.blobContainerPath}/${blobName}?${options.blobCreateSas}`;
+
+  const result = await fetch(url, {
+    method: "PUT",
+    body: body,
+    headers: {
+      "x-ms-blob-type": "BlockBlob",
+    },
+  });
+
+  if (result.status > 201) {
+    const text = await result.text();
+    context.log.error("Error saving file to storage", text);
+    return HttpProblems.internalServerError(request, context, {
+      detail: text,
+    });
+  }
+
+  // continue
+  return request;
+}

package/docs/policies/archive-request-azure-storage-inbound/schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/archive-request-azure-storage-inbound.json",
+  "type": "object",
+  "title": "Archive Request to Azure Storage",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Archive the incoming request to Azure blob storage.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": [],
+          "properties": {
+            "blobCreateSas": {
+              "type": "string",
+              "description": "The Azure shared access token with permission to write to the bucket"
+            },
+            "blobContainerPath": {
+              "type": "string",
+              "description": "The path to the Azure blob container"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "blobCreateSas": "$env(BLOB_CREATE_SAS)",
+            "blobContainerPath": "$env(BLOB_CONTAINER_PATH)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/archive-request-gcp-storage-inbound/doc.md

@@ -0,0 +1,63 @@
+## Using the Policy
+
+In order to use this policy, you'll need to setup Google Cloud Storage, create
+an IAM Service Account, and configure the
+[Upstream GCP Service Auth Policy](/docs/policies/upstream-gcp-service-auth-inbound).
+You'll find instructions on how to do that below.
+
+### Setup a Google Service Account
+
+In order to authorize your Zuplo API to upload files to Google Storage, you will
+need to create a Service Account. Instructions for doing so can be found here:
+https://cloud.google.com/iam/docs/service-accounts-create
+
+The service account you create will also need permissions to write objects to
+the storage bucket you will use. The easiest way to do that's to assign the
+account the **Storage Object Creator (roles/storage.objectCreator)** role.
+However, you can also scope the permissions to a single bucket if you like.
+
+Download the service account JSON and create an environment variable secret with
+the contents. In this example, the variable is named `SERVICE_ACCOUNT_JSON`
+
+### Setup Google Cloud Storage
+
+In order to use Google Cloud Storage you will need to have a bucket created. If
+you don't have one you can do so by following this guide:
+https://cloud.google.com/storage/docs/creating-buckets
+
+### Upstream GCP Service Auth Policy
+
+In order to authorize your Zuplo API to upload to the GCP bucket, you will
+configured the
+[Upstream GCP Service Auth Policy](/docs/policies/upstream-gcp-service-auth-inbound).
+It's important that the auth policy runs **before** this custom policy.
+
+The service auth policy will set the `Authorization` header of the request to a
+JWT token with the requested permissions. In order to generate the correct JWT,
+you must set the `scopes` to
+`https://www.googleapis.com/auth/devstorage.read_write` as shown below.
+
+```json
+{
+  "export": "UpstreamGcpServiceAuthInboundPolicy",
+  "module": "$import(@zuplo/runtime)",
+  "options": {
+    "expirationOffsetSeconds": 300,
+    "scopes": ["https://www.googleapis.com/auth/devstorage.read_write"],
+    "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)",
+    "tokenRetries": 3
+  }
+}
+```
+
+:::tip
+
+You can have multiple Upstream GCP Service Auth Policies on the same request. So
+for example, you might generate a JWT token that first has permission to upload
+to GCP storage, then you might have a second policy that runs after this policy
+that authorizes your Zuplo API to all downstream Cloud Run service.
+
+Each auth policy will cache the JWT tokens for an hour by default so having
+multiple policies will have virtually no impact on your APIs latency.
+
+:::

package/docs/policies/archive-request-gcp-storage-inbound/intro.md

@@ -0,0 +1,4 @@
+In this example shows how you can archive the body of incoming requests to
+Google Cloud Storage. This can be useful for auditing, logging, or archival
+scenarios. Additionally, you could use this policy to save the body of a request
+and then enqueue some asynchronous work that uses this body.

package/docs/policies/archive-request-gcp-storage-inbound/policy.ts

@@ -0,0 +1,68 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+type GoogleStoragePolicyOptions = {
+  bucketName: any;
+};
+
+export default async function policy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: GoogleStoragePolicyOptions,
+  policyName: string,
+) {
+  // NOTE: policy options should be validated, but to keep the sample short,
+  // we are skipping that here.
+
+  // because we will read the body, we need to
+  // create a clone of this request first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = request.clone();
+
+  // In this example we assume the body could be text, but you could also
+  // request the blob() to handle binary data types like images.
+  //
+  // This example loads the entire body into memory. This is fine for
+  // small payloads, but if you have a large payload you should instead
+  // save the body via streaming.
+  const body = await clone.text();
+
+  // generate a unique blob name based on the date and requestId
+  const objectName = `${Date.now()}-${context.requestId}`;
+
+  const authHeader = request.headers.get("Authorization");
+
+  // This uses simple uploads where the parameters are in the query string, you
+  // could also use multipart uploads to set more properties
+  // See: https://cloud.google.com/storage/docs/uploading-objects#rest-upload-objects
+  const url = new URL(
+    `https://storage.googleapis.com/upload/storage/v1/b/${options.bucketName}/o`,
+  );
+  url.searchParams.set("uploadType", "media");
+  url.searchParams.set("name", objectName);
+
+  const response = await fetch(url.toString(), {
+    method: "POST",
+    body: body,
+    headers: {
+      // Using the authorization header generated by the previous policy
+      authorization: authHeader,
+      // change to whatever content type you want to save
+      "Content-Type": "text/plain",
+    },
+  });
+
+  if (response.status > 201) {
+    const text = await response.text();
+    context.log.error(
+      `Error saving file to storage in policy ${policyName}.`,
+      text,
+    );
+    return HttpProblems.internalServerError(request, context, {
+      detail: text,
+    });
+  }
+
+  // continue
+  return request;
+}

package/docs/policies/archive-request-gcp-storage-inbound/schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/archive-request-gcp-storage-inbound.json",
+  "type": "object",
+  "title": "Archive Request to GCP Storage",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Archive the incoming request to Google Cloud Storage.",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": [],
+          "properties": {
+            "bucketName": {
+              "type": "string",
+              "description": "The name of the bucket to archive the request."
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "bucketName": "my-bucket"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/archive-response-aws-s3-outbound/intro.md

@@ -0,0 +1,2 @@
+In this example shows how you can archive the body of outgoing responses to AWS
+S3 Storage. This can be useful for auditing, logging, or archival scenarios.

package/docs/policies/archive-response-aws-s3-outbound/policy.ts

@@ -0,0 +1,59 @@
+import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  region: string;
+  bucketName: string;
+  path: string;
+  accessKeyId: string;
+  accessKeySecret: string;
+}
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+) {
+  // NOTE: policy options should be validated, but to keep the sample short,
+  // we are skipping that here.
+
+  // Initialize the S3 client
+  const s3Client = new S3Client({
+    region: options.region,
+    credentials: {
+      accessKeyId: options.accessKeyId,
+      secretAccessKey: options.accessKeySecret,
+    },
+  });
+
+  // Create the file
+  const file = `${options.path}/${Date.now()}-${crypto.randomUUID()}.req.txt`;
+
+  // because we will read the body, we need to
+  // create a clone of this response first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = response.clone();
+
+  // In this example we assume the body could be text, but you could also
+  // response the blob() to handle binary data types like images.
+  //
+  // This example loads the entire body into memory. This is fine for
+  // small payloads, but if you have a large payload you should instead
+  // save the body via streaming.
+  const body = await clone.text();
+
+  // Create the S3 command
+  const command = new PutObjectCommand({
+    Bucket: options.bucketName,
+    Key: file,
+    Body: body,
+  });
+
+  // Use the S3 client to save the object
+  await s3Client.send(command);
+
+  // Continue the response
+  return response;
+}

package/docs/policies/archive-response-aws-s3-outbound/schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "$id": "http://zuplo.com/schemas/policies/archive-response-aws-s3-outbound.json",
+  "type": "object",
+  "title": "Archive Response to AWS S3",
+  "isCustom": true,
+  "products": ["api-gateway"],
+  "description": "Archive the outgoing response body to AWS S3 storage",
+  "required": ["handler"],
+  "properties": {
+    "handler": {
+      "type": "object",
+      "default": {},
+      "required": ["export", "module", "options"],
+      "properties": {
+        "export": {
+          "const": "default",
+          "description": "The name of the exported type"
+        },
+        "module": {
+          "const": "$import(./modules/YOUR_MODULE)",
+          "description": "The module containing the policy"
+        },
+        "options": {
+          "type": "object",
+          "description": "The options for this policy",
+          "required": [],
+          "properties": {
+            "region": {
+              "type": "string",
+              "description": "The AWS region where the bucket is located"
+            },
+            "bucketName": {
+              "type": "string",
+              "description": "The name of the storage bucket"
+            },
+            "path": {
+              "type": "string",
+              "description": "The path where requests are stored"
+            },
+            "accessKeyId": {
+              "type": "string",
+              "description": "The Access Key ID of the account authorized to write to the bucket"
+            },
+            "accessKeySecret": {
+              "type": "string",
+              "description": "The Access Key Secret of the account authorized to write to the bucket"
+            }
+          }
+        }
+      },
+      "examples": [
+        {
+          "_name": "basic",
+          "export": "default",
+          "module": "$import(./modules/YOUR_MODULE)",
+          "options": {
+            "region": "us-east-1",
+            "bucketName": "test-bucket-123.s3.amazonaws.com",
+            "path": "responses/",
+            "accessKeyId": "$env(AWS_ACCESS_KEY_ID)",
+            "accessKeySecret": "$env(AWS_ACCESS_KEY_SECRET)"
+          }
+        }
+      ]
+    }
+  }
+}

package/docs/policies/archive-response-azure-storage-outbound/doc.md

@@ -0,0 +1,31 @@
+## Using the Policy
+
+In order to use this policy, you'll need to setup Azure storage. You'll find
+instructions on how to do that below.
+
+### Setup Azure
+
+First, let's set up Azure. You'll need a container in Azure storage
+([docs](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal)).
+Once you have your container you'll need the URL - you can get it on the
+`properties` tab of your container as shown below.
+
+![Azure](../../public/media/guides/archiving-requests-to-storage/Untitled.png)
+
+This URL will be the `blobPath` in our policy options.
+
+Next, we'll need a SAS (Shared Access Secret) to authenticate with Azure. You
+can generate one of these on the `Shared access tokens` tab.
+
+Note, you should minimize the permissions - and select only the `Create`
+permission. Choose a sensible start and expiration time for your token. Note, we
+don't recommend restricting IP addresses because Zuplo runs at the edge in over
+200 data-centers world-wide.
+
+![Create permission](../../public/media/guides/archiving-requests-to-storage/Untitled_1.png)
+
+Then generate your SAS token - copy the token (not the URL) to the clipboard and
+enter it into a new environment variable in your API called `BLOB_CREATE_SAS`.
+You'll need another environment variable called `BLOB_CONTAINER_PATH`.
+
+![SAS token](../../public/media/guides/archiving-requests-to-storage/Untitled_2.png)

package/docs/policies/archive-response-azure-storage-outbound/intro.md

@@ -0,0 +1,3 @@
+In this example shows how you can archive the body of outgoing responses to
+Azure Blob Storage. This can be useful for auditing, logging, or archival
+scenarios.

package/docs/policies/archive-response-azure-storage-outbound/policy.ts

@@ -0,0 +1,54 @@
+import { HttpProblems, ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+interface PolicyOptions {
+  blobContainerPath: string;
+  blobCreateSas: string;
+}
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: PolicyOptions,
+) {
+  // NOTE: policy options should be validated, but to keep the sample short,
+  // we are skipping that here.
+
+  // because we will read the body, we need to
+  // create a clone of this response first, otherwise
+  // there may be two attempts to read the body
+  // causing a runtime error
+  const clone = response.clone();
+
+  // In this example we assume the body could be text, but you could also
+  // response the blob() to handle binary data types like images.
+  //
+  // This example loads the entire body into memory. This is fine for
+  // small payloads, but if you have a large payload you should instead
+  // save the body via streaming.
+  const body = await clone.text();
+
+  // let's generate a unique blob name based on the date and requestId
+  const blobName = `${Date.now()}-${context.requestId}.req.txt`;
+
+  const url = `${options.blobContainerPath}/${blobName}?${options.blobCreateSas}`;
+
+  const result = await fetch(url, {
+    method: "PUT",
+    body: body,
+    headers: {
+      "x-ms-blob-type": "BlockBlob",
+    },
+  });
+
+  if (result.status > 201) {
+    const text = await result.text();
+    context.log.error("Error saving file to storage", text);
+    return HttpProblems.internalServerError(request, context, {
+      detail: text,
+    });
+  }
+
+  // Continue the response
+  return response;
+}