counterfact 0.14.0 → 0.15.0

package/.vscode/settings.json

@@ -15,5 +15,14 @@
   "[typescript]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
-  "cSpell.words": ["bodyparser", "counterfact", "openapi", "transpiles"]
+  "cSpell.words": [
+    "bodyparser",
+    "counterfact",
+    "Deno",
+    "openapi",
+    "Petstore",
+    "counterfactuals",
+    "openapi",
+    "transpiles"
+  ]
 }

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # counterfact
 
+## 0.15.0
+
+### Minor Changes
+
+- 78c0c31: return $.proxy(url) to proxy to another server
+- 6bf3d42: $context.ts -> $.context.ts
+- 7c2893a: change rapidoc configuration to show paths in the nav bar
+- 033c067: new landing page with links to Rapidoc and Swagger UI
+- 6bf3d42: improve and document the REPL
+
+### Patch Changes
+
+- a2d6bf0: always start the server regardless of which command line options are present
+- 4a96dfa: fix crash when a path is not found
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -1,75 +1,126 @@
+<div align="center" markdown="1">
 
+# Counterfact is the mock server that front end engineers need to be productive
 
-<div align="center" markdown="1">
+[Quick Start](./docs/quick-start.md) | [Documentation](./docs/usage.md) | [Contributing](CONTRIBUTING.md)
 
-# Counterfact
+</div>
 
-_Front end development without back end headaches_
+<br>
 
-[Quick Start](#quick-start) | [Documentation](./docs/usage.md) | [Contributing](CONTRIBUTING.md)
+<div align="center"  markdown="1">
 
-Counterfact is a stand-in REST server powered by Node, TypeScript, and OpenAPI.<br>
-It enables you to write front end code and test UX flows without a complete back end.
+[![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpmcelhaney%2Fcounterfact%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/pmcelhaney/counterfact/main) ![MIT License](https://img.shields.io/badge/license-MIT-blue)
 
 </div>
 
-<br>
+## Features
 
-<table align="center" cols="2"  markdown="1">
+- Supports JavaScript and TypeScript
+- Runs on Node, Deno, and Bun
+- Uses Swagger / OpenAPI if you have it
+- File system based routing
+- Hot reload server-side code
+- Manipulate test data with a REPL
+- Toggle between the mock and real backend at runtime
+- Works with any “front end” that calls RESTful services (a React app, a native iOS app, a web service, etc.)
+- Emulates the real back end, but 100X faster
 
-<tr>
-<td>
+## Use Cases
 
-💪 build the UI before the API or build both in parallel<br>
-🏎️ quickly and cheaply prototype UX workflows<br>
-🎉 turn OpenAPI docs into functional code
+- Rapidly iterate on the front end without waiting for back end features or changes
+- Reproduce bugs when the conditions on the server side are hard to replicate
+- Test against a private, local stack that you fully control
+- Write contract tests for APIs
 
-</td>
+Unlike similar tools, Counterfact is not limited to canned or randomly generated responses. It can mimic as much or as little of the business logic in your n-tier / cloud-native back end as you want. Test end-to-end scenarios in your front end code as if a lighting-fast implementation of the real backend is running on your machine. Because it is.
 
-<td>
+As a front end dev, when you have **complete and granular control over the back end**, and you can **modify anything on a whim**, it **enhances your developer experience** in ways that are hard to describe.
 
-⛓️ write fast, repeatable UI integration tests<br>
-🧑‍🔬 test UI code against hard-to-recreate edge cases<br>
-🔌 plug into your existing toolchain
+## What does the code look like?
 
-</td>
+<details markdown="1">
 
-</tr>
+<summary><code>GET /hello/world</code></summary>
 
-</table>
+```js
+// ./paths/hello/world.js
+export const GET = () => "Hello World!";
+```
 
-<div align="center"  markdown="1">
+</details>
 
-[![Coverage Status](https://coveralls.io/repos/github/pmcelhaney/counterfact/badge.svg)](https://coveralls.io/github/pmcelhaney/counterfact) [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpmcelhaney%2Fcounterfact%2Fmain)](https://dashboard.stryker-mutator.io/reports/github.com/pmcelhaney/counterfact/main) ![MIT License](https://img.shields.io/badge/license-MIT-blue)
+<details>
 
+<summary markdown="1">Using the <a href="https://petstore3.swagger.io">Swagger Petstore</a> as an example, here’s one way to implement <code>GET /pet/{petId}`</code> and <code>POST `POST /pets`</code>.</summary>
 
-</div>
+```js
+// ./paths/pet/{petId}.js
+export const GET = ({ context, response, path }) => {
+  const pet = context.getPetById(path.petId);
 
-<h2 id="quick-start">Got 60 Seconds? Try me!</h2>
+  if (!pet) {
+    return response[404].text(`Pet with ID ${path.petID} not found.`);
+  }
 
-Copy the following command into your terminal. The only prerequisite is Node 16+.
+  return response[200].json(pet);
+};
+```
 
-```sh copy
-npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --open
+```js
+// ./paths/pets.js
+export const POST = ({ context, response, body }) => {
+  const pet = context.addPet(body);
+
+  return response[200].json(pet);
+};
 ```
 
-<details>
-<summary>What does that command do?</summary>
+```js
+// ./paths/$.context.js
+class PetStore () {
+    pets = {};
+
+    getPetById(petId) {
+        return pets[id];
+    }
 
-1. installs the `@latest` version of `counterfact`
-2. reads an [OpenAPI 3](https://oai.github.io/Documentation/) document (`https://petstore3.swagger.io/api/v3/openapi.json`)
-3. generates TypeScript files in the `api` directory
-4. starts a server which implements the API
-5. opens your browser to [Swagger UI](https://swagger.io/tools/swagger-ui/) (`--open`)
+    addPet(pet) {
+        this.pets[pet.id] = pet;
+    }
+}
 
-You can use Swagger to try out the auto-generated API. Out of the box, it returns random responses using metadata from the OpenAPI document. Edit the files under `./api/paths` to add more realistic behavior. There's no need to restart the server.
+export default new PetStore();
+```
 
 </details>
 
-<br>
+## If you have a Swagger / OpenAPI spec, you'll be up and running in seconds
+
+For example, run the following command to generate code for the Swagger Petstore.
+
+```sh copy
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --open
+```
 
-📗 See [Usage](./docs/usage.md) for detailed documentation.
+That command generates and starts a TypeScript implementation of the Swagger Petstore which returns random, valid responses. Not too shabby for _a few seconds of work_!
+
+## It's your server. Do whatever you want with it.
+
+Edit the code under `./api/paths` to **implement real behavior**, as we did in the JavaScript examples above. Store and retrieve data, perform calculations, filter / sort / paginate, whatever it takes the make the API real enough to support the development and testing of your front end.
+
+- Use autocomplete as documentation. For example, when you're working on an operation that takes query parameters, type "`$.query.`" to list all of the available parameters.
+- Stay in sync with changes in your OpenAPI / Swagger document. Counterfact will keep the type definitions up to date without overwriting your work.
+- Get immediate feedback. Modules are hot reloaded so changes apply immediately without restarting the server or resetting its state.
+- Interact with the running server using a REPL. For example, type `context.addPet({id: 2, name: "Fido"})` to add a pet to the store. Then view the pet you just added at `http://localhost:3100/pet/2`.
+- Much more!
+
+See the [Usage Guide](./docs/usage.md) for details.
 
 ---
 
-Counterfact is brand new as of October 5, 2022. Please send feedback / questions to pmcelhaney@gmail.com or [create a new issue](https://github.com/pmcelhaney/counterfact/issues/new). If you like what you see, please give this project a star!
+Counterfact is brand new as of November 30, 2022. Please send feedback / questions to pmcelhaney@gmail.com or [create a new issue](https://github.com/pmcelhaney/counterfact/issues/new). If you like what you see, please give this project a star!
+
+```
+
+```

package/bin/counterfact.js

@@ -20,32 +20,79 @@ async function main(source, destination) {
   const basePath = nodePath.resolve(nodePath.join(process.cwd(), destination));
 
   const openBrowser = options.open;
-  const includeSwagger = options.swagger || openBrowser;
-  const startServer = options.server || includeSwagger;
 
-  if (startServer) {
-    const { contextRegistry } = await start({
+  const url = `http://localhost:${options.port}`;
+
+  const guiUrl = `${url}/counterfact/`;
+
+  const { contextRegistry } = await start({
+    basePath,
+    port: options.port,
+    openApiPath: source,
+    includeSwaggerUi: true,
+  });
+
+  const waysToInteract = [
+    `Call the REST APIs at ${url} (with your front end app, curl, Postman, etc.)`,
+    `Change the implementation of the APIs by editing files under ${nodePath.join(
       basePath,
-      port: options.port,
-      openApiPath: source,
-      includeSwaggerUi: includeSwagger,
-    });
+      "paths"
+    )} (no need to restart)`,
+    `Use the GUI at ${guiUrl}`,
+    "Use the REPL below (type .counterfact for more information)",
+  ];
 
-    process.stdout.write(
-      `API is running at http://localhost:${options.port}.\n`
-    );
+  const introduction = [
+    "",
+    "Welcome to Counterfact!",
+    "",
+    "Counterfact is a mock server used to develop and test your front end app.",
+    "There are several ways to poke and prod the server in order to make it behave the way you need for testing.",
+    "",
+  ];
 
-    process.stdout.write(
-      '\n\nStarting REPL... (start with `const context = loadContext("/")`)\n'
-    );
+  process.stdout.write(`${introduction.join("\n")}\n`);
 
-    const replServer = repl.start("> ");
+  process.stdout.write(
+    waysToInteract.map((text, index) => `${index + 1}. ${text}`).join("\n")
+  );
 
-    replServer.context.loadContext = (path) => contextRegistry.find(path);
-  }
+  process.stdout.write("\n\n");
+
+  process.stdout.write("Starting REPL...\n");
+
+  const replServer = repl.start("> ");
+
+  replServer.defineCommand("counterfact", {
+    help: "Get help with Counterfact",
+
+    action() {
+      process.stdout.write(
+        "This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.\n"
+      );
+      process.stdout.write(
+        "Except that it's connected to the running server, which you can access with the following globals:\n\n"
+      );
+      process.stdout.write(
+        "- loadContext('/some/path'): to access the context object for a given path\n"
+      );
+      process.stdout.write(
+        "- context: the root context ( same as loadContext('/') )\n"
+      );
+      process.stdout.write(
+        "\nFor more information, see https://counterfact.dev/docs/usage.html\n\n"
+      );
+
+      this.clearBufferedCommand();
+      this.displayPrompt();
+    },
+  });
+
+  replServer.context.loadContext = (path) => contextRegistry.find(path);
+  replServer.context.context = replServer.context.loadContext("/");
 
   if (openBrowser) {
-    await open(`http://localhost:${options.port}/counterfact`);
+    await open(guiUrl);
   }
 }
 
@@ -56,12 +103,8 @@ program
   )
   .argument("<openapi.yaml>", "path or URL to OpenAPI document")
   .argument("[destination]", "path to generated code", ".")
-  .option("--serve", "start the server after generating code")
   .option("--port <number>", "server port number", DEFAULT_PORT)
-  .option("--swagger", "include swagger-ui (implies --serve)")
-  .option(
-    "--open",
-    "open a browser to swagger-ui (implies --swagger and --serve)"
-  )
+  .option("--swagger", "include swagger-ui")
+  .option("--open", "open a browser")
   .action(main)
   .parse(process.argv);

package/docs/quick-start.md

@@ -0,0 +1,19 @@
+# Got 60 Seconds? Try me!
+
+Copy the following command into your terminal. The only prerequisite is Node 16+.
+
+```sh copy
+npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api --open
+```
+
+## What does that command do?
+
+1. installs the `@latest` version of `counterfact`
+2. reads an [OpenAPI 3](https://oai.github.io/Documentation/) document (`https://petstore3.swagger.io/api/v3/openapi.json`)
+3. generates TypeScript files in the `api` directory
+4. starts a server which implements the API
+5. opens your browser to [Swagger UI](https://swagger.io/tools/swagger-ui/) (`--open`)
+
+You can use Swagger to try out the auto-generated API. Out of the box, it returns random responses using metadata from the OpenAPI document. Edit the files under `./api/paths` to add more realistic behavior. There's no need to restart the server.
+
+To learn more, see the [Usage Guide](./usage.md).

package/docs/usage.md

@@ -117,7 +117,9 @@ Note that each of these objects is typed so you can use autocomplete to identify
 
 The `$.path` parameters are identified by dynamic sections of the path, i.e. `/groups/{groupName}/user/{userId}.ts`.
 
-### Working with state: the `$.context` object and `$context.ts`
+<a id="context-object"></a>
+
+### Working with state: the `$.context` object and `$.context.ts`
 
 There's one more parameter we need to explore, the `$.context` object. It stands in for microservices, databases, and other entities with which the real API interacts. It looks something like this:
 
@@ -137,7 +139,7 @@ export const POST: HTTP_POST = ($) => {
  };
 ```
 
-The `context` object is defined in `$context.js` in the same directory as the file that uses it. It's up to you to define the API for a context object. For example, your `$context.js` file might look like this.
+The `context` object is defined in `$.context.js` in the same directory as the file that uses it. It's up to you to define the API for a context object. For example, your `$.context.js` file might look like this.
 
 ```ts
 class PetStore {
@@ -157,7 +159,7 @@ class PetStore {
 export default new PetStore();
 ```
 
-By default, each `$context.ts` delegates to its parent directory, so you can define one context object in the root `$context.ts` and use it everywhere.
+By default, each `$.context.ts` delegates to its parent directory, so you can define one context object in the root `$.context.ts` and use it everywhere.
 
 > You can make the context objects do whatever you want, including things like writing to databases. But remember that Counterfact is meant for testing, so holding on to data between sessions is an anti-pattern. Keeping everything in memory also makes it fast.
 
@@ -174,23 +176,61 @@ Hot reloading supports one of Counterfact's key design goals. While developing a
 
 In such cases, we want to be sure the front end code responds appropriately. Getting a real server to do what we need to test front end code is usually difficult if not impossible. Counterfact is optimized to make bending the server's behavior to suit a test case as painless as possible, in both manual and automated tests.
 
+## REPL without a Pause ⏯
+
+Another way to explore counterfactuals in real time is to interact with the running server via the read-eval-print loop (REPL), in the same way that you interact with running UI code in your browser's developer tools console. If you look in the terminal after starting Counterfact you should see a prompt like this:
+
+```txt
+Welcome to Counterfact!
+
+Counterfact is a mock server used to develop and test your front end app.
+There are several ways to poke and prod the server in order to make it behave the way you need for testing.
+
+1. Call the REST APIs at http://localhost:3100 (with your front end app, curl, Postman, etc.)
+2. Change the implementation of the APIs by editing files under /Users/pmcelhaney/code/counterfact/out/paths (no need to restart)
+3. Use the GUI at http://localhost:3100
+4. Use the REPL below (type .counterfact for more information)
+
+>
+```
+
+At the `> ` prompt, you can enter JavaScript code to interact with the live [context object](#context-object). For example, here's a quick way to add a pet to the store.
+
+```js
+context.addPet({ name: "Fluffy", photoUrls: [] });
+```
+
+Or add 100 pets:
+
+```js
+for (i = 0; i < 100; i++) context.addPet({ name: `Pet ${i}`, photoUrls: [] });
+```
+
+Or get a list of pets whose names start with "F"
+
+```js
+context.pets.find((pet) => pet.name.startsWith("F"));
+```
+
+Using the REPL is a lot faster (and more fun) than wrangling config files and SQL and whatever else it takes to a real back end into the states you need to test your UI flows.
+
 ## No Cap Recap 🧢
 
-That's everything you need to know about Counterfact. Using convention over configuration and automatically generated types, it allows front-end developers to quickly build fake REST APIs for prototype and testing purposes.
+Using convention over configuration and automatically generated types, Counterfact allows front-end developers to quickly build fake REST APIs for prototype and testing purposes.
 
 - Given an OpenAPI document, you can generate working TypeScript code and start up a server in seconds.
 - By default, the server returns random responses based on metadata in the OpenAPI document (e.g. it uses examples where provided).
 - Each endpoint is represented by a TypeScript file where the path to the file corresponds to the path of the endpoint.
 - You can change the implementation at any time by changing these files.
 - You can and should commit the generated code to source control. Files you change will not be overwritten when you start the server again. (The _types_ will be updated if the OpenAPI document changes, but you shouldn't need to edit the type definitions by hand.)
-- Put behavior in `$context.ts` files. These are created for you, but you should rewrite them to suit your needs. (At least update the root `$context.ts` file.)
+- Put behavior in `$.context.ts` files. These are created for you, but you should rewrite them to suit your needs. (At least update the root `$.context.ts` file.)
+- Use the REPL to manipulate the server's state at runtime
 
 ## We're Just Getting Started 🐣
 
-"Advanced" features are coming soon:
+More features are coming soon:
 
 - Integrate Counterfact into your workflow (Express, Koa, Webpack Dev Server, etc.)
-- Use a REPL to interact with the context objects while the server is running
 - Use Counterfact in your automated tests
 - Record API calls while testing the front end manually and reuse those calls in automated tests (ala [Playwright](https://playwright.dev/))
 - Use [HAR](https://toolbox.googleapps.com/apps/har_analyzer/) files to recreate scenarios / bugs encountered by real users

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "counterfact",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "a library for building a fake REST API for testing",
   "type": "module",
   "main": "./src/server/counterfact.js",
@@ -41,7 +41,7 @@
     "@stryker-mutator/jest-runner": "6.3.0",
     "@types/koa": "2.13.5",
     "@types/koa-static": "^4.0.2",
-    "eslint": "8.27.0",
+    "eslint": "8.28.0",
     "eslint-config-hardcore": "25.1.0",
     "eslint-formatter-github-annotations": "0.1.0",
     "eslint-import-resolver-typescript": "^3.2.5",
@@ -61,6 +61,7 @@
     "@types/json-schema": "^7.0.11",
     "chokidar": "^3.5.3",
     "commander": "^9.4.0",
+    "fetch": "^1.1.0",
     "fs-extra": "^10.1.0",
     "handlebars": "^4.7.7",
     "js-yaml": "^4.1.0",
@@ -69,6 +70,7 @@
     "jsonwebtoken": "^8.5.1",
     "koa": "^2.13.4",
     "koa-bodyparser": "^4.3.0",
+    "koa-proxy": "^1.0.0-alpha.3",
     "koa2-swagger-ui": "^5.6.0",
     "node-fetch": "^3.2.10",
     "open": "^8.4.0",

package/src/client/index.html.hbs

@@ -3,37 +3,43 @@
   <head>
     <title>Counterfact</title>
     <meta charset="utf-8">
-    <meta name="description" content="Counterfact dashboard" />
+    <meta name="description" content="Counterfact Dashboard" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
 
-
-     
-  </head>
+    <style type="text/css">
+        body { 
+            font-family: Helvetica, Arial, sans-serif;
+            max-width: 800px;
+            margin: 0 auto;
+        }
+    </style>
   <body>
 
+    <h1>Counterfact</h1>
 
+    <p>
+        This server implements the OpenAPI spec at <a href="{{openApiHref}}">{{openApiPath}}</a>. 
+        You can try it out using your favorite REST client (curl, Postman, etc.) or browse the interactive API documentation in <a href="./swagger">Swagger UI</a> or <a href="./rapidoc">Rapidoc</a>. 
 
-     <rapi-doc spec-url = "/counterfact/openapi"> 
+    </p>
 
-      <div slot="overview" style="background-color: #eee">
-        <p>Put an explanation of Counterfact here.</p>
-         <a
-            href="https://github.com/pmcelhaney/counterfact/blob/main/docs/usage.md#generated-code-"
-            >How does this work?</a
-          > 
-      </div>
-      {{#each routes as |route|}}
-        <a slot="get-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
-        <a slot="put-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
-        <a slot="post-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
-        <a slot="delete-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
-        <a slot="patch-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+    <p>
+        The TypeScript code for each path can be found under <code>{{basePath}}</code>. 
+        Click on a path below to edit its corresponding TypeScript file in VSCode.
+        For more information, see the <a href="https://counterfact.dev/docs/usage.html">usage guide</a>.
+    </p>
+    
+    <ul>
+    {{#each routes as |route|}}
+        <li><a href="vscode://file/{{../basePath}}/paths/{{route}}.ts">{{route}}</a></li>
+    {{/each}}
+    </ul>
 
-      {{/each}}
-      </rapi-doc>
 
+    <hr>
 
+    <p>👋 Thanks for trying <a href="https://github.com/pmcelhaney/counterfact/">Counterfact</a>! Let me know how it goes at <a href="mailto:pmcelhaney@gmail.com">pmcelhaney@gmail.com</a> or <a href="https://github.com/pmcelhaney/counterfact/issues/new">Github</a> - <a href="https://patrickmcelhaney.com">Patrick</a></p>
 
+  
   </body>
 </html>

package/src/client/rapi-doc.html.hbs

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Counterfact</title>
+    <meta charset="utf-8">
+    <meta name="description" content="Rapidoc" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+  </head>
+  <body>
+
+
+
+     <rapi-doc spec-url="/counterfact/openapi" show-method-in-nav-bar="as-colored-block" nav-active-item-marker="left-bar" use-path-in-nav-bar="true"> 
+
+      <div slot="overview" style="background-color: #eee">
+        <p>Put an explanation of Counterfact here.</p>
+         <a
+            href="https://github.com/pmcelhaney/counterfact/blob/main/docs/usage.md#generated-code-"
+            >How does this work?</a
+          > 
+      </div>
+      {{#each routes as |route|}}
+        <a slot="get-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+        <a slot="put-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+        <a slot="post-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+        <a slot="delete-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+        <a slot="patch-{{escape_route route}}" href="vscode://file/{{../basePath}}/paths/{{.}}.ts">Edit in VSCode</a>
+
+      {{/each}}
+      </rapi-doc>
+
+
+
+  </body>
+</html>

package/src/server/dispatcher.js

@@ -1,4 +1,6 @@
 import Accept from "@hapi/accept";
+// eslint-disable-next-line no-shadow
+import fetch, { Headers } from "node-fetch";
 
 import { createResponseBuilder } from "./response-builder.js";
 import { Tools } from "./tools.js";
@@ -30,6 +32,9 @@ function parameterTypes(parameters) {
 export class Dispatcher {
   registry;
 
+  // alias the fetch function so we can mock it in tests
+  fetch = fetch;
+
   constructor(registry, contextRegistry, openApiDocument) {
     this.registry = registry;
     this.contextRegistry = contextRegistry;
@@ -61,6 +66,32 @@ export class Dispatcher {
           method
         )
       ),
+
+      proxy: async (hostOrOptions) => {
+        const options =
+          typeof hostOrOptions === "string"
+            ? { host: hostOrOptions }
+            : hostOrOptions;
+
+        const fetchResponse = await this.fetch(options.host, {
+          method,
+          path,
+          headers: new Headers(headers),
+          query,
+          ...options,
+        });
+
+        const responseHeaders = Object.fromEntries(
+          fetchResponse.headers.entries()
+        );
+
+        return {
+          status: fetchResponse.status,
+          contentType: responseHeaders["content-type"] ?? "unknown/unknown",
+          headers: responseHeaders,
+          body: await fetchResponse.text(),
+        };
+      },
     });
 
     const normalizedResponse = this.normalizeResponse(

package/src/server/koa-middleware.js

@@ -1,12 +1,19 @@
+import koaProxy from "koa-proxy";
+
 const HTTP_STATUS_CODE_OK = 200;
 
-export function koaMiddleware(dispatcher) {
-  return async function middleware(ctx) {
-    const { method, path, body, query } = ctx.request;
+export function koaMiddleware(dispatcher, options = {}, proxy = koaProxy) {
+  return async function middleware(ctx, next) {
+    const { method, path, headers, body, query } = ctx.request;
+
+    if (options.proxyUrl) {
+      return proxy({ host: options.proxyUrl })(ctx, next);
+    }
 
     const response = await dispatcher.request({
       method,
       path,
+      headers,
       body,
       query,
     });
@@ -15,5 +22,7 @@ export function koaMiddleware(dispatcher) {
     ctx.body = response.body;
     ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
     /* eslint-enable require-atomic-updates */
+
+    return undefined;
   };
 }