@travetto/web-http 8.0.0-alpha.3 → 8.0.0-alpha.30

package/README.md

@@ -13,10 +13,38 @@ npm install @travetto/web-http
 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.
+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.
+
+## CLI - web:http
+By default, the framework provides a default [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L20) 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: Help for web:http**
+```bash
+$ trv web:http --help
+
+Usage: web:http [options]
+
+Description:
+  Start the configured web HTTP server for a module.
+
+  Initializes registry and server bindings, supports restart-aware development
+  flags, and can attempt to clear conflicting port owners in local workflows.
+
+Options:
+  -p, --port <number>                          Port to run on
+  --kill-conflict, --no-kill-conflict          Kill conflicting port owner (default: true)
+  -m, --module <module>                        Module to run for
+  --profile <string>                           Application profiles
+  --restart-on-change, --no-restart-on-change  Should the invocation automatically restart on source changes (default: true)
+  -d, --debug-ipc                              Should the invocation support debugging via IPC (e.g. from VSCode)
+  --help                                       display help for command
+
+Examples:
+  Starting a web server on port 8000
+    trv web:http -m <MODULE> -p 8000
+```
 
 ## Running a Server
-By default, the framework provides a default [@CliCommand](https://github.com/travetto/travetto/tree/main/module/cli/src/registry/decorator.ts#L27) 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
@@ -89,7 +117,6 @@ Listening on port { port: 3000 }
 **Code: Standard Web Http Config**
 ```typescript
 export class WebHttpConfig {
-
   /**
    * What version of HTTP to use
    * Version 2 requires SSL for direct browser access
@@ -125,8 +152,8 @@ export class WebHttpConfig {
 
   @PostConstruct()
   async finalizeConfig(): Promise<void> {
-    this.tls ??= (this.httpVersion === '2' || !!this.tlsKeys);
-    this.port = (this.port < 0 ? await NetUtil.getFreePort() : this.port);
+    this.tls ??= this.httpVersion === '2' || !!this.tlsKeys;
+    this.port = this.port < 0 ? await NetUtil.getFreePort() : this.port;
     this.bindAddress ||= NetUtil.getLocalAddress();
 
     if (!this.tls) {
@@ -138,9 +165,10 @@ export class WebHttpConfig {
       }
       this.tlsKeys = await WebTlsUtil.generateKeyPair();
     } else {
-      if (this.tlsKeys.key.length < 100) { // We have files or resources
-        this.tlsKeys.key = await RuntimeResources.readText(this.tlsKeys.key);
-        this.tlsKeys.cert = await RuntimeResources.readText(this.tlsKeys.cert);
+      if (this.tlsKeys.key.length < 100) {
+        // We have files or resources
+        this.tlsKeys.key = await RuntimeResources.readUTF8(this.tlsKeys.key);
+        this.tlsKeys.cert = await RuntimeResources.readUTF8(this.tlsKeys.cert);
       }
     }
 
@@ -150,21 +178,20 @@ export class WebHttpConfig {
 ```
 
 ### 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#L27) decorator. This could look like:
+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#L20) 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 { type WebHttpServer, WebHttpConfig } from '@travetto/web-http';
+import { Env, toConcrete } from '@travetto/runtime';
+import { WebHttpConfig, type WebHttpServer } from '@travetto/web-http';
 
 import './config-override.ts';
 
 @CliCommand({ runTarget: true })
 export class SampleApp {
-
   preMain(): void {
     Env.NODE_ENV.set('production');
   }
@@ -260,7 +287,6 @@ Listening on port { port: 3000 }
 **Code: Implementation**
 ```typescript
 export class NodeWebHttpServer implements WebHttpServer {
-
   @Inject()
   serverConfig: WebHttpConfig;
 
@@ -271,7 +297,7 @@ export class NodeWebHttpServer implements WebHttpServer {
   configService: ConfigurationService;
 
   async serve(): Promise<WebServerHandle> {
-    const handle = await WebHttpUtil.startHttpServer({ ...this.serverConfig, dispatcher: this.router, });
+    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;
@@ -279,7 +305,7 @@ export class NodeWebHttpServer implements WebHttpServer {
 }
 ```
 
-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.
+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:
@@ -315,18 +341,18 @@ static buildHandler(dispatcher: WebDispatcher): (request: HttpRequest, response:
     return async (request: HttpRequest, response: HttpResponse): Promise<void> => {
       const webRequest = this.toWebRequest(request);
       const webResponse = await dispatcher.dispatch({ request: webRequest });
-      this.respondToServerResponse(webResponse, response);
+      await this.respondToServerResponse(webResponse, response);
     };
   }
 ```
 
 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)
+   *  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:
+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 production
@@ -334,4 +360,4 @@ Additionally the framework supports TLS out of the box, by allowing you to speci
 
 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).
+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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/web-http",
-  "version": "8.0.0-alpha.3",
+  "version": "8.0.0-alpha.30",
   "type": "module",
   "description": "Web HTTP Server Support",
   "keywords": [
@@ -27,11 +27,11 @@
     "directory": "module/web-http"
   },
   "dependencies": {
-    "@travetto/web": "^8.0.0-alpha.3"
+    "@travetto/web": "^8.0.0-alpha.29"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.4",
-    "@travetto/test": "^8.0.0-alpha.3"
+    "@travetto/cli": "^8.0.0-alpha.32",
+    "@travetto/test": "^8.0.0-alpha.25"
   },
   "peerDependenciesMeta": {
     "@travetto/test": {

package/src/config.ts

@@ -1,18 +1,17 @@
 import { Config, EnvVar } from '@travetto/config';
+import { PostConstruct } from '@travetto/di';
+import { Runtime, RuntimeError, RuntimeResources } from '@travetto/runtime';
 import { Ignore, Secret } from '@travetto/schema';
-import { RuntimeError, Runtime, RuntimeResources } from '@travetto/runtime';
 import { NetUtil } from '@travetto/web';
-import { PostConstruct } from '@travetto/di';
 
-import type { WebSecureKeyPair } from './types.ts';
 import { WebTlsUtil } from './tls.ts';
+import type { WebSecureKeyPair } from './types.ts';
 
 /**
  * Web HTTP configuration
  */
 @Config('web.http')
 export class WebHttpConfig {
-
   /**
    * What version of HTTP to use
    * Version 2 requires SSL for direct browser access
@@ -48,8 +47,8 @@ export class WebHttpConfig {
 
   @PostConstruct()
   async finalizeConfig(): Promise<void> {
-    this.tls ??= (this.httpVersion === '2' || !!this.tlsKeys);
-    this.port = (this.port < 0 ? await NetUtil.getFreePort() : this.port);
+    this.tls ??= this.httpVersion === '2' || !!this.tlsKeys;
+    this.port = this.port < 0 ? await NetUtil.getFreePort() : this.port;
     this.bindAddress ||= NetUtil.getLocalAddress();
 
     if (!this.tls) {
@@ -61,12 +60,13 @@ export class WebHttpConfig {
       }
       this.tlsKeys = await WebTlsUtil.generateKeyPair();
     } else {
-      if (this.tlsKeys.key.length < 100) { // We have files or resources
-        this.tlsKeys.key = await RuntimeResources.readText(this.tlsKeys.key);
-        this.tlsKeys.cert = await RuntimeResources.readText(this.tlsKeys.cert);
+      if (this.tlsKeys.key.length < 100) {
+        // We have files or resources
+        this.tlsKeys.key = await RuntimeResources.readUTF8(this.tlsKeys.key);
+        this.tlsKeys.cert = await RuntimeResources.readUTF8(this.tlsKeys.cert);
       }
     }
 
     this.fetchUrl = `${this.tls ? 'https' : 'http'}://${this.bindAddress}:${this.port}`;
   }
-}
+}

package/src/http.ts

@@ -1,11 +1,11 @@
-import type net from 'node:net';
 import http from 'node:http';
 import http2 from 'node:http2';
 import https from 'node:https';
+import type net from 'node:net';
 import { TLSSocket } from 'node:tls';
 
-import { WebBodyUtil, WebCommonUtil, type WebDispatcher, WebRequest, WebResponse } from '@travetto/web';
 import { type BinaryType, BinaryUtil, castTo, ShutdownManager } from '@travetto/runtime';
+import { WebBodyUtil, WebCommonUtil, type WebDispatcher, WebRequest, WebResponse } from '@travetto/web';
 
 import type { WebSecureKeyPair, WebServerHandle } from './types.ts';
 
@@ -24,7 +24,6 @@ type WebHttpServerConfig = {
 };
 
 export class WebHttpUtil {
-
   /**
    * Build a simple request handler
    * @param dispatcher
@@ -33,7 +32,7 @@ export class WebHttpUtil {
     return async (request: HttpRequest, response: HttpResponse): Promise<void> => {
       const webRequest = this.toWebRequest(request);
       const webResponse = await dispatcher.dispatch({ request: webRequest });
-      this.respondToServerResponse(webResponse, response);
+      await this.respondToServerResponse(webResponse, response);
     };
   }
 
@@ -69,9 +68,7 @@ export class WebHttpUtil {
       socket.on('close', () => activeConnections.delete(socket));
     });
 
-    target.listen(config.port, config.bindAddress)
-      .on('error', reject)
-      .on('listening', resolve);
+    target.listen(config.port, config.bindAddress).on('error', reject).on('listening', resolve);
 
     await promise;
 
@@ -115,7 +112,7 @@ export class WebHttpUtil {
         },
         httpMethod: castTo(request.method?.toUpperCase()),
         path,
-        httpQuery: Object.fromEntries(new URLSearchParams(query)),
+        httpQuery: Object.fromEntries(new URLSearchParams(query))
       },
       headers: request.headers,
       body: WebBodyUtil.markRawBinary(request)
@@ -127,14 +124,20 @@ export class WebHttpUtil {
    */
   static async respondToServerResponse(webResponse: WebResponse, response: HttpResponse): Promise<void> {
     const binaryResponse = new WebResponse<BinaryType>({ context: webResponse.context, ...WebBodyUtil.toBinaryMessage(webResponse) });
-    binaryResponse.headers.forEach((value, key) => response.setHeader(key, value));
+    binaryResponse.headers.forEach((value, key) => {
+      response.setHeader(key, value);
+    });
     response.statusCode = WebCommonUtil.getStatusCode(binaryResponse);
 
     if (binaryResponse.body) {
-      await BinaryUtil.pipeline(binaryResponse.body, response);
+      try {
+        await BinaryUtil.pipeline(binaryResponse.body, response);
+      } catch (error) {
+        console.error('Failed to send response', { error });
+      }
     }
-    if (!response.closed) {
+    if (!response.closed && !response.destroyed) {
       response.end();
     }
   }
-}
+}

package/src/node.ts

@@ -1,6 +1,6 @@
+import type { ConfigurationService } from '@travetto/config';
 import { Inject, Injectable } from '@travetto/di';
 import type { StandardWebRouter } from '@travetto/web';
-import type { ConfigurationService } from '@travetto/config';
 
 import type { WebHttpConfig } from './config.ts';
 import { WebHttpUtil } from './http.ts';
@@ -11,7 +11,6 @@ import type { WebHttpServer, WebServerHandle } from './types.ts';
  */
 @Injectable()
 export class NodeWebHttpServer implements WebHttpServer {
-
   @Inject()
   serverConfig: WebHttpConfig;
 
@@ -22,9 +21,9 @@ export class NodeWebHttpServer implements WebHttpServer {
   configService: ConfigurationService;
 
   async serve(): Promise<WebServerHandle> {
-    const handle = await WebHttpUtil.startHttpServer({ ...this.serverConfig, dispatcher: this.router, });
+    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

@@ -1,4 +1,4 @@
-import { Runtime } from '@travetto/runtime';
+import { type Any, Runtime } from '@travetto/runtime';
 
 import type { WebSecureKeyPair } from './types.ts';
 
@@ -6,13 +6,12 @@ import type { 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;
+    let forge: Any;
 
     try {
       forge = (await import('node-forge')).default;
@@ -47,4 +46,4 @@ export class WebTlsUtil {
       key: pki.privateKeyToPem(keys.privateKey)
     };
   }
-}
+}

package/src/types.ts

@@ -1,6 +1,6 @@
 import type { Any } from '@travetto/runtime';
 
-export type WebSecureKeyPair = { cert: string, key: string };
+export type WebSecureKeyPair = { cert: string; key: string };
 
 /**
  * Handle for a web server
@@ -18,4 +18,4 @@ export type WebServerHandle<T = Any> = {
  */
 export interface WebHttpServer {
   serve(): Promise<WebServerHandle>;
-}
+}

package/support/cli.web_http.ts

@@ -1,17 +1,23 @@
-import { Runtime, toConcrete } from '@travetto/runtime';
+import { CliCommand, type CliCommandShape, CliDebugIpcFlag, CliModuleFlag, CliProfilesFlag, CliRestartOnChangeFlag } from '@travetto/cli';
 import { DependencyRegistryIndex } from '@travetto/di';
-import { CliCommand, CliDebugIpcFlag, CliModuleFlag, CliProfilesFlag, CliRestartOnChangeFlag, type CliCommandShape } from '@travetto/cli';
-import { NetUtil } from '@travetto/web';
 import { Registry } from '@travetto/registry';
+import { Runtime, toConcrete } from '@travetto/runtime';
+import { NetUtil } from '@travetto/web';
 
 import type { WebHttpServer } from '../src/types.ts';
 
 /**
- * Run a web server
+ * Start the configured web HTTP server for a module.
+ *
+ * Initializes registry and server bindings, supports restart-aware development
+ * flags, and can attempt to clear conflicting port owners in local workflows.
+ *
+ * @example
+ * Starting a web server on port 8000
+ * > trv web:http -m <MODULE> -p 8000
  */
 @CliCommand()
 export class WebHttpCommand implements CliCommandShape {
-
   /** Port to run on */
   port?: number;
 
@@ -25,7 +31,7 @@ export class WebHttpCommand implements CliCommandShape {
   profile: string[];
 
   @CliRestartOnChangeFlag()
-  restartOnChange: boolean = true;
+  restartOnChange: boolean = Runtime.localDevelopment;
 
   @CliDebugIpcFlag()
   debugIpc?: boolean;
@@ -53,4 +59,4 @@ export class WebHttpCommand implements CliCommandShape {
       throw err;
     }
   }
-}
+}

package/support/test/dispatcher.ts

@@ -1,6 +1,6 @@
 import { Inject, Injectable } from '@travetto/di';
-import { type WebFilterContext, WebResponse, type WebDispatcher, WebBodyUtil } from '@travetto/web';
 import { BinaryUtil, castTo } from '@travetto/runtime';
+import { WebBodyUtil, type WebDispatcher, type WebFilterContext, WebResponse } from '@travetto/web';
 
 import { WebTestDispatchUtil } from '@travetto/web/support/test/dispatch-util.ts';
 
@@ -11,22 +11,21 @@ import type { WebHttpConfig } from '../../src/config.ts';
  */
 @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.isRawBinary(request.body) ?
-      await BinaryUtil.toBinaryArray(request.body) :
-      castTo(request.body);
-    const { context: { httpMethod: method }, headers } = request;
+    const body: RequestInit['body'] = WebBodyUtil.isRawBinary(request.body)
+      ? await BinaryUtil.toBinaryArray(request.body)
+      : castTo(request.body);
+    const {
+      context: { httpMethod: method },
+      headers
+    } = request;
 
-    const response = await fetch(
-      `${this.config.fetchUrl}${finalPath}`,
-      { method, headers, body }
-    );
+    const response = await fetch(`${this.config.fetchUrl}${finalPath}`, { method, headers, body });
 
     return await WebTestDispatchUtil.finalizeResponseBody(
       new WebResponse({
@@ -36,4 +35,4 @@ export class FetchWebDispatcher implements WebDispatcher {
       })
     );
   }
-}
+}