@afora/core 0.0.8 → 0.0.11

package/dist/core/output/http.js

@@ -0,0 +1,351 @@
+import { jwtOf, jwtOptionsIssue } from "../auth/jwt.js";
+import { Exception } from "../exception/exception.js";
+import { HEADER_NAME } from "../use-case/route.js";
+import { coerceTextValues } from "./coerce.js";
+import { InvalidOutputStage } from "./exceptions.js";
+import {
+  openapi,
+  operationRoutes,
+  ROUTE_OPTION_KEYS,
+  requestIdHeaderOf,
+  routeOptionsIssue
+} from "./openapi-sink.js";
+import { outputValueOf, PROBLEM_MEDIA_TYPE, problemOf } from "./problem.js";
+import { statusOf } from "./status.js";
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function onlyKeys(value, allowed, where) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key))
+      return `${where} has no option "${key}".`;
+  }
+  return;
+}
+export const HTTP_OPTION_KEYS = [
+  ...ROUTE_OPTION_KEYS,
+  "docs",
+  "debug",
+  "context",
+  "auth"
+];
+export function httpOptionsIssue(options, where) {
+  const given = options;
+  const routing = routeOptionsIssue(options, where);
+  if (routing)
+    return routing;
+  if (given.debug !== undefined && typeof given.debug !== "boolean") {
+    return `Expected ${where}.debug to be a boolean.`;
+  }
+  const { docs, context, auth } = given;
+  if (auth !== undefined) {
+    if (!isObject(auth) || Object.keys(auth).join() !== "jwt") {
+      return `Expected ${where}.auth to be { jwt: { secret, ... } }.`;
+    }
+    const bad = jwtOptionsIssue(auth.jwt, `${where}.auth.jwt`, ["header", "cookie"], true);
+    if (bad)
+      return bad;
+    const { header, cookie } = auth.jwt;
+    for (const [key, value] of [
+      ["header", header],
+      ["cookie", cookie]
+    ]) {
+      if (value !== undefined && (typeof value !== "string" || !HEADER_NAME.test(value))) {
+        return `Expected ${where}.auth.jwt.${key} to be the name of a ${key}.`;
+      }
+    }
+  }
+  if (docs !== undefined) {
+    if (!isObject(docs))
+      return `Expected ${where}.docs to be an object.`;
+    const docsBad = onlyKeys(docs, ["path", "info", "servers"], `${where}.docs`);
+    if (docsBad)
+      return docsBad;
+    if (typeof docs.path !== "string" || !docs.path.startsWith("/") || /[{}?#\s:*]/.test(docs.path)) {
+      return `Expected ${where}.docs.path to be a path such as "/openapi.json".`;
+    }
+    try {
+      openapi({
+        info: docs.info,
+        ...docs.servers ? { servers: docs.servers } : {}
+      });
+    } catch (error) {
+      const reason = error.details?.reason;
+      return (reason ?? `Expected ${where}.docs to be valid.`).replaceAll("openapi.", `${where}.docs.`);
+    }
+  }
+  if (context !== undefined) {
+    if (!isObject(context))
+      return `Expected ${where}.context to be an object.`;
+    const contextBad = onlyKeys(context, ["headers", "variables"], `${where}.context`);
+    if (contextBad)
+      return contextBad;
+    const { headers, variables } = context;
+    if (headers !== undefined) {
+      if (!isObject(headers)) {
+        return `Expected ${where}.context.headers to be an object.`;
+      }
+      for (const [key, name] of Object.entries(headers)) {
+        if (typeof name !== "string" || !HEADER_NAME.test(name)) {
+          return `Expected ${where}.context.headers["${key}"] to be a header name.`;
+        }
+      }
+    }
+    if (variables !== undefined) {
+      if (!isObject(variables)) {
+        return `Expected ${where}.context.variables to be an object.`;
+      }
+      for (const [key, name] of Object.entries(variables)) {
+        if (typeof name !== "string" || name === "") {
+          return `Expected ${where}.context.variables["${key}"] to be the name of a variable.`;
+        }
+        if (isObject(headers) && Object.hasOwn(headers, key)) {
+          return `${where}.context maps "${key}" both from a header and from a variable; keep one.`;
+        }
+      }
+    }
+  }
+  return;
+}
+const REQUEST_ID = /^[\x21-\x7e]{1,200}$/;
+const JSON_TYPE = "application/json";
+const NO_COOKIES = Object.freeze([]);
+function cookiesOf(header) {
+  const cookies = new Map;
+  if (!header)
+    return cookies;
+  for (const pair of header.split(";")) {
+    const at = pair.indexOf("=");
+    if (at < 0)
+      continue;
+    const name = pair.slice(0, at).trim();
+    if (name === "" || cookies.has(name))
+      continue;
+    let value = pair.slice(at + 1).trim();
+    if (value.length > 1 && value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    }
+    if (value.includes("%")) {
+      try {
+        value = decodeURIComponent(value);
+      } catch {}
+    }
+    cookies.set(name, value);
+  }
+  return cookies;
+}
+function cookieWriterOf(cookie) {
+  const sameSite = cookie.sameSite ?? "lax";
+  const attributes = [
+    `Path=${cookie.path ?? "/"}`,
+    ...cookie.domain === undefined ? [] : [`Domain=${cookie.domain}`],
+    ...cookie.httpOnly === false ? [] : ["HttpOnly"],
+    ...cookie.secure === false ? [] : ["Secure"],
+    `SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`
+  ].join("; ");
+  const lasting = cookie.maxAge === undefined ? "" : `; Max-Age=${cookie.maxAge}`;
+  return (value) => value === "" ? `${cookie.name}=; ${attributes}; Max-Age=0` : `${cookie.name}=${encodeURIComponent(value)}; ${attributes}${lasting}`;
+}
+export function compileRoutes(operations, options, context, settings) {
+  const { source } = settings;
+  const { output } = context;
+  let authenticator = settings.authenticator;
+  if (!authenticator && options.auth) {
+    const { header, cookie, ...jwt } = options.auth.jwt;
+    authenticator = jwtOf(jwt).authenticator({
+      ...header === undefined ? {} : { header },
+      ...cookie === undefined ? {} : { cookie }
+    });
+  }
+  const routes = operationRoutes(operations, options, source);
+  const debug = options.debug === true;
+  const contextHeaders = options.context?.headers ?? {};
+  const contextVariables = options.context?.variables ?? {};
+  const requestIdHeader = requestIdHeaderOf(options);
+  const idOf = (request) => {
+    const sent = request?.header(requestIdHeader);
+    return sent !== undefined && REQUEST_ID.test(sent) ? sent : crypto.randomUUID();
+  };
+  const headersOf = (headers, request) => requestIdHeader === undefined ? headers : { ...headers, [requestIdHeader]: idOf(request) };
+  const problemHeaders = Object.freeze({ "content-type": PROBLEM_MEDIA_TYPE });
+  const problem = (body, status, request) => ({
+    status,
+    headers: headersOf(problemHeaders, request),
+    cookies: NO_COOKIES,
+    body: JSON.stringify(body)
+  });
+  const fail = (error, operation, request, fallback) => {
+    const status = fallback !== undefined && !(error instanceof Exception && Object.hasOwn(output.statuses, error.name)) ? fallback : statusOf(error, operation, output.statuses);
+    return problem(problemOf(error, { status, debug }), status, request);
+  };
+  const failure = (error, given) => fail(error, given?.operation, given?.request, given?.status);
+  const compiled = operations.map((operation) => {
+    const route = routes.get(operation.id);
+    const { method, path, parameters, status, body } = route;
+    const queryKeys = body ? route.query : [];
+    const headerKeys = Object.entries(route.requestHeaders);
+    const cookieKeys = Object.entries(route.cookies);
+    const placed = parameters.length + queryKeys.length + headerKeys.length + cookieKeys.length > 0;
+    const declared = operation.context ? Object.keys(operation.context.properties) : [];
+    const contextHeaderKeys = declared.filter((key) => Object.hasOwn(contextHeaders, key)).map((key) => [key, contextHeaders[key].toLowerCase()]);
+    const contextVariableKeys = declared.filter((key) => Object.hasOwn(contextVariables, key)).map((key) => [key, contextVariables[key]]);
+    const guarded = operation.access !== undefined && operation.access.public !== true;
+    const setCookies = Object.entries(route.setCookies).map(([key, cookie]) => [key, cookieWriterOf(cookie)]);
+    const successHeaders = Object.freeze(status === 204 ? { ...route.headers } : { "content-type": JSON_TYPE, ...route.headers });
+    const readsCookies = cookieKeys.length > 0;
+    const authenticates = guarded && authenticator !== undefined;
+    const hasContext = operation.context !== undefined;
+    const handle = async (request) => {
+      try {
+        let cookies;
+        let principal;
+        if (authenticates) {
+          principal = await authenticator({
+            header: (name) => request.header(name),
+            cookie: (name) => {
+              cookies ??= cookiesOf(request.header("cookie"));
+              return cookies.get(name);
+            },
+            operation,
+            native: request.native
+          });
+        }
+        let input;
+        if (body) {
+          const text = await request.text();
+          try {
+            input = text.trim() === "" ? {} : JSON.parse(text);
+          } catch {
+            return problem({
+              type: "urn:afora:exception:InvalidRequestBody",
+              title: "InvalidRequestBody",
+              status: 400,
+              detail: "The request body is not valid JSON."
+            }, 400, request);
+          }
+        } else {
+          input = coerceTextValues(operation.input, request.query());
+        }
+        if (placed && isObject(input)) {
+          const texts = {};
+          if (queryKeys.length > 0) {
+            const query = request.query();
+            for (const key of queryKeys)
+              texts[key] = query[key];
+          }
+          for (const [key, name] of headerKeys) {
+            texts[key] = request.header(name);
+          }
+          if (readsCookies) {
+            cookies ??= cookiesOf(request.header("cookie"));
+            for (const [key, name] of cookieKeys)
+              texts[key] = cookies.get(name);
+          }
+          for (const name of parameters)
+            texts[name] = request.param(name);
+          input = { ...input, ...coerceTextValues(operation.input, texts) };
+        }
+        let call;
+        if (hasContext) {
+          const raw = {};
+          for (const [key, name] of contextHeaderKeys) {
+            raw[key] = request.header(name);
+          }
+          const values = coerceTextValues(operation.context, raw);
+          for (const [key, name] of contextVariableKeys) {
+            const value = request.variable?.(name);
+            if (value !== undefined)
+              values[key] = value;
+          }
+          call = guarded ? { context: values, principal: principal ?? null } : { context: values };
+        } else if (guarded)
+          call = { principal: principal ?? null };
+        const response = await operation.invoke(input, call);
+        if (setCookies.length === 0) {
+          return {
+            status,
+            headers: headersOf(successHeaders, request),
+            cookies: NO_COOKIES,
+            body: status === 204 ? null : JSON.stringify(response) ?? "null"
+          };
+        }
+        const value = outputValueOf(response);
+        const sent = [];
+        if (isObject(value)) {
+          for (const [key, write] of setCookies) {
+            const cookie = value[key];
+            delete value[key];
+            if (cookie !== undefined && cookie !== null) {
+              sent.push(write(String(cookie)));
+            }
+          }
+        }
+        return {
+          status,
+          headers: headersOf(successHeaders, request),
+          cookies: sent,
+          body: status === 204 ? null : JSON.stringify(value) ?? "null"
+        };
+      } catch (error) {
+        return fail(error, operation, request);
+      }
+    };
+    return Object.freeze({ operation, method, path, parameters, handle });
+  });
+  let docs;
+  if (options.docs) {
+    const { path, info, servers } = options.docs;
+    if (compiled.some((route) => route.method === "get" && route.path === path)) {
+      throw new InvalidOutputStage({
+        source,
+        details: {
+          reason: `${source}.docs.path "${path}" collides with a GET operation route.`
+        }
+      });
+    }
+    const routing = {};
+    for (const key of ROUTE_OPTION_KEYS) {
+      if (options[key] !== undefined)
+        routing[key] = options[key];
+    }
+    if (options.auth && routing.security === undefined) {
+      const { header, cookie } = options.auth.jwt;
+      routing.security = {
+        schemes: cookie !== undefined && header === undefined ? { session: { type: "apiKey", in: "cookie", name: cookie } } : header !== undefined && header.toLowerCase() !== "authorization" ? { token: { type: "apiKey", in: "header", name: header } } : {
+          bearer: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT"
+          }
+        }
+      };
+    }
+    const document = openapi({
+      info,
+      ...servers ? { servers } : {},
+      ...routing
+    }).build(operations, context);
+    const text = JSON.stringify(settings.document ? settings.document(document) : document);
+    const headers = Object.freeze({ "content-type": JSON_TYPE });
+    docs = Object.freeze({
+      path,
+      handle: (request) => ({
+        status: 200,
+        headers: headersOf(headers, request),
+        cookies: NO_COOKIES,
+        body: text
+      })
+    });
+  }
+  return Object.freeze({
+    routes: Object.freeze(compiled),
+    ...docs ? { docs } : {},
+    notFound: (request) => problem({
+      type: "urn:afora:exception:NotFound",
+      title: "NotFound",
+      status: 404,
+      detail: "No operation is served at this method and path."
+    }, 404, request),
+    failure
+  });
+}

package/dist/core/output/openapi-sink.d.ts

@@ -1,4 +1,5 @@
 import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { RouteCookie } from "../use-case/types/route.interface.js";
 import type { OperationDescriptor } from "./types/output.interface.js";
 declare const METHODS: readonly ["get", "post", "put", "patch", "delete"];
 /** An HTTP method an operation can be routed to. */
@@ -44,7 +45,11 @@ export interface SecurityRequirement {
  * sinks that serve HTTP, so the served routes and the document agree.
  */
 export interface RouteOptions {
-    /** Prefix of every path, e.g. `"/api"`. Empty by default. */
+    /**
+     * Prefix of every path, e.g. `"/api"`.
+     *
+     * @default ""
+     */
     readonly basePath?: string;
     /**
      * Method, path and success status by operation id, e.g.
@@ -55,7 +60,11 @@ export interface RouteOptions {
         readonly [operationId: string]: {
             readonly method?: OpenAPIMethod;
             readonly path?: string;
-            /** `200` by default. */
+            /**
+             * The status of a successful response.
+             *
+             * @default 200
+             */
             readonly status?: RouteStatus;
         };
     };
@@ -146,10 +155,30 @@ export interface OperationRoute {
     readonly headers: {
         readonly [name: string]: string;
     };
+    /**
+     * Whether the input keys with no other place are a JSON body (`post`,
+     * `put`, `patch`); otherwise they are read from the query.
+     */
+    readonly body: boolean;
+    /** The input keys the use case route reads from the query, whatever the method. */
+    readonly query: readonly string[];
+    /** The input keys read from request headers, with the header of each (lower case). */
+    readonly requestHeaders: {
+        readonly [inputKey: string]: string;
+    };
+    /** The input keys read from cookies, with the cookie of each. */
+    readonly cookies: {
+        readonly [inputKey: string]: string;
+    };
+    /** The response keys sent as cookies instead of in the body, with the cookie of each. */
+    readonly setCookies: {
+        readonly [responseKey: string]: RouteCookie;
+    };
 }
 /**
  * The route of every operation, by id: `POST {basePath}/{kebab(command)}/{kebab(operation)}`
- * with `200`, changed per operation id with `route` and `responses`. Throws
+ * with `200`, changed by the route the use case declares (`operation.route`)
+ * and, over it, per operation id with `route` and `responses`. Throws
  * `InvalidOutputStage` (with `source`) when `route`, `responses` or
  * `security.operations` name an unknown operation, a path parameter is not a
  * scalar key of the input, or two operations share a method and path. The
@@ -179,5 +208,5 @@ export declare function operationRoutes(operations: readonly OperationDescriptor
  * transport-specific and not part of the document; sinks that serve HTTP map
  * it (headers, middleware).
  */
-export declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions>;
+export declare const openapi: import("./types/output.interface.js").SinkFactory<OpenAPIDocument, OpenAPISinkOptions, never>;
 export {};