@travetto/web 6.0.0-rc.2

package/__index__.ts

@@ -0,0 +1,44 @@
+export * from './src/types/filter.ts';
+export * from './src/types/request.ts';
+export * from './src/types/response.ts';
+export * from './src/types/core.ts';
+export * from './src/types/dispatch.ts';
+export * from './src/types/error.ts';
+export * from './src/types/cookie.ts';
+export * from './src/types/interceptor.ts';
+export * from './src/types/headers.ts';
+
+export * from './src/context.ts';
+export * from './src/config.ts';
+
+export * from './src/router/standard.ts';
+export * from './src/router/base.ts';
+
+export * from './src/decorator/common.ts';
+export * from './src/decorator/controller.ts';
+export * from './src/decorator/param.ts';
+export * from './src/decorator/endpoint.ts';
+
+export * from './src/registry/controller.ts';
+export * from './src/registry/visitor.ts';
+export * from './src/registry/types.ts';
+
+export * from './src/interceptor/accept.ts';
+export * from './src/interceptor/body-parse.ts';
+export * from './src/interceptor/cors.ts';
+export * from './src/interceptor/cookies.ts';
+export * from './src/interceptor/compress.ts';
+export * from './src/interceptor/context.ts';
+export * from './src/interceptor/decompress.ts';
+export * from './src/interceptor/etag.ts';
+export * from './src/interceptor/response-cache.ts';
+export * from './src/interceptor/logging.ts';
+export * from './src/interceptor/respond.ts';
+export * from './src/interceptor/trust-proxy.ts';
+
+export * from './src/util/body.ts';
+export * from './src/util/endpoint.ts';
+export * from './src/util/mime.ts';
+export * from './src/util/cookie.ts';
+export * from './src/util/common.ts';
+export * from './src/util/net.ts';

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@travetto/web",
+  "version": "6.0.0-rc.2",
+  "description": "Declarative api for Web Applications with support for the dependency injection.",
+  "keywords": [
+    "web",
+    "dependency-injection",
+    "decorators",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/web"
+  },
+  "dependencies": {
+    "@travetto/config": "^6.0.0-rc.2",
+    "@travetto/context": "^6.0.0-rc.2",
+    "@travetto/di": "^6.0.0-rc.2",
+    "@travetto/registry": "^6.0.0-rc.2",
+    "@travetto/runtime": "^6.0.0-rc.2",
+    "@travetto/schema": "^6.0.0-rc.2",
+    "@types/fresh": "^0.5.2",
+    "@types/keygrip": "^1.0.6",
+    "@types/negotiator": "^0.6.3",
+    "find-my-way": "^9.3.0",
+    "fresh": "^0.5.2",
+    "iconv-lite": "^0.6.3",
+    "keygrip": "^1.1.0",
+    "negotiator": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@travetto/cli": "^6.0.0-rc.2",
+    "@travetto/test": "^6.0.0-rc.2",
+    "@travetto/transformer": "^6.0.0-rc.3"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/transformer": {
+      "optional": true
+    },
+    "@travetto/cli": {
+      "optional": true
+    },
+    "@travetto/test": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Web API"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/common/global.ts

@@ -0,0 +1,30 @@
+import { DependencyRegistry } from '@travetto/di';
+import { Runtime } from '@travetto/runtime';
+
+import { Controller } from '../decorator/controller.ts';
+import { ConditionalRegister, ConfigureInterceptor, Undocumented } from '../decorator/common.ts';
+import { Get, Options } from '../decorator/endpoint.ts';
+import { WebConfig } from '../config.ts';
+import { LoggingInterceptor, } from '../interceptor/logging.ts';
+
+@Undocumented()
+@Controller('/')
+@ConfigureInterceptor(LoggingInterceptor, { applies: false })
+export class GlobalHandler {
+
+  @Get('')
+  @ConditionalRegister(async () => {
+    const config = await DependencyRegistry.getInstance(WebConfig);
+    return config.defaultMessage;
+  })
+  message(): { module: string, version: string, env?: string } {
+    return {
+      module: Runtime.main.name,
+      version: Runtime.main.version,
+      env: Runtime.env
+    };
+  }
+
+  @Options('*all')
+  options(): void { }
+}

package/src/config.ts

@@ -0,0 +1,18 @@
+import { Config, EnvVar } from '@travetto/config';
+
+/**
+ * Web configuration
+ */
+@Config('web')
+export class WebConfig {
+  /**
+   * Should the app provide the global endpoint for app info
+   */
+  @EnvVar('WEB_DEFAULT_MESSAGE')
+  defaultMessage = true;
+  /**
+   * Base Url
+   */
+  @EnvVar('WEB_BASE_URL')
+  baseUrl?: string;
+}

package/src/context.ts

@@ -0,0 +1,49 @@
+import { AsyncContextValue, AsyncContext } from '@travetto/context';
+import { Inject, Injectable } from '@travetto/di';
+import { AppError, castTo, Class, toConcrete } from '@travetto/runtime';
+
+import { WebRequest } from './types/request.ts';
+
+/**
+ * Shared Async Context, powering the @ContextParams
+ */
+@Injectable()
+export class WebAsyncContext {
+
+  #request = new AsyncContextValue<WebRequest>(this);
+  #byType = new Map<string, () => unknown>();
+
+  @Inject()
+  context: AsyncContext;
+
+  get request(): WebRequest {
+    return this.#request.get()!;
+  }
+
+  postConstruct(): void {
+    this.registerSource(toConcrete<WebRequest>(), () => this.#request.get());
+  }
+
+  withContext<T>(request: WebRequest, next: () => Promise<T>): Promise<T> {
+    return this.context.run(() => {
+      this.#request.set(request);
+      return next();
+    });
+  }
+
+  registerSource<T>(cls: Class<T>, provider: () => T): void {
+    this.#byType.set(cls.Ⲑid, provider);
+  }
+
+  getSource<T>(cls: Class<T>): () => T {
+    const item = this.#byType.get(cls.Ⲑid);
+    if (!item) {
+      throw new AppError('Unknown type for web context');
+    }
+    return castTo(item);
+  }
+
+  getValue<T>(cls: Class<T>): T {
+    return this.getSource(cls)();
+  }
+}

package/src/decorator/common.ts

@@ -0,0 +1,87 @@
+import { asConstructable, castTo, Class, TimeSpan } from '@travetto/runtime';
+
+import { ControllerRegistry } from '../registry/controller.ts';
+import { EndpointConfig, ControllerConfig, DescribableConfig, EndpointDecorator, EndpointFunctionDescriptor } from '../registry/types.ts';
+import { AcceptInterceptor } from '../interceptor/accept.ts';
+import { WebInterceptor } from '../types/interceptor.ts';
+import { WebCommonUtil, CacheControlFlag } from '../util/common.ts';
+
+function register(config: Partial<EndpointConfig | ControllerConfig>): EndpointDecorator {
+  return function <T>(target: T | Class<T>, property?: string, descriptor?: EndpointFunctionDescriptor) {
+    if (descriptor) {
+      return ControllerRegistry.registerPendingEndpoint(asConstructable(target).constructor, descriptor, config);
+    } else {
+      return ControllerRegistry.registerPending(castTo(target), config);
+    }
+  };
+}
+
+/**
+ * Decorator used to add description metadata to a class or method
+ * @param desc The describe config
+ */
+export function Describe(desc: DescribableConfig): EndpointDecorator { return register(desc); }
+
+/**
+ * Marks a class/endpoint as being undocumented
+ */
+export function Undocumented(): EndpointDecorator { return register({ documented: false }); }
+
+/**
+ * Set response headers on success
+ * @param headers The response headers to set
+ */
+export function SetHeaders(headers: EndpointConfig['responseHeaders']): EndpointDecorator {
+  return register({ responseHeaders: headers });
+}
+
+/**
+ * Specifies content type for response
+ */
+export function Produces(mime: string): EndpointDecorator { return SetHeaders({ 'Content-Type': mime }); }
+
+/**
+ * Specifies if endpoint should be conditional
+ */
+export function ConditionalRegister(handler: () => (boolean | Promise<boolean>)): EndpointDecorator {
+  return register({ conditional: handler });
+}
+
+/**
+ * Set the max-age of a response based on the config
+ * @param value The value for the duration
+ * @param unit The unit of measurement
+ */
+export function CacheControl(value: number | TimeSpan, flags: CacheControlFlag[] = []): EndpointDecorator {
+  return SetHeaders({ 'Cache-Control': WebCommonUtil.getCacheControlValue(value, flags) });
+}
+
+/**
+ * Disable cache control, ensuring endpoint will not cache
+ */
+export const DisableCacheControl = (): EndpointDecorator => CacheControl(0);
+
+/**
+ * Define an endpoint to support specific input types
+ * @param types The list of mime types to allow/deny
+ */
+export function Accepts(types: [string, ...string[]]): EndpointDecorator {
+  return ControllerRegistry.createInterceptorConfigDecorator(
+    AcceptInterceptor,
+    { types, applies: true },
+    { responseHeaders: { accepts: types.join(', ') } }
+  );
+}
+
+/**
+ * Allows for configuring interceptor-level support at an endpoint or controller level
+ */
+export const ConfigureInterceptor =
+  ControllerRegistry.createInterceptorConfigDecorator.bind(ControllerRegistry);
+
+/**
+ * Registers an interceptor exclusion filter
+ */
+export function ExcludeInterceptors(interceptorExclude: (val: WebInterceptor) => boolean): EndpointDecorator {
+  return register({ interceptorExclude });
+};

package/src/decorator/controller.ts

@@ -0,0 +1,13 @@
+import { Class } from '@travetto/runtime';
+import { ControllerRegistry } from '../registry/controller.ts';
+
+/**
+ * Decorator to register a new web controller
+ * @augments `@travetto/di:Injectable`
+ * @augments `@travetto/web:Controller`
+ */
+export function Controller(path: string) {
+  return function <T>(target: Class<T>): void {
+    ControllerRegistry.registerPending(target, { basePath: path, class: target, });
+  };
+}

package/src/decorator/endpoint.ts

@@ -0,0 +1,102 @@
+import { asConstructable } from '@travetto/runtime';
+
+import { ControllerRegistry } from '../registry/controller.ts';
+import { EndpointConfig, EndpointFunctionDescriptor, EndpointIOType } from '../registry/types.ts';
+import { HTTP_METHODS, HttpMethod } from '../types/core.ts';
+
+type EndpointFunctionDecorator = <T>(target: T, prop: symbol | string, descriptor: EndpointFunctionDescriptor) => EndpointFunctionDescriptor;
+
+type EndpointDecConfig = Partial<EndpointConfig> & { path: string };
+
+/**
+ * Generic Endpoint Decorator
+ */
+export function Endpoint(config: EndpointDecConfig): EndpointFunctionDecorator {
+  return function <T>(target: T, prop: symbol | string, descriptor: EndpointFunctionDescriptor): EndpointFunctionDescriptor {
+    const result = ControllerRegistry.registerPendingEndpoint(
+      asConstructable(target).constructor, descriptor, config
+    );
+    return result;
+  };
+}
+
+
+function HttpEndpoint(method: HttpMethod, path: string): EndpointFunctionDecorator {
+  const { body: allowsBody, cacheable, emptyStatusCode } = HTTP_METHODS[method];
+  return Endpoint({
+    path,
+    allowsBody,
+    cacheable,
+    httpMethod: method,
+    responseFinalizer: v => {
+      v.context.httpStatusCode ??= (v.body === null || v.body === undefined || v.body === '') ? emptyStatusCode : 200;
+      return v;
+    }
+  });
+}
+
+/**
+ * Registers GET requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Get(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('GET', path); }
+/**
+ * Registers POST requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:HttpRequestBody`
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Post(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('POST', path); }
+/**
+ * Registers PUT requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:HttpRequestBody`
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Put(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('PUT', path); }
+/**
+ * Registers PATCH requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:HttpRequestBody`
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Patch(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('PATCH', path); }
+/**
+ * Registers DELETE requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Delete(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('DELETE', path); }
+/**
+ * Registers HEAD requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Head(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('HEAD', path); }
+/**
+ * Registers OPTIONS requests
+ * @param path The endpoint path for the request
+ * @augments `@travetto/web:Endpoint`
+ */
+export function Options(path = '/'): EndpointFunctionDecorator { return HttpEndpoint('OPTIONS', path); }
+
+/**
+ * Defines the response type of the endpoint
+ * @param responseType The desired response mime type
+ */
+export function ResponseType(responseType: EndpointIOType): EndpointFunctionDecorator {
+  return function <T>(target: T, property: string | symbol, descriptor: EndpointFunctionDescriptor) {
+    return ControllerRegistry.registerPendingEndpoint(asConstructable(target).constructor, descriptor, { responseType });
+  };
+}
+
+/**
+ * Defines the supported request body type
+ * @param requestType The type of the request body
+ */
+export function RequestType(requestType: EndpointIOType): EndpointFunctionDecorator {
+  return function <T>(target: T, property: string | symbol, descriptor: EndpointFunctionDescriptor) {
+    return ControllerRegistry.registerPendingEndpoint(asConstructable(target).constructor, descriptor, { requestType });
+  };
+}

package/src/decorator/param.ts

@@ -0,0 +1,64 @@
+import { asConstructable, Class, ClassInstance } from '@travetto/runtime';
+
+import { ControllerRegistry } from '../registry/controller.ts';
+import { EndpointParamConfig } from '../registry/types.ts';
+
+type ParamDecorator = (target: ClassInstance, propertyKey: string | symbol, idx: number) => void;
+
+/**
+ * Get the param configuration
+ * @param location The location of the parameter
+ * @param extra Any additional configuration for the param config
+ */
+export const paramConfig = (location: EndpointParamConfig['location'], extra: string | Partial<EndpointParamConfig>): EndpointParamConfig => ({
+  location,
+  ...((typeof extra === 'string' ? { name: extra } : extra))
+});
+
+/**
+ * Define a parameter
+ * @param location The location of the parameter
+ * @param extra Any extra configuration for the param
+ * @augments `@travetto/web:Param`
+ */
+export function Param(location: EndpointParamConfig['location'], extra: string | Partial<EndpointParamConfig>): ParamDecorator {
+  const param = paramConfig(location, extra);
+  return (target: ClassInstance, propertyKey: string | symbol, idx: number): void => {
+    const handler = target.constructor.prototype[propertyKey];
+    ControllerRegistry.registerEndpointParameter(target.constructor, handler, param, idx);
+  };
+}
+
+/**
+ * Define a Path param
+ * @param param The param configuration or name
+ * @augments `@travetto/web:Param`
+ */
+export function PathParam(param: string | Partial<EndpointParamConfig> = {}): ParamDecorator { return Param('path', param); }
+/**
+ * Define a Query param
+ * @param param The param configuration or name
+ * @augments `@travetto/web:Param`
+ */
+export function QueryParam(param: string | Partial<EndpointParamConfig> = {}): ParamDecorator { return Param('query', param); }
+/**
+ * Define a Header param
+ * @param param The param configuration or name
+ * @augments `@travetto/web:Param`
+ */
+export function HeaderParam(param: string | Partial<EndpointParamConfig> = {}): ParamDecorator { return Param('header', param); }
+/**
+ * Define a body param as an input
+ * @param param The param configuration
+ * @augments `@travetto/web:Param`
+ */
+export function Body(param: Partial<EndpointParamConfig> = {}): ParamDecorator { return Param('body', param); }
+
+/**
+ * A contextual field as provided by the WebAsyncContext
+ * @augments `@travetto/web:ContextParam`
+ */
+export function ContextParam(config?: { target: Class }) {
+  return (inst: unknown, field: string): void =>
+    ControllerRegistry.registerControllerContextParam(asConstructable(inst).constructor, field, config!.target);
+}

package/src/interceptor/accept.ts

@@ -0,0 +1,70 @@
+import { Injectable, Inject } from '@travetto/di';
+import { Config } from '@travetto/config';
+import { Ignore } from '@travetto/schema';
+
+import { MimeUtil } from '../util/mime.ts';
+import { WebCommonUtil } from '../util/common.ts';
+
+import { WebChainedContext } from '../types/filter.ts';
+import { WebInterceptor, WebInterceptorContext } from '../types/interceptor.ts';
+import { WebInterceptorCategory } from '../types/core.ts';
+import { WebResponse } from '../types/response.ts';
+import { WebRequest } from '../types/request.ts';
+import { WebError } from '../types/error.ts';
+
+@Config('web.accept')
+export class AcceptConfig {
+  /**
+   * Accepts certain request content types
+   */
+  applies = false;
+  /**
+   * The accepted types
+   */
+  types: string[] = [];
+
+  @Ignore()
+  matcher: (type: string) => boolean;
+}
+
+/**
+ * Enables access to contextual data when running in a web application
+ */
+@Injectable()
+export class AcceptInterceptor implements WebInterceptor<AcceptConfig> {
+
+  category: WebInterceptorCategory = 'request';
+
+  @Inject()
+  config: AcceptConfig;
+
+  finalizeConfig({ config }: WebInterceptorContext<AcceptConfig>): AcceptConfig {
+    config.matcher = MimeUtil.matcher(config.types ?? []);
+    return config;
+  }
+
+  applies({ config }: WebInterceptorContext<AcceptConfig>): boolean {
+    return config.applies && !!config.types.length;
+  }
+
+  validate(request: WebRequest, config: AcceptConfig): void {
+    const contentType = request.headers.get('Content-Type');
+    if (!contentType) {
+      throw WebError.for('Content type was not specified', 416);
+    } else if (!config.matcher(contentType)) {
+      throw WebError.for(`Content type ${contentType} violated ${config.types.join(', ')}`, 406);
+    }
+  }
+
+  async filter({ request, config, next }: WebChainedContext<AcceptConfig>): Promise<WebResponse> {
+    let res: WebResponse | undefined;
+    try {
+      this.validate(request, config);
+      return res = await next();
+    } catch (err) {
+      throw res = await WebCommonUtil.catchResponse(err);
+    } finally {
+      res?.headers.setIfAbsent('Accept', config.types.join(','));
+    }
+  }
+}

package/src/interceptor/body-parse.ts

@@ -0,0 +1,123 @@
+import { Injectable, Inject, DependencyRegistry } from '@travetto/di';
+import { Config } from '@travetto/config';
+import { toConcrete } from '@travetto/runtime';
+import { Ignore } from '@travetto/schema';
+
+import { WebChainedContext } from '../types/filter.ts';
+import { WebResponse } from '../types/response.ts';
+import { WebInterceptorCategory } from '../types/core.ts';
+import { WebInterceptor, WebInterceptorContext } from '../types/interceptor.ts';
+
+import { WebBodyUtil } from '../util/body.ts';
+import { WebCommonUtil } from '../util/common.ts';
+
+import { AcceptInterceptor } from './accept.ts';
+import { DecompressInterceptor } from './decompress.ts';
+import { WebError } from '../types/error.ts';
+
+/**
+ * @concrete
+ */
+export interface BodyContentParser {
+  type: string;
+  parse: (source: string) => unknown;
+};
+
+/**
+ * Web body parse configuration
+ */
+@Config('web.bodyParse')
+export class BodyParseConfig {
+  /**
+   * Parse request body
+   */
+  applies: boolean = true;
+  /**
+   * Max body size limit
+   */
+  limit: `${number}${'mb' | 'kb' | 'gb' | 'b' | ''}` = '1mb';
+  /**
+   * How to interpret different content types
+   */
+  parsingTypes: Record<string, string> = {
+    text: 'text',
+    'application/json': 'json',
+    'application/x-www-form-urlencoded': 'form'
+  };
+
+  @Ignore()
+  _limit: number | undefined;
+
+  postConstruct(): void {
+    this._limit = WebCommonUtil.parseByteSize(this.limit);
+  }
+}
+
+
+/**
+ * Parses the body input content
+ */
+@Injectable()
+export class BodyParseInterceptor implements WebInterceptor<BodyParseConfig> {
+
+  dependsOn = [AcceptInterceptor, DecompressInterceptor];
+  category: WebInterceptorCategory = 'request';
+  parsers: Record<string, BodyContentParser> = {};
+
+  @Inject()
+  config: BodyParseConfig;
+
+  async postConstruct(): Promise<void> {
+    // Load all the parser types
+    const instances = await DependencyRegistry.getCandidateInstances(toConcrete<BodyContentParser>());
+    for (const instance of instances) {
+      this.parsers[instance.type] = instance;
+    }
+  }
+
+  applies({ endpoint, config }: WebInterceptorContext<BodyParseConfig>): boolean {
+    return config.applies && endpoint.allowsBody;
+  }
+
+  async filter({ request, config, next }: WebChainedContext<BodyParseConfig>): Promise<WebResponse> {
+    const input = request.body;
+
+    if (!WebBodyUtil.isRaw(input)) {
+      return next();
+    }
+
+    const lengthRead = +(request.headers.get('Content-Length') || '');
+    const length = Number.isNaN(lengthRead) ? undefined : lengthRead;
+
+    const limit = config._limit ?? Number.MAX_SAFE_INTEGER;
+    if (length && length > limit) {
+      throw WebError.for('Request entity too large', 413, { length, limit });
+    }
+
+    const contentType = request.headers.getContentType();
+    if (!contentType) {
+      return next();
+    }
+
+    const parserType = config.parsingTypes[contentType.full] ?? config.parsingTypes[contentType.type];
+    if (!parserType) {
+      return next();
+    }
+
+    const { text, read } = await WebBodyUtil.readText(input, limit, contentType.parameters.charset);
+
+    if (length && read !== length) {
+      throw WebError.for('Request size did not match Content-Length', 400, { length, read });
+    }
+
+    try {
+      request.body = parserType in this.parsers ?
+        this.parsers[parserType].parse(text) :
+        WebBodyUtil.parseBody(parserType, text);
+
+      return next();
+    } catch (err) {
+      throw WebError.for('Malformed input', 400, { cause: err });
+    }
+  }
+}