Managed Dedicated: Host Header Override

By default, the Host header your gateway sends to a backend is derived from the URL it connects to. Host header override lets your code send a Host header that differs from the hostname in the request URL, so the gateway can connect to one address while the backend sees the hostname it expects.

This setting is only available on Managed Dedicated instances and is off by default.

When to use it

Reach for this when the address you connect to and the hostname your backend expects aren't the same:

• Virtual-hosted backends. A single load balancer, ingress controller, or web server hosts several sites and picks one based on the Host header. Your gateway connects to the shared address and names the site it wants.
• Private networking. With private networking, you reach a backend through an internal endpoint or IP whose DNS name doesn't match the public hostname the backend is configured for, such as https://10.0.4.12 with a Host of api.acme.com.
• Testing a new backend before DNS moves. Point the gateway at the new origin's address while sending the production Host header, so you can validate the migration without changing public DNS.
• Legacy backends keyed on the hostname. Applications that route, build links, or select a tenant from the Host header keep working when the gateway sits in front of them.

Enable the setting

Add allowHostHeaderOverride to the zuplo.jsonc file at the root of your project and deploy:

Code
{
  "version": 1,
  "projectType": "managed-dedicated",
  "allowHostHeaderOverride": true,
}

The setting applies to the whole project. Without it, a Host header you set on an outbound request is ignored.

Example

Once the setting is enabled, set the Host header on any outbound request. This custom handler connects to an internal load balancer and tells it which site to serve:

Code
import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const url = new URL(request.url);

  return fetch(`${environment.INTERNAL_ORIGIN}${url.pathname}${url.search}`, {
    method: request.method,
    body: request.body,
    headers: {
      ...Object.fromEntries(request.headers),
      Host: "api.acme.com",
    },
  });
}

With INTERNAL_ORIGIN set to https://10.0.4.12, the gateway connects to 10.0.4.12 and the backend receives a request for api.acme.com.