Moovweb XDN Documentation

Cookbook

This guide gives examples of common routing patterns using the XDN.

Proxying a backend

Same Path

To forward a request to the same path to one of the backends listed in xdn.config.js use the proxy method of ResponseWriter:

router.get('/some-path', ({ proxy }) => {
  proxy('origin')
})

The first argument corresponds to the name of a backend in xdn.config.js. For example:

module.exports = {
  backends: {
    origin: {
      domainOrIp: 'my-shop.myshopify.com',
      hostHeader: 'my-shop.myshopify.com',
    },
  },
}

Different Path

To forward the request to a different path use the path option of the ProxyOptions interface:

router.get('/products/:productId', ({ proxy }) => {
  proxy('origin', { path: '/p/:productId' })
})

Adding Caching

To cache proxied requests at the edge, use the cache method.

router.get('/products/:productId', ({ proxy }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24           // keep entries in the cache for 24 hours
      staleWhileRevalidateSeconds: 60 * 60  // when a cached page is older than 24 hours, serve it one more time
                                            // for up to 60 minutes while fetching a new version from the origin
    }
  })
  proxy('origin')
})

Altering the request

You can alter request headers when forwarding a request to a backend:

router.get(
  '/products/:productId',
  ({ setRequestHeader, updateRequestHeader, removeRequestHeader, proxy }) => {
    setRequestHeader('header-name', 'header-value')
    updateRequestHeader('header-name', /some-.*-part/gi, 'some-replacement')
    removeRequestHeader('header-name')
    proxy('origin')
  },
)

The above example makes use of setRequestHeader, updateRequestHeader, and removeRequestHeader API calls.

Altering the response

You can also alter the response before and after the cache:

router.get(
  '/products/:productId',
  ({
    setUpstreamResponseHeader,
    setResponseHeader,
    removeResponseHeader,
    removeUpstreamResponseHeader,
    updateResponseHeader
    updateUpstreamResponseHeader
    proxy,
  }) => {
    proxy('origin')

    // applied before the cache
    setUpstreamResponseHeader('header-name', 'header-value')
    updateUpstreamResponseHeader('header-name', /some-.*-part/gi, 'some-replacement')
    removeUpstreamResponseHeader('header-name')

    // applied after the cache
    setResponseHeader('header-name', 'header-value')
    updateResponseHeader('header-name', /some-.*-part/gi, 'some-replacement')
    removeResponseHeader('header-name')
  },
)

Altering all responses

You can also write catch-all routes that will alter all responses. One example where this is useful is injecting Content Security Policy headers.

Another example is adding response headers for debugging, which is often useful if XDN is behind another CDN or if you are troubleshooting your router rules. For example, you could respond with the value of request x-forwarded-for into x-debug-xff to see the value that XDN is receiving from the CDN:

router.match(
  {
    path: '/:path*',
    query: {
      my_site_debug: 'true',
    },
  },
  ({ setResponseHeader }) => {
    setResponseHeader('x-debug-xff', '${req:x-forwarded-for}')
  },
)
// The rest of your router...

The rules for interpolating the values of request and response objects can be found in the routing guide. Note that catch-all routes that alter headers, cookies, or caching can be placed at the start of your router while allowing subsequent routes to run because they alter the request or the response without actually sending a response. See route execution for more information on route execution order and sending responses.

Manipulating Cookies

You can manipulate cookies before they are sent to the browser using cookie response API calls like addResponseCookie:

router.get('/some/path', ({
  setUpstreamResponseCookie,
  addResponseCookie,
  removeResponseCookie,
  removeUpstreamResponseCookie,
  updateResponseCookie
  updateUpstreamResponseCookie,
  proxy
}) => {
  proxy('origin')

  // applied before the cache
  addUpstreamResponseCookie('cookie-to-add', 'cookie-value')
  removeUpstreamResponseCookie('cookie-to-remove')
  updateUpstreamResponseCookie('cookie-to-alter', /Domain=.+;/, 'Domain=mydomain.com;')

  // applied after the cache
  addResponseCookie('cookie-to-add', 'cookie-value')
  removeResponseCookie('cookie-to-remove')
  updateResponseCookie('cookie-to-alter', /Domain=.+;/, 'Domain=mydomain.com;')
})

Serving a static file

To serve a specific file use the serveStatic API:

router.get('/favicon.ico', ({ serveStatic, cache }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24, // cache at the edge for 24 hours
    },
    browser: {
      maxAgeSeconds: 60 * 60 * 24, // cache for 24 hours
    },
  })
  serveStatic('assets/favicon.ico') // path is relative to the root of your project
})

To serve all files in a directory tree under a specific path prefix:

router.get('/assets/:path*', ({ serveStatic, cache }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24, // cache at the edge for 24 hours
    },
    browser: {
      maxAgeSeconds: 60 * 60 * 24, // cache for 24 hours
    },
  })
  serveStatic('assets/:path*')
})

Responding with a string response body

To respond with a simple, constant string as the response body use the send method:

router.get('/some-path', ({ cache, setResponseHeader, send }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24, // cache for 24 hours
    },
  })
  setResponseHeader('Content-Type', 'text/html')
  send(`
    <!doctype html>
    <html>
      <body>Hello World</body>
    </html>
  `)
})

To compute a dynamic response use the compute method:

router.get('/hello/:name', ({ cache, setResponseHeader, compute, send }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24, // cache for 24 hours
    },
  })
  setResponseHeader('Content-Type', 'text/html')
  compute((request, response) => {
    send(`
      <!doctype html>
      <html>
        <body>Hello ${request.params.name}</body>
      </html>
    `)
  })
})

Redirecting

To redirect the browser to a different URL use the redirect API:

router.get('/p/:productId', ({ redirect }) => {
  return redirect('/products/:productId', 301) // overrides the default status of 302 (Temporary Redirect)
})

If you need to compute the destination with sophisticated logic:

router.get('/p/:productId', ({ redirect, compute, cache }) => {
  cache({
    edge: {
      maxAgeSeconds: 60 * 60 * 24, // cache for 24 hours
    },
  })
  compute(async request => {
    const destination = await getDestinationFromMyAPI(request.params.productId)
    redirect(destination)
  })
})

Redirecting all traffic to a different domain

This example redirects all traffic from www.mysite.com to mysite.com. It should be placed at the top of your router:

router.match({ headers: { host: /^www\.mysite\.com$/, path: '/:path*' } }, ({ redirect }) => {
  redirect('https://mysite.com/:path*')
})

Blocking unwanted traffic

Blocking traffic from specific countries

If you need to block all traffic from a specific country or set of countries, you can do so by matching requests by the country code geolocation header:

router.get(
  {
    headers: {
      'x-xdn-geo-country-code': /XX|XY|XZ/, // Regex matching two-letter country codes of the countries you want to block
    },
  },
  ({ send }) => {
    send('Blocked', 403)
  },
)

You can find more about geolocation headers here.