@travetto/web-connect 6.0.0-rc.2

package/README.md

@@ -0,0 +1,47 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/web-connect/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web Connect Support
+
+## Web integration for Connect-Like Resources
+
+**Install: @travetto/web-connect**
+```bash
+npm install @travetto/web-connect
+
+# or
+
+yarn add @travetto/web-connect
+```
+
+This module provides basic integration for calling [connect](https://github.com/senchalabs/connect) related middleware with [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection."). This logic is not intended to be exhaustive, but intended to provide a quick bridge.  This only consumer of this is [Web Auth Passport](https://github.com/travetto/travetto/tree/main/module/auth-web-passport#readme "Web authentication integration support for the Travetto framework") as it needs to bind the [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) and [WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3) to standard contracts for [passport](http://passportjs.org). 
+
+This module is already most likely compatible with quite a bit of middleware, but will fail under any of the following conditions:
+   *  The calling code expects the request or response to be a proper [EventEmitter](https://nodejs.org/api/events.html#class-eventemitter)
+   *  The calling code expects the request/response sockets to be live.
+   *  The calling code modifies the shape of the objects (e.g. rewrites the close method on response).
+Barring these exceptions, gaps will be filled in as more use cases arise.  The above exceptions are non-negotiable as they are are enforced by the invocation method defined by [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.").
+
+**Code: Example of using the Connect Adaptor with Passport**
+```typescript
+async authenticate(input: object, ctx: WebFilterContext): Promise<Principal | undefined> {
+    const requestOptions = this.#passportOptions(ctx);
+    const options = {
+      session: this.session,
+      failWithError: true,
+      ...requestOptions,
+      state: PassportUtil.enhanceState(ctx, requestOptions.state)
+    };
+
+    const user = await WebConnectUtil.invoke<V>(ctx, (req, res, next) =>
+      passport.authenticate(this.#strategyName, options, next)(req, res)
+    );
+
+    if (user) {
+      delete user._raw;
+      delete user._json;
+      delete user.source;
+      return this.#toPrincipal(user, this.#strategyName);
+    }
+  }
+}
+```

package/__index__.ts

@@ -0,0 +1,2 @@
+export * from './src/connect.ts';
+export * from './src/util.ts';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@travetto/web-connect",
+  "version": "6.0.0-rc.2",
+  "description": "Web integration for Connect-Like Resources",
+  "keywords": [
+    "web",
+    "connect",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/web-connect"
+  },
+  "dependencies": {
+    "@travetto/web": "^6.0.0-rc.2"
+  },
+  "peerDependencies": {
+    "@travetto/cli": "^6.0.0-rc.2",
+    "@travetto/test": "^6.0.0-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/test": {
+      "optional": true
+    },
+    "@travetto/cli": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Web Connect Support"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/connect.ts

@@ -0,0 +1,155 @@
+import { OutgoingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
+
+import { castTo } from '@travetto/runtime';
+import { WebRequest, WebResponse } from '@travetto/web';
+
+export class ConnectRequest implements Pick<IncomingMessage, 'url' | 'headers'> {
+
+  /**
+   * Get a connect incoming message given a framework request
+   */
+  static get(request: WebRequest): ConnectRequest & IncomingMessage {
+    return castTo(new ConnectRequest(request));
+  }
+
+  #request: WebRequest;
+  constructor(request: WebRequest) {
+    this.#request = request;
+  }
+
+  get path(): string {
+    return this.#request.context.path;
+  }
+
+  get url(): string {
+    return this.#request.context.path;
+  }
+
+  get headers(): Record<string, string> {
+    return Object.fromEntries(this.#request.headers.entries());
+  }
+
+  get query(): Record<string, unknown> {
+    return this.#request.context.httpQuery ?? {};
+  }
+}
+
+export class ConnectResponse implements Pick<ServerResponse,
+  'getHeader' | 'getHeaderNames' | 'getHeaders' | 'hasHeader' |
+  'headersSent' | 'write' | 'flushHeaders'
+> {
+
+  /**
+   * Get a connect server response given a framework response
+   */
+  static get(response?: WebResponse): ConnectResponse & ServerResponse {
+    return castTo(new ConnectResponse(response));
+  }
+
+  #response: WebResponse;
+  #headersSent = false;
+  #finished = false;
+  #written: Buffer[] = [];
+
+  constructor(response?: WebResponse) {
+    this.#response = response ?? new WebResponse();
+  }
+
+  get headersSent(): boolean {
+    return this.#headersSent;
+  }
+
+  get finished(): boolean {
+    return this.#finished;
+  }
+
+  get statusCode(): number | undefined {
+    return this.#response.context.httpStatusCode;
+  }
+
+  set statusCode(val: number) {
+    this.#response.context.httpStatusCode = val;
+  }
+
+  writeHead(statusCode: unknown, statusMessage?: unknown, headers?: unknown): this {
+    this.#response.context.httpStatusCode = castTo(statusCode);
+    for (const [k, v] of Object.entries(headers ?? {})) {
+      this.#response.headers.set(k, v);
+    }
+    this.#headersSent = true;
+    return this;
+  }
+  setHeader(name: string, value: number | string | readonly string[]): this {
+    if (Array.isArray(value)) {
+      this.#response.headers.delete(name);
+      for (const item of value) {
+        this.#response.headers.append(name, item);
+      }
+    } else {
+      this.#response.headers.set(name, `${value}`);
+    }
+    return this;
+  }
+  appendHeader(name: string, value: string | readonly string[]): this {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        this.#response.headers.append(name, item);
+      }
+    } else {
+      this.#response.headers.append(name, `${value}`);
+    }
+    return this;
+  }
+  getHeader(name: string): number | string | string[] | undefined {
+    return this.#response.headers.get(name)!;
+  }
+  getHeaders(): OutgoingHttpHeaders {
+    return Object.fromEntries(this.#response.headers.entries());
+  }
+  getHeaderNames(): string[] {
+    return [...this.#response.headers.keys()];
+  }
+  hasHeader(name: string): boolean {
+    return this.#response.headers.has(name);
+  }
+  removeHeader(name: string): void {
+    this.#response.headers.delete(name);
+  }
+  flushHeaders(): void {
+    this.#headersSent = true;
+  }
+  write(chunk: unknown, encoding?: unknown, callback?: (err?: Error) => void): boolean {
+    if (this.#headersSent) {
+      this.flushHeaders();
+    }
+    if (!Buffer.isBuffer(chunk)) {
+      this.#written.push(Buffer.from(`${chunk}`, castTo(encoding)));
+    } else {
+      this.#written.push(chunk);
+    }
+    callback?.();
+    return true;
+  }
+  redirect(location: string, code?: number): this {
+    this.#response.context.httpStatusCode = code ?? 301;
+    this.#response.headers.set('Location', location);
+    return this;
+  }
+
+  end(chunk?: unknown, encoding?: unknown, cb?: () => void): this {
+    this.flushHeaders();
+    if (chunk) {
+      this.write(chunk, encoding);
+    }
+    this.#finished = true;
+    cb?.();
+    return this;
+  }
+
+  throwIfSent(): void {
+    if (!this.#headersSent) {
+      this.#response.body = Buffer.concat(this.#written);
+      throw this.#response;
+    }
+  }
+}

package/src/util.ts

@@ -0,0 +1,35 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+import { WebFilterContext } from '@travetto/web';
+
+import { ConnectRequest, ConnectResponse } from './connect';
+
+
+type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+
+/**
+ * Utilities for invoking express middleware with a WebFilterContext
+ */
+export class WebConnectUtil {
+  /**
+   * Invoke express middleware, and return the result as a promise.
+   *
+   * NOTE: If a response is written, then it is thrown as an "error"
+   */
+  static async invoke<T>(ctx: WebFilterContext,
+    handler: (
+      req: IncomingMessage,
+      res: ServerResponse,
+      next: (err: Error | null | undefined, value: T | undefined | null) => void
+    ) => Middleware
+  ): Promise<T | undefined> {
+    const connectReq = ConnectRequest.get(ctx.request);
+    const connectRes = ConnectResponse.get();
+
+    const p = Promise.withResolvers<T | undefined>();
+    handler(connectReq, connectRes, (err, value) => err ? p.reject(err) : p.resolve(value!));
+    const result = await p.promise;
+    connectRes.throwIfSent();
+    return result;
+  }
+}