Mocking third-party APIs

Answering requests to another host

Put io:host on the first <script type=worker> of the page. The worker is then called for every request that the output makes to one of the listed hosts: fetch(), XHR, EventSource, images, scripts and styles. Inside the handler, request.url is the original URL on the other host, and request.rt is attached as usual. Requests made with fetch() keep their method, headers and body.

A script without edge runs only in the playground, which is where a mock belongs.

<pre id=profile></pre>
<script type=module>
  profile.textContent = JSON.stringify(await fetch('https://api.example.com/v1/users/7').then(r => r.json()))
</script>
<script type=worker io:host=api.example.com>
  export default {
    fetch: async request => {
      const { pathname } = new URL(request.url)
      if (pathname.startsWith('/v1/users/')) return Response.json({ id: +pathname.split('/').at(-1), name: 'Ada' })
    }
  }
</script>

Choosing hosts

io:host is a space-separated list. The editor lowercases it, collapses whitespace and removes duplicates, and the service worker turns each token into a host with new URL('https://' + token).host. That converts internationalized names to punycode, drops :443 and keeps other ports. Tokens that cannot be parsed are dropped, and so is an empty value.

A request matches when its host, with its port, is equal to a token, or when a token is *.

Write hosts without trailing dots. For http:// requests, a :80 token does not match, because the host of such a request omits the port.

Answering and passing through

• Return a Response to answer the request. The page receives it as if the other host had sent it.
• Return nothing (undefined) to let the request go on to the real host unchanged. Use this for every request you do not mock.
• Do not return anything else. A truthy value that is not a Response, such as a string, makes the page see a network error.

Avoid mocking URLs whose path contains a :. The playground treats that colon like the worker prefix, so the worker sees a shortened path: a request for https://api.example.com/v1/x:batch arrives as https://api.example.com/batch.

Failing open or closed

io:fail on the first worker script decides what happens when the worker fails. Only the exact value open turns fail-open on. Any other value, an empty one or a different case included, means closed, which is the default.

Failures are logged to the playground console as console.error with the 🛎️⚙️ prefix. ☁️ marks the closed mode and ⛅ the open mode, followed by a stack. Throw Error objects: other values are not logged reliably. The line numbers in the stack are approximate and are not editor line numbers.

<script type=worker io:host=api.stripe.com io:fail=open>
  export default { fetch: r => new Response(undefined.url) }
</script>
<script type=module>
  console.log(await fetch('//api.stripe.com/v1/charges').then(r => r.status))
</script>

Mocks next to your own API

All worker scripts of a page form one program, and only the first script's io:host and io:fail count. A page that has its own edge worker therefore needs one handler for both jobs: put io:host on the first, edge script, and branch on the host. RTEdge.net ignores io:host, and an edge worker only receives requests for its own route, so the mock branch never runs there.

<pre id=out></pre>
<script type=module>
  const user = await fetch('https://api.example.com/v1/users/7').then(r => r.json())
  const mine = await fetch(':stats').then(r => r.json())
  out.textContent = JSON.stringify({ user, mine }, null, 2)
</script>
<script type=worker edge io:host=api.example.com>
  export default {
    fetch: async request => {
      const { host, pathname } = new URL(request.url)
      if (host === 'api.example.com') return pathname.startsWith('/v1/users/') ? Response.json({ id: 7, name: 'Ada' }) : undefined
      return Response.json({ where: request.rt.edge ? 'edge' : 'playground' })
    }
  }
</script>

Pitfalls

• Outbound requests that your worker makes are browser fetches. CORS applies to cross-origin reads, headers such as Cookie, Host and User-Agent cannot be set, and credentials default to same-origin. An API that works from an edge worker can therefore fail from a playground worker.
• Write export default { fetch } in the form that the transform supports, keep a single export default across all worker scripts, and end the script with a line break.
• Do not leave the worker empty while an output is open; see Module scope and state.

See also

• <script type=worker>
• The fetch() handler
• Request.rt
• Using workers
• Playground and edge differences
• Console and network