@travetto/web 6.0.0-rc.2

package/src/util/common.ts

@@ -0,0 +1,142 @@
+import { AppError, ErrorCategory, TimeSpan, TimeUtil } from '@travetto/runtime';
+
+import { WebResponse } from '../types/response.ts';
+import { WebRequest } from '../types/request.ts';
+
+type List<T> = T[] | readonly T[];
+type OrderedState<T> = { after?: List<T>, before?: List<T>, key: T };
+
+const WebRequestParamsSymbol = Symbol();
+
+export type CacheControlFlag =
+  'must-revalidate' | 'public' | 'private' | 'no-cache' |
+  'no-store' | 'no-transform' | 'proxy-revalidate' | 'immutable' |
+  'must-understand' | 'stale-if-error' | 'stale-while-revalidate';
+
+/**
+ * Mapping from error category to standard http error codes
+ */
+const ERROR_CATEGORY_STATUS: Record<ErrorCategory, number> = {
+  general: 500,
+  notfound: 404,
+  data: 400,
+  permissions: 403,
+  authentication: 401,
+  timeout: 408,
+  unavailable: 503,
+};
+
+export class WebCommonUtil {
+  static #unitMapping: Record<string, number> = {
+    kb: 2 ** 10,
+    mb: 2 ** 20,
+    gb: 2 ** 30,
+  };
+
+  static #buildEdgeMap<T, U extends OrderedState<T>>(items: List<U>): Map<T, Set<T>> {
+    const edgeMap = new Map(items.map(x => [x.key, new Set(x.after ?? [])]));
+
+    // Build out edge map
+    for (const input of items) {
+      for (const bf of input.before ?? []) {
+        if (edgeMap.has(bf)) {
+          edgeMap.get(bf)!.add(input.key);
+        }
+      }
+      const afterSet = edgeMap.get(input.key)!;
+      for (const el of input.after ?? []) {
+        afterSet.add(el);
+      }
+    }
+    return edgeMap;
+  }
+
+  /**
+   * Produces a satisfied ordering for a list of orderable elements
+   */
+  static ordered<T, U extends OrderedState<T>>(items: List<U>): U[] {
+    const edgeMap = this.#buildEdgeMap<T, U>(items);
+
+    // Loop through all items again
+    const keys: T[] = [];
+    while (edgeMap.size > 0) {
+
+      // Find node with no dependencies
+      const key = [...edgeMap].find(([, after]) => after.size === 0)?.[0];
+      if (!key) {
+        throw new Error(`Unsatisfiable dependency: ${[...edgeMap.keys()]}`);
+      }
+
+      // Store, and remove
+      keys.push(key);
+      edgeMap.delete(key);
+
+      // Remove node from all other elements in `all`
+      for (const [, rem] of edgeMap) {
+        rem.delete(key);
+      }
+    }
+
+    const inputMap = new Map(items.map(x => [x.key, x]));
+    return keys.map(k => inputMap.get(k)!);
+  }
+
+  /**
+   * Get status code
+   */
+  static getStatusCode(response: WebResponse): number {
+    return (response.headers.has('Content-Range') && response.context.httpStatusCode === 200) ?
+      206 :
+      response.context.httpStatusCode ?? 200;
+  }
+
+  /**
+   * From catch value
+   */
+  static catchResponse(err: unknown): WebResponse<Error> {
+    if (err instanceof WebResponse) {
+      return err;
+    }
+
+    const body = err instanceof Error ? err :
+      (!!err && typeof err === 'object' && ('message' in err && typeof err.message === 'string')) ?
+        new AppError(err.message, { details: err }) :
+        new AppError(`${err}`);
+
+    const error: Error & { category?: ErrorCategory, details?: { statusCode: number } } = body;
+    const statusCode = error.details?.statusCode ?? ERROR_CATEGORY_STATUS[error.category!] ?? 500;
+
+    return new WebResponse({ body, context: { httpStatusCode: statusCode } });
+  }
+
+  /**
+   * Get request parameters
+   */
+  static getRequestParams(request: WebRequest & { [WebRequestParamsSymbol]?: unknown[] }): unknown[] {
+    return request[WebRequestParamsSymbol] ?? [];
+  }
+
+  /**
+   * Set request parameters
+   */
+  static setRequestParams(request: WebRequest & { [WebRequestParamsSymbol]?: unknown[] }, params: unknown[]): void {
+    request[WebRequestParamsSymbol] ??= params;
+  }
+
+  /**
+   * Get a cache control value
+   */
+  static getCacheControlValue(value: number | TimeSpan, flags: CacheControlFlag[] = []): string {
+    const delta = TimeUtil.asSeconds(value);
+    const finalFlags = delta === 0 ? ['no-cache'] : flags;
+    return [...finalFlags, `max-age=${delta}`].join(',');
+  }
+
+  /**
+   * Parse byte size
+   */
+  static parseByteSize(input: `${number}${'mb' | 'kb' | 'gb' | 'b' | ''}`): number {
+    const [, num, unit] = input.toLowerCase().split(/(\d+)/);
+    return parseInt(num, 10) * (this.#unitMapping[unit] ?? 1);
+  }
+}

package/src/util/cookie.ts

@@ -0,0 +1,145 @@
+import keygrip from 'keygrip';
+import { AppError, castKey, castTo } from '@travetto/runtime';
+
+import { Cookie, CookieGetOptions } from '../types/cookie.ts';
+
+const pairText = (c: Cookie): string => `${c.name}=${c.value}`;
+const pair = (k: string, v: unknown): string => `${k}=${v}`;
+
+export class CookieJar {
+
+  static fromHeaderValue(header: string): Cookie {
+    const parts = header.split(/\s{0,4};\s{0,4}/g);
+    const [name, value] = parts[0].split(/\s{0,4}=\s{0,4}/);
+    const c: Cookie = { name, value };
+    for (const p of parts.slice(1)) {
+      // eslint-disable-next-line prefer-const
+      let [k, v = ''] = p.split(/\s{0,4}=\s{0,4}/);
+      if (v[0] === '"') {
+        v = v.slice(1, -1);
+      }
+      if (k === 'expires') {
+        c[k] = new Date(v);
+      } else {
+        c[castKey(k)] = castTo(v || true);
+      }
+    }
+    return c;
+  }
+
+  static toHeaderValue(c: Cookie, response = true): string {
+    const header = [pair(c.name, c.value)];
+    if (response) {
+      if (!c.value) {
+        c.expires = new Date(0);
+        c.maxAge = undefined;
+      }
+      if (c.maxAge) {
+        c.expires = new Date(Date.now() + c.maxAge);
+      }
+
+      if (c.path) { header.push(pair('path', c.path)); }
+      if (c.expires) { header.push(pair('expires', c.expires.toUTCString())); }
+      if (c.domain) { header.push(pair('domain', c.domain)); }
+      if (c.priority) { header.push(pair('priority', c.priority.toLowerCase())); }
+      if (c.sameSite) { header.push(pair('samesite', c.sameSite.toLowerCase())); }
+      if (c.secure) { header.push('secure'); }
+      if (c.httpOnly) { header.push('httponly'); }
+      if (c.partitioned) { header.push('partitioned'); }
+    }
+    return header.join(';');
+  }
+
+  #secure?: boolean;
+  #grip?: keygrip;
+  #cookies: Record<string, Cookie> = {};
+
+  constructor(input?: string | string[] | null | undefined | Cookie[] | CookieJar, options?: { keys?: string[], secure?: boolean }) {
+    this.#grip = options?.keys?.length ? new keygrip(options.keys) : undefined;
+    this.#secure = options?.secure ?? false;
+    if (input instanceof CookieJar) {
+      this.#cookies = { ...input.#cookies };
+    } else if (Array.isArray(input)) {
+      this.#import(input);
+    } else {
+      this.#import(input?.split(/\s{0,4},\s{0,4}/) ?? []);
+    }
+  }
+
+  #checkSignature(c: Cookie): Cookie | undefined {
+    if (!this.#grip) { return; }
+    const key = pairText(c);
+    const sc = this.#cookies[`${c.name}.sig`];
+    if (!sc.value) { return; }
+
+    const index = this.#grip.index(key, sc.value);
+    c.signed = index >= 0;
+    sc.signed = false;
+    sc.secure = c.secure;
+
+    if (index >= 1) {
+      sc.value = this.#grip.sign(key);
+      sc.response = true;
+      return sc;
+    }
+  }
+
+  #signCookie(c: Cookie): Cookie {
+    if (!this.#grip) {
+      throw new AppError('.keys required for signed cookies');
+    } else if (!this.#secure && c.secure) {
+      throw new AppError('Cannot send secure cookie over unencrypted connection');
+    }
+    return { ...c, name: `${c.name}.sig`, value: this.#grip.sign(pairText(c)) };
+  }
+
+  #import(inputs: (string | Cookie)[]): void {
+    const toCheck = [];
+    for (const input of inputs) {
+      const c = typeof input === 'string' ? CookieJar.fromHeaderValue(input) : input;
+      this.#cookies[c.name] = c;
+      if (this.#grip && !c.name.endsWith('.sig')) {
+        toCheck.push(c);
+      }
+    }
+    for (const c of toCheck) {
+      const sc = this.#checkSignature(c);
+      if (sc) {
+        this.set(sc);
+      }
+    }
+  }
+
+  get(name: string, opts: CookieGetOptions = {}): string | undefined {
+    const c = this.#cookies[name];
+    return (c?.signed || !(opts.signed ?? !!this.#grip)) ? c?.value : undefined;
+  }
+
+  set(c: Cookie): void {
+    this.#cookies[c.name] = c;
+    c.secure ??= this.#secure;
+    c.signed ??= !!this.#grip;
+    c.response = true;
+
+    if (c.value === null || c.value === undefined) {
+      c.maxAge = -1;
+      c.expires = undefined;
+    }
+
+    if (c.signed) {
+      const sc = this.#signCookie(c);
+      this.#cookies[sc.name] = sc;
+      sc.response = true;
+    }
+  }
+
+  export(response = true): string[] {
+    return this.getAll()
+      .filter(x => !response || x.response)
+      .map(c => CookieJar.toHeaderValue(c, response));
+  }
+
+  getAll(): Cookie[] {
+    return Object.values(this.#cookies);
+  }
+}

package/src/util/endpoint.ts

@@ -0,0 +1,277 @@
+import { asConstructable, castTo, Class, Runtime, TypedObject } from '@travetto/runtime';
+import { BindUtil, FieldConfig, SchemaRegistry, SchemaValidator, ValidationResultError } from '@travetto/schema';
+import { DependencyRegistry } from '@travetto/di';
+import { RetargettingProxy } from '@travetto/registry';
+
+import { WebChainedFilter, WebChainedContext, WebFilter } from '../types/filter.ts';
+import { WebResponse } from '../types/response.ts';
+import { WebInterceptor } from '../types/interceptor.ts';
+import { WebRequest } from '../types/request.ts';
+import { WEB_INTERCEPTOR_CATEGORIES } from '../types/core.ts';
+import { EndpointConfig, ControllerConfig, EndpointParamConfig } from '../registry/types.ts';
+import { ControllerRegistry } from '../registry/controller.ts';
+import { WebCommonUtil } from './common.ts';
+
+
+const WebQueryExpandedSymbol = Symbol();
+
+/**
+ * Endpoint specific utilities
+ */
+export class EndpointUtil {
+
+  static #compareEndpoints(a: number[], b: number[]): number {
+    const al = a.length;
+    const bl = b.length;
+    if (al !== bl) {
+      return bl - al;
+    }
+    let i = 0;
+    while (i < al) {
+      if (a[i] !== b[i]) {
+        return b[i] - a[i];
+      }
+      i += 1;
+    }
+    return 0;
+  }
+
+  static MissingParamSymbol = Symbol();
+
+  /**
+   * Create a full filter chain given the provided filters
+   * @param filters Filters to chain
+   */
+  static createFilterChain(filters: { filter: WebChainedFilter, config?: unknown }[]): WebChainedFilter {
+    const len = filters.length - 1;
+    return function filterChain(ctx: WebChainedContext, idx: number = 0): Promise<WebResponse> {
+      const { filter, config } = filters[idx]!;
+      const chainedNext = idx === len ? ctx.next : filterChain.bind(null, ctx, idx + 1);
+      return filter({ request: ctx.request, next: chainedNext, config });
+    };
+  }
+
+  /**
+   * Resolve interceptors with configs
+   * @param interceptors
+   * @param endpoint
+   * @param controller
+   */
+  static resolveInterceptorsWithConfig(
+    interceptors: WebInterceptor[],
+    endpoint: EndpointConfig,
+    controller?: ControllerConfig
+  ): [WebInterceptor, unknown][] {
+
+    const inputByClass = Map.groupBy(
+      [...controller?.interceptorConfigs ?? [], ...endpoint.interceptorConfigs ?? []],
+      x => x[0]
+    );
+
+    const configs = new Map<Class, unknown>(interceptors.map(inst => {
+      const cls = asConstructable<WebInterceptor>(inst).constructor;
+      const inputs = (inputByClass.get(cls) ?? []).map(x => x[1]);
+      const config = Object.assign({}, inst.config, ...inputs);
+      return [cls, inst.finalizeConfig?.({ config, endpoint }, castTo(inputs)) ?? config];
+    }));
+
+    return interceptors.map(inst => [
+      inst,
+      configs.get(asConstructable(inst).constructor)
+    ]);
+  }
+
+  /**
+   * Extract parameter from request
+   */
+  static extractParameter(request: WebRequest, param: EndpointParamConfig, field: FieldConfig, value?: unknown): unknown {
+    if (value !== undefined && value !== this.MissingParamSymbol) {
+      return value;
+    } else if (param.extract) {
+      return param.extract(request, param);
+    }
+
+    const name = param.name!;
+    switch (param.location) {
+      case 'path': return request.context.pathParams?.[name];
+      case 'header': return field.array ? request.headers.getList(name) : request.headers.get(name);
+      case 'body': return request.body;
+      case 'query': {
+        const withQuery: typeof request & { [WebQueryExpandedSymbol]?: Record<string, unknown> } = request;
+        const q = withQuery[WebQueryExpandedSymbol] ??= BindUtil.expandPaths(request.context.httpQuery ?? {});
+        return param.prefix ? q[param.prefix] : (field.type.Ⲑid ? q : q[name]);
+      }
+    }
+  }
+
+  /**
+   * Extract all parameters for a given endpoint/request/response combo
+   * @param endpoint The endpoint to extract for
+   * @param req The request
+   * @param res The response
+   */
+  static async extractParameters(endpoint: EndpointConfig, request: WebRequest): Promise<unknown[]> {
+    const cls = endpoint.class;
+    const method = endpoint.name;
+    const vals = WebCommonUtil.getRequestParams(request);
+
+    try {
+      const fields = SchemaRegistry.getMethodSchema(cls, method);
+      const extracted = endpoint.params.map((c, i) => this.extractParameter(request, c, fields[i], vals?.[i]));
+      const params = BindUtil.coerceMethodParams(cls, method, extracted);
+      await SchemaValidator.validateMethod(cls, method, params, endpoint.params.map(x => x.prefix));
+      return params;
+    } catch (err) {
+      if (err instanceof ValidationResultError) {
+        for (const el of err.details?.errors ?? []) {
+          if (el.kind === 'required') {
+            const config = endpoint.params.find(x => x.name === el.path);
+            if (config) {
+              el.message = `Missing ${config.location.replace(/s$/, '')}: ${config.name}`;
+            }
+          }
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Endpoint invocation code
+   */
+  static async invokeEndpoint(endpoint: EndpointConfig, { request }: WebChainedContext): Promise<WebResponse> {
+    try {
+      const params = await this.extractParameters(endpoint, request);
+      const body = await endpoint.endpoint.apply(endpoint.instance, params);
+      const headers = endpoint.responseHeaderMap;
+      const response = body instanceof WebResponse ? body : new WebResponse({ body, headers });
+      if (response === body) {
+        for (const [k, v] of headers) { response.headers.setIfAbsent(k, v); }
+      }
+      return endpoint.responseFinalizer?.(response) ?? response;
+    } catch (err) {
+      throw WebCommonUtil.catchResponse(err);
+    }
+  }
+
+  /**
+   * Create a full endpoint handler
+   * @param interceptors Interceptors to apply
+   * @param endpoint The endpoint to call
+   * @param controller The controller to tie to
+   */
+  static createEndpointHandler(
+    interceptors: WebInterceptor[],
+    endpoint: EndpointConfig,
+    controller?: ControllerConfig
+  ): WebFilter {
+
+    // Filter interceptors if needed
+    for (const filter of [controller?.interceptorExclude, endpoint.interceptorExclude]) {
+      interceptors = filter ? interceptors.filter(x => !filter(x)) : interceptors;
+    }
+
+    const interceptorFilters =
+      this.resolveInterceptorsWithConfig(interceptors, endpoint, controller)
+        .filter(([inst, config]) => inst.applies?.({ endpoint, config }) ?? true)
+        .map(([inst, config]) => ({ filter: inst.filter.bind(inst), config }));
+
+    const endpointFilters = [
+      ...(controller?.filters ?? []).map(fn => fn.bind(controller?.instance)),
+      ...(endpoint.filters ?? []).map(fn => fn.bind(endpoint.instance)),
+      ...(endpoint.params.filter(cfg => cfg.resolve).map(fn => fn.resolve!))
+    ]
+      .map(fn => ({ filter: fn }));
+
+    const result = this.createFilterChain([
+      ...interceptorFilters,
+      ...endpointFilters,
+      { filter: this.invokeEndpoint.bind(this, endpoint) }
+    ]);
+
+    return castTo(result);
+  }
+
+
+  /**
+   * Get bound endpoints, honoring the conditional status
+   */
+  static async getBoundEndpoints(c: Class): Promise<EndpointConfig[]> {
+    const config = ControllerRegistry.get(c);
+
+    // Skip registering conditional controllers
+    if (config.conditional && !await config.conditional()) {
+      return [];
+    }
+
+    config.instance = await DependencyRegistry.getInstance(config.class);
+
+    if (Runtime.dynamic) {
+      config.instance = RetargettingProxy.unwrap(config.instance);
+    }
+
+    // Filter out conditional endpoints
+    const endpoints = (await Promise.all(
+      config.endpoints.map(ep => Promise.resolve(ep.conditional?.() ?? true).then(v => v ? ep : undefined))
+    )).filter(x => !!x);
+
+    if (!endpoints.length) {
+      return [];
+    }
+
+    for (const ep of endpoints) {
+      ep.instance = config.instance;
+    }
+
+    return endpoints;
+  }
+
+  /**
+   * Order endpoints by a set of rules, to ensure consistent registration and that precedence is honored
+   */
+  static orderEndpoints(endpoints: EndpointConfig[]): EndpointConfig[] {
+    return endpoints
+      .map(ep => {
+        const parts = ep.path.replace(/^[/]|[/]$/g, '').split('/');
+        return [ep, parts.map(x => /[*]/.test(x) ? 1 : /:/.test(x) ? 2 : 3)] as const;
+      })
+      .toSorted((a, b) => this.#compareEndpoints(a[1], b[1]) || a[0].path.localeCompare(b[0].path))
+      .map(([ep,]) => ep);
+  }
+
+
+  /**
+   * Order interceptors
+   */
+  static orderInterceptors(instances: WebInterceptor[]): WebInterceptor[] {
+    const cats = WEB_INTERCEPTOR_CATEGORIES.map(x => ({
+      key: x,
+      start: castTo<Class<WebInterceptor>>({ name: `${x}Start` }),
+      end: castTo<Class<WebInterceptor>>({ name: `${x}End` }),
+    }));
+
+    const categoryMapping = TypedObject.fromEntries(cats.map(x => [x.key, x]));
+
+    const ordered = instances.map(x => {
+      const group = categoryMapping[x.category];
+      const after = [...x.dependsOn ?? [], group.start];
+      const before = [...x.runsBefore ?? [], group.end];
+      return ({ key: x.constructor, before, after, target: x, placeholder: false });
+    });
+
+    // Add category sets into the ordering
+    let i = 0;
+    for (const cat of cats) {
+      const prevEnd = cats[i - 1]?.end ? [cats[i - 1].end] : [];
+      ordered.push(
+        { key: cat.start, before: [cat.end], after: prevEnd, placeholder: true, target: undefined! },
+        { key: cat.end, before: [], after: [cat.start], placeholder: true, target: undefined! }
+      );
+      i += 1;
+    }
+
+    return WebCommonUtil.ordered(ordered)
+      .filter(x => !x.placeholder)  // Drop out the placeholders
+      .map(x => x.target);
+  }
+}

package/src/util/mime.ts

@@ -0,0 +1,36 @@
+import { Util } from '@travetto/runtime';
+
+export type MimeType = { type: string, subtype: string, full: string, parameters: Record<string, string> };
+
+/**
+ * Utils for checking mime patterns
+ */
+export class MimeUtil {
+
+  static #convert(rule: string): RegExp {
+    const core = (rule.endsWith('/*') || !rule.includes('/')) ?
+      `${rule.replace(/[/].{0,20}$/, '')}\/.*` : rule;
+    return new RegExp(`^${core}[ ]{0,10}(;|$)`);
+  }
+
+  static parse(mimeType?: string): MimeType | undefined {
+    if (mimeType) {
+      const [full, ...params] = mimeType.split(/;/).map(x => x.trim());
+      const [type, subtype] = full.split('/');
+      const parameters = Object.fromEntries(params.map(v => v.split('=')).map(([k, v]) => [k.toLowerCase(), v]));
+      return { type, subtype, full, parameters };
+    }
+  }
+
+  /**
+   * Build matcher
+   */
+  static matcher(rules: string[] | string = []): (contentType: string) => boolean {
+    return Util.allowDeny<RegExp, [string]>(
+      rules,
+      this.#convert.bind(this),
+      (regex, mime) => regex.test(mime),
+      k => k
+    );
+  }
+}

package/src/util/net.ts

@@ -0,0 +1,61 @@
+import os from 'node:os';
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+
+import { ExecUtil } from '@travetto/runtime';
+
+/** Net utilities */
+export class NetUtil {
+
+  /** Is an error an address in use error */
+  static isPortUsedError(err: unknown): err is Error & { port: number } {
+    return !!err && err instanceof Error && err.message.includes('EADDRINUSE');
+  }
+
+  /** Get the port process id */
+  static async getPortProcessId(port: number): Promise<number | undefined> {
+    const proc = spawn('lsof', ['-t', '-i', `tcp:${port}`]);
+    const result = await ExecUtil.getResult(proc, { catch: true });
+    const [pid] = result.stdout.trim().split(/\n/g);
+    if (pid && +pid > 0) {
+      return +pid;
+    }
+  }
+
+  /** Free port if in use */
+  static async freePort(port: number): Promise<void> {
+    const pid = await this.getPortProcessId(port);
+    if (pid) {
+      process.kill(pid);
+    }
+  }
+
+  /** Find free port */
+  static async getFreePort(): Promise<number> {
+    return new Promise<number>((resolve, reject) => {
+      const server = net.createServer();
+      server.unref();
+      server.on('error', reject);
+
+      server.listen({ port: 0 }, () => {
+        const addr = server.address();
+        if (!addr || typeof addr === 'string') {
+          reject(new Error('Unable to get a free port'));
+          return;
+        }
+        const { port } = addr;
+        server.close(() => { resolve(port); });
+      });
+    });
+  }
+
+  /**
+   * Get local address for listening
+   */
+  static getLocalAddress(): string {
+    const useIPv4 = !![...Object.values(os.networkInterfaces())]
+      .find(interfaces => interfaces?.find(nic => nic.family === 'IPv4'));
+
+    return useIPv4 ? '0.0.0.0' : '::';
+  }
+}