@travetto/web 6.0.0-rc.2

package/src/router/standard.ts

@@ -0,0 +1,59 @@
+import router from 'find-my-way';
+
+import { AppError } from '@travetto/runtime';
+import { Inject, Injectable } from '@travetto/di';
+
+import { EndpointConfig } from '../registry/types.ts';
+
+import { WebResponse } from '../types/response.ts';
+import { HTTP_METHODS } from '../types/core.ts';
+import type { WebFilterContext } from '../types/filter.ts';
+import { WebConfig } from '../config.ts';
+
+import { BaseWebRouter } from './base.ts';
+
+const DEFAULT_HTTP_METHOD = 'POST';
+
+/**
+ * The web router
+ */
+@Injectable()
+export class StandardWebRouter extends BaseWebRouter {
+
+  @Inject()
+  config: WebConfig;
+
+  #cache = new Map<Function, EndpointConfig>();
+  raw = router();
+
+  async register(endpoints: EndpointConfig[]): Promise<() => void> {
+    for (const ep of endpoints) {
+      const fullPath = ep.fullPath.replace(/[*][^*]+/g, '*'); // Flatten wildcards
+      const handler = (): void => { };
+      this.#cache.set(handler, ep);
+      this.raw[HTTP_METHODS[ep.httpMethod ?? DEFAULT_HTTP_METHOD].lower](fullPath, handler);
+    }
+
+    return (): void => {
+      for (const ep of endpoints ?? []) {
+        this.raw.off(ep.httpMethod ?? DEFAULT_HTTP_METHOD, ep.fullPath);
+      }
+    };
+  }
+
+  /**
+   * Route and execute the request
+   */
+  async dispatch({ request }: WebFilterContext): Promise<WebResponse> {
+    const httpMethod = request.context.httpMethod ?? DEFAULT_HTTP_METHOD;
+    const { params, handler } = this.raw.find(httpMethod, request.context.path) ?? {};
+    const endpoint = this.#cache.get(handler!);
+    if (!endpoint) {
+      return new WebResponse({
+        body: new AppError(`Unknown endpoint ${httpMethod} ${request.context.path}`, { category: 'notfound' }),
+      });
+    }
+    Object.assign(request.context, { pathParams: params });
+    return endpoint.filter!({ request });
+  }
+}

package/src/types/cookie.ts

@@ -0,0 +1,18 @@
+export type Cookie = {
+  name: string;
+  value?: string;
+  expires?: Date;
+  signed?: boolean;
+  maxAge?: number;
+  path?: string;
+  domain?: string;
+  priority?: 'low' | 'medium' | 'high';
+  sameSite?: 'strict' | 'lax' | 'none';
+  secure?: boolean;
+  httpOnly?: boolean;
+  partitioned?: boolean;
+  response?: boolean;
+};
+
+export type CookieGetOptions = { signed?: boolean };
+export type CookieSetOptions = Omit<Cookie, 'name' | 'value'>;

package/src/types/core.ts

@@ -0,0 +1,33 @@
+type MethodConfig = { body: boolean, emptyStatusCode: number, cacheable: boolean };
+function verb<
+  M extends string,
+  L extends string,
+  C extends Partial<MethodConfig>
+>(method: M, lower: L, cfg: C): { method: M, lower: L } & C & MethodConfig {
+  return { body: false, cacheable: false, emptyStatusCode: 204, ...cfg, method, lower, };
+}
+
+export const HTTP_METHODS = {
+  PUT: verb('PUT', 'put', { body: true }),
+  POST: verb('POST', 'post', { body: true, emptyStatusCode: 201 }),
+  PATCH: verb('PATCH', 'patch', { body: true }),
+  GET: verb('GET', 'get', { cacheable: true }),
+  DELETE: verb('DELETE', 'delete', {}),
+  HEAD: verb('HEAD', 'head', { cacheable: true }),
+  OPTIONS: verb('OPTIONS', 'options', {}),
+} as const;
+
+export type HttpMethod = keyof typeof HTTP_METHODS;
+export type HttpProtocol = 'http' | 'https';
+
+/**
+ * High level categories with a defined ordering
+ */
+export const WEB_INTERCEPTOR_CATEGORIES = [
+  'global', 'terminal', 'pre-request', 'request', 'response', 'application'
+] as const;
+
+/**
+ * High level categories with a defined ordering
+ */
+export type WebInterceptorCategory = (typeof WEB_INTERCEPTOR_CATEGORIES)[number];

package/src/types/dispatch.ts

@@ -0,0 +1,23 @@
+import { ControllerConfig, EndpointConfig } from '../registry/types.ts';
+import { WebFilter } from './filter.ts';
+
+/**
+ * Defines the shape for a web dispatcher
+ * @concrete
+ */
+export interface WebDispatcher {
+  /**
+   * Dispatch a request, and return a promise when completed
+   */
+  dispatch: WebFilter;
+}
+
+/**
+ * Web router pattern
+ */
+export interface WebRouter extends WebDispatcher {
+  /**
+   * Register a controller with the prepared endpoints
+   */
+  register(endpoints: EndpointConfig[], controller: ControllerConfig): Promise<() => void>;
+}

package/src/types/error.ts

@@ -0,0 +1,10 @@
+import { AnyMap, AppError, ErrorCategory } from '@travetto/runtime';
+
+/**
+ * Web Error
+ */
+export class WebError extends AppError<{ statusCode?: number }> {
+  static for(message: string, code: number, details?: AnyMap, category: ErrorCategory = 'data'): WebError {
+    return new WebError(message, { category, details: { ...details, statusCode: code } });
+  }
+}

package/src/types/filter.ts

@@ -0,0 +1,7 @@
+import { WebResponse } from './response.ts';
+import { WebRequest } from './request.ts';
+
+export type WebFilterContext<C = {}> = { request: WebRequest } & C;
+export type WebFilter<C extends WebFilterContext = WebFilterContext> = (context: C) => Promise<WebResponse>;
+export type WebChainedContext<C = unknown> = WebFilterContext<{ next: () => Promise<WebResponse>, config: C }>;
+export type WebChainedFilter<C = unknown> = WebFilter<WebChainedContext<C>>;

package/src/types/headers.ts

@@ -0,0 +1,108 @@
+import { Any, ByteRange, castTo } from '@travetto/runtime';
+import { MimeType, MimeUtil } from '../util/mime.ts';
+
+type Prim = number | boolean | string;
+type HeaderValue = Prim | Prim[] | readonly Prim[];
+export type WebHeadersInit = Headers | Record<string, undefined | null | HeaderValue> | [string, HeaderValue][];
+
+const FILENAME_EXTRACT = /filename[*]?=["]?([^";]*)["]?/;
+
+/**
+ * Simple Headers wrapper with additional logic for common patterns
+ */
+export class WebHeaders extends Headers {
+
+  #parsedType?: MimeType;
+
+  constructor(o?: WebHeadersInit) {
+    const passed = (o instanceof Headers);
+    super(passed ? o : undefined);
+
+    if (o && !passed) {
+      for (const [k, v] of (Array.isArray(o) ? o : Object.entries(o))) {
+        if (v !== undefined && v !== null) {
+          this.append(k, castTo(v));
+        }
+      }
+    }
+  }
+
+  /** Set if key not already set */
+  setIfAbsent(key: string, value: string): void {
+    if (!this.has(key)) {
+      this.set(key, value);
+    }
+  }
+
+  /**
+   * Get a header value as a list, breaking on commas except for cookies
+   */
+  getList(key: string): string[] | undefined {
+    const v = this.get(key);
+    if (!v) {
+      return;
+    } else if (v.toLowerCase() === 'set-cookie') {
+      return this.getSetCookie();
+    }
+    return v.split(key === 'cookie' ? /\s{0,3};\s{0,3}/ : /\s{0,3},\s{0,3}/);
+  }
+
+  // @ts-expect-error
+  forEach(set: (v: string | string[], k: string, headers: WebHeaders) => void): void;
+  forEach(set: (v: Any, k: string, headers: WebHeaders) => void): void;
+  forEach(set: (v: string | string[], k: string, headers: WebHeaders) => void): void {
+    for (const [k, v] of this.entries()) {
+      set(k === 'set-cookie' ? this.getSetCookie() : v, k, this);
+    }
+  }
+
+  /**
+   * Vary a value
+   */
+  vary(value: string): void {
+    this.append('Vary', value);
+  }
+
+  /**
+   * Get the fully parsed content type
+   */
+  getContentType(): MimeType | undefined {
+    return this.#parsedType ??= MimeUtil.parse(this.get('Content-Type')!);
+  }
+
+  /**
+   * Read the filename from the content disposition
+   */
+  getFilename(): string | undefined {
+    const [, match] = (this.get('Content-Disposition') ?? '').match(FILENAME_EXTRACT) ?? [];
+    return match;
+  }
+
+  /**
+   * Get requested byte range for a given request
+   */
+  getRange(chunkSize: number = 100 * 1024): ByteRange | undefined {
+    const rangeHeader = this.get('Range');
+    if (rangeHeader) {
+      const [start, end] = rangeHeader.replace(/bytes=/, '').split('-')
+        .map(x => x ? parseInt(x, 10) : undefined);
+      if (start !== undefined) {
+        return { start, end: end ?? (start + chunkSize) };
+      }
+    }
+  }
+
+  /**
+   * Set header value with a prefix
+   */
+  setWithPrefix(key: string, value: string | undefined, prefix: string = ''): void {
+    value ? this.set(key, `${prefix} ${value}`.trim()) : this.delete(key);
+  }
+
+  /**
+   * Get with prefix
+   */
+  getWithPrefix(key: string, prefix: string = ''): string | undefined {
+    return this.get(key)?.replace(prefix, '').trim();
+  }
+}

package/src/types/interceptor.ts

@@ -0,0 +1,54 @@
+import type { Class } from '@travetto/runtime';
+
+import type { EndpointConfig } from '../registry/types.ts';
+import type { WebChainedContext } from './filter.ts';
+import { WebResponse } from './response.ts';
+import { WebInterceptorCategory } from './core.ts';
+
+export type WebInterceptorContext<C = unknown> = { endpoint: EndpointConfig, config: C };
+
+/**
+ * Web interceptor structure
+ *
+ * @concrete
+ */
+export interface WebInterceptor<C = unknown> {
+
+  /**
+   * The category an interceptor belongs to
+   */
+  category: WebInterceptorCategory;
+
+  /**
+   * Config for interceptor
+   */
+  config?: Readonly<C>;
+
+  /**
+   * This interceptor must run after these
+   */
+  dependsOn?: Class<WebInterceptor>[];
+
+  /**
+   * This interceptor must run before these
+   */
+  runsBefore?: Class<WebInterceptor>[];
+
+  /**
+   * Determines the current endpoint is applicable for the interceptor
+   * @param endpoint The endpoint to check
+   * @param config The root configuration
+   */
+  applies?(context: WebInterceptorContext<C>): boolean;
+
+  /**
+   * Finalize config before use
+   */
+  finalizeConfig?(context: WebInterceptorContext<C>, inputs: Partial<C>[]): C;
+
+  /**
+   * Process the request
+   * @param {WebChainedContext} context The context of to process
+   */
+  filter(context: WebChainedContext<C>): Promise<WebResponse>;
+}

package/src/types/message.ts

@@ -0,0 +1,33 @@
+import { Readable } from 'node:stream';
+import { castTo } from '@travetto/runtime';
+import { WebHeaders, WebHeadersInit } from './headers';
+
+export type WebBinaryBody = Readable | Buffer;
+
+export interface WebMessageInit<B = unknown, C = unknown> {
+  context?: C;
+  headers?: WebHeadersInit;
+  body?: B;
+}
+
+
+export interface WebMessage<B = unknown, C = unknown> {
+  readonly context: C;
+  readonly headers: WebHeaders;
+  body?: B;
+}
+
+/**
+ * Common implementation for a rudimentary web message (request / response)
+ */
+export class BaseWebMessage<B = unknown, C = unknown> implements WebMessage<B, C> {
+  readonly context: C;
+  readonly headers: WebHeaders;
+  body?: B;
+
+  constructor(o: WebMessageInit<B, C> = {}) {
+    this.context = o.context ?? castTo<C>({});
+    this.headers = new WebHeaders(o.headers);
+    this.body = o.body;
+  }
+}

package/src/types/request.ts

@@ -0,0 +1,22 @@
+import { HttpMethod, HttpProtocol } from './core.ts';
+import { BaseWebMessage } from './message.ts';
+
+export interface WebConnection {
+  host?: string;
+  port?: number;
+  ip?: string;
+  httpProtocol?: HttpProtocol;
+}
+
+export interface WebRequestContext {
+  path: string;
+  pathParams?: Record<string, unknown>;
+  httpQuery?: Record<string, unknown>;
+  httpMethod?: HttpMethod;
+  connection?: WebConnection;
+}
+
+/**
+ * Web Request object
+ */
+export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> { }

package/src/types/response.ts

@@ -0,0 +1,20 @@
+import { BaseWebMessage } from './message.ts';
+
+export interface WebResponseContext {
+  httpStatusCode?: number;
+}
+
+/**
+ * Web Response as a simple object
+ */
+export class WebResponse<B = unknown> extends BaseWebMessage<B, WebResponseContext> {
+
+  /**
+    * Build the redirect
+    * @param location Location to redirect to
+    * @param statusCode Status code
+    */
+  static redirect(location: string, statusCode = 302): WebResponse<undefined> {
+    return new WebResponse({ context: { httpStatusCode: statusCode }, headers: { Location: location } });
+  }
+}

package/src/util/body.ts

@@ -0,0 +1,220 @@
+import iconv from 'iconv-lite';
+
+import { Readable } from 'node:stream';
+import { buffer as toBuffer } from 'node:stream/consumers';
+
+import { Any, BinaryUtil, castTo, hasToJSON, Util } from '@travetto/runtime';
+
+import { WebBinaryBody, WebMessage } from '../types/message.ts';
+import { WebHeaders } from '../types/headers.ts';
+import { WebError } from '../types/error.ts';
+
+const WebRawStreamSymbol = Symbol();
+
+/**
+ * Utility classes for supporting web body operations
+ */
+export class WebBodyUtil {
+
+  /**
+   * Convert a node binary input to a buffer
+   */
+  static async toBuffer(src: WebBinaryBody): Promise<Buffer> {
+    return Buffer.isBuffer(src) ? src : toBuffer(src);
+  }
+
+  /**
+   * Convert a node binary input to a readable
+   */
+  static toReadable(src: WebBinaryBody): Readable {
+    return Buffer.isBuffer(src) ? Readable.from(src) : src;
+  }
+
+  /**
+   * Generate multipart body
+   */
+  static async * buildMultiPartBody(form: FormData, boundary: string): AsyncIterable<string | Buffer> {
+    const nl = '\r\n';
+    for (const [k, v] of form.entries()) {
+      const data = v.slice();
+      const filename = data instanceof File ? data.name : undefined;
+      const size = data instanceof Blob ? data.size : data.length;
+      const type = data instanceof Blob ? data.type : undefined;
+      yield `--${boundary}${nl}`;
+      yield `Content-Disposition: form-data; name="${k}"; filename="${filename ?? k}"${nl}`;
+      yield `Content-Length: ${size}${nl}`;
+      if (type) {
+        yield `Content-Type: ${type}${nl}`;
+      }
+      yield nl;
+      if (data instanceof Blob) {
+        for await (const chunk of data.stream()) {
+          yield chunk;
+        }
+      } else {
+        yield data;
+      }
+      yield nl;
+    }
+    yield `--${boundary}--${nl}`;
+  }
+
+  /** Get Blob Headers */
+  static getBlobHeaders(value: Blob): [string, string][] {
+    const meta = BinaryUtil.getBlobMeta(value);
+
+    const toAdd: [string, string | undefined][] = [
+      ['Content-Type', value.type],
+      ['Content-Length', `${value.size}`],
+      ['Content-Encoding', meta?.contentEncoding],
+      ['Cache-Control', meta?.cacheControl],
+      ['Content-Language', meta?.contentLanguage],
+    ];
+
+    if (meta?.range) {
+      toAdd.push(
+        ['Accept-Ranges', 'bytes'],
+        ['Content-Range', `bytes ${meta.range.start}-${meta.range.end}/${meta.size}`],
+      );
+    }
+
+    if (value instanceof File && value.name) {
+      toAdd.push(['Content-disposition', `attachment; filename="${value.name}"`]);
+    }
+
+    return toAdd.filter((x): x is [string, string] => !!x[1]);
+  }
+
+  /**
+   * Build WebResponse based on return value
+   */
+  static defaultContentType(value: unknown): string {
+    if (value === undefined || value === null) {
+      return '';
+    } else if (typeof value === 'string') {
+      return 'text/plain';
+    } else if (BinaryUtil.isBinaryType(value)) {
+      return 'application/octet-stream';
+    } else if (value instanceof FormData) {
+      return 'multipart/form-data';
+    } else {
+      return 'application/json';
+    }
+  }
+
+  /**
+   * Convert an existing web message to a binary web message
+   */
+  static toBinaryMessage(message: WebMessage): Omit<WebMessage<WebBinaryBody>, 'context'> {
+    const body = message.body;
+    if (Buffer.isBuffer(body) || BinaryUtil.isReadable(body)) {
+      return castTo(message);
+    }
+
+    const out: Omit<WebMessage<WebBinaryBody>, 'context'> = { headers: new WebHeaders(message.headers), body: null! };
+    if (body instanceof Blob) {
+      for (const [k, v] of this.getBlobHeaders(body)) {
+        out.headers.set(k, v);
+      }
+      out.body = Readable.fromWeb(body.stream());
+    } else if (body instanceof FormData) {
+      const boundary = `${'-'.repeat(24)}-multipart-${Util.uuid()}`;
+      out.headers.set('Content-Type', `multipart/form-data; boundary=${boundary}`);
+      out.body = Readable.from(this.buildMultiPartBody(body, boundary));
+    } else if (BinaryUtil.isReadableStream(body)) {
+      out.body = Readable.fromWeb(body);
+    } else if (BinaryUtil.isAsyncIterable(body)) {
+      out.body = Readable.from(body);
+    } else if (body === null || body === undefined) {
+      out.body = Buffer.alloc(0);
+    } else if (BinaryUtil.isArrayBuffer(body)) {
+      out.body = Buffer.from(body);
+    } else {
+      let text: string;
+      if (typeof body === 'string') {
+        text = body;
+      } else if (hasToJSON(body)) {
+        text = JSON.stringify(body.toJSON());
+      } else if (body instanceof Error) {
+        text = JSON.stringify({ message: body.message });
+      } else {
+        text = JSON.stringify(body);
+      }
+      out.body = Buffer.from(text, 'utf-8');
+    }
+
+    if (Buffer.isBuffer(out.body)) {
+      out.headers.set('Content-Length', `${out.body.byteLength}`);
+    }
+
+    out.headers.setIfAbsent('Content-Type', this.defaultContentType(message.body));
+
+    return castTo(out);
+  }
+
+  /**
+   * Set body and mark as unprocessed
+   */
+  static markRaw(val: WebBinaryBody | undefined): typeof val {
+    if (val) {
+      Object.defineProperty(val, WebRawStreamSymbol, { value: val });
+    }
+    return val;
+  }
+
+  /**
+   * Is the input raw
+   */
+  static isRaw(val: unknown): val is WebBinaryBody {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return !!val && ((Buffer.isBuffer(val) || BinaryUtil.isReadable(val)) && (val as Any)[WebRawStreamSymbol] === val);
+  }
+
+  /**
+   * Simple parse support
+   */
+  static parseBody(type: string, val: string): unknown {
+    switch (type) {
+      case 'text': return val;
+      case 'json': return JSON.parse(val);
+      case 'form': return Object.fromEntries(new URLSearchParams(val));
+    }
+  }
+
+  /**
+   * Read text from an input source
+   */
+  static async readText(input: Readable | Buffer, limit: number, encoding?: string): Promise<{ text: string, read: number }> {
+    encoding ??= (Buffer.isBuffer(input) ? undefined : input.readableEncoding) ?? 'utf-8';
+
+    if (!iconv.encodingExists(encoding)) {
+      throw WebError.for('Specified Encoding Not Supported', 415, { encoding });
+    }
+
+    if (Buffer.isBuffer(input)) {
+      return { text: iconv.decode(input, encoding), read: input.byteLength };
+    }
+
+    let received = Buffer.isBuffer(input) ? input.byteOffset : 0;
+    const decoder = iconv.getDecoder(encoding);
+    const all: string[] = [];
+
+    try {
+      for await (const chunk of input.iterator({ destroyOnReturn: false })) {
+        received += Buffer.isBuffer(chunk) ? chunk.byteLength : (typeof chunk === 'string' ? chunk.length : chunk.length);
+        if (received > limit) {
+          throw WebError.for('Request Entity Too Large', 413, { received, limit });
+        }
+        all.push(decoder.write(chunk));
+      }
+      all.push(decoder.end() ?? '');
+      return { text: all.join(''), read: received };
+    } catch (err) {
+      if (err instanceof Error && err.name === 'AbortError') {
+        throw WebError.for('Request Aborted', 400, { received });
+      } else {
+        throw err;
+      }
+    }
+  }
+}