@travetto/web 6.0.0-rc.2

package/README.md

@@ -0,0 +1,734 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/web/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web API
+
+## Declarative api for Web Applications with support for the dependency injection.
+
+**Install: @travetto/web**
+```bash
+npm install @travetto/web
+
+# or
+
+yarn add @travetto/web
+```
+
+The module provides a declarative API for creating and describing a Web application.  Since the framework is declarative, decorators are used to configure almost everything. The general layout of an application is a collection of [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9)s that employ some combination of [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s to help manage which functionality is executed before the [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14) code, within the [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9). This module will look at:
+   *  Request/Response Pattern
+   *  Defining a [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9)
+   *  Defining an [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14)s
+   *  Using [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s
+   *  Creating a Custom [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)
+   *  Cookies
+   *  SSL Support
+   *  Error Handling
+
+## Request/Response Pattern
+Unlike other frameworks (e.g. [express](https://expressjs.com), [fastify](https://www.fastify.io/)), this module takes an approach that is similar to [AWS Lambda](https://aws.amazon.com/lambda/)'s model for requests and responses. What you can see here is that [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) and [WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3) are very simple objects, with the focus being on the `payload` and `body`.  This is intended to provide maximal compatibility with non-HTTP sources.  The driving goal is to support more than just standard HTTP servers but also allow for seamless integration with tools like event queues, web sockets, etc.
+
+**Code: Base Shape**
+```typescript
+export class BaseWebMessage<B = unknown, C = unknown> implements WebMessage<B, C> {
+  readonly context: C;
+  readonly headers: WebHeaders;
+  body?: B;
+  constructor(o: WebMessageInit<B, C> = {});
+}
+```
+
+**Code: Request Shape**
+```typescript
+
+```
+
+**Code: Response Shape**
+```typescript
+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>;
+}
+```
+
+These objects do not represent the underlying sockets provided by various http servers, but in fact are simple wrappers that track the flow through the call stack of the various [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s and the [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14) handler.  One of the biggest departures here, is that the response is not an entity that is passed around from call-site to call-site, but is is solely a return-value.  This doesn't mean the return value has to be static and pre-allocated, on the contrary streams are still supported.  The difference here is that the streams/asynchronous values will be consumed until the response is sent back to the user. The [CompressInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/compress.ts#L50) is a good reference for transforming a [WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3) that can either be a stream or a fixed value.
+
+## Defining a Controller
+To start, we must define a [@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9), which is only allowed on classes. Controllers can be configured with:
+   *  `path` - The required context path the controller will operate atop
+   *  `title` - The definition of the controller
+   *  `description` - High level description fo the controller
+Additionally, the module is predicated upon [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support."), and so all standard injection techniques (constructor, fields) work for registering dependencies. 
+
+[JSDoc](http://usejsdoc.org/about-getting-started.html) comments can also be used to define the `title` attribute.
+
+**Code: Basic Controller Registration**
+```typescript
+import { Controller } from '@travetto/web';
+
+@Controller('/simple')
+class SimpleController {
+  // endpoints
+}
+```
+
+## Defining an Endpoint
+Once the controller is declared, each method of the controller is a candidate for being an endpoint.  By design, everything is asynchronous, and so async/await is natively supported. 
+
+The most common pattern is to register HTTP-driven endpoints.  The HTTP methods that are currently supported:
+   *  [@Get](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L43)
+   *  [@Post](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L50)
+   *  [@Put](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L57)
+   *  [@Delete](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L70)
+   *  [@Patch](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L64)
+   *  [@Head](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L76)
+   *  [@Options](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L82)
+Similar to the Controller, each endpoint decorator handles the following config:
+   *  `title` - The definition of the endpoint
+   *  `description` - High level description fo the endpoint
+[JSDoc](http://usejsdoc.org/about-getting-started.html) comments can also be used to define the `title` attribute, as well as describing the parameters using `@param` tags in the comment. 
+
+The return type of the method will also be used to describe the `responseType` if not specified manually.
+
+**Code: Controller with Sample Endpoint**
+```typescript
+import { Get, Controller } from '@travetto/web';
+
+class Data { }
+
+@Controller('/simple')
+class SimpleController {
+
+  /**
+   * Gets the most basic of data
+   */
+  @Get('/')
+  async simpleGet() {
+    let data: Data | undefined;
+    //
+    return data;
+  }
+}
+```
+
+**Note**: In development mode the module supports hot reloading of `class`es.  Endpoints can be added/modified/removed at runtime.
+
+### Parameters
+Endpoints can be configured to describe and enforce parameter behavior.  Request parameters can be defined in five areas:
+   *  [@PathParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L37) - Path params
+   *  [@QueryParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L43) - Query params - can be either a single value or bind to a whole object
+   *  [@Body](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L55) - Request body
+   *  [@HeaderParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L49) - Header values
+Each [@Param](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L24) can be configured to indicate:
+   *  `name` - Name of param, field name, defaults to handler parameter name if necessary
+   *  `description` - Description of param, pulled from [JSDoc](http://usejsdoc.org/about-getting-started.html), or defaults to name if empty
+   *  `required?` - Is the field required?, defaults to whether or not the parameter itself is optional
+   *  `type` - The class of the type to be enforced, pulled from parameter type
+[JSDoc](http://usejsdoc.org/about-getting-started.html) comments can also be used to describe parameters using `@param` tags in the comment.
+
+**Code: Full-fledged Controller with Endpoints**
+```typescript
+import { Get, Controller, Post, QueryParam, WebRequest, ContextParam } from '@travetto/web';
+import { Integer, Min } from '@travetto/schema';
+
+import { MockService } from './mock.ts';
+
+@Controller('/simple')
+export class Simple {
+
+  service: MockService;
+
+  @ContextParam()
+  request: WebRequest;
+
+  constructor(service: MockService) {
+    this.service = service;
+  }
+
+  /**
+   * Get a random user by name
+   */
+  @Get('/name')
+  async getName() {
+    const user = await this.service.fetch();
+    return `/simple/name => ${user.first.toLowerCase()}`;
+  }
+
+  /**
+   * Get a user by id
+   */
+  @Get('/:id')
+  async getById(id: number) {
+    const user = await this.service.fetch(id);
+    return `/simple/id => ${user.first.toLowerCase()}`;
+  }
+
+  @Post('/name')
+  async createName(person: { name: string }) {
+    await this.service.update({ name: person.name });
+    return { success: true };
+  }
+
+  @Get('img/*')
+  async getImage(
+    @QueryParam('w') @Integer() @Min(100) width?: number,
+    @QueryParam('h') @Integer() @Min(100) height?: number
+  ) {
+    const img = await this.service.fetchImage(this.request.context.path, { width, height });
+    return img;
+  }
+}
+```
+
+### ContextParam
+In addition to endpoint parameters (i.e. user-provided inputs), there may also be a desire to access indirect contextual information.  Specifically you may need access to the entire [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11).  These are able to be injected using the [@ContextParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L61) on a class-level field from the [WebAsyncContext](https://github.com/travetto/travetto/tree/main/module/web/src/context.ts#L11).  These are not exposed as endpoint parameters as they cannot be provided when making RPC invocations.
+
+**Code: Example ContextParam usage**
+```typescript
+import { CacheControl, ContextParam, Controller, Get, WebRequest, WebResponse } from '@travetto/web';
+
+@Controller('/context')
+class ContextController {
+
+  @ContextParam()
+  request: WebRequest;
+
+  /**
+   * Gets the ip of the user, ensure no caching
+   */
+  @CacheControl(0)
+  @Get('/ip')
+  async getIp() {
+    return new WebResponse({
+      body: { ip: this.request.context.connection?.ip },
+      headers: {
+        'Content-Type': 'application/json+ip'
+      }
+    });
+  }
+}
+```
+
+**Note**: When referencing the [@ContextParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L61) values, the contract for idempotency needs to be carefully inspected, if expected. You can see in the example above that the [CacheControl](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/common.ts#L55) decorator is used to ensure that the response is not cached.
+
+### Validating Inputs
+The module provides high level access for [Schema](https://github.com/travetto/travetto/tree/main/module/schema#readme "Data type registry for runtime validation, reflection and binding.") support, via decorators, for validating and typing request inputs. 
+
+By default, all endpoint parameters are validated for type, and any additional constraints added (required, vs optional, minlength, etc).  Each parameter location ([@PathParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L37), [@Body](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L55), [@QueryParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L43), [@HeaderParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L49)) primarily provides a source to bind the endpoint arguments from.  Once bound, the module will validate that the provided arguments are in fact valid. All validation will occur before the endpoint is ever executed, ensuring a strong contract.
+
+**Code: Using Body for POST requests**
+```typescript
+import { Schema } from '@travetto/schema';
+import { Controller, Post, Body } from '@travetto/web';
+
+@Schema()
+class User {
+  name: string;
+  age: number;
+}
+
+@Controller('/user')
+class UserController {
+
+  private service: {
+    update(user: User): Promise<User>;
+  };
+
+  @Post('/saveUser')
+  async save(@Body() user: User) {
+    const saved = await this.service.update(user);
+    return { success: !!saved };
+  }
+}
+```
+
+**Code: Using Query + Schema for GET requests**
+```typescript
+import { Schema } from '@travetto/schema';
+import { Controller, Get } from '@travetto/web';
+
+@Schema()
+class SearchParams {
+  page: number = 0;
+  pageSize: number = 100;
+}
+
+@Controller('/user')
+class UserController {
+
+  private service: {
+    search(query: SearchParams): Promise<number[]>;
+  };
+
+  @Get('/search')
+  async search(query: SearchParams) {
+    return await this.service.search(query);
+  }
+}
+```
+
+Additionally, schema related inputs can also be used with `interface`s and `type` literals in lieu of classes. This is best suited for simple types:
+
+**Code: Using QuerySchema with a type literal**
+```typescript
+import { Controller, Get } from '@travetto/web';
+
+type Paging = {
+  page?: number;
+  pageSize?: number;
+};
+
+@Controller('/user')
+class UserController {
+
+  private service: {
+    search(query: Paging): Promise<number>;
+  };
+
+  @Get('/search')
+  async search(query: Paging = { page: 0, pageSize: 100 }) {
+    return await this.service.search(query);
+  }
+}
+```
+
+## Using Interceptors
+[WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15)s are a key part of the web framework, to allow for conditional functionality to be added, across all endpoints.
+
+### Anatomy of an Interceptor
+
+**Code: A Simple Interceptor**
+```typescript
+import { WebChainedContext, WebInterceptor, WebInterceptorCategory, WebInterceptorContext } from '@travetto/web';
+import { Injectable } from '@travetto/di';
+
+@Injectable()
+export class HelloWorldInterceptor implements WebInterceptor {
+
+  category: WebInterceptorCategory = 'application';
+
+  applies(context: WebInterceptorContext<unknown>): boolean {
+    return context.endpoint.httpMethod === 'HEAD';
+  }
+
+  filter(ctx: WebChainedContext) {
+    console.log('Hello world!');
+    return ctx.next();
+  }
+}
+```
+
+In this example you can see the markers of a simple interceptor:
+
+#### category
+`category` - This represents the generally request lifecycle phase an interceptor will run in.  It can be customized further with `dependsOn` and `runsBefore` to control exact ordering within a category.  In this example `application` represents the lowest priority, and will run right before the endpoint is executed.
+
+#### applies
+`applies` - This represents ability for the per-endpoint configuration to determine if an interceptor is applicable.  By default, all interceptors will auto-register on every endpoint. Some interceptors are opt-in, and control that by setting applies to constantly return `false`.
+
+#### filter
+`filter` - This is the actual logic that will be invoked around the endpoint call, represented by `ctx.next()`.  The next call passes control to the next interceptor all the way down to the endpoint, and then will pop back up the stack.  Code executed before `next()` is generally used for request filtering, and code afterwards is generally used for response control.
+
+Out of the box, the web framework comes with a few interceptors, and more are contributed by other modules as needed.  The default interceptor set is (in order of execution):
+
+### Order of Execution
+
+   1. global - Intended to run outside of the request flow - [AsyncContextInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/context.ts#L13)
+   1. terminal - Handles once request and response are finished building - [LoggingInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/logging.ts#L28), [RespondInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/respond.ts#L12)
+   1. pre-request - Prepares the request for running - [TrustProxyInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/trust-proxy.ts#L23)
+   1. request - Handles inbound request, validation, and body preparation - [DecompressInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/decompress.ts#L53), [AcceptInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/accept.ts#L34), [BodyParseInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/body-parse.ts#L61), [CookiesInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/cookies.ts#L56) 
+   1. response - Prepares outbound response - [CompressInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/compress.ts#L50), [CorsInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/cors.ts#L51), [EtagInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/etag.ts#L34), [ResponseCacheInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/response-cache.ts#L30) 
+   1. application - Lives outside of the general request/response behavior, [Web Auth](https://github.com/travetto/travetto/tree/main/module/auth-web#readme "Web authentication integration support for the Travetto framework") uses this for login and logout flows.
+
+### Packaged Interceptors
+
+#### AsyncContextInterceptor
+[AsyncContextInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/context.ts#L13) is responsible for sharing context across the various layers that may be touched by a request.  This
+
+#### LoggingInterceptor
+[LoggingInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/logging.ts#L28) is used for logging the request/response, handling any error logging as needed. This interceptor can be noisy, and so can easily be disabled as needed by setting `web.log.applies: false` in your config.
+
+**Code: Web Log Config**
+```typescript
+export class WebLogConfig {
+  /**
+   * Enable logging of all requests
+   */
+  applies = true;
+  /**
+   * Should errors be dumped as full stack traces
+   */
+  showStackTrace = true;
+}
+```
+
+#### RespondInterceptor
+[RespondInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/respond.ts#L12) is a basic catch-all that forces errors and data alike into a consistent format for sending back to the user.
+
+#### TrustProxyInterceptor
+[TrustProxyInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/trust-proxy.ts#L23) allows for overriding connection information (host, ip, protocol) using `X-Forwarded-*` headers.  This allows for proxied requests to retain access to the "source" request information as necessary.
+
+**Code: TrustProxy Config**
+```typescript
+export class TrustProxyConfig {
+  /**
+   * Enforces trust rules for X-Forwarded-* headers
+   */
+  applies = true;
+  /**
+   * The accepted ips
+   */
+  ips: string[] = [];
+}
+```
+
+#### AcceptInterceptor
+[AcceptInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/accept.ts#L34) handles verifying the inbound request matches the allowed content-types. This acts as a standard gate-keeper for spurious input.
+
+**Code: Accept Config**
+```typescript
+export class AcceptConfig {
+  /**
+   * Accepts certain request content types
+   */
+  applies = false;
+  /**
+   * The accepted types
+   */
+  types: string[] = [];
+
+  @Ignore()
+  matcher: (type: string) => boolean;
+}
+```
+
+#### DecompressInterceptor
+[DecompressInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/decompress.ts#L53) handles decompressing the inbound request, if supported.  This relies upon HTTP standards for content encoding, and negotiating the appropriate decompression scheme.
+
+**Code: Decompress Config**
+```typescript
+export class DecompressConfig {
+  /**
+   * Parse request body
+   */
+  applies: boolean = true;
+  /**
+   * Supported encodings
+   */
+  supportedEncodings: WebDecompressEncoding[] = ['br', 'gzip', 'deflate', 'identity'];
+}
+```
+
+#### CookiesInterceptor
+[CookiesInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/cookies.ts#L56) is responsible for processing inbound cookie headers and populating the appropriate data on the request, as well as sending the appropriate response data
+
+**Code: Cookies Config**
+```typescript
+export class CookieConfig implements CookieSetOptions {
+  /**
+   * Support reading/sending cookies
+   */
+  applies = true;
+  /**
+   * Are they signed
+   */
+  signed = true;
+  /**
+   * Supported only via http (not in JS)
+   */
+  httpOnly = true;
+  /**
+   * Enforce same site policy
+   */
+  sameSite: Cookie['sameSite'] = 'lax';
+  /**
+   * The signing keys
+   */
+  @Secret()
+  keys?: string[];
+  /**
+   * Is the cookie only valid for https
+   */
+  secure?: boolean = false;
+  /**
+   * The domain of the cookie
+   */
+  domain?: string;
+}
+```
+
+#### BodyParseInterceptor
+[BodyParseInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/body-parse.ts#L61) handles the inbound request, and converting the body payload into an appropriate format.
+
+**Code: Body Parse Config**
+```typescript
+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);
+  }
+}
+```
+
+#### CompressInterceptor
+[CompressInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/compress.ts#L50) by default, will compress all valid outbound responses over a certain size, or for streams will cache every response. This relies on Node's [Buffer](https://nodejs.org/api/zlib.html) support for compression.
+
+**Code: Compress Config**
+```typescript
+export class CompressConfig {
+  /**
+   * Attempting to compressing responses
+   */
+  applies: boolean = true;
+  /**
+   * Raw encoding options
+   */
+  raw?: (ZlibOptions & BrotliOptions) | undefined;
+  /**
+   * Preferred encodings
+   */
+  preferredEncodings?: WebCompressEncoding[] = ['br', 'gzip', 'identity'];
+  /**
+   * Supported encodings
+   */
+  supportedEncodings: WebCompressEncoding[] = ['br', 'gzip', 'identity', 'deflate'];
+}
+```
+
+#### EtagInterceptor
+[EtagInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/etag.ts#L34) by default, will tag all cacheable HTTP responses, when the response value/length is known.  Streams, and other async data sources do not have a pre-defined length, and so are ineligible for etagging.
+
+**Code: ETag Config**
+```typescript
+export class EtagConfig {
+  /**
+   * Attempt ETag generation
+   */
+  applies = true;
+  /**
+   * Should we generate a weak etag
+   */
+  weak?: boolean;
+
+  @Ignore()
+  cacheable?: boolean;
+}
+```
+
+#### CorsInterceptor
+[CorsInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/cors.ts#L51) allows cors functionality to be configured out of the box, by setting properties in your `application.yml`, specifically, the `web.cors` config space.
+
+**Code: Cors Config**
+```typescript
+export class CorsConfig {
+  /**
+   * Send CORS headers on responses
+   */
+  applies = true;
+  /**
+   * Allowed origins
+   */
+  origins?: string[];
+  /**
+   * Allowed http methods
+   */
+  methods?: HttpMethod[];
+  /**
+   * Allowed http headers
+   */
+  headers?: string[];
+  /**
+   * Support credentials?
+   */
+  credentials?: boolean;
+
+  @Ignore()
+  resolved: {
+    origins: Set<string>;
+    methods: string;
+    headers: string;
+    credentials: boolean;
+  };
+}
+```
+
+#### ResponseCacheInterceptor
+[ResponseCacheInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/interceptor/response-cache.ts#L30) by default, disables caching for all GET requests if the response does not include caching headers.  This can be managed by setting `web.getCache.applies: <boolean>` in your config.  This interceptor applies by default.
+
+### Configuring Interceptors
+All framework-provided interceptors, follow the same patterns for general configuration.  This falls into three areas:
+
+#### Enable/disable of individual interceptors via configuration
+This applies only to interceptors that have opted in, to exposing a config, and tying that configuration to the applies logic.
+
+**Code: Sample interceptor disabling configuration**
+```yaml
+web:
+  trustProxy:
+    applies: false
+```
+
+**Code: Configurable Interceptor**
+```typescript
+export class TrustProxyConfig {
+  /**
+   * Enforces trust rules for X-Forwarded-* headers
+   */
+  applies = true;
+  /**
+   * The accepted ips
+   */
+  ips: string[] = [];
+}
+```
+
+#### Endpoint-enabled control via decorators
+
+**Code: Sample controller with endpoint-level allow/deny**
+```typescript
+import { Controller, Get, QueryParam, ConfigureInterceptor, CorsInterceptor, ExcludeInterceptors } from '@travetto/web';
+
+@Controller('/allowDeny')
+@ConfigureInterceptor(CorsInterceptor, { applies: true })
+export class AlowDenyController {
+
+  @Get('/override')
+  @ConfigureInterceptor(CorsInterceptor, { applies: false })
+  withoutCors(@QueryParam() value: string) {
+
+  }
+
+  @Get('/raw')
+  @ExcludeInterceptors(v => v.category === 'response')
+  withoutResponse(@QueryParam() value: string) {
+
+  }
+}
+```
+
+The resolution logic is as follows:
+   *  Check the resolved [Endpoint](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/endpoint.ts#L14)/[@Controller](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/controller.ts#L9) overrides to see if an interceptor is explicitly allowed or disallowed
+   *  Default to `applies()` logic for all available interceptors
+
+## Creating a Custom WebInterceptor
+Additionally it may be desirable to create a custom interceptor.  Interceptors can be registered with the [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.") by implementing the [WebInterceptor](https://github.com/travetto/travetto/tree/main/module/web/src/types/interceptor.ts#L15) interface and adding an [@Injectable](https://github.com/travetto/travetto/tree/main/module/di/src/decorator.ts#L29) decorator. A simple logging interceptor:
+
+**Code: Defining a new Interceptor**
+```typescript
+import { WebChainedContext, WebInterceptor, WebInterceptorCategory } from '@travetto/web';
+import { Injectable } from '@travetto/di';
+
+class Appender {
+  write(...args: unknown[]): void { }
+}
+
+@Injectable()
+export class CustomLoggingInterceptor implements WebInterceptor {
+
+  category: WebInterceptorCategory = 'terminal';
+
+  appender: Appender;
+
+  constructor(appender: Appender) {
+    this.appender = appender;
+  }
+
+  async filter({ request, next }: WebChainedContext) {
+    try {
+      return await next();
+    } finally {
+      // Write request to database
+      this.appender.write(request.context.httpMethod, request.context.path, request.context.httpQuery);
+    }
+  }
+}
+```
+
+When running an interceptor, if you chose to skip calling `ctx.next()`, you will bypass all the downstream interceptors and return a response directly.
+
+**Code: Defining a fully controlled Interceptor**
+```typescript
+import { WebInterceptor, WebInterceptorCategory, WebChainedContext, WebError } from '@travetto/web';
+import { Injectable } from '@travetto/di';
+
+@Injectable()
+export class SimpleAuthInterceptor implements WebInterceptor {
+
+  category: WebInterceptorCategory = 'terminal';
+
+  async filter(ctx: WebChainedContext) {
+    if (ctx.request.headers.has('X-Auth')) {
+      return await ctx.next();
+    } else {
+      throw WebError.for('Missing auth', 401, {}, 'authentication');
+    }
+  }
+}
+```
+
+## Cookie Support
+[express](https://expressjs.com)/[koa](https://koajs.com/)/[fastify](https://www.fastify.io/) all have their own cookie implementations that are common for each framework but are somewhat incompatible.  To that end, cookies are supported for every platform, by using [cookies](https://www.npmjs.com/package/cookies).  This functionality is exposed onto the [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11) object following the pattern set forth by Koa (this is the library Koa uses).  This choice also enables better security support as we are able to rely upon standard behavior when it comes to cookies, and signing.
+
+**Code: Sample Cookie Usage**
+```typescript
+import {
+  Controller, Get, QueryParam, WebRequest, ContextParam,
+  WebResponse, CookieJar, CookieGetOptions, CookieSetOptions
+} from '@travetto/web';
+
+@Controller('/simple')
+export class SimpleEndpoints {
+
+  private getOptions: CookieGetOptions;
+  private setOptions: CookieSetOptions;
+
+  @ContextParam()
+  request: WebRequest;
+
+  @ContextParam()
+  cookies: CookieJar;
+
+  @Get('/cookies')
+  getCookies(@QueryParam() value: string) {
+    this.cookies.get('name', this.getOptions);
+
+    // Set a cookie on response
+    this.cookies.set({ name: 'name', value, ...this.setOptions });
+    return new WebResponse({ body: null });
+  }
+}
+```
+
+## SSL Support
+Additionally the framework supports SSL out of the box, by allowing you to specify your public and private keys for the cert.  In dev mode, the framework will also automatically generate a self-signed cert if:
+   *  SSL support is configured
+   *  [node-forge](https://www.npmjs.com/package/node-forge) is installed
+   *  Not running in prod
+   *  No keys provided
+This is useful for local development where you implicitly trust the cert. 
+
+SSL support can be enabled by setting `web.ssl.active: true` in your config. The key/cert can be specified as string directly in the config file/environment variables.  The key/cert can also be specified as a path to be picked up by [RuntimeResources](https://github.com/travetto/travetto/tree/main/module/runtime/src/resources.ts#L8).
+
+## Full Config
+The entire [WebConfig](https://github.com/travetto/travetto/tree/main/module/web/src/config.ts#L7) which will show the full set of valid configuration parameters for the web module.