Zuplo Changelog

The wave of fresh logging plugins continues this week with the addition of Splunk. Now available for use direct from your Zuplo API project.

To add the Splunk logging plugin to your Zuplo project, add the following code to your zuplo.runtime.ts file. Set the url parameter to your Splunk HEC endpoint and the token parameter to your Splunk HEC token.

import {
  RuntimeExtensions,
  SplunkLoggingPlugin,
  environment,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new SplunkLoggingPlugin({
      // For Splunk Cloud
      url: "https://<your-instance>.splunkcloud.com:8088/services/collector",
      token: environment.SPLUNK_TOKEN,
      // Channel ID for Splunk HEC with indexer acknowledgment
      channel: "FE0ECFAD-13D5-401B-847D-77833BD77131",
      // Optional parameters with defaults
      index: "main",
      sourcetype: "json",
      host: "zuplo-api",
      fields: {
        environment: "production",
        application: "my-api",
      },
    }),
  );
}

As with all our loggers, the Splunk Plugin supports custom fields via the fields object, in addition to the standard fields.

Full details can be found in the documentation.

We have added the ability to specify redirect behavior for the URL Forward handler using a new forwardRedirects option.

You can implement this manually from routes.oas.json in your Zuplo project by adding it to the options object for urlForwardHandler on any route you want to use it on.

"paths": {
  "/v1/links": {
    "x-zuplo-path": {
      "pathMode": "open-api"
    },
    "get": {
      "summary": "Gets a list of links",
      "x-zuplo-route": {
        "corsPolicy": "none",
        "handler": {
          "export": "urlForwardHandler",
          "module": "$import(@zuplo/runtime)",
          "options": {
            "baseUrl": "${env.BASE_URL}",
            "forwardRedirects": true
          }
        },
        "policies": {
          "inbound": []
        }
      }
    }
  }
}

When set to false or not specified, redirects won't be followed - the status and location header will be returned as received.

We’ve introduced a new default compatibility date for projects created after
March 27, 2025, which includes some breaking changes that improve the overall behavior of Zuplo APIs.

The new default compatibility date is 2025-02-06.

Previously, special characters in open-api formatted URLs were not escaped. This led to unintended behavior where regex patterns could be included, even though OpenAPI format URLs don’t support regex. This has now been fixed—all special characters are escaped.

Additionally, some Zuplo log plugins could be enabled using undocumented environment variables and special properties on context.custom to set global log attributes.

These legacy features, which predate the current plugin system, have now been removed.

Log plugins should now be enabled using the documented plugin system.

For full details on compatibility dates and the changes they include, see our documentation.

We've expanded our range of third-party logging plugins yet again—this time with the addition of New Relic.

Full details can be found in the documentation, but usage follows the same pattern as all the other loggers.

Add the plugin to the Zuplo runtime and configure your options.

import {
  RuntimeExtensions,
  NewRelicLoggingPlugin,
  environment,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new NewRelicLoggingPlugin({
      // Optional, defaults to "https://log-api.newrelic.com/log/v1"
      url: "https://log-api.newrelic.com/log/v1",
      apiKey: environment.NEW_RELIC_API_KEY,
      service: "MyAPI", // Optional, defaults to "Zuplo"
      fields: {
        field1: "value1",
        field2: "value2",
      },
    }),
  );
}

As with all our loggers, the New Relic Plugin supports custom fields in addition to the standard fields.

The new Pre-Routing Hook allows you to manipulate an incoming request before it's checked for routing. For example, if you want all routes to be case insensitive you could just lowercase the URL as it comes into the gateway, as shown below:

runtime.addPreRoutingHook(async (request) => {
  const nr = new Request(request.url.toLowerCase(), request);
  return nr;
});

Another example would be URL path normalization to remove trailing slashes:

runtime.addPreRoutingHook(async (request) => {
  const url = new URL(request.url);
  if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
    url.pathname = url.pathname.slice(0, -1);
    const nr = new Request(url, request);
    return nr;
  }
  return request;
});

Keep in mind that this will run on all requests so the code you use here needs to be appropriately performant and aware it can generate weird downstream effects by changing URLs and headers.

The method is async but reading and manipulating the request body is not recommended for performance reasons.

A new fields option is now available across all logging plugins. This addition enables you to append arbitrary custom fields to each log entry, providing additional context and information in your logs.

For example, using our Google Cloud Logging plugin:

import {
  RuntimeExtensions,
  GoogleCloudLoggingPlugin,
  environment,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new GoogleCloudLoggingPlugin({
      logName: "projects/my-project/logs/my-api",
      serviceAccountJson: environment.GCP_SERVICE_ACCOUNT,
      fields: {
        myCustomField: "value",
        anotherCustomField: "value2",
      },
    }),
  );
}

You can use this feature to include relevant metadata, application-specific details, or contextual information that may be useful for debugging or analysis purposes.