Changelog

This release introduces powerful new features for API management including internal route invocation and improved authentication policies.

Breaking Changes 🛠

• Removed the deprecated Aserto authorization policy due to Aserto shutting down. If you're currently using this policy, please migrate to an alternative authorization solution.

New Features 🎉

• Internal Route Invocation: Added context.invokeRoute capability that allows you to internally invoke a route without making an external HTTP request. This enables more efficient internal API calls and better performance for complex routing scenarios.

• Enhanced Client IP Parsing: Improved parsing of client IP addresses from the X-Forwarded-For header, providing more accurate client identification for rate limiting and analytics.

• CLI Log Verbosity Control: Added a new flag to control log verbosity levels in the Zuplo CLI, making debugging and troubleshooting easier during local development.

• Custom Domain Aliases: Introduced support for custom domain aliases, allowing you to map multiple domains to a single API deployment for more flexible domain management.

• Web Bot Authentication: New policy for authenticating and managing web bot traffic, helping you control automated access to your APIs. See the policy docs for more details

• API Key Management Enhancement: You can now delete the default API key, providing more flexibility in API key lifecycle management. See documentation

Bug Fixes 🐛

• Fixed an issue that prevented changing deployments for custom domains.
• Increased the body size limit on GitHub webhooks to support larger payloads.
• Enhanced error handling in mock API policy to support single example responses.

Documentation 📚

• Updated documentation for the Auth0 JWT authentication policy.

This release includes important improvements to error handling, and bug fixes to the GitLab integration. We've also made improvements to our project templates and development tooling.

New Features 🎉

• Improved error messages for invalid module imports - When importing modules incorrectly in your Zuplo project, you'll now receive more helpful and descriptive error messages that make it easier to identify and fix import issues. This enhancement improves the developer experience when working with custom modules and policies.

Bug Fixes 🐛

• Fixed virtual module namespace collisions - Resolved an issue where virtual modules could conflict with each other due to namespace collisions. Virtual modules are now properly namespaced to ensure they work reliably alongside other modules in your project.

• Fixed GitLab integration infinite loop - Corrected a critical issue where fetching from GitLab repositories could cause infinite loops under certain conditions. This fix ensures stable and reliable synchronization with your GitLab repositories when using Zuplo's source control integration.

Documentation 📚

• Added /hello route to project template - The default project template now includes a /hello route example, making it easier for new users to understand how to create and configure routes in their Zuplo API gateway.

Other Changes 🔄

• Zudoku template enhancements - Updated the Zudoku documentation template to properly set Zuplo flags on scripts, ensuring better integration between Zuplo and the Dev Portal.

This release includes improvements to OpenAPI schema reference handling and a fix for the Zuplo CLI login behavior on middleware platforms.

Bug Fixes 🐛

• Improved nested schema reference traversing - Fixed an issue where deeply nested schema references in OpenAPI specifications were not being properly resolved. This enhancement ensures that complex OpenAPI documents with multiple levels of $ref pointers are correctly processed, improving compatibility with sophisticated API specifications.

• Fixed CLI login behavior on middleware platforms - Resolved an issue where the Zuplo CLI would unexpectedly exit after login when running on certain middleware platforms. The CLI now properly maintains the session after successful authentication, ensuring a smooth development experience.

This release introduces improved support for special characters in OpenAPI URL paths, adds redirect functionality to the URL forward handler, and includes important compatibility date changes that affect log initialization.

Breaking Changes 🛠

Breaking changes are always behind a compatibility date

• Enhanced support for special characters in OpenAPI URL paths - Zuplo now properly handles special characters in OpenAPI-formatted URL paths, improving compatibility with APIs that use non-standard characters in their routes. This change ensures better compliance with OpenAPI specifications and more flexible path matching. See our advanced path matching documentation for more details.

• Legacy log initialization removed for compatibility date 2025-02-06 - Starting with compatibility date 2025-02-06, the legacy log initialization system has been removed in favor of the modern logging infrastructure. This change provides better performance and more consistent logging behavior across your API gateway.

New Features 🎉

• URL forward handler now supports redirects - The URL forward handler has been enhanced with a new option to handle HTTP redirects. This feature allows you to configure whether the handler should follow redirects automatically or return the redirect response to the client, giving you more control over how your API gateway handles upstream redirect responses.

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.