@travetto/web 6.0.3 → 7.0.0-rc.0

package/src/registry/registry-adapter.ts

@@ -0,0 +1,185 @@
+import { RegistryAdapter } from '@travetto/registry';
+import { AppError, asFull, castTo, Class, RetainPrimitiveFields, safeAssign } from '@travetto/runtime';
+import { WebHeaders } from '@travetto/web';
+import { SchemaParameterConfig, SchemaRegistryIndex } from '@travetto/schema';
+
+import { ControllerConfig, EndpointConfig, EndpointParameterConfig, EndpointParamLocation } from './types';
+import type { WebInterceptor } from '../types/interceptor.ts';
+
+function combineCommon<T extends ControllerConfig | EndpointConfig>(base: T, override: Partial<T>): T {
+  base.filters = [...(base.filters ?? []), ...(override.filters ?? [])];
+  base.interceptorConfigs = [...(base.interceptorConfigs ?? []), ...(override.interceptorConfigs ?? [])];
+  base.interceptorExclude = base.interceptorExclude ?? override.interceptorExclude;
+  base.responseHeaders = { ...override.responseHeaders, ...base.responseHeaders };
+  base.responseContext = { ...override.responseContext, ...base.responseContext };
+  return base;
+}
+
+function combineClassConfigs(base: ControllerConfig, ...overrides: Partial<ControllerConfig>[]): ControllerConfig {
+  for (const override of overrides) {
+    combineCommon(base, override);
+    Object.assign(base, {
+      basePath: override.basePath || base.basePath,
+      contextParams: { ...base.contextParams, ...override.contextParams },
+    });
+  }
+  // Ensure we have full path
+  if (!base.basePath.startsWith('/')) {
+    base.basePath = `/${base.basePath}`;
+  }
+  return base;
+}
+
+function combineEndpointConfigs(ctrl: ControllerConfig, base: EndpointConfig, ...overrides: Partial<EndpointConfig>[]): EndpointConfig {
+  for (const override of overrides) {
+    combineCommon(base, override);
+    Object.assign(
+      base,
+      {
+        cacheable: override.cacheable ?? base.cacheable,
+        httpMethod: override.httpMethod ?? base.httpMethod,
+        allowsBody: override.allowsBody ?? base.allowsBody,
+        path: override.path || base.path,
+        parameters: (override.parameters ?? base.parameters).map(x => ({ ...x })),
+        responseFinalizer: override.responseFinalizer ?? base.responseFinalizer,
+      }
+    );
+  }
+  // Ensure we have full path
+  if (!base.path.startsWith('/')) {
+    base.path = `/${base.path}`;
+  }
+  return base;
+}
+
+/**
+ * Compute the location of a parameter within an endpoint
+ */
+function computeParameterLocation(ep: EndpointConfig, schema: SchemaParameterConfig): EndpointParamLocation {
+  const name = schema?.name;
+  if (!SchemaRegistryIndex.has(schema.type)) {
+    if ((schema.type === String || schema.type === Number) && name && ep.path.includes(`:${name.toString()}`)) {
+      return 'path';
+    } else if (schema.type === Blob || schema.type === File || schema.type === ArrayBuffer || schema.type === Uint8Array) {
+      return 'body';
+    }
+    return 'query';
+  } else {
+    return ep.allowsBody ? 'body' : 'query';
+  }
+}
+
+/**
+ * Adapter for controller registry
+ */
+export class ControllerRegistryAdapter implements RegistryAdapter<ControllerConfig> {
+  #config: ControllerConfig;
+  #endpoints: Map<string | symbol, EndpointConfig> = new Map();
+  #cls: Class;
+  #finalizeHandlers: Function[] = [];
+
+  constructor(cls: Class) {
+    this.#cls = cls;
+  }
+
+  register(...data: Partial<ControllerConfig>[]): ControllerConfig {
+    this.#config ??= {
+      class: this.#cls,
+      filters: [],
+      interceptorConfigs: [],
+      basePath: '',
+      externalName: this.#cls.name.replace(/(Controller|Web|Service)$/, ''),
+      endpoints: [],
+      contextParams: {},
+      responseHeaders: {}
+    };
+    combineClassConfigs(this.#config, ...data);
+    return this.#config;
+  }
+
+  registerEndpoint(method: string | symbol, ...data: Partial<EndpointConfig>[]): EndpointConfig {
+    this.register();
+
+    if (!this.#endpoints.has(method)) {
+      const endpointConfig = asFull<EndpointConfig>({
+        path: '/',
+        fullPath: '/',
+        cacheable: false,
+        allowsBody: false,
+        class: this.#cls,
+        filters: [],
+        endpoint: this.#cls.prototype[method],
+        methodName: method.toString(),
+        id: `${this.#cls.name}#${method.toString()}`,
+        parameters: [],
+        interceptorConfigs: [],
+        responseHeaders: {},
+        finalizedResponseHeaders: new WebHeaders(),
+        responseFinalizer: undefined
+      });
+      this.#config.endpoints.push(endpointConfig);
+      this.#endpoints.set(method, endpointConfig);
+    }
+
+    combineEndpointConfigs(this.#config, this.#endpoints.get(method)!, ...data);
+    return this.#endpoints.get(method)!;
+  }
+
+  registerEndpointParameter(method: string | symbol, index: number, ...config: Partial<EndpointParameterConfig>[]): EndpointParameterConfig {
+    const ep = this.registerEndpoint(method);
+    ep.parameters[index] ??= { index, location: 'query' };
+    safeAssign(ep.parameters[index], ...config);
+    return ep.parameters[index];
+  }
+
+  finalize(): void {
+    // Merge into controller
+    for (const ep of this.#config.endpoints) {
+      // Store full path from base for use in other contexts
+      ep.fullPath = `/${this.#config.basePath}/${ep.path}`.replace(/[/]{1,4}/g, '/').replace(/(.)[/]$/, (_, a) => a);
+      ep.finalizedResponseHeaders = new WebHeaders({ ...this.#config.responseHeaders, ...ep.responseHeaders });
+      ep.responseContext = { ...this.#config.responseContext, ...ep.responseContext };
+      for (const schema of SchemaRegistryIndex.getMethodConfig(this.#cls, ep.methodName).parameters) {
+        ep.parameters[schema.index!] ??= { index: schema.index!, location: undefined! };
+        ep.parameters[schema.index!].location ??= computeParameterLocation(ep, schema);
+      }
+    }
+    for (const item of this.#finalizeHandlers) {
+      item();
+    }
+    this.#finalizeHandlers = [];
+  }
+
+  get(): ControllerConfig {
+    return this.#config;
+  }
+
+  getEndpointConfig(method: string | symbol): EndpointConfig {
+    const endpoint = this.#endpoints.get(method);
+    if (!endpoint) {
+      throw new AppError(`Endpoint not registered: ${String(method)} on ${this.#cls.name}`);
+    }
+    return endpoint;
+  }
+
+  registerInterceptorConfig<T extends WebInterceptor>(
+    cls: Class<T>,
+    config: Partial<RetainPrimitiveFields<T['config']>>,
+    extra?: Partial<EndpointConfig & ControllerConfig>
+  ): ControllerConfig {
+    return this.register({ interceptorConfigs: [[cls, castTo(config)]], ...extra });
+  }
+
+  registerEndpointInterceptorConfig<T extends WebInterceptor>(
+    property: string | symbol,
+    cls: Class<T>,
+    config: Partial<RetainPrimitiveFields<T['config']>>,
+    extra?: Partial<EndpointConfig>
+  ): EndpointConfig {
+    return this.registerEndpoint(property, { interceptorConfigs: [[cls, castTo(config)]], ...extra });
+  }
+
+  registerFinalizeHandler(fn: () => void): void {
+    this.#finalizeHandlers.push(fn);
+  }
+}

package/src/registry/registry-index.ts

@@ -0,0 +1,110 @@
+import { ChangeEvent, RegistryIndex, RegistryIndexStore, Registry } from '@travetto/registry';
+import { Class, ClassInstance, getClass, RetainPrimitiveFields } from '@travetto/runtime';
+import { DependencyRegistryIndex } from '@travetto/di';
+import { SchemaRegistryIndex } from '@travetto/schema';
+
+import { ControllerRegistryAdapter } from './registry-adapter';
+import { ControllerConfig, EndpointConfig, EndpointDecorator } from './types';
+import { WebAsyncContext } from '../context';
+import type { WebInterceptor } from '../types/interceptor.ts';
+
+const isClass = (property: unknown, target: unknown): target is Class => !property;
+
+export class ControllerRegistryIndex implements RegistryIndex {
+
+  static #instance = Registry.registerIndex(this);
+
+  static getClasses(): Class[] {
+    return this.#instance.store.getClasses();
+  }
+
+  static getForRegister(cls: Class): ControllerRegistryAdapter {
+    return this.#instance.store.getForRegister(cls);
+  }
+
+  static getConfig(cls: Class): ControllerConfig {
+    return this.#instance.store.get(cls).get();
+  }
+
+  static getEndpointConfigById(id: string): EndpointConfig | undefined {
+    return this.#instance.getEndpointById(id);
+  }
+
+  static bindContextParamsOnPostConstruct(cls: Class): void {
+    this.#instance.bindContextParamsOnPostConstruct(cls);
+  }
+
+  /**
+   * Register a controller/endpoint with specific config for an interceptor
+   * @param cls The interceptor to register data for
+   * @param cfg The partial config override
+   */
+  static createInterceptorConfigDecorator<T extends WebInterceptor>(
+    cls: Class<T>,
+    cfg: Partial<RetainPrimitiveFields<T['config']>>,
+    extra?: Partial<EndpointConfig & ControllerConfig>
+  ): EndpointDecorator {
+    return (instanceOrCls: Class | ClassInstance, property?: symbol | string): void => {
+      const adapter = ControllerRegistryIndex.getForRegister(getClass(instanceOrCls));
+      if (isClass(property, instanceOrCls)) {
+        adapter.registerInterceptorConfig(cls, cfg, extra);
+      } else {
+        adapter.registerEndpointInterceptorConfig(property!, cls, cfg, extra);
+      }
+    };
+  }
+
+  #endpointsById = new Map<string, EndpointConfig>();
+
+  store = new RegistryIndexStore(ControllerRegistryAdapter);
+
+  async #bindContextParams<T>(instance: ClassInstance<T>): Promise<void> {
+    const ctx = await DependencyRegistryIndex.getInstance(WebAsyncContext);
+    const cls = getClass(instance);
+    const map = this.getController(cls).contextParams;
+    for (const field of Object.keys(map)) {
+      const { type } = SchemaRegistryIndex.getFieldMap(cls)[field];
+      Object.defineProperty(instance, field, { get: ctx.getSource(type) });
+    }
+  }
+
+  /**
+   * Register a controller to bind context params on post construct
+   * @param target Controller class
+   */
+  bindContextParamsOnPostConstruct(cls: Class): void {
+    DependencyRegistryIndex.registerClassMetadata(cls, {
+      postConstruct: {
+        ContextParam: (instance: ClassInstance) => this.#bindContextParams(instance)
+      }
+    });
+  }
+
+  getController(cls: Class): ControllerConfig {
+    return this.store.get(cls).get();
+  }
+
+  getEndpoint(cls: Class, method: string | symbol): EndpointConfig {
+    return this.getController(cls).endpoints.find(e => e.methodName === method)!;
+  }
+
+  getEndpointById(id: string): EndpointConfig | undefined {
+    return this.#endpointsById.get(id.replace(':', '#'));
+  }
+
+  process(events: ChangeEvent<Class>[]): void {
+    for (const evt of events) {
+      if ('curr' in evt) {
+        for (const ep of this.getController(evt.curr).endpoints) {
+          this.#endpointsById.set(`${evt.curr.name}#${ep.methodName.toString()}`, ep);
+        }
+      } else {
+        // Match by name
+        const toDelete = [...this.#endpointsById.values()].filter(x => x.class.name === evt.prev.name);
+        for (const ep of toDelete) {
+          this.#endpointsById.delete(ep.id);
+        }
+      }
+    }
+  }
+}

package/src/registry/types.ts

@@ -1,5 +1,5 @@
 import type { Any, Class, TypedFunction } from '@travetto/runtime';
-import type { FieldConfig, ClassConfig } from '@travetto/schema';
+import type { SchemaClassConfig, SchemaParameterConfig } from '@travetto/schema';
 
 import type { WebInterceptor } from '../types/interceptor.ts';
 import type { WebChainedFilter, WebFilter } from '../types/filter.ts';
@@ -16,35 +16,10 @@ export type EndpointFunctionDescriptor = TypedPropertyDescriptor<EndpointFunctio
  */
 export type EndpointDecorator = (
   (<T extends Class>(target: T) => void) &
-  (<U>(target: U, prop: string, descriptor?: EndpointFunctionDescriptor) => void)
+  (<U>(target: U, prop: string | symbol, 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;
-}
+export type EndpointParamLocation = 'path' | 'query' | 'body' | 'header';
 
 /**
  * Core configuration for endpoints and controllers
@@ -85,21 +60,17 @@ interface CoreConfig {
 }
 
 /**
- * Endpoint param configuration
+ * Endpoint parameter configuration
  */
-export interface EndpointParamConfig {
-  /**
-   * Name of the parameter
-   */
-  name?: string;
+export interface EndpointParameterConfig {
   /**
-   * Raw text of parameter at source
+   * Index of parameter
    */
-  sourceText?: string;
+  index: number;
   /**
    * Location of the parameter
    */
-  location: 'path' | 'query' | 'body' | 'header';
+  location: EndpointParamLocation;
   /**
    * Resolves the value by executing with req/res as input
    */
@@ -108,7 +79,7 @@ export interface EndpointParamConfig {
    * Extract the value from request
    * @param context The http context with the endpoint param config
    */
-  extract?: (ctx: WebRequest, config: EndpointParamConfig) => unknown;
+  extract?: (ctx: WebRequest, config: EndpointParameterConfig) => unknown;
   /**
    * Input prefix for parameter
    */
@@ -118,15 +89,15 @@ export interface EndpointParamConfig {
 /**
  * Endpoint configuration
  */
-export interface EndpointConfig extends CoreConfig, DescribableConfig {
+export interface EndpointConfig extends CoreConfig {
   /**
    * Unique identifier
    */
   id: string;
   /**
-   * The name of the method
+   * Name of the endpoint (method name)
    */
-  name: string;
+  methodName: string | symbol;
   /**
    * Instance the endpoint is for
    */
@@ -158,15 +129,7 @@ export interface EndpointConfig extends CoreConfig, DescribableConfig {
   /**
    * List of params for the endpoint
    */
-  params: EndpointParamConfig[];
-  /**
-   * The response type
-   */
-  responseType?: EndpointIOType;
-  /**
-   * The request type
-   */
-  requestType?: EndpointIOType;
+  parameters: EndpointParameterConfig[];
   /**
    * Full path including controller
    */
@@ -184,7 +147,7 @@ export interface EndpointConfig extends CoreConfig, DescribableConfig {
 /**
  * Controller configuration
  */
-export interface ControllerConfig extends CoreConfig, DescribableConfig {
+export interface ControllerConfig extends CoreConfig {
   /**
    * The base path of the controller
    */
@@ -200,13 +163,13 @@ export interface ControllerConfig extends CoreConfig, DescribableConfig {
   /**
    * Context parameters to bind at create
    */
-  contextParams: Record<string, Class>;
+  contextParams: Record<string | symbol, boolean>;
 }
 
 /**
  * Controller visitor options
  */
-export type ControllerVisitorOptions = { skipUndocumented?: boolean };
+export type ControllerVisitorOptions = { skipPrivate?: boolean };
 
 /**
  * Controller visitor pattern
@@ -218,10 +181,10 @@ export interface ControllerVisitor<T = unknown> {
   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;
+  onEndpointStart?(endpoint: EndpointConfig, controller: ControllerConfig, methodParams: SchemaParameterConfig[]): Promise<unknown> | unknown;
+  onEndpointEnd?(endpoint: EndpointConfig, controller: ControllerConfig, methodParams: SchemaParameterConfig[]): Promise<unknown> | unknown;
 
-  onSchema?(schema: ClassConfig): Promise<unknown> | unknown;
+  onSchema?(schema: SchemaClassConfig): Promise<unknown> | unknown;
 
   onControllerAdd?(cls: Class): Promise<unknown> | unknown;
   onControllerRemove?(cls: Class): Promise<unknown> | unknown;

package/src/registry/visitor.ts

@@ -1,8 +1,8 @@
 import { Class } from '@travetto/runtime';
-import { SchemaRegistry } from '@travetto/schema';
+import { SchemaRegistryIndex } from '@travetto/schema';
 
 import { ControllerVisitor, ControllerVisitorOptions } from './types.ts';
-import { ControllerRegistry } from './controller.ts';
+import { ControllerRegistryIndex } from './registry-index.ts';
 
 /**
  * Supports visiting the controller structure
@@ -10,7 +10,7 @@ import { ControllerRegistry } from './controller.ts';
 export class ControllerVisitUtil {
 
   static #onSchemaEvent(visitor: ControllerVisitor, type?: Class): unknown | Promise<unknown> {
-    return type && SchemaRegistry.has(type) ? visitor.onSchema?.(SchemaRegistry.get(type)) : undefined;
+    return type && SchemaRegistryIndex.has(type) ? visitor.onSchema?.(SchemaRegistryIndex.getConfig(type)) : undefined;
   }
 
   static async visitController(visitor: ControllerVisitor, cls: Class, options: ControllerVisitorOptions = {}): Promise<void> {
@@ -18,23 +18,26 @@ export class ControllerVisitUtil {
       options = Object.assign(visitor.getOptions(), options);
     }
 
-    options.skipUndocumented ??= true;
+    options.skipPrivate ??= true;
 
-    const controller = ControllerRegistry.get(cls);
-    if (!controller || controller.documented === false && options.skipUndocumented) {
+    const controller = ControllerRegistryIndex.getConfig(cls);
+    const schema = SchemaRegistryIndex.getConfig(cls);
+    if (schema.private === true && options.skipPrivate) {
       return;
     }
 
     await visitor.onControllerStart?.(controller);
     for (const endpoint of controller.endpoints) {
-      if (endpoint.documented === false && options.skipUndocumented) {
+      const endpointSchema = SchemaRegistryIndex.getMethodConfig(cls, endpoint.methodName);
+      if (endpointSchema.private === true && options.skipPrivate) {
         continue;
       }
 
-      const params = SchemaRegistry.getMethodSchema(cls, endpoint.name);
+      const { parameters: params, returnType } = SchemaRegistryIndex.getMethodConfig(cls, endpoint.methodName);
       await visitor.onEndpointStart?.(endpoint, controller, params);
-      await this.#onSchemaEvent(visitor, endpoint.responseType?.type);
-      await this.#onSchemaEvent(visitor, endpoint.requestType?.type);
+      if (returnType) {
+        await this.#onSchemaEvent(visitor, returnType.type);
+      }
       for (const param of params) {
         await this.#onSchemaEvent(visitor, param.type);
       }
@@ -44,7 +47,7 @@ export class ControllerVisitUtil {
   }
 
   static async visit<T = unknown>(visitor: ControllerVisitor<T>, options: ControllerVisitorOptions = {}): Promise<T> {
-    for (const cls of ControllerRegistry.getClasses()) {
+    for (const cls of ControllerRegistryIndex.getClasses()) {
       await this.visitController(visitor, cls, options);
     }
     return await visitor.onComplete?.() ?? undefined!;

package/src/router/base.ts

@@ -1,9 +1,9 @@
 import { Class, toConcrete } from '@travetto/runtime';
-import { DependencyRegistry } from '@travetto/di';
+import { DependencyRegistryIndex, Injectable } from '@travetto/di';
+import { ControllerRegistryIndex } from '@travetto/web';
+import { Registry } from '@travetto/registry';
 
 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';
@@ -14,13 +14,14 @@ import { EndpointUtil } from '../util/endpoint.ts';
 /**
  * Supports the base pattern for the most common web router implementations
  */
+@Injectable()
 export abstract class BaseWebRouter implements WebRouter {
 
   #cleanup = new Map<string, Function>();
   #interceptors: WebInterceptor[];
 
   async #register(c: Class): Promise<void> {
-    const config = ControllerRegistry.get(c);
+    const config = ControllerRegistryIndex.getConfig(c);
 
     let endpoints = await EndpointUtil.getBoundEndpoints(c);
     endpoints = EndpointUtil.orderEndpoints(endpoints);
@@ -29,7 +30,6 @@ export abstract class BaseWebRouter implements WebRouter {
       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);
   };
@@ -39,27 +39,29 @@ export abstract class BaseWebRouter implements WebRouter {
    */
   async postConstruct(): Promise<void> {
 
-    this.#interceptors = await DependencyRegistry.getCandidateInstances(toConcrete<WebInterceptor>());
+    this.#interceptors = await DependencyRegistryIndex.getInstances(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()) {
+    for (const c of ControllerRegistryIndex.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)) {
+    Registry.onClassChange(async e => {
+      const targetCls = 'curr' in e ? e.curr : e.prev;
+      console.debug('Registry event', { type: e.type, target: targetCls.Ⲑid });
+
+      if ('prev' in e) {
         this.#cleanup.get(e.prev.Ⲑid)?.();
         this.#cleanup.delete(e.prev.Ⲑid);
       }
-      if (e.curr) {
+      if ('curr' in e) {
         await this.#register(e.curr);
       }
-    });
+    }, ControllerRegistryIndex);
   }
 
   abstract register(endpoints: EndpointConfig[], controller: ControllerConfig): Promise<() => void>;