@travetto/web 6.0.0-rc.2 → 6.0.0-rc.4

package/README.md

@@ -20,7 +20,6 @@ The module provides a declarative API for creating and describing a Web applicat
    *  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
@@ -38,18 +37,53 @@ export class BaseWebMessage<B = unknown, C = unknown> implements WebMessage<B, C
 
 **Code: Request Shape**
 ```typescript
+import { HttpMethod, HttpProtocol } from './core.ts';
+import { BaseWebMessage } from './message.ts';
+
+export interface WebConnection {
+  host?: string;
+  port?: number;
+  ip?: string;
+  httpProtocol?: HttpProtocol;
+}
+
+export interface WebRequestContext {
+  path: string;
+  pathParams?: Record<string, unknown>;
+  httpQuery?: Record<string, unknown>;
+  httpMethod?: HttpMethod;
+  connection?: WebConnection;
+}
 
+/**
+ * Web Request object
+ */
+export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> {
+
+}
 ```
 
 **Code: Response Shape**
 ```typescript
+import { BaseWebMessage } from './message.ts';
+
+export interface WebResponseContext {
+  httpStatusCode?: number;
+}
+
+/**
+ * Web Response as a simple object
+ */
 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>;
+  static redirect(location: string, statusCode = 302): WebResponse<undefined> {
+    return new WebResponse({ context: { httpStatusCode: statusCode }, headers: { Location: location } });
+  }
 }
 ```
 
@@ -60,6 +94,7 @@ To start, we must define a [@Controller](https://github.com/travetto/travetto/tr
    *  `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.
@@ -85,9 +120,11 @@ The most common pattern is to register HTTP-driven endpoints.  The HTTP methods
    *  [@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.
@@ -121,11 +158,13 @@ Endpoints can be configured to describe and enforce parameter behavior.  Request
    *  [@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**
@@ -720,15 +759,5 @@ export class SimpleEndpoints {
 }
 ```
 
-## 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.

package/__index__.ts

@@ -26,7 +26,7 @@ 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/cookie.ts';
 export * from './src/interceptor/compress.ts';
 export * from './src/interceptor/context.ts';
 export * from './src/interceptor/decompress.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/web",
-  "version": "6.0.0-rc.2",
+  "version": "6.0.0-rc.4",
   "description": "Declarative api for Web Applications with support for the dependency injection.",
   "keywords": [
     "web",
@@ -42,7 +42,7 @@
     "negotiator": "^1.0.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^6.0.0-rc.2",
+    "@travetto/cli": "^6.0.0-rc.3",
     "@travetto/test": "^6.0.0-rc.2",
     "@travetto/transformer": "^6.0.0-rc.3"
   },

package/src/interceptor/{cookies.ts → cookie.ts}

@@ -25,7 +25,7 @@ export class CookieConfig implements CookieSetOptions {
   /**
    * Are they signed
    */
-  signed = true;
+  signed?: boolean;
   /**
    * Supported only via http (not in JS)
    */
@@ -42,18 +42,22 @@ export class CookieConfig implements CookieSetOptions {
   /**
    * Is the cookie only valid for https
    */
-  secure?: boolean = false;
+  secure?: boolean;
   /**
    * The domain of the cookie
    */
   domain?: string;
+  /**
+   * The default path of the cookie
+   */
+  path: string = '/';
 }
 
 /**
  * Loads cookies from the request, verifies, exposes, and then signs and sets
  */
 @Injectable()
-export class CookiesInterceptor implements WebInterceptor<CookieConfig> {
+export class CookieInterceptor implements WebInterceptor<CookieConfig> {
 
   #cookieJar = new AsyncContextValue<CookieJar>(this);
 
@@ -77,8 +81,9 @@ export class CookiesInterceptor implements WebInterceptor<CookieConfig> {
 
   finalizeConfig({ config }: WebInterceptorContext<CookieConfig>): CookieConfig {
     const url = new URL(this.webConfig.baseUrl ?? 'x://localhost');
-    config.secure ??= url.protocol === 'https';
+    config.secure ??= url.protocol === 'https:';
     config.domain ??= url.hostname;
+    config.signed ??= !!config.keys?.length;
     return config;
   }
 
@@ -87,11 +92,11 @@ export class CookiesInterceptor implements WebInterceptor<CookieConfig> {
   }
 
   async filter({ request, config, next }: WebChainedContext<CookieConfig>): Promise<WebResponse> {
-    const jar = new CookieJar(request.headers.get('Cookie'), config);
+    const jar = new CookieJar(config).importCookieHeader(request.headers.get('Cookie'));
     this.#cookieJar.set(jar);
 
     const response = await next();
-    for (const c of jar.export()) { response.headers.append('Set-Cookie', c); }
+    for (const c of jar.exportSetCookieHeader()) { response.headers.append('Set-Cookie', c); }
     return response;
   }
 }

package/src/types/cookie.ts

@@ -15,4 +15,4 @@ export type Cookie = {
 };
 
 export type CookieGetOptions = { signed?: boolean };
-export type CookieSetOptions = Omit<Cookie, 'name' | 'value'>;
+export type CookieSetOptions = Omit<Cookie, 'name' | 'value' | 'response'>;

package/src/types/request.ts

@@ -19,4 +19,6 @@ export interface WebRequestContext {
 /**
  * Web Request object
  */
-export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> { }
+export class WebRequest<B = unknown> extends BaseWebMessage<B, Readonly<WebRequestContext>> {
+
+}

package/src/util/cookie.ts

@@ -1,14 +1,26 @@
 import keygrip from 'keygrip';
 import { AppError, castKey, castTo } from '@travetto/runtime';
 
-import { Cookie, CookieGetOptions } from '../types/cookie.ts';
+import { Cookie, CookieGetOptions, CookieSetOptions } from '../types/cookie.ts';
 
 const pairText = (c: Cookie): string => `${c.name}=${c.value}`;
 const pair = (k: string, v: unknown): string => `${k}=${v}`;
 
+type CookieJarOptions = { keys?: string[] } & CookieSetOptions;
+
 export class CookieJar {
 
-  static fromHeaderValue(header: string): Cookie {
+  static parseCookieHeader(header: string): Cookie[] {
+    return header.split(/\s{0,4};\s{0,4}/g)
+      .map(x => x.trim())
+      .filter(x => !!x)
+      .map(item => {
+        const kv = item.split(/\s{0,4}=\s{0,4}/);
+        return { name: kv[0], value: kv[1] };
+      });
+  }
+
+  static parseSetCookieHeader(header: string): Cookie {
     const parts = header.split(/\s{0,4};\s{0,4}/g);
     const [name, value] = parts[0].split(/\s{0,4}=\s{0,4}/);
     const c: Cookie = { name, value };
@@ -27,119 +39,125 @@ export class CookieJar {
     return c;
   }
 
-  static toHeaderValue(c: Cookie, response = true): string {
-    const header = [pair(c.name, c.value)];
-    if (response) {
-      if (!c.value) {
-        c.expires = new Date(0);
-        c.maxAge = undefined;
-      }
-      if (c.maxAge) {
-        c.expires = new Date(Date.now() + c.maxAge);
-      }
-
-      if (c.path) { header.push(pair('path', c.path)); }
-      if (c.expires) { header.push(pair('expires', c.expires.toUTCString())); }
-      if (c.domain) { header.push(pair('domain', c.domain)); }
-      if (c.priority) { header.push(pair('priority', c.priority.toLowerCase())); }
-      if (c.sameSite) { header.push(pair('samesite', c.sameSite.toLowerCase())); }
-      if (c.secure) { header.push('secure'); }
-      if (c.httpOnly) { header.push('httponly'); }
-      if (c.partitioned) { header.push('partitioned'); }
-    }
-    return header.join(';');
+  static responseSuffix(c: Cookie): string[] {
+    const parts = [];
+    if (c.path) { parts.push(pair('path', c.path)); }
+    if (c.expires) { parts.push(pair('expires', c.expires.toUTCString())); }
+    if (c.domain) { parts.push(pair('domain', c.domain)); }
+    if (c.priority) { parts.push(pair('priority', c.priority.toLowerCase())); }
+    if (c.sameSite) { parts.push(pair('samesite', c.sameSite.toLowerCase())); }
+    if (c.secure) { parts.push('secure'); }
+    if (c.httpOnly) { parts.push('httponly'); }
+    if (c.partitioned) { parts.push('partitioned'); }
+    return parts;
   }
 
-  #secure?: boolean;
   #grip?: keygrip;
   #cookies: Record<string, Cookie> = {};
-
-  constructor(input?: string | string[] | null | undefined | Cookie[] | CookieJar, options?: { keys?: string[], secure?: boolean }) {
-    this.#grip = options?.keys?.length ? new keygrip(options.keys) : undefined;
-    this.#secure = options?.secure ?? false;
-    if (input instanceof CookieJar) {
-      this.#cookies = { ...input.#cookies };
-    } else if (Array.isArray(input)) {
-      this.#import(input);
-    } else {
-      this.#import(input?.split(/\s{0,4},\s{0,4}/) ?? []);
-    }
+  #setOptions: CookieSetOptions = {};
+  #deleteOptions: CookieSetOptions = { maxAge: 0, expires: undefined };
+
+  constructor({ keys, ...options }: CookieJarOptions = {}) {
+    this.#grip = keys?.length ? new keygrip(keys) : undefined;
+    this.#setOptions = {
+      secure: false,
+      path: '/',
+      signed: !!keys?.length,
+      ...options,
+    };
   }
 
-  #checkSignature(c: Cookie): Cookie | undefined {
-    if (!this.#grip) { return; }
-    const key = pairText(c);
-    const sc = this.#cookies[`${c.name}.sig`];
-    if (!sc.value) { return; }
-
-    const index = this.#grip.index(key, sc.value);
-    c.signed = index >= 0;
-    sc.signed = false;
-    sc.secure = c.secure;
-
-    if (index >= 1) {
-      sc.value = this.#grip.sign(key);
-      sc.response = true;
-      return sc;
+  #exportCookie(cookie: Cookie, response?: boolean): string[] {
+    const suffix = response ? CookieJar.responseSuffix(cookie) : null;
+    const payload = pairText(cookie);
+    const out = suffix ? [[payload, ...suffix].join(';')] : [payload];
+    if (cookie.signed) {
+      const sigPair = pair(`${cookie.name}.sig`, this.#grip!.sign(payload));
+      out.push(suffix ? [sigPair, ...suffix].join(';') : sigPair);
     }
+    return out;
   }
 
-  #signCookie(c: Cookie): Cookie {
-    if (!this.#grip) {
-      throw new AppError('.keys required for signed cookies');
-    } else if (!this.#secure && c.secure) {
-      throw new AppError('Cannot send secure cookie over unencrypted connection');
+  import(cookies: Cookie[]): this {
+    const signatures: Record<string, string> = {};
+    for (const cookie of cookies) {
+      if (this.#setOptions.signed && cookie.name.endsWith('.sig')) {
+        signatures[cookie.name.replace(/[.]sig$/, '')] = cookie.value!;
+      } else {
+        this.#cookies[cookie.name] = { signed: false, ...cookie };
+      }
     }
-    return { ...c, name: `${c.name}.sig`, value: this.#grip.sign(pairText(c)) };
-  }
 
-  #import(inputs: (string | Cookie)[]): void {
-    const toCheck = [];
-    for (const input of inputs) {
-      const c = typeof input === 'string' ? CookieJar.fromHeaderValue(input) : input;
-      this.#cookies[c.name] = c;
-      if (this.#grip && !c.name.endsWith('.sig')) {
-        toCheck.push(c);
+    for (const [name, value] of Object.entries(signatures)) {
+      const cookie = this.#cookies[name];
+      if (!cookie) {
+        continue;
       }
-    }
-    for (const c of toCheck) {
-      const sc = this.#checkSignature(c);
-      if (sc) {
-        this.set(sc);
+      cookie.signed = true;
+
+      const computed = pairText(cookie);
+      const index = this.#grip!.index(computed, value);
+
+      if (index < 0) {
+        delete this.#cookies[name];
+      } else if (index >= 1) {
+        cookie.response = true;
       }
     }
+    return this;
+  }
+
+  has(name: string, opts: CookieGetOptions = {}): boolean {
+    const needSigned = opts.signed ?? this.#setOptions.signed;
+    return name in this.#cookies && this.#cookies[name].signed === needSigned;
   }
 
   get(name: string, opts: CookieGetOptions = {}): string | undefined {
-    const c = this.#cookies[name];
-    return (c?.signed || !(opts.signed ?? !!this.#grip)) ? c?.value : undefined;
+    if (this.has(name, opts)) {
+      return this.#cookies[name]?.value;
+    }
   }
 
-  set(c: Cookie): void {
-    this.#cookies[c.name] = c;
-    c.secure ??= this.#secure;
-    c.signed ??= !!this.#grip;
-    c.response = true;
+  set(cookie: Cookie): void {
+    const alias = this.#cookies[cookie.name] = {
+      ...this.#setOptions,
+      ...cookie,
+      response: true,
+      ...(cookie.value === null || cookie.value === undefined) ? this.#deleteOptions : {},
+    };
 
-    if (c.value === null || c.value === undefined) {
-      c.maxAge = -1;
-      c.expires = undefined;
+    if (!this.#setOptions.secure && alias.secure) {
+      throw new AppError('Cannot send secure cookie over unencrypted connection');
     }
 
-    if (c.signed) {
-      const sc = this.#signCookie(c);
-      this.#cookies[sc.name] = sc;
-      sc.response = true;
+    if (alias.signed && !this.#grip) {
+      throw new AppError('Signing keys required for signed cookies');
     }
-  }
 
-  export(response = true): string[] {
-    return this.getAll()
-      .filter(x => !response || x.response)
-      .map(c => CookieJar.toHeaderValue(c, response));
+    if (alias.maxAge !== undefined && !alias.expires) {
+      alias.expires = new Date(Date.now() + alias.maxAge);
+    }
   }
 
   getAll(): Cookie[] {
     return Object.values(this.#cookies);
   }
+
+  importCookieHeader(header: string | null | undefined): this {
+    return this.import(CookieJar.parseCookieHeader(header ?? ''));
+  }
+
+  importSetCookieHeader(headers: string[] | null | undefined): this {
+    return this.import(headers?.map(CookieJar.parseSetCookieHeader) ?? []);
+  }
+
+  exportCookieHeader(): string {
+    return this.getAll().flatMap(c => this.#exportCookie(c)).join('; ');
+  }
+
+  exportSetCookieHeader(): string[] {
+    return this.getAll()
+      .filter(x => x.response)
+      .flatMap(c => this.#exportCookie(c, true));
+  }
 }