@afora/core 0.0.8 → 0.0.11

package/dist/core/output/openapi-sink.js

@@ -0,0 +1,571 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant } from "../blueprint/variant.js";
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { Exception } from "../exception/exception.js";
+import { toOpenAPI } from "../openapi/openapi.js";
+import { isProperty } from "../property/is-property.js";
+import { recordNameOf } from "../record/name.js";
+import {
+  HEADER_NAME,
+  isRoutePath as isPath,
+  isScalarKey as isScalarInputKey,
+  isScalarSchema,
+  parametersOfPath
+} from "../use-case/route.js";
+import { InvalidOutputStage } from "./exceptions.js";
+import { PROBLEM_MEDIA_TYPE } from "./problem.js";
+import { sinkOf } from "./stage.js";
+import { statusOf } from "./status.js";
+const METHODS = ["get", "post", "put", "patch", "delete"];
+const SUCCESS_STATUSES = [200, 201, 202, 204];
+const REQUEST_ID_HEADER = "x-request-id";
+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;
+}
+const COMPONENT_NAME = /^[A-Za-z0-9._-]+$/;
+function isHeaderValue(value) {
+  if (typeof value !== "string")
+    return false;
+  for (let i = 0;i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 32 && code !== 9 || code === 127)
+      return false;
+  }
+  return true;
+}
+function isScopes(value) {
+  return value === undefined || Array.isArray(value) && value.every((scope) => typeof scope === "string" && scope !== "");
+}
+const SCHEME_KEYS = {
+  http: ["scheme", "bearerFormat"],
+  apiKey: ["name", "in"],
+  oauth2: ["flows"],
+  openIdConnect: ["openIdConnectUrl"],
+  mutualTLS: []
+};
+function schemeIssue(scheme, where) {
+  if (!isObject(scheme) || typeof scheme.type !== "string") {
+    return `Expected ${where} to be a security scheme with a "type".`;
+  }
+  const keys = Object.hasOwn(SCHEME_KEYS, scheme.type) ? SCHEME_KEYS[scheme.type] : undefined;
+  if (!keys) {
+    return `Expected ${where}.type to be one of ${Object.keys(SCHEME_KEYS).join(", ")}.`;
+  }
+  const bad = onlyKeys(scheme, ["type", "description", ...keys], where);
+  if (bad)
+    return bad;
+  if (scheme.description !== undefined && typeof scheme.description !== "string") {
+    return `Expected ${where}.description to be a string.`;
+  }
+  switch (scheme.type) {
+    case "http":
+      if (typeof scheme.scheme !== "string" || !scheme.scheme) {
+        return `Expected ${where}.scheme to be a scheme such as "bearer".`;
+      }
+      if (scheme.bearerFormat !== undefined && typeof scheme.bearerFormat !== "string") {
+        return `Expected ${where}.bearerFormat to be a string.`;
+      }
+      return;
+    case "apiKey":
+      if (typeof scheme.name !== "string" || !scheme.name) {
+        return `Expected ${where}.name to be a non-empty string.`;
+      }
+      if (!["header", "query", "cookie"].includes(scheme.in)) {
+        return `Expected ${where}.in to be "header", "query" or "cookie".`;
+      }
+      return;
+    case "oauth2":
+      return isObject(scheme.flows) ? undefined : `Expected ${where}.flows to be an object.`;
+    case "openIdConnect":
+      return typeof scheme.openIdConnectUrl === "string" && scheme.openIdConnectUrl ? undefined : `Expected ${where}.openIdConnectUrl to be a URL.`;
+    default:
+      return;
+  }
+}
+function requirementIssue(requirement, schemes, where) {
+  if (!isObject(requirement) || onlyKeys(requirement, ["scheme", "scopes"], where) || typeof requirement.scheme !== "string" || !isScopes(requirement.scopes)) {
+    return `Expected ${where} to be { scheme, scopes? }.`;
+  }
+  if (!Object.hasOwn(schemes, requirement.scheme)) {
+    return `${where}.scheme names the unknown security scheme "${requirement.scheme}".`;
+  }
+  return;
+}
+function securityIssue(security, where) {
+  if (!isObject(security))
+    return `Expected ${where} to be an object.`;
+  const bad = onlyKeys(security, ["schemes", "operations", "default"], where);
+  if (bad)
+    return bad;
+  const { schemes, operations } = security;
+  if (!isObject(schemes))
+    return `Expected ${where}.schemes to be an object.`;
+  for (const [name, scheme] of Object.entries(schemes)) {
+    if (!COMPONENT_NAME.test(name)) {
+      return `Expected the security scheme "${name}" to be named with letters, digits, ".", "_" or "-".`;
+    }
+    const schemeBad = schemeIssue(scheme, `${where}.schemes["${name}"]`);
+    if (schemeBad)
+      return schemeBad;
+  }
+  if (operations !== undefined) {
+    if (!isObject(operations)) {
+      return `Expected ${where}.operations to be an object.`;
+    }
+    for (const [id, requirement] of Object.entries(operations)) {
+      if (requirement === false)
+        continue;
+      const requirementBad = requirementIssue(requirement, schemes, `${where}.operations["${id}"]`);
+      if (requirementBad)
+        return requirementBad;
+    }
+  }
+  if (security.default !== undefined) {
+    return requirementIssue(security.default, schemes, `${where}.default`);
+  }
+  return;
+}
+export const ROUTE_OPTION_KEYS = [
+  "basePath",
+  "route",
+  "responses",
+  "requestId",
+  "security"
+];
+export function routeOptionsIssue(options, where) {
+  const { basePath, route, responses, requestId, security } = options;
+  if (basePath !== undefined && (typeof basePath !== "string" || basePath !== "" && !isPath(basePath, false))) {
+    return `Expected ${where}.basePath to be "" or a path such as "/api".`;
+  }
+  if (route !== undefined) {
+    if (!isObject(route))
+      return `Expected ${where}.route to be an object.`;
+    for (const [id, entry] of Object.entries(route)) {
+      if (!isObject(entry) || onlyKeys(entry, ["method", "path", "status"], "route")) {
+        return `Expected ${where}.route["${id}"] to be { method?, path?, status? }.`;
+      }
+      if (entry.method !== undefined && !METHODS.includes(entry.method)) {
+        return `Expected ${where}.route["${id}"].method to be one of ${METHODS.join(", ")}.`;
+      }
+      if (entry.path !== undefined) {
+        if (!isPath(entry.path)) {
+          return `Expected ${where}.route["${id}"].path to start with "/", with parameters only as whole "{name}" segments and no query.`;
+        }
+        const names = parametersOfPath(entry.path);
+        if (new Set(names).size !== names.length) {
+          return `Expected ${where}.route["${id}"].path to name each parameter once.`;
+        }
+      }
+      if (entry.status !== undefined && !SUCCESS_STATUSES.includes(entry.status)) {
+        return `Expected ${where}.route["${id}"].status to be one of ${SUCCESS_STATUSES.join(", ")}.`;
+      }
+    }
+  }
+  if (responses !== undefined) {
+    if (!isObject(responses)) {
+      return `Expected ${where}.responses to be an object.`;
+    }
+    for (const [id, entry] of Object.entries(responses)) {
+      const at = `${where}.responses["${id}"]`;
+      if (!isObject(entry) || onlyKeys(entry, ["headers"], at) || entry.headers !== undefined && !isObject(entry.headers)) {
+        return `Expected ${at} to be { headers?: { name: value } }.`;
+      }
+      for (const [name, value] of Object.entries(entry.headers ?? {})) {
+        if (!HEADER_NAME.test(name)) {
+          return `Expected ${at}.headers to be named by header names, not "${name}".`;
+        }
+        if (name.toLowerCase() === "content-type") {
+          return `${at}.headers cannot set "content-type": the sink sets it.`;
+        }
+        if (!isHeaderValue(value)) {
+          return `Expected ${at}.headers["${name}"] to be text without line breaks.`;
+        }
+      }
+    }
+  }
+  if (requestId !== undefined && requestId !== true && (typeof requestId !== "string" || !HEADER_NAME.test(requestId))) {
+    return `Expected ${where}.requestId to be true or a header name.`;
+  }
+  if (security !== undefined) {
+    return securityIssue(security, `${where}.security`);
+  }
+  return;
+}
+export function requestIdHeaderOf(options) {
+  return options.requestId === true ? REQUEST_ID_HEADER : options.requestId ?? undefined;
+}
+function validate(options) {
+  const bad = onlyKeys(options, ["info", "servers", ...ROUTE_OPTION_KEYS], "openapi");
+  if (bad)
+    return bad;
+  const { info, servers } = options;
+  if (!isObject(info))
+    return "Expected openapi.info to be an object.";
+  const infoBad = onlyKeys(info, ["title", "version", "description"], "info");
+  if (infoBad)
+    return infoBad;
+  for (const key of ["title", "version"]) {
+    if (typeof info[key] !== "string" || !info[key]) {
+      return `Expected openapi.info.${key} to be a non-empty string.`;
+    }
+  }
+  if (info.description !== undefined && typeof info.description !== "string") {
+    return "Expected openapi.info.description to be a string.";
+  }
+  if (servers !== undefined) {
+    if (!Array.isArray(servers))
+      return "Expected openapi.servers to be a list.";
+    for (const server of servers) {
+      if (!isObject(server) || typeof server.url !== "string" || !server.url || server.description !== undefined && typeof server.description !== "string" || onlyKeys(server, ["url", "description"], "server")) {
+        return "Expected each openapi.servers entry to be { url, description? }.";
+      }
+    }
+  }
+  return routeOptionsIssue(options, "openapi");
+}
+function invalid(reason, source = "openapi") {
+  throw new InvalidOutputStage({ source, details: { reason } });
+}
+function kebab(text) {
+  return text.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function isScalarKey(operation, name) {
+  return isScalarInputKey(operation.input, name);
+}
+export function operationRoutes(operations, options, source = "openapi") {
+  const base = options.basePath ?? "";
+  const route = options.route ?? {};
+  const responses = options.responses ?? {};
+  const ids = new Set(operations.map(({ id }) => id));
+  for (const [where, entries] of [
+    ["route", route],
+    ["responses", responses],
+    ["security.operations", options.security?.operations ?? {}]
+  ]) {
+    for (const id of Object.keys(entries)) {
+      if (!ids.has(id)) {
+        invalid(`${source}.${where} names the unknown operation "${id}".`, source);
+      }
+    }
+  }
+  const routes = new Map;
+  const taken = new Map;
+  for (const operation of operations) {
+    const chosen = route[operation.id] ?? {};
+    const declared = operation.route;
+    const method = chosen.method ?? declared?.method ?? "post";
+    const path = base + (chosen.path ?? declared?.path ?? `/${kebab(operation.command)}/${kebab(operation.name)}`);
+    const parameters = parametersOfPath(path);
+    const query = declared?.query ?? [];
+    const requestHeaders = declared?.headers ?? {};
+    const cookies = declared?.cookie ?? {};
+    for (const name of parameters) {
+      if (!isScalarKey(operation, name)) {
+        invalid(`${source}.route["${operation.id}"].path has the parameter "{${name}}", which is not a scalar key of the input of ${operation.id}.`, source);
+      }
+      if (query.includes(name) || Object.hasOwn(requestHeaders, name) || Object.hasOwn(cookies, name)) {
+        invalid(`${source}.route["${operation.id}"].path has the parameter "{${name}}", which the route of ${operation.useCase} reads from another place.`, source);
+      }
+    }
+    const key = `${method} ${path.replace(/\{[^}]*\}/g, "{}")}`;
+    const other = taken.get(key);
+    if (other !== undefined) {
+      invalid(`Two operations are routed to ${method.toUpperCase()} ${path}: ${other} and ${operation.id}. Give one another route, on its use case or in ${source}.route["${operation.id}"].`, source);
+    }
+    taken.set(key, operation.id);
+    routes.set(operation.id, {
+      method,
+      path,
+      parameters,
+      status: chosen.status ?? declared?.status ?? 200,
+      headers: { ...responses[operation.id]?.headers ?? {} },
+      body: method !== "get" && method !== "delete",
+      query,
+      requestHeaders,
+      cookies,
+      setCookies: declared?.setCookie ?? {}
+    });
+  }
+  return routes;
+}
+function collectRecords(properties, found) {
+  const visit = (field) => {
+    if (isBlueprintList(field)) {
+      visit(field.item);
+      return;
+    }
+    if (isBlueprint(field)) {
+      collectRecords(field.properties, found);
+      return;
+    }
+    if (isBlueprintVariant(field)) {
+      for (const variant of Object.values(field.variants)) {
+        visit(variant);
+      }
+      return;
+    }
+    const record = recordFieldOf(field)?.record;
+    if (record && !found.has(record)) {
+      found.add(record);
+      collectRecords(record.blueprint.properties, found);
+    }
+  };
+  for (const field of Object.values(properties))
+    visit(field);
+}
+function problemSchema() {
+  return {
+    type: "object",
+    properties: {
+      type: { type: "string" },
+      title: { type: "string" },
+      status: { type: "integer" },
+      detail: { type: "string" },
+      layer: { type: "string" },
+      issues: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            path: {
+              type: "array",
+              items: { type: ["string", "integer"] }
+            },
+            code: { type: "string" },
+            message: { type: "string" }
+          },
+          required: ["path", "code", "message"]
+        }
+      },
+      trace: { type: "string" }
+    },
+    required: ["type", "title", "status", "detail"]
+  };
+}
+const PROBLEM_REF = "#/components/schemas/Problem";
+const problemContent = {
+  [PROBLEM_MEDIA_TYPE]: { schema: { $ref: PROBLEM_REF } }
+};
+const STATUS_TEXT = {
+  400: "Invalid input or context.",
+  401: "Authentication is required.",
+  403: "The caller may not do this.",
+  404: "Not found.",
+  409: "Conflict.",
+  422: "Declared error of the operation.",
+  500: "Internal error."
+};
+const SUCCESS_TEXT = {
+  200: "Success.",
+  201: "Created.",
+  202: "Accepted.",
+  204: "No content."
+};
+function responsesOf(operation, statuses, response, route, requestIdHeader) {
+  const names = new Map([
+    [400, []],
+    [500, []]
+  ]);
+  const access = operation.access;
+  if (access && access.public !== true) {
+    names.set(401, []);
+    if ((access.scopes?.length ?? 0) > 0 || access.owner)
+      names.set(403, []);
+  }
+  for (const Declared of operation.errors) {
+    const synthetic = new Exception({
+      layer: ExceptionLayers.UseCase,
+      name: Declared.name,
+      source: "openapi",
+      message: Declared.name
+    });
+    const status = statusOf(synthetic, operation, statuses);
+    const list = names.get(status) ?? [];
+    if (!list.includes(Declared.name))
+      list.push(Declared.name);
+    names.set(status, list);
+  }
+  const idHeaders = requestIdHeader ? {
+    [requestIdHeader]: {
+      description: "The id of the request: the one it sent in this header, else a new one.",
+      schema: { type: "string" }
+    }
+  } : {};
+  const successHeaders = { ...idHeaders };
+  const setCookies = Object.values(route.setCookies);
+  if (setCookies.length > 0) {
+    successHeaders["set-cookie"] = {
+      description: `Sets ${setCookies.map(({ name }) => `\`${name}\``).join(", ")}.`,
+      schema: { type: "string" }
+    };
+  }
+  for (const [name, value] of Object.entries(route.headers)) {
+    successHeaders[name] = { schema: { type: "string", const: value } };
+  }
+  const withHeaders = (headers) => Object.keys(headers).length > 0 ? { headers } : {};
+  const responses = {
+    [String(route.status)]: {
+      description: SUCCESS_TEXT[route.status],
+      ...withHeaders(successHeaders),
+      ...route.status === 204 ? {} : { content: { "application/json": { schema: response } } }
+    }
+  };
+  for (const status of [...names.keys()].sort((a, b) => a - b)) {
+    const declared = names.get(status) ?? [];
+    const text = STATUS_TEXT[status] ?? `Error ${status}.`;
+    responses[String(status)] = {
+      description: declared.length > 0 ? `${text} Declared: ${declared.join(", ")}.` : text,
+      ...withHeaders(idHeaders),
+      content: problemContent
+    };
+  }
+  return responses;
+}
+function parameterOf(name, property, where, required) {
+  const { description, ...rest } = property;
+  return {
+    name,
+    in: where,
+    required: where === "path" || required,
+    ...typeof description === "string" ? { description } : {},
+    schema: rest
+  };
+}
+function queryParametersOf(operation, schema) {
+  const required = new Set(schema.required ?? []);
+  return Object.entries(schema.properties ?? {}).map(([name, property]) => {
+    if (!isProperty(operation.input.properties[name]) || !isScalarSchema(property)) {
+      invalid(`${operation.id} uses a get/delete route, whose input becomes query parameters, but "${name}" is not a scalar; route it with method "post".`);
+    }
+    return parameterOf(name, property, "query", required.has(name));
+  });
+}
+function withoutKeys(schema, keys) {
+  if (keys.length === 0)
+    return schema;
+  const properties = { ...schema.properties ?? {} };
+  for (const key of keys)
+    delete properties[key];
+  const required = (schema.required ?? []).filter((key) => !keys.includes(key));
+  const { required: _, ...rest } = schema;
+  return {
+    ...rest,
+    properties,
+    ...required.length > 0 ? { required } : {}
+  };
+}
+function requirementOf(requirement) {
+  return { [requirement.scheme]: [...requirement.scopes ?? []] };
+}
+export const openapi = sinkOf({
+  name: "openapi",
+  validate,
+  build: (operations, options, { output }) => {
+    const routes = operationRoutes(operations, options);
+    const requestIdHeader = requestIdHeaderOf(options);
+    const security = options.security;
+    const records = new Set;
+    for (const operation of operations) {
+      collectRecords(operation.input.properties, records);
+      collectRecords(operation.response.properties, records);
+    }
+    const models = {};
+    const classes = new Map;
+    for (const record of records) {
+      const name = recordNameOf(record);
+      if (!COMPONENT_NAME.test(name) || name === "Problem") {
+        invalid(`The record class "${name}" cannot be a component name; give the class a name that is not "Problem".`);
+      }
+      if (classes.has(name)) {
+        invalid(`Two record classes are named "${name}"; rename one.`);
+      }
+      classes.set(name, record);
+      models[name] = record;
+    }
+    for (const operation of operations) {
+      models[`${operation.id}#input`] = operation.input;
+      models[`${operation.id}#response`] = operation.response;
+    }
+    const { schemas } = toOpenAPI(models);
+    const paths = {};
+    const operationIds = new Set;
+    const components = {};
+    for (const name of classes.keys())
+      components[name] = schemas[name];
+    components.Problem = problemSchema();
+    for (const operation of operations) {
+      const route = routes.get(operation.id);
+      const { method, path } = route;
+      const operationId = operation.id.replaceAll(".", "_");
+      if (operationIds.has(operationId)) {
+        invalid(`The operationId "${operationId}" is produced twice.`);
+      }
+      operationIds.add(operationId);
+      const slot = paths[path] ?? {};
+      paths[path] = slot;
+      const full = schemas[`${operation.id}#input`];
+      const required = new Set(full.required ?? []);
+      const hasBody = route.body;
+      const input = withoutKeys(full, [
+        ...route.parameters,
+        ...hasBody ? route.query : [],
+        ...Object.keys(route.requestHeaders),
+        ...Object.keys(route.cookies)
+      ]);
+      const response = withoutKeys(schemas[`${operation.id}#response`], Object.keys(route.setCookies));
+      const hasInput = Object.keys(input.properties ?? {}).length > 0;
+      const placed = (keys, where) => Object.entries(keys).map(([key, name]) => parameterOf(name, full.properties?.[key], where, required.has(key)));
+      const parameters = [
+        ...route.parameters.map((name) => parameterOf(name, full.properties?.[name], "path", true)),
+        ...hasBody ? route.query.map((name) => parameterOf(name, full.properties?.[name], "query", required.has(name))) : queryParametersOf(operation, input),
+        ...placed(route.requestHeaders, "header"),
+        ...placed(route.cookies, "cookie")
+      ];
+      const explicit = security?.operations?.[operation.id];
+      const access = operation.access;
+      const guarded = access !== undefined && access.public !== true;
+      if (guarded && explicit === false) {
+        invalid(`openapi.security.operations["${operation.id}"] is false, but ${operation.useCase} declares an access that the output enforces.`);
+      }
+      const schemeNames = Object.keys(security?.schemes ?? {});
+      const scheme = security?.default?.scheme ?? (schemeNames.length === 1 ? schemeNames[0] : undefined);
+      const requirement = explicit !== undefined ? explicit : guarded && scheme !== undefined ? { scheme, scopes: access.scopes ?? [] } : access?.public === true && security?.default ? false : undefined;
+      slot[method] = {
+        operationId,
+        summary: operation.id,
+        ...operation.description ? { description: operation.description } : {},
+        ...operation.tags.length > 0 ? { tags: [...operation.tags] } : {},
+        ...operation.deprecated ? { deprecated: true } : {},
+        ...!hasBody || parameters.length > 0 ? { parameters } : {},
+        ...hasBody && hasInput ? {
+          requestBody: {
+            required: true,
+            content: { "application/json": { schema: input } }
+          }
+        } : {},
+        responses: responsesOf(operation, output.statuses, response, route, requestIdHeader),
+        ...requirement === false ? { security: [] } : requirement ? { security: [requirementOf(requirement)] } : {}
+      };
+    }
+    return {
+      openapi: "3.1.0",
+      info: options.info,
+      ...options.servers ? { servers: options.servers } : {},
+      ...security?.default ? { security: [requirementOf(security.default)] } : {},
+      paths,
+      components: {
+        schemas: components,
+        ...security ? { securitySchemes: security.schemes } : {}
+      }
+    };
+  }
+});