@travetto/web-http 7.0.0-rc.0

package/README.md

@@ -0,0 +1,343 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/web-http/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web HTTP Server Support
+
+## Web HTTP Server Support
+
+**Install: @travetto/web-http**
+```bash
+npm install @travetto/web-http
+
+# or
+
+yarn add @travetto/web-http
+```
+
+This module provides basic for running [http](https://nodejs.org/api/http.html). [https](https://nodejs.org/api/https.html)  and [http2](https://nodejs.org/api/http2.html) servers, along with support for tls key generation during development.
+
+## Running a Server
+By default, the framework provides a default [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) for [WebHttpServer](https://github.com/travetto/travetto/tree/main/module/web-http/src/types.ts#L19) that will follow default behaviors, and spin up the server.
+
+**Terminal: Standard application**
+```bash
+$ trv web:http
+
+Initialized {
+  manifest: {
+    main: {
+      name: '@travetto-doc/web-http',
+      folder: './doc-exec'
+    },
+    workspace: {
+      name: '@travetto-doc/web-http',
+      path: './doc-exec',
+      mono: false,
+      manager: 'npm',
+      type: 'commonjs',
+      defaultEnv: 'local'
+    }
+  },
+  runtime: {
+    env: 'local',
+    debug: false,
+    production: false,
+    dynamic: false,
+    resourcePaths: [
+      './doc-exec/resources'
+    ],
+    profiles: []
+  },
+  config: {
+    sources: [ { priority: 999, source: 'memory://override' } ],
+    active: {
+      AcceptConfig: { applies: false, types: [] },
+      CacheControlConfig: { applies: true },
+      CompressConfig: {
+        applies: true,
+        supportedEncodings: [ 'br', 'gzip', 'identity', 'deflate' ]
+      },
+      CookieConfig: { applies: true, httponly: true, sameSite: 'lax', path: '/' },
+      CorsConfig: { applies: true },
+      DecompressConfig: {
+        applies: true,
+        supportedEncodings: [ 'br', 'gzip', 'deflate', 'identity' ]
+      },
+      EtagConfig: { applies: true, minimumSize: '10kb' },
+      TrustProxyConfig: { applies: true, ips: [] },
+      WebBodyConfig: {
+        applies: true,
+        limit: '1mb',
+        parsingTypes: {
+          text: 'text',
+          'application/json': 'json',
+          'application/x-www-form-urlencoded': 'form'
+        }
+      },
+      WebConfig: { defaultMessage: true },
+      WebHttpConfig: {
+        httpVersion: '1.1',
+        port: 3000,
+        bindAddress: '0.0.0.0',
+        tls: false
+      },
+      WebLogConfig: { applies: true, showStackTrace: true }
+    }
+  }
+}
+Listening on port { port: 3000 }
+```
+
+### Configuration
+
+**Code: Standard Web Http Config**
+```typescript
+export class WebHttpConfig {
+
+  /**
+   * What version of HTTP to use
+   * Version 2 requires SSL for direct browser access
+   */
+  @EnvVar('WEB_HTTP_VERSION')
+  httpVersion: '1.1' | '2' = '1.1';
+
+  /**
+   * The port to run on
+   */
+  @EnvVar('WEB_HTTP_PORT')
+  port: number = 3000;
+
+  /**
+   * The bind address, defaults to 0.0.0.0
+   */
+  bindAddress: string = '';
+
+  /**
+   * Is TLS active
+   */
+  @EnvVar('WEB_HTTP_TLS')
+  tls?: boolean;
+
+  /**
+   * TLS Keys
+   */
+  @Secret()
+  tlsKeys?: WebSecureKeyPair;
+
+  @Ignore()
+  fetchUrl: string;
+
+  async postConstruct(): Promise<void> {
+    this.tls ??= (this.httpVersion === '2' || !!this.tlsKeys);
+    this.port = (this.port < 0 ? await NetUtil.getFreePort() : this.port);
+    this.bindAddress ||= await NetUtil.getLocalAddress();
+
+    if (!this.tls) {
+      // Clear out keys if ssl is not set
+      this.tlsKeys = undefined;
+    } else if (!this.tlsKeys) {
+      if (Runtime.production) {
+        throw new AppError('Default ssl keys are only valid for development use, please specify a config value at web.ssl.keys');
+      }
+      this.tlsKeys = await WebTlsUtil.generateKeyPair();
+    } else {
+      if (this.tlsKeys.key.length < 100) { // We have files or resources
+        this.tlsKeys.key = (await RuntimeResources.read(this.tlsKeys.key, true)).toString('utf8');
+        this.tlsKeys.cert = (await RuntimeResources.read(this.tlsKeys.cert, true)).toString('utf8');
+      }
+    }
+
+    this.fetchUrl = `${this.tls ? 'https' : 'http'}://${this.bindAddress}:${this.port}`;
+  }
+}
+```
+
+### Creating a Custom CLI Entry Point
+To customize a Web server, you may need to construct an entry point using the [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L85) decorator. This could look like:
+
+**Code: Application entry point for Web Applications**
+```typescript
+import { Env, toConcrete } from '@travetto/runtime';
+import { CliCommand } from '@travetto/cli';
+import { DependencyRegistryIndex } from '@travetto/di';
+import { Registry } from '@travetto/registry';
+import { WebHttpServer, WebHttpConfig } from '@travetto/web-http';
+
+import './config-override.ts';
+
+@CliCommand({ runTarget: true })
+export class SampleApp {
+
+  preMain(): void {
+    Env.TRV_ENV.set('prod');
+    Env.NODE_ENV.set('production');
+  }
+
+  async main() {
+    console.log('CUSTOM STARTUP');
+    await Registry.init();
+    const ssl = await DependencyRegistryIndex.getInstance(WebHttpConfig);
+    ssl.tls = true;
+
+    // Configure server before running
+    const instance = await DependencyRegistryIndex.getInstance(toConcrete<WebHttpServer>());
+    const { complete } = await instance.serve();
+    return complete;
+  }
+}
+```
+
+And using the pattern established in the [Command Line Interface](https://github.com/travetto/travetto/tree/main/module/cli#readme "CLI infrastructure for Travetto framework") module, you would run your program using `npx trv web:custom`.
+
+**Terminal: Custom application**
+```bash
+$ trv web:custom
+
+CUSTOM STARTUP
+Initialized {
+  manifest: {
+    main: {
+      name: '@travetto-doc/web-http',
+      folder: './doc-exec'
+    },
+    workspace: {
+      name: '@travetto-doc/web-http',
+      path: './doc-exec',
+      mono: false,
+      manager: 'npm',
+      type: 'commonjs',
+      defaultEnv: 'local'
+    }
+  },
+  runtime: {
+    env: 'prod',
+    debug: false,
+    production: true,
+    dynamic: false,
+    resourcePaths: [
+      './doc-exec/resources'
+    ],
+    profiles: []
+  },
+  config: {
+    sources: [
+      { priority: 10, source: 'direct' },
+      { priority: 999, source: 'memory://override' }
+    ],
+    active: {
+      AcceptConfig: { applies: false, types: [] },
+      CacheControlConfig: { applies: true },
+      CompressConfig: {
+        applies: true,
+        supportedEncodings: [ 'br', 'gzip', 'identity', 'deflate' ]
+      },
+      CookieConfig: { applies: true, httponly: true, sameSite: 'lax', path: '/' },
+      CorsConfig: { applies: true },
+      DecompressConfig: {
+        applies: true,
+        supportedEncodings: [ 'br', 'gzip', 'deflate', 'identity' ]
+      },
+      EtagConfig: { applies: true, minimumSize: '10kb' },
+      TrustProxyConfig: { applies: true, ips: [] },
+      WebBodyConfig: {
+        applies: true,
+        limit: '1mb',
+        parsingTypes: {
+          text: 'text',
+          'application/json': 'json',
+          'application/x-www-form-urlencoded': 'form'
+        }
+      },
+      WebConfig: { defaultMessage: true },
+      WebHttpConfig: {
+        httpVersion: '1.1',
+        port: 3000,
+        bindAddress: '0.0.0.0',
+        tls: true
+      },
+      WebLogConfig: { applies: true, showStackTrace: true }
+    }
+  }
+}
+Listening on port { port: 3000 }
+```
+
+## Node Web Http Server
+
+**Code: Implementation**
+```typescript
+export class NodeWebHttpServer implements WebHttpServer {
+
+  @Inject()
+  serverConfig: WebHttpConfig;
+
+  @Inject()
+  router: StandardWebRouter;
+
+  @Inject()
+  configService: ConfigurationService;
+
+  async serve(): Promise<WebServerHandle> {
+    const handle = await WebHttpUtil.startHttpServer({ ...this.serverConfig, dispatcher: this.router, });
+    console.log('Initialized', await this.configService.initBanner());
+    console.log('Listening', { port: this.serverConfig.port });
+    return handle;
+  }
+}
+```
+
+Current the [NodeWebHttpServer](https://github.com/travetto/travetto/tree/main/module/web-http/src/node.ts#L13) is the only provided [WebHttpServer](https://github.com/travetto/travetto/tree/main/module/web-http/src/types.ts#L19) implementation.  It supports http/1.1, http/2, and tls, and is the same foundation as used by express, koa, and other popular frameworks.
+
+## Standard Utilities
+The module also provides standard utilities for starting http servers programmatically:
+
+**Code: Web Http Utilities**
+```typescript
+export class WebHttpUtil {
+  /**
+   * Build a simple request handler
+   * @param dispatcher
+   */
+  static buildHandler(dispatcher: WebDispatcher): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+  /**
+   * Start an http server
+   */
+  static async startHttpServer(config: WebHttpServerConfig): Promise<WebServerHandle<HttpServer>>;
+  /**
+   * Create a WebRequest given an incoming http request
+   */
+  static toWebRequest(req: HttpRequest): WebRequest;
+  /**
+   * Send WebResponse to outbound http response
+   */
+  static async respondToServerResponse(webRes: WebResponse, res: HttpResponse): Promise<void>;
+}
+```
+
+Specifically, looking at `buildHandler`,
+
+**Code: Web Http Utilities**
+```typescript
+static buildHandler(dispatcher: WebDispatcher): (req: HttpRequest, res: HttpResponse) => Promise<void> {
+    return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+      const request = this.toWebRequest(req);
+      const response = await dispatcher.dispatch({ request });
+      this.respondToServerResponse(response, res);
+    };
+  }
+```
+
+we can see the structure for integrating the server behavior with the [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative support for creating Web Applications") module dispatcher:
+   *  Converting the node primitive request to a  [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11)
+   *  Dispatching the request through the framework
+   *  Receiving the [WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3) and sending that back over the primitive response.
+
+## TLS Support
+Additionally the framework supports TLS out of the box, by allowing you to specify your public and private keys for the cert.  In dev mode, the framework will also automatically generate a self-signed cert if:
+   *  TLS support is configured
+   *  [node-forge](https://www.npmjs.com/package/node-forge) is installed
+   *  Not running in prod
+   *  No keys provided
+
+This is useful for local development where you implicitly trust the cert. 
+
+TLS support can be enabled by setting `web.http.tls: true` in your config. The key/cert can be specified as string directly in the config file/environment variables.  The key/cert can also be specified as a path to be picked up by [RuntimeResources](https://github.com/travetto/travetto/tree/main/module/runtime/src/resources.ts#L8).

package/__index__.ts

@@ -0,0 +1,5 @@
+export * from './src/config.ts';
+export * from './src/http.ts';
+export * from './src/tls.ts';
+export * from './src/types.ts';
+export * from './src/node.ts';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@travetto/web-http",
+  "version": "7.0.0-rc.0",
+  "description": "Web HTTP Server Support",
+  "keywords": [
+    "web",
+    "http",
+    "server",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/web-http"
+  },
+  "dependencies": {
+    "@travetto/web": "^7.0.0-rc.0"
+  },
+  "peerDependencies": {
+    "@travetto/cli": "^7.0.0-rc.0",
+    "@travetto/test": "^7.0.0-rc.0"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/test": {
+      "optional": true
+    },
+    "@travetto/cli": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Web HTTP Server Support"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,70 @@
+import { Config, EnvVar } from '@travetto/config';
+import { Ignore, Secret } from '@travetto/schema';
+import { AppError, Runtime, RuntimeResources } from '@travetto/runtime';
+import { NetUtil } from '@travetto/web';
+
+import { WebSecureKeyPair } from './types.ts';
+import { WebTlsUtil } from './tls.ts';
+
+/**
+ * Web HTTP configuration
+ */
+@Config('web.http')
+export class WebHttpConfig {
+
+  /**
+   * What version of HTTP to use
+   * Version 2 requires SSL for direct browser access
+   */
+  @EnvVar('WEB_HTTP_VERSION')
+  httpVersion: '1.1' | '2' = '1.1';
+
+  /**
+   * The port to run on
+   */
+  @EnvVar('WEB_HTTP_PORT')
+  port: number = 3000;
+
+  /**
+   * The bind address, defaults to 0.0.0.0
+   */
+  bindAddress: string = '';
+
+  /**
+   * Is TLS active
+   */
+  @EnvVar('WEB_HTTP_TLS')
+  tls?: boolean;
+
+  /**
+   * TLS Keys
+   */
+  @Secret()
+  tlsKeys?: WebSecureKeyPair;
+
+  @Ignore()
+  fetchUrl: string;
+
+  async postConstruct(): Promise<void> {
+    this.tls ??= (this.httpVersion === '2' || !!this.tlsKeys);
+    this.port = (this.port < 0 ? await NetUtil.getFreePort() : this.port);
+    this.bindAddress ||= await NetUtil.getLocalAddress();
+
+    if (!this.tls) {
+      // Clear out keys if ssl is not set
+      this.tlsKeys = undefined;
+    } else if (!this.tlsKeys) {
+      if (Runtime.production) {
+        throw new AppError('Default ssl keys are only valid for development use, please specify a config value at web.ssl.keys');
+      }
+      this.tlsKeys = await WebTlsUtil.generateKeyPair();
+    } else {
+      if (this.tlsKeys.key.length < 100) { // We have files or resources
+        this.tlsKeys.key = (await RuntimeResources.read(this.tlsKeys.key, true)).toString('utf8');
+        this.tlsKeys.cert = (await RuntimeResources.read(this.tlsKeys.cert, true)).toString('utf8');
+      }
+    }
+
+    this.fetchUrl = `${this.tls ? 'https' : 'http'}://${this.bindAddress}:${this.port}`;
+  }
+}

package/src/http.ts

@@ -0,0 +1,145 @@
+import net from 'node:net';
+import http from 'node:http';
+import http2 from 'node:http2';
+import https from 'node:https';
+import { pipeline } from 'node:stream/promises';
+import { TLSSocket } from 'node:tls';
+
+import { WebBodyUtil, WebCommonUtil, WebDispatcher, WebRequest, WebResponse } from '@travetto/web';
+import { BinaryUtil, castTo, ShutdownManager } from '@travetto/runtime';
+
+import { WebSecureKeyPair, WebServerHandle } from './types.ts';
+
+type HttpServer = http.Server | http2.Http2Server;
+type HttpResponse = http.ServerResponse | http2.Http2ServerResponse;
+type HttpRequest = http.IncomingMessage | http2.Http2ServerRequest;
+type HttpSocket = net.Socket | http2.Http2Stream;
+
+type WebHttpServerConfig = {
+  httpVersion?: '1.1' | '2';
+  port: number;
+  bindAddress: string;
+  sslKeys?: WebSecureKeyPair;
+  dispatcher: WebDispatcher;
+  signal?: AbortSignal;
+};
+
+export class WebHttpUtil {
+
+  /**
+   * Build a simple request handler
+   * @param dispatcher
+   */
+  static buildHandler(dispatcher: WebDispatcher): (req: HttpRequest, res: HttpResponse) => Promise<void> {
+    return async (req: HttpRequest, res: HttpResponse): Promise<void> => {
+      const request = this.toWebRequest(req);
+      const response = await dispatcher.dispatch({ request });
+      this.respondToServerResponse(response, res);
+    };
+  }
+
+  /**
+   * Start an http server
+   */
+  static async startHttpServer(config: WebHttpServerConfig): Promise<WebServerHandle<HttpServer>> {
+    const { reject, resolve, promise } = Promise.withResolvers<void>();
+
+    const handler = this.buildHandler(config.dispatcher);
+
+    let target: HttpServer;
+    if (config.httpVersion === '2') {
+      if (config.sslKeys) {
+        target = http2.createSecureServer(config.sslKeys, handler);
+      } else {
+        target = http2.createServer(handler);
+      }
+    } else {
+      if (config.sslKeys) {
+        target = https.createServer(config.sslKeys, handler);
+      } else {
+        target = http.createServer(handler);
+      }
+    }
+
+    const complete = new Promise<void>(r => target.on('close', r));
+
+    // Track connections for shutdown
+    const activeConnections = new Set<HttpSocket>();
+    target.on('connection', (socket: HttpSocket) => {
+      activeConnections.add(socket);
+      socket.on('close', () => activeConnections.delete(socket));
+    });
+
+    target.listen(config.port, config.bindAddress)
+      .on('error', reject)
+      .on('listening', resolve);
+
+    await promise;
+
+    target.off('error', reject);
+
+    async function stop(immediate?: boolean): Promise<void> {
+      if (!target.listening) {
+        return;
+      }
+      console.debug('Stopping http server');
+      target.close();
+      if (immediate) {
+        for (const connection of activeConnections) {
+          if (!connection.destroyed) {
+            connection.destroy();
+          }
+        }
+      }
+      return complete;
+    }
+
+    ShutdownManager.onGracefulShutdown(() => stop(false));
+    config.signal?.addEventListener('abort', () => stop(true));
+
+    return { target, complete, stop };
+  }
+
+  /**
+   * Create a WebRequest given an incoming http request
+   */
+  static toWebRequest(req: HttpRequest): WebRequest {
+    const secure = req.socket instanceof TLSSocket;
+    const [path, query] = (req.url ?? '/').split('?') ?? [];
+    return new WebRequest({
+      context: {
+        connection: {
+          ip: req.socket.remoteAddress!,
+          host: req.headers.host,
+          httpProtocol: secure ? 'https' : 'http',
+          port: req.socket.localPort
+        },
+        httpMethod: castTo(req.method?.toUpperCase()),
+        path,
+        httpQuery: Object.fromEntries(new URLSearchParams(query)),
+      },
+      headers: req.headers,
+      body: WebBodyUtil.markRaw(req)
+    });
+  }
+
+  /**
+   * Send WebResponse to outbound http response
+   */
+  static async respondToServerResponse(webRes: WebResponse, res: HttpResponse): Promise<void> {
+    const binaryResponse = new WebResponse({ context: webRes.context, ...WebBodyUtil.toBinaryMessage(webRes) });
+    binaryResponse.headers.forEach((v, k) => res.setHeader(k, v));
+    res.statusCode = WebCommonUtil.getStatusCode(binaryResponse);
+    const body = binaryResponse.body;
+
+    if (BinaryUtil.isReadable(body)) {
+      await pipeline(body, res);
+    } else {
+      if (body) {
+        // Weird type union that http2 uses
+        'stream' in res ? res.write(body) : res.write(body);
+      }
+      res.end();
+    }
+  }
+}

package/src/node.ts

@@ -0,0 +1,30 @@
+import { Inject, Injectable } from '@travetto/di';
+import { StandardWebRouter } from '@travetto/web';
+import { ConfigurationService } from '@travetto/config';
+
+import { WebHttpConfig } from './config';
+import { WebHttpUtil } from './http';
+import { WebHttpServer, WebServerHandle } from './types';
+
+/**
+ * A node http server
+ */
+@Injectable()
+export class NodeWebHttpServer implements WebHttpServer {
+
+  @Inject()
+  serverConfig: WebHttpConfig;
+
+  @Inject()
+  router: StandardWebRouter;
+
+  @Inject()
+  configService: ConfigurationService;
+
+  async serve(): Promise<WebServerHandle> {
+    const handle = await WebHttpUtil.startHttpServer({ ...this.serverConfig, dispatcher: this.router, });
+    console.log('Initialized', await this.configService.initBanner());
+    console.log('Listening', { port: this.serverConfig.port });
+    return handle;
+  }
+}

package/src/tls.ts

@@ -0,0 +1,51 @@
+import { PackageUtil } from '@travetto/manifest';
+import { Runtime } from '@travetto/runtime';
+
+import { WebSecureKeyPair } from './types.ts';
+
+/**
+ * Utils for generating key pairs
+ */
+export class WebTlsUtil {
+
+  /**
+   * Generate TLS key pair on demand
+   * @param subj The subject for the app
+   */
+  static async generateKeyPair(subj = { C: 'US', ST: 'CA', O: 'TRAVETTO', OU: 'WEB', CN: 'DEV' }): Promise<WebSecureKeyPair> {
+    let forge;
+
+    try {
+      forge = (await import('node-forge')).default;
+    } catch {
+      const install = PackageUtil.getInstallCommand(Runtime, 'node-forge');
+      throw new Error(`In order to generate TLS keys, you must install node-forge, "${install}"`);
+    }
+
+    const pki = forge.pki;
+
+    const keys = pki.rsa.generateKeyPair(2048);
+    const cert = pki.createCertificate();
+
+    // fill the required fields
+    cert.publicKey = keys.publicKey;
+    cert.serialNumber = '01';
+    cert.validity.notBefore = new Date();
+    cert.validity.notAfter = new Date();
+    cert.validity.notAfter.setFullYear(cert.validity.notBefore.getFullYear() + 1);
+
+    const attrs = Object.entries(subj).map(([shortName, value]) => ({ shortName, value }));
+
+    // here we set subject and issuer as the same one
+    cert.setSubject(attrs);
+    cert.setIssuer(attrs);
+
+    // the actual certificate signing
+    cert.sign(keys.privateKey);
+
+    return {
+      cert: pki.certificateToPem(cert),
+      key: pki.privateKeyToPem(keys.privateKey)
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,21 @@
+import { Any } from '@travetto/runtime';
+
+export type WebSecureKeyPair = { cert: string, key: string };
+
+/**
+ * Handle for a web server
+ */
+export type WebServerHandle<T = Any> = {
+  target: T;
+  complete: Promise<void>;
+  stop: (immediate?: boolean) => Promise<void>;
+};
+
+/**
+ * Defines the shape of the web server
+ *
+ * @concrete
+ */
+export interface WebHttpServer {
+  serve(): Promise<WebServerHandle>;
+}

package/support/cli.web_http.ts

@@ -0,0 +1,39 @@
+import { Runtime, toConcrete, Util } from '@travetto/runtime';
+import { DependencyRegistryIndex } from '@travetto/di';
+import { CliCommand, CliCommandShape } from '@travetto/cli';
+import { NetUtil } from '@travetto/web';
+import { Registry } from '@travetto/registry';
+
+import type { WebHttpServer } from '../src/types.ts';
+
+/**
+ * Run a web server
+ */
+@CliCommand({ runTarget: true, with: { debugIpc: true, canRestart: true, module: true, env: true } })
+export class WebHttpCommand implements CliCommandShape {
+
+  /** Port to run on */
+  port?: number;
+
+  /** Kill conflicting port owner */
+  killConflict?: boolean;
+
+  preMain(): void {
+    if (this.port) {
+      process.env.WEB_HTTP_PORT = `${this.port}`;
+    }
+  }
+
+  async main(): Promise<void> {
+    await Registry.init();
+    const instance = await DependencyRegistryIndex.getInstance(toConcrete<WebHttpServer>());
+
+    const handle = await Util.acquireWithRetry(
+      () => instance.serve(),
+      NetUtil.freePortOnConflict,
+      this.killConflict && !Runtime.production ? 5 : 1
+    );
+
+    return handle.complete;
+  }
+}

package/support/test/dispatcher.ts

@@ -0,0 +1,43 @@
+import { Readable } from 'node:stream';
+import { buffer } from 'node:stream/consumers';
+
+import { Inject, Injectable } from '@travetto/di';
+import { WebFilterContext, WebResponse, WebDispatcher, WebBodyUtil } from '@travetto/web';
+import { castTo } from '@travetto/runtime';
+
+
+import { WebTestDispatchUtil } from '@travetto/web/support/test/dispatch-util.ts';
+
+import { WebHttpConfig } from '../../src/config.ts';
+
+const toBuffer = (src: Buffer | Readable) => Buffer.isBuffer(src) ? src : buffer(src);
+
+/**
+ * Support for invoking http requests against the server
+ */
+@Injectable()
+export class FetchWebDispatcher implements WebDispatcher {
+
+  @Inject()
+  config: WebHttpConfig;
+
+  async dispatch({ request }: WebFilterContext): Promise<WebResponse> {
+    const baseRequest = await WebTestDispatchUtil.applyRequestBody(request);
+    const finalPath = WebTestDispatchUtil.buildPath(baseRequest);
+    const body: RequestInit['body'] = WebBodyUtil.isRaw(request.body) ? await toBuffer(request.body) : castTo(request.body);
+    const { context: { httpMethod: method }, headers } = request;
+
+    const response = await fetch(
+      `${this.config.fetchUrl}${finalPath}`,
+      { method, headers, body }
+    );
+
+    return await WebTestDispatchUtil.finalizeResponseBody(
+      new WebResponse({
+        body: Buffer.from(await response.arrayBuffer()),
+        context: { httpStatusCode: response.status },
+        headers: response.headers
+      })
+    );
+  }
+}