@travetto/web 6.0.0-rc.2

package/src/interceptor/trust-proxy.ts

@@ -0,0 +1,53 @@
+import { Config } from '@travetto/config';
+import { Inject, Injectable } from '@travetto/di';
+import { castTo } from '@travetto/runtime';
+
+import { WebInterceptor, WebInterceptorContext } from '../types/interceptor.ts';
+import { WebInterceptorCategory } from '../types/core.ts';
+import { WebResponse } from '../types/response.ts';
+import { WebChainedContext } from '../types/filter.ts';
+
+@Config('web.trustProxy')
+export class TrustProxyConfig {
+  /**
+   * Enforces trust rules for X-Forwarded-* headers
+   */
+  applies = true;
+  /**
+   * The accepted ips
+   */
+  ips: string[] = [];
+}
+
+@Injectable()
+export class TrustProxyInterceptor implements WebInterceptor<TrustProxyConfig> {
+
+  category: WebInterceptorCategory = 'pre-request';
+
+  @Inject()
+  config: TrustProxyConfig;
+
+  applies({ config }: WebInterceptorContext<TrustProxyConfig>): boolean {
+    return config.applies;
+  }
+
+  filter({ request, next, config }: WebChainedContext<TrustProxyConfig>): Promise<WebResponse> {
+    const forwardedFor = request.headers.get('X-Forwarded-For');
+
+    if (forwardedFor) {
+      const connection = request.context.connection ?? {};
+      if (config.ips[0] === '*' || (connection.ip && config.ips.includes(connection.ip))) {
+        connection.httpProtocol = castTo(request.headers.get('X-Forwarded-Proto')!) || connection.httpProtocol;
+        connection.host = request.headers.get('X-Forwarded-Host') || connection.host;
+        connection.ip = forwardedFor;
+        Object.assign(request.context, { connection });
+      }
+    }
+
+    request.headers.delete('X-Forwarded-For');
+    request.headers.delete('X-Forwarded-Proto');
+    request.headers.delete('X-Forwarded-Host');
+
+    return next();
+  }
+}

package/src/registry/controller.ts

@@ -0,0 +1,288 @@
+import { DependencyRegistry } from '@travetto/di';
+import { type Primitive, type Class, asFull, castTo, asConstructable, ClassInstance } from '@travetto/runtime';
+import { MetadataRegistry } from '@travetto/registry';
+
+import { EndpointConfig, ControllerConfig, EndpointDecorator, EndpointParamConfig, EndpointFunctionDescriptor, EndpointFunction } from './types.ts';
+import { WebChainedFilter, WebFilter } from '../types/filter.ts';
+import { WebInterceptor } from '../types/interceptor.ts';
+import { WebHeaders } from '../types/headers.ts';
+
+import { WebAsyncContext } from '../context.ts';
+
+type ValidFieldNames<T> = {
+  [K in keyof T]:
+  (T[K] extends (Primitive | undefined) ? K :
+    (T[K] extends (Function | undefined) ? never :
+      K))
+}[keyof T];
+
+type RetainFields<T> = Pick<T, ValidFieldNames<T>>;
+
+/**
+ * Controller registry
+ */
+class $ControllerRegistry extends MetadataRegistry<ControllerConfig, EndpointConfig> {
+
+  #endpointsById = new Map<string, EndpointConfig>();
+
+  constructor() {
+    super(DependencyRegistry);
+  }
+
+  async #bindContextParams<T>(inst: ClassInstance<T>): Promise<void> {
+    const ctx = await DependencyRegistry.getInstance(WebAsyncContext);
+    const map = this.get(inst.constructor).contextParams;
+    for (const [field, type] of Object.entries(map)) {
+      Object.defineProperty(inst, field, { get: ctx.getSource(type) });
+    }
+  }
+
+  getEndpointById(id: string): EndpointConfig | undefined {
+    return this.#endpointsById.get(id.replace(':', '#'));
+  }
+
+  createPending(cls: Class): ControllerConfig {
+    return {
+      class: cls,
+      filters: [],
+      interceptorConfigs: [],
+      basePath: '',
+      externalName: cls.name.replace(/(Controller|Web|Service)$/, ''),
+      endpoints: [],
+      contextParams: {},
+    };
+  }
+
+  createPendingField(cls: Class, endpoint: EndpointFunction): EndpointConfig {
+    const controllerConf = this.getOrCreatePending(cls);
+
+    const fieldConf: EndpointConfig = {
+      id: `${cls.name}#${endpoint.name}`,
+      path: '/',
+      fullPath: '/',
+      cacheable: false,
+      allowsBody: false,
+      class: cls,
+      filters: [],
+      params: [],
+      interceptorConfigs: [],
+      name: endpoint.name,
+      endpoint,
+      responseHeaderMap: new WebHeaders(),
+      responseFinalizer: undefined
+    };
+
+    controllerConf.endpoints!.push(fieldConf);
+
+    return fieldConf;
+  }
+
+  /**
+   * Register the endpoint config
+   * @param cls Controller class
+   * @param endpoint Endpoint target function
+   */
+  getOrCreateEndpointConfig<T>(cls: Class<T>, endpoint: EndpointFunction): EndpointConfig {
+    const fieldConf = this.getOrCreatePendingField(cls, endpoint);
+    return asFull(fieldConf);
+  }
+
+  /**
+   * Register the controller filter
+   * @param cls Controller class
+   * @param filter The filter to call
+   */
+  registerControllerFilter(target: Class, filter: WebFilter | WebChainedFilter): void {
+    const config = this.getOrCreatePending(target);
+    config.filters!.push(filter);
+  }
+
+  /**
+   * Register the controller filter
+   * @param cls Controller class
+   * @param endpoint Endpoint function
+   * @param filter The filter to call
+   */
+  registerEndpointFilter(target: Class, endpoint: EndpointFunction, filter: WebFilter | WebChainedFilter): void {
+    const config = this.getOrCreateEndpointConfig(target, endpoint);
+    config.filters!.unshift(filter);
+  }
+
+  /**
+   * Register the endpoint parameter
+   * @param cls Controller class
+   * @param endpoint Endpoint function
+   * @param param The param config
+   * @param index The parameter index
+   */
+  registerEndpointParameter(target: Class, endpoint: EndpointFunction, param: EndpointParamConfig, index: number): void {
+    const config = this.getOrCreateEndpointConfig(target, endpoint);
+    if (index >= config.params.length) {
+      config.params.length = index + 1;
+    }
+    config.params[index] = param;
+  }
+
+  /**
+   * Register the endpoint interceptor config
+   * @param cls Controller class
+   * @param endpoint Endpoint function
+   * @param param The param config
+   * @param index The parameter index
+   */
+  registerEndpointInterceptorConfig<T extends WebInterceptor>(target: Class, endpoint: EndpointFunction, interceptorCls: Class<T>, config: Partial<T['config']>): void {
+    const endpointConfig = this.getOrCreateEndpointConfig(target, endpoint);
+    (endpointConfig.interceptorConfigs ??= []).push([interceptorCls, { ...config }]);
+  }
+
+  /**
+   * Register the controller interceptor config
+   * @param cls Controller class
+   * @param param The param config
+   * @param index The parameter index
+   */
+  registerControllerInterceptorConfig<T extends WebInterceptor>(target: Class, interceptorCls: Class<T>, config: Partial<T['config']>): void {
+    const controllerConfig = this.getOrCreatePending(target);
+    (controllerConfig.interceptorConfigs ??= []).push([interceptorCls, { ...config }]);
+  }
+
+  /**
+   * Register a controller context param
+   * @param target Controller class
+   * @param field Field on controller to bind context param to
+   * @param type The context type to bind to field
+   */
+  registerControllerContextParam<T>(target: Class, field: string, type: Class<T>): void {
+    const controllerConfig = this.getOrCreatePending(target);
+    controllerConfig.contextParams![field] = type;
+    DependencyRegistry.registerPostConstructHandler(target, 'ContextParam', inst => this.#bindContextParams(inst));
+  }
+
+  /**
+   * Create a filter decorator
+   * @param filter The filter to call
+   */
+  createFilterDecorator(filter: WebFilter): EndpointDecorator {
+    return (target: unknown, prop?: symbol | string, descriptor?: EndpointFunctionDescriptor): void => {
+      if (prop) {
+        this.registerEndpointFilter(asConstructable(target).constructor, descriptor!.value!, filter);
+      } else {
+        this.registerControllerFilter(castTo(target), filter);
+      }
+    };
+  }
+
+  /**
+   * Register a controller/endpoint with specific config for an interceptor
+   * @param cls The interceptor to register data for
+   * @param cfg The partial config override
+   */
+  createInterceptorConfigDecorator<T extends WebInterceptor>(
+    cls: Class<T>,
+    cfg: Partial<RetainFields<T['config']>>,
+    extra?: Partial<EndpointConfig & ControllerConfig>
+  ): EndpointDecorator {
+    return (target: unknown, prop?: symbol | string, descriptor?: EndpointFunctionDescriptor): void => {
+      const outCls: Class = descriptor ? asConstructable(target).constructor : castTo(target);
+      if (prop && descriptor) {
+        this.registerEndpointInterceptorConfig(outCls, descriptor!.value!, cls, castTo(cfg));
+        extra && this.registerPendingEndpoint(outCls, descriptor, extra);
+      } else {
+        this.registerControllerInterceptorConfig(outCls, cls, castTo(cfg));
+        extra && this.registerPending(outCls, extra);
+      }
+    };
+  }
+
+  /**
+   * Merge describable
+   * @param src Root describable (controller, endpoint)
+   * @param dest Target (controller, endpoint)
+   */
+  mergeDescribable(src: Partial<ControllerConfig | EndpointConfig>, dest: Partial<ControllerConfig | EndpointConfig>): void {
+    dest.filters = [...(dest.filters ?? []), ...(src.filters ?? [])];
+    dest.interceptorConfigs = [...(dest.interceptorConfigs ?? []), ...(src.interceptorConfigs ?? [])];
+    dest.interceptorExclude = dest.interceptorExclude ?? src.interceptorExclude;
+    dest.title = src.title || dest.title;
+    dest.description = src.description || dest.description;
+    dest.documented = src.documented ?? dest.documented;
+    dest.responseHeaders = { ...src.responseHeaders, ...dest.responseHeaders };
+  }
+
+  /**
+   * Register an endpoint as pending
+   * @param target Controller class
+   * @param descriptor Prop descriptor
+   * @param config The endpoint config
+   */
+  registerPendingEndpoint(target: Class, descriptor: EndpointFunctionDescriptor, config: Partial<EndpointConfig>): EndpointFunctionDescriptor {
+    const srcConf = this.getOrCreateEndpointConfig(target, descriptor.value!);
+    srcConf.cacheable = config.cacheable ?? srcConf.cacheable;
+    srcConf.httpMethod = config.httpMethod ?? srcConf.httpMethod;
+    srcConf.allowsBody = config.allowsBody ?? srcConf.allowsBody;
+    srcConf.path = config.path || srcConf.path;
+    srcConf.responseType = config.responseType ?? srcConf.responseType;
+    srcConf.requestType = config.requestType ?? srcConf.requestType;
+    srcConf.params = (config.params ?? srcConf.params).map(x => ({ ...x }));
+    srcConf.responseFinalizer = config.responseFinalizer ?? srcConf.responseFinalizer;
+
+    // Ensure path starts with '/'
+    if (!srcConf.path.startsWith('/')) {
+      srcConf.path = `/${srcConf.path}`;
+    }
+
+    this.mergeDescribable(config, srcConf);
+
+    return descriptor;
+  }
+
+  /**
+   * Register a pending configuration
+   * @param target The target class
+   * @param config The controller configuration
+   */
+  registerPending(target: Class, config: Partial<ControllerConfig>): void {
+    const srcConf = this.getOrCreatePending(target);
+    srcConf.basePath = config.basePath || srcConf.basePath;
+
+    if (!srcConf.basePath!.startsWith('/')) {
+      srcConf.basePath = `/${srcConf.basePath}`;
+    }
+
+    srcConf.contextParams = { ...srcConf.contextParams, ...config.contextParams };
+
+
+    this.mergeDescribable(config, srcConf);
+  }
+
+  /**
+   * Finalize endpoints, removing duplicates based on ids
+   */
+  onInstallFinalize(cls: Class): ControllerConfig {
+    const final = asFull(this.getOrCreatePending(cls));
+
+    // Store for lookup
+    for (const ep of final.endpoints) {
+      this.#endpointsById.set(ep.id, ep);
+      // Store full path from base for use in other contexts
+      ep.fullPath = `/${final.basePath}/${ep.path}`.replace(/[/]{1,4}/g, '/').replace(/(.)[/]$/, (_, a) => a);
+      ep.responseHeaderMap = new WebHeaders({ ...final.responseHeaders ?? {}, ...ep.responseHeaders ?? {} });
+    }
+
+    if (this.has(final.basePath)) {
+      console.debug('Reloading controller', { name: cls.name, path: final.basePath });
+    }
+
+    return final;
+  }
+
+  onUninstallFinalize<T>(cls: Class<T>): void {
+    const toDelete = [...this.#endpointsById.values()].filter(x => x.class.name === cls.name);
+    for (const k of toDelete) {
+      this.#endpointsById.delete(k.id);
+    }
+    super.onUninstallFinalize(cls);
+  }
+}
+
+export const ControllerRegistry = new $ControllerRegistry();

package/src/registry/types.ts

@@ -0,0 +1,229 @@
+import type { Any, Class, TypedFunction } from '@travetto/runtime';
+import type { FieldConfig, ClassConfig } from '@travetto/schema';
+
+import type { WebInterceptor } from '../types/interceptor.ts';
+import type { WebChainedFilter, WebFilter } from '../types/filter.ts';
+import { HttpMethod } from '../types/core.ts';
+import { WebHeaders } from '../types/headers.ts';
+import { WebResponse } from '../types/response.ts';
+import { WebRequest } from '../types/request.ts';
+
+export type EndpointFunction = TypedFunction<Any, unknown>;
+export type EndpointFunctionDescriptor = TypedPropertyDescriptor<EndpointFunction>;
+
+/**
+ * Endpoint decorator for composition of routing logic
+ */
+export type EndpointDecorator = (
+  (<T extends Class>(target: T) => void) &
+  (<U>(target: U, prop: string, descriptor?: EndpointFunctionDescriptor) => void)
+);
+
+/**
+ * Endpoint type
+ */
+export type EndpointIOType = {
+  type: Class;
+  array?: boolean;
+  description?: string;
+};
+
+/**
+ * Describable elements
+ */
+export interface DescribableConfig {
+  /**
+   * The title
+   */
+  title?: string;
+  /**
+   * Description
+   */
+  description?: string;
+  /**
+   * Is the resource documented
+   */
+  documented?: boolean;
+}
+
+/**
+ * Core configuration for endpoints and controllers
+ */
+interface CoreConfig {
+  /**
+   * The related class
+   */
+  class: Class;
+  /**
+   * The actual class instance
+   */
+  instance?: unknown;
+  /**
+   * List of filters to run on request
+   */
+  filters: (WebFilter | WebChainedFilter)[];
+  /**
+   * Set of interceptor configs
+   */
+  interceptorConfigs?: [Class<WebInterceptor>, unknown][];
+  /**
+   * Should the resource only be used conditionally?
+   */
+  conditional?: () => (boolean | Promise<boolean>);
+  /**
+   * Control which interceptors are excluded
+   */
+  interceptorExclude?: (val: WebInterceptor) => boolean;
+  /**
+   * Response headers
+   */
+  responseHeaders?: Record<string, string>;
+}
+
+/**
+ * Endpoint param configuration
+ */
+export interface EndpointParamConfig {
+  /**
+   * Name of the parameter
+   */
+  name?: string;
+  /**
+   * Raw text of parameter at source
+   */
+  sourceText?: string;
+  /**
+   * Location of the parameter
+   */
+  location: 'path' | 'query' | 'body' | 'header';
+  /**
+   * Resolves the value by executing with req/res as input
+   */
+  resolve?: WebFilter;
+  /**
+   * Extract the value from request
+   * @param context The http context with the endpoint param config
+   */
+  extract?: (ctx: WebRequest, config: EndpointParamConfig) => unknown;
+  /**
+   * Input prefix for parameter
+   */
+  prefix?: string;
+}
+
+/**
+ * Endpoint configuration
+ */
+export interface EndpointConfig extends CoreConfig, DescribableConfig {
+  /**
+   * Unique identifier
+   */
+  id: string;
+  /**
+   * The name of the method
+   */
+  name: string;
+  /**
+   * Instance the endpoint is for
+   */
+  instance?: unknown;
+  /**
+   * Method alias for the endpoint
+   */
+  httpMethod?: HttpMethod;
+  /**
+   * Is this endpoint cacheable
+   */
+  cacheable: boolean;
+  /**
+   * Does this endpoint allow a body
+   */
+  allowsBody: boolean;
+  /**
+   * The path of the endpoint
+   */
+  path: string;
+  /**
+   * The function the endpoint will call
+   */
+  endpoint: EndpointFunction;
+  /**
+   * The compiled and finalized handler
+   */
+  filter?: WebFilter;
+  /**
+   * List of params for the endpoint
+   */
+  params: EndpointParamConfig[];
+  /**
+   * The response type
+   */
+  responseType?: EndpointIOType;
+  /**
+   * The request type
+   */
+  requestType?: EndpointIOType;
+  /**
+   * Full path including controller
+   */
+  fullPath: string;
+  /**
+   * Response header map
+   */
+  responseHeaderMap: WebHeaders;
+  /**
+   * Response finalizer
+   */
+  responseFinalizer?: (res: WebResponse) => WebResponse;
+}
+
+/**
+ * Controller configuration
+ */
+export interface ControllerConfig extends CoreConfig, DescribableConfig {
+  /**
+   * The base path of the controller
+   */
+  basePath: string;
+  /**
+   * List of all endpoints
+   */
+  endpoints: EndpointConfig[];
+  /**
+   * Client name, used by consuming tools/clients
+   */
+  externalName: string;
+  /**
+   * Context parameters to bind at create
+   */
+  contextParams: Record<string, Class>;
+}
+
+/**
+ * Controller visitor options
+ */
+export type ControllerVisitorOptions = { skipUndocumented?: boolean };
+
+/**
+ * Controller visitor pattern
+ */
+export interface ControllerVisitor<T = unknown> {
+
+  getOptions?: () => ControllerVisitorOptions;
+
+  onControllerStart?(controller: ControllerConfig): Promise<unknown> | unknown;
+  onControllerEnd?(controller: ControllerConfig): Promise<unknown> | unknown;
+
+  onEndpointStart?(endpoint: EndpointConfig, controller: ControllerConfig, methodParams: FieldConfig[]): Promise<unknown> | unknown;
+  onEndpointEnd?(endpoint: EndpointConfig, controller: ControllerConfig, methodParams: FieldConfig[]): Promise<unknown> | unknown;
+
+  onSchema?(schema: ClassConfig): Promise<unknown> | unknown;
+
+  onControllerAdd?(cls: Class): Promise<unknown> | unknown;
+  onControllerRemove?(cls: Class): Promise<unknown> | unknown;
+
+  onSchemaAdd?(cls: Class): Promise<boolean> | boolean;
+  onSchemaRemove?(cls: Class): Promise<boolean> | boolean;
+
+  onComplete?(): T | Promise<T>;
+}

package/src/registry/visitor.ts

@@ -0,0 +1,52 @@
+import { Class } from '@travetto/runtime';
+import { SchemaRegistry } from '@travetto/schema';
+
+import { ControllerVisitor, ControllerVisitorOptions } from './types.ts';
+import { ControllerRegistry } from './controller.ts';
+
+/**
+ * Supports visiting the controller structure
+ */
+export class ControllerVisitUtil {
+
+  static #onSchemaEvent(visitor: ControllerVisitor, type?: Class): unknown | Promise<unknown> {
+    return type && SchemaRegistry.has(type) ? visitor.onSchema?.(SchemaRegistry.get(type)) : undefined;
+  }
+
+  static async visitController(visitor: ControllerVisitor, cls: Class, options: ControllerVisitorOptions = {}): Promise<void> {
+    if (visitor.getOptions) {
+      options = Object.assign(visitor.getOptions(), options);
+    }
+
+    options.skipUndocumented ??= true;
+
+    const controller = ControllerRegistry.get(cls);
+    if (!controller || controller.documented === false && options.skipUndocumented) {
+      return;
+    }
+
+    await visitor.onControllerStart?.(controller);
+    for (const endpoint of controller.endpoints) {
+      if (endpoint.documented === false && options.skipUndocumented) {
+        continue;
+      }
+
+      const params = SchemaRegistry.getMethodSchema(cls, endpoint.name);
+      await visitor.onEndpointStart?.(endpoint, controller, params);
+      await this.#onSchemaEvent(visitor, endpoint.responseType?.type);
+      await this.#onSchemaEvent(visitor, endpoint.requestType?.type);
+      for (const param of params) {
+        await this.#onSchemaEvent(visitor, param.type);
+      }
+      await visitor.onEndpointEnd?.(endpoint, controller, params);
+    }
+    await visitor.onControllerEnd?.(controller);
+  }
+
+  static async visit<T = unknown>(visitor: ControllerVisitor<T>, options: ControllerVisitorOptions = {}): Promise<T> {
+    for (const cls of ControllerRegistry.getClasses()) {
+      await this.visitController(visitor, cls, options);
+    }
+    return await visitor.onComplete?.() ?? undefined!;
+  }
+}

package/src/router/base.ts

@@ -0,0 +1,67 @@
+import { Class, toConcrete } from '@travetto/runtime';
+import { DependencyRegistry } from '@travetto/di';
+
+import { ControllerConfig, EndpointConfig } from '../registry/types.ts';
+import { ControllerRegistry } from '../registry/controller.ts';
+
+import type { WebRouter } from '../types/dispatch.ts';
+import { WebInterceptor } from '../types/interceptor.ts';
+import { WebResponse } from '../types/response.ts';
+import type { WebFilterContext } from '../types/filter.ts';
+
+import { EndpointUtil } from '../util/endpoint.ts';
+
+/**
+ * Supports the base pattern for the most common web router implementations
+ */
+export abstract class BaseWebRouter implements WebRouter {
+
+  #cleanup = new Map<string, Function>();
+  #interceptors: WebInterceptor[];
+
+  async #register(c: Class): Promise<void> {
+    const config = ControllerRegistry.get(c);
+
+    let endpoints = await EndpointUtil.getBoundEndpoints(c);
+    endpoints = EndpointUtil.orderEndpoints(endpoints);
+
+    for (const ep of endpoints) {
+      ep.filter = EndpointUtil.createEndpointHandler(this.#interceptors, ep, config);
+    }
+
+    console.debug('Registering Controller Instance', { id: config.class.Ⲑid, path: config.basePath, endpointCount: endpoints.length });
+    const fn = await this.register(endpoints, config);
+    this.#cleanup.set(c.Ⲑid, fn);
+  };
+
+  /**
+   * Initialize router, encapsulating common patterns for standard router setup
+   */
+  async postConstruct(): Promise<void> {
+
+    this.#interceptors = await DependencyRegistry.getCandidateInstances(toConcrete<WebInterceptor>());
+    this.#interceptors = EndpointUtil.orderInterceptors(this.#interceptors);
+    const names = this.#interceptors.map(x => x.constructor.name);
+    console.debug('Sorting interceptors', { count: names.length, names });
+
+    // Register all active
+    for (const c of ControllerRegistry.getClasses()) {
+      await this.#register(c);
+    }
+
+    // Listen for updates
+    ControllerRegistry.on(async e => {
+      console.debug('Registry event', { type: e.type, target: (e.curr ?? e.prev)?.Ⲑid });
+      if (e.prev && ControllerRegistry.hasExpired(e.prev)) {
+        this.#cleanup.get(e.prev.Ⲑid)?.();
+        this.#cleanup.delete(e.prev.Ⲑid);
+      }
+      if (e.curr) {
+        await this.#register(e.curr);
+      }
+    });
+  }
+
+  abstract register(endpoints: EndpointConfig[], controller: ControllerConfig): Promise<() => void>;
+  abstract dispatch(ctx: WebFilterContext): Promise<WebResponse>;
+}