counterfact 0.25.5 → 0.26.1

package/bin/counterfact.js

@@ -6,9 +6,9 @@ import { program } from "commander";
 import createDebug from "debug";
 import open from "open";
 
-import { startRepl } from "../src/server/repl.js";
-import { start } from "../src/server/start.js";
-import { generate } from "../src/typescript-generator/generate.js";
+import { startRepl } from "../dist/src/server/repl.js";
+import { start } from "../dist/src/server/start.js";
+import { generate } from "../dist/src/typescript-generator/generate.js";
 
 const DEFAULT_PORT = 3100;
 

package/dist/src/server/constants.js

@@ -0,0 +1,3 @@
+export const CHOKIDAR_OPTIONS = {
+    usePolling: process.platform === "win32",
+};

package/dist/src/server/context-registry.js

@@ -0,0 +1,32 @@
+export function parentPath(path) {
+    return String(path.split("/").slice(0, -1).join("/")) || "/";
+}
+export class ContextRegistry {
+    entries = new Map();
+    constructor() {
+        this.add("/", {});
+    }
+    add(path, context) {
+        if (context === undefined) {
+            throw new Error("context cannot be undefined");
+        }
+        this.entries.set(path, context);
+    }
+    find(path) {
+        return this.entries.get(path) ?? this.find(parentPath(path));
+    }
+    update(path, updatedContext) {
+        if (updatedContext === undefined) {
+            return;
+        }
+        const context = this.find(path);
+        for (const property in updatedContext) {
+            if (Object.prototype.hasOwnProperty.call(updatedContext, property) &&
+                !Object.prototype.hasOwnProperty.call(context, property)) {
+                context[property] = updatedContext[property];
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        Object.setPrototypeOf(context, Object.getPrototypeOf(updatedContext));
+    }
+}

package/dist/src/server/counterfact.js

@@ -0,0 +1,47 @@
+import nodePath from "node:path";
+import yaml from "js-yaml";
+import $RefParser from "json-schema-ref-parser";
+import { readFile } from "../util/read-file.js";
+import { ContextRegistry } from "./context-registry.js";
+import { Dispatcher } from "./dispatcher.js";
+import { koaMiddleware } from "./koa-middleware.js";
+import { ModuleLoader } from "./module-loader.js";
+import { Registry } from "./registry.js";
+import { Transpiler } from "./transpiler.js";
+async function loadOpenApiDocument(source) {
+    try {
+        const text = await readFile(source);
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const openApiDocument = (await yaml.load(text));
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        return (await $RefParser.dereference(openApiDocument));
+    }
+    catch {
+        return undefined;
+    }
+}
+// eslint-disable-next-line max-statements
+export async function counterfact(basePath, openApiPath = nodePath
+    .join(basePath, "../openapi.yaml")
+    .replaceAll("\\", "/"), options = {}) {
+    const openApiDocument = await loadOpenApiDocument(openApiPath);
+    const registry = new Registry();
+    const modulesPath = basePath;
+    const contextRegistry = new ContextRegistry();
+    const dispatcher = new Dispatcher(registry, contextRegistry, openApiDocument);
+    const compiledPathsDirectory = nodePath
+        .join(modulesPath, ".cache")
+        .replaceAll("\\", "/");
+    const transpiler = new Transpiler(nodePath.join(modulesPath, "paths").replaceAll("\\", "/"), compiledPathsDirectory);
+    await transpiler.watch();
+    const moduleLoader = new ModuleLoader(compiledPathsDirectory, registry, contextRegistry);
+    await moduleLoader.load();
+    await moduleLoader.watch();
+    return {
+        contextRegistry,
+        // eslint-disable-next-line total-functions/no-unsafe-readonly-mutable-assignment
+        koaMiddleware: koaMiddleware(dispatcher, options),
+        moduleLoader,
+        registry,
+    };
+}

package/dist/src/server/dispatcher.js

@@ -0,0 +1,150 @@
+/* eslint-disable import/newline-after-import */
+/* eslint-disable max-lines */
+import { mediaTypes } from "@hapi/accept";
+import createDebugger from "debug";
+// eslint-disable-next-line @typescript-eslint/no-shadow
+import fetch, { Headers } from "node-fetch";
+import { createResponseBuilder, } from "./response-builder.js";
+import { Tools } from "./tools.js";
+const debug = createDebugger("counterfact:server:dispatcher");
+export class Dispatcher {
+    registry;
+    contextRegistry;
+    openApiDocument;
+    fetch;
+    constructor(registry, contextRegistry, openApiDocument) {
+        this.registry = registry;
+        this.contextRegistry = contextRegistry;
+        this.openApiDocument = openApiDocument;
+        this.fetch = fetch;
+    }
+    parameterTypes(parameters) {
+        const types = {
+            body: {},
+            cookie: {},
+            formData: {},
+            header: {},
+            path: {},
+            query: {},
+        };
+        if (!parameters) {
+            return types;
+        }
+        for (const parameter of parameters) {
+            if (parameter.schema !== undefined) {
+                types[parameter.in][parameter.name] =
+                    parameter.schema.type === "integer"
+                        ? "number"
+                        : parameter.schema.type;
+            }
+        }
+        return types;
+    }
+    operationForPathAndMethod(path, method) {
+        const operation = this.openApiDocument?.paths[path]?.[
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        method.toLowerCase()];
+        if (operation === undefined) {
+            return undefined;
+        }
+        if (this.openApiDocument?.produces) {
+            return {
+                produces: this.openApiDocument.produces,
+                ...operation,
+            };
+        }
+        return operation;
+    }
+    normalizeResponse(response, acceptHeader) {
+        if (typeof response === "string") {
+            return {
+                body: response,
+                contentType: "text/plain",
+                headers: {},
+                status: 200,
+            };
+        }
+        if (response.content !== undefined) {
+            const content = this.selectContent(acceptHeader, response.content);
+            if (content === undefined) {
+                return {
+                    body: `Not Acceptable: could not produce a response matching any of the following content types: ${acceptHeader}`,
+                    contentType: "text/plain",
+                    status: 406,
+                };
+            }
+            const normalizedResponse = {
+                ...response,
+                body: content.body,
+                contentType: content.type,
+            };
+            delete normalizedResponse.content;
+            return normalizedResponse;
+        }
+        return {
+            ...response,
+            contentType: response.headers?.["content-type"]?.toString() ?? "unknown/unknown",
+        };
+    }
+    selectContent(acceptHeader, content) {
+        const preferredMediaTypes = mediaTypes(acceptHeader);
+        for (const mediaType of preferredMediaTypes) {
+            const contentItem = content.find((item) => this.isMediaType(item.type, mediaType));
+            if (contentItem) {
+                return contentItem;
+            }
+        }
+        return undefined;
+    }
+    isMediaType(type, pattern) {
+        if (pattern === "*/*") {
+            return true;
+        }
+        const [baseType, subType] = type.split("/");
+        const [patternType, patternSubType] = pattern.split("/");
+        if (baseType === patternType) {
+            return subType === patternSubType || patternSubType === "*";
+        }
+        if (subType === patternSubType) {
+            return baseType === patternType || patternType === "*";
+        }
+        return false;
+    }
+    // eslint-disable-next-line sonarjs/cognitive-complexity
+    async request({ body, headers = {}, method, path, query, req, }) {
+        debug(`request: ${method} ${path}`);
+        const { matchedPath } = this.registry.handler(path);
+        const operation = this.operationForPathAndMethod(matchedPath, method);
+        const response = await this.registry.endpoint(method, path, this.parameterTypes(operation?.parameters))({
+            body,
+            context: this.contextRegistry.find(path),
+            headers,
+            proxy: async (url) => {
+                if (body !== undefined && headers.contentType !== "application/json") {
+                    throw new Error(`$.proxy() is currently limited to application/json requests. You tried to proxy to ${url} with a Content-Type of ${headers.contentType ?? "[unknown]"}. Please open an issue at https://github.com/pmcelhaney/counterfact/issues and prod me to fix this limitation.`);
+                }
+                const fetchResponse = await this.fetch(`${url}${req.path ?? ""}`, {
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    headers: new Headers(headers),
+                    method,
+                });
+                const responseHeaders = Object.fromEntries(fetchResponse.headers.entries());
+                return {
+                    body: await fetchResponse.text(),
+                    contentType: responseHeaders["content-type"] ?? "unknown/unknown",
+                    headers: responseHeaders,
+                    status: fetchResponse.status,
+                };
+            },
+            query,
+            // @ts-expect-error - Might be pushing the limits of what TypeScript can do here
+            response: createResponseBuilder(operation ?? { responses: {} }),
+            tools: new Tools({ headers }),
+        });
+        const normalizedResponse = this.normalizeResponse(response, headers.accept ?? "*/*");
+        if (!mediaTypes(headers.accept ?? "*/*").some((type) => this.isMediaType(normalizedResponse.contentType, type))) {
+            return { body: mediaTypes(headers.accept ?? "*/*"), status: 406 };
+        }
+        return normalizedResponse;
+    }
+}

package/dist/src/server/koa-middleware.js

@@ -0,0 +1,42 @@
+import koaProxy from "koa-proxy";
+const HTTP_STATUS_CODE_OK = 200;
+function addCors(ctx, headers) {
+    // Always append CORS headers, reflecting back the headers requested if any
+    ctx.set("Access-Control-Allow-Origin", headers?.origin ?? "*");
+    ctx.set("Access-Control-Allow-Methods", "GET,HEAD,PUT,POST,DELETE,PATCH");
+    ctx.set("Access-Control-Allow-Headers", headers?.["access-control-request-headers"] ?? []);
+    ctx.set("Access-Control-Expose-Headers", headers?.["access-control-request-headers"] ?? []);
+    ctx.set("Access-Control-Allow-Credentials", "true");
+}
+export function koaMiddleware(dispatcher, { proxyEnabled = false, proxyUrl = "" } = {}, proxy = koaProxy) {
+    // eslint-disable-next-line max-statements
+    return async function middleware(ctx, next) {
+        const { body, headers, path, query } = ctx.request;
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const method = ctx.request.method;
+        if (proxyEnabled && proxyUrl) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return proxy({ host: proxyUrl })(ctx, next);
+        }
+        addCors(ctx, headers);
+        if (method === "OPTIONS") {
+            ctx.status = HTTP_STATUS_CODE_OK;
+            return undefined;
+        }
+        const response = await dispatcher.request({
+            body,
+            /* @ts-expect-error the value of a header can be an array and we don't have a solution for that yet */
+            headers,
+            method,
+            path,
+            /* @ts-expect-error the value of a querystring item can be an array and we don't have a solution for that yet */
+            query,
+            req: { path: "", ...ctx.req },
+        });
+        /* eslint-disable require-atomic-updates */
+        ctx.body = response.body;
+        ctx.status = response.status ?? HTTP_STATUS_CODE_OK;
+        /* eslint-enable require-atomic-updates */
+        return undefined;
+    };
+}

package/dist/src/server/module-loader.js

@@ -0,0 +1,109 @@
+import { once } from "node:events";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import nodePath from "node:path";
+import { pathToFileURL } from "node:url";
+import { watch } from "chokidar";
+import createDebug from "debug";
+import { ContextRegistry } from "./context-registry.js";
+const debug = createDebug("counterfact:typescript-generator:module-loader");
+export class ModuleLoader extends EventTarget {
+    basePath;
+    registry;
+    watcher;
+    contextRegistry;
+    constructor(basePath, registry, contextRegistry = new ContextRegistry()) {
+        super();
+        this.basePath = basePath.replaceAll("\\", "/");
+        this.registry = registry;
+        this.contextRegistry = contextRegistry;
+    }
+    async watch() {
+        this.watcher = watch(`${this.basePath}/**/*.{js,mjs,ts,mts}`).on("all", 
+        // eslint-disable-next-line max-statements
+        (eventName, pathNameOriginal) => {
+            const pathName = pathNameOriginal.replaceAll("\\", "/");
+            if (!["add", "change", "unlink"].includes(eventName)) {
+                return;
+            }
+            const parts = nodePath.parse(pathName.replace(this.basePath, ""));
+            const url = `/${parts.dir}/${parts.name}`
+                .replaceAll("\\", "/")
+                .replaceAll(/\/+/gu, "/");
+            if (eventName === "unlink") {
+                this.registry.remove(url);
+                this.dispatchEvent(new Event("remove"));
+            }
+            const fileUrl = `${pathToFileURL(pathName).toString()}?cacheBust=${Date.now()}`;
+            debug("importing module: %s", fileUrl);
+            // eslint-disable-next-line import/no-dynamic-require, no-unsanitized/method
+            import(fileUrl)
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .then((endpoint) => {
+                this.dispatchEvent(new Event(eventName));
+                if (pathName.includes("$.context")) {
+                    this.contextRegistry.update(parts.dir, 
+                    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                    endpoint.default);
+                    return "context";
+                }
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                this.registry.add(url, endpoint);
+                return "path";
+            })
+                // eslint-disable-next-line promise/prefer-await-to-then
+                .catch((error) => {
+                process.stdout.write(`\nError loading ${fileUrl}:\n${String(error)}\n`);
+            });
+        });
+        await once(this.watcher, "ready");
+    }
+    async stopWatching() {
+        await this.watcher?.close();
+    }
+    async load(directory = "") {
+        if (!existsSync(nodePath.join(this.basePath, directory).replaceAll("\\", "/"))) {
+            throw new Error(`Directory does not exist ${this.basePath}`);
+        }
+        const files = await fs.readdir(nodePath.join(this.basePath, directory).replaceAll("\\", "/"), {
+            withFileTypes: true,
+        });
+        const imports = files.flatMap(async (file) => {
+            const extension = file.name.split(".").at(-1);
+            if (file.isDirectory()) {
+                await this.load(nodePath.join(directory, file.name).replaceAll("\\", "/"));
+                return;
+            }
+            if (!["js", "mjs", "mts", "ts"].includes(extension ?? "")) {
+                return;
+            }
+            const fullPath = nodePath
+                .join(this.basePath, directory, file.name)
+                .replaceAll("\\", "/");
+            await this.loadEndpoint(fullPath, directory, file);
+        });
+        await Promise.all(imports);
+    }
+    async loadEndpoint(fullPath, directory, file) {
+        const fileUrl = `${pathToFileURL(fullPath).toString()}?cacheBust=${Date.now()}`;
+        try {
+            // eslint-disable-next-line import/no-dynamic-require, no-unsanitized/method, @typescript-eslint/consistent-type-assertions
+            const endpoint = (await import(fileUrl));
+            if (file.name.includes("$.context")) {
+                this.contextRegistry.add(`/${directory.replaceAll("\\", "/")}`, 
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                endpoint.default);
+            }
+            else {
+                const url = `/${nodePath.join(directory, nodePath.parse(file.name).name)}`
+                    .replaceAll("\\", "/")
+                    .replaceAll(/\/+/gu, "/");
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                this.registry.add(url, endpoint);
+            }
+        }
+        catch (error) {
+            process.stdout.write(`\nError loading ${fileUrl}:\n${String(error)}\n`);
+        }
+    }
+}

package/dist/src/server/registry.js

@@ -0,0 +1,116 @@
+import createDebugger from "debug";
+const debug = createDebugger("counterfact:server:registry");
+function castParameters(parameters, parameterTypes) {
+    const copy = { ...parameters };
+    Object.entries(copy).forEach(([key, value]) => {
+        copy[key] =
+            parameterTypes?.[key] === "number"
+                ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                    Number.parseInt(value, 10)
+                : value;
+    });
+    return copy;
+}
+function maybe(flag, value) {
+    return flag ? [value] : [];
+}
+function stripBrackets(string) {
+    return string.replaceAll(/\{|\}/gu, "");
+}
+function routesForNode(node) {
+    if (!node.children) {
+        return [];
+    }
+    return Object.entries(node.children)
+        .flatMap(([segment, child]) => [
+        ...maybe(child.module, `/${segment}`),
+        ...routesForNode(child).map((route) => `/${segment}${route}`),
+    ])
+        .sort((segment1, segment2) => stripBrackets(segment1).localeCompare(stripBrackets(segment2)));
+}
+export class Registry {
+    modules = {};
+    moduleTree = { children: {} };
+    get routes() {
+        return routesForNode(this.moduleTree);
+    }
+    add(url, module) {
+        let node = this.moduleTree;
+        for (const segment of url.split("/").slice(1)) {
+            node.children ??= {};
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            node.children[segment] ??= {};
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            node = node.children[segment];
+        }
+        node.module = module;
+    }
+    remove(url) {
+        let node = this.moduleTree;
+        for (const segment of url.split("/").slice(1)) {
+            node = node.children?.[segment];
+            if (!node) {
+                return false;
+            }
+        }
+        delete node.module;
+        return true;
+    }
+    exists(method, url) {
+        return Boolean(this.handler(url).module?.[method]);
+    }
+    // eslint-disable-next-line max-statements, sonarjs/cognitive-complexity
+    handler(url) {
+        let node = this.moduleTree;
+        const path = {};
+        const matchedParts = [""];
+        for (const segment of url.split("/").slice(1)) {
+            if (node === undefined) {
+                throw new Error("node or node node.children cannot be undefined");
+            }
+            if (node.children === undefined) {
+                throw new Error("node or node node.children cannot be undefined");
+            }
+            const matchingChild = Object.keys(node.children).find((candidate) => candidate.toLowerCase() === segment.toLowerCase());
+            debug("segment: %s", segment);
+            debug("matching child: %s", matchingChild);
+            if (matchingChild === undefined) {
+                const dynamicSegment = Object.keys(node.children).find((ds) => ds.startsWith("{") && ds.endsWith("}"));
+                if (dynamicSegment !== undefined) {
+                    const variableName = dynamicSegment.slice(1, -1);
+                    path[variableName] = segment;
+                    node = node.children[dynamicSegment];
+                    matchedParts.push(dynamicSegment);
+                }
+            }
+            else {
+                node = node.children[matchingChild];
+                matchedParts.push(matchingChild);
+            }
+        }
+        if (node === undefined) {
+            throw new Error("node cannot be undefined");
+        }
+        return { matchedPath: matchedParts.join("/"), module: node.module, path };
+    }
+    endpoint(httpRequestMethod, url, parameterTypes = {}) {
+        const handler = this.handler(url);
+        debug("handler for %s: %o", url, handler);
+        const execute = handler.module?.[httpRequestMethod];
+        if (!execute) {
+            return () => ({
+                body: `Could not find a ${httpRequestMethod} method matching ${url}\n`,
+                contentType: "text/plain",
+                headers: {},
+                status: 404,
+            });
+        }
+        return async ({ ...requestData }) => await execute({
+            ...requestData,
+            headers: castParameters(requestData.headers, parameterTypes.header),
+            matchedPath: handler.matchedPath,
+            path: castParameters(handler.path, parameterTypes.path),
+            query: castParameters(requestData.query, parameterTypes.query),
+        });
+    }
+}

package/dist/src/server/repl.js

@@ -0,0 +1,33 @@
+import repl from "node:repl";
+export function startRepl(contextRegistry, config) {
+    const replServer = repl.start("> ");
+    replServer.defineCommand("counterfact", {
+        action() {
+            process.stdout.write("This is a read-eval-print loop (REPL), the same as the one you get when you run node with no arguments.\n");
+            process.stdout.write("Except that it's connected to the running server, which you can access with the following globals:\n\n");
+            process.stdout.write("- loadContext('/some/path'): to access the context object for a given path\n");
+            process.stdout.write("- context: the root context ( same as loadContext('/') )\n");
+            process.stdout.write("\nFor more information, see https://counterfact.dev/docs/usage.html\n\n");
+            this.clearBufferedCommand();
+            this.displayPrompt();
+        },
+        help: "Get help with Counterfact",
+    });
+    replServer.defineCommand("proxy", {
+        action(state) {
+            if (state === "on") {
+                config.proxyEnabled = true;
+            }
+            if (state === "off") {
+                config.proxyEnabled = false;
+            }
+            process.stdout.write(`Proxy is ${config.proxyEnabled ? "on" : "off"}: ${config.proxyUrl}\n`);
+            this.clearBufferedCommand();
+            this.displayPrompt();
+        },
+        help: "proxy [on|off] - turn the proxy on or off; proxy - print proxy info",
+    });
+    replServer.context.loadContext = (path) => contextRegistry.find(path);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
+    replServer.context.context = replServer.context.loadContext("/");
+}

package/dist/src/server/response-builder.js

@@ -0,0 +1,97 @@
+import { JSONSchemaFaker } from "json-schema-faker";
+JSONSchemaFaker.option("useExamplesValue", true);
+function oneOf(items) {
+    if (Array.isArray(items)) {
+        return items[Math.floor(Math.random() * items.length)];
+    }
+    return oneOf(Object.values(items));
+}
+function unknownStatusCodeResponse(statusCode) {
+    return {
+        content: [
+            {
+                body: `The Open API document does not specify a response for status code ${statusCode ?? '""'}`,
+                type: "text/plain",
+            },
+        ],
+        status: 500,
+    };
+}
+export function createResponseBuilder(operation) {
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    return new Proxy({}, {
+        // eslint-disable-next-line sonarjs/cognitive-complexity
+        get: (target, statusCode) => ({
+            header(name, value) {
+                return {
+                    ...this,
+                    headers: {
+                        ...this.headers,
+                        [name]: value,
+                    },
+                };
+            },
+            html(body) {
+                return this.match("text/html", body);
+            },
+            json(body) {
+                return this.match("application/json", body);
+            },
+            match(contentType, body) {
+                return {
+                    ...this,
+                    content: [
+                        ...(this.content ?? []),
+                        {
+                            body,
+                            type: contentType,
+                        },
+                    ],
+                };
+            },
+            random() {
+                if (operation.produces) {
+                    return this.randomLegacy();
+                }
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                if (response?.content === undefined) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const { content } = response;
+                return {
+                    ...this,
+                    content: Object.keys(content).map((type) => ({
+                        body: content[type]?.examples
+                            ? oneOf(Object.values(content[type]?.examples ?? []).map((example) => example.value))
+                            : JSONSchemaFaker.generate(
+                            // eslint-disable-next-line total-functions/no-unsafe-readonly-mutable-assignment
+                            content[type]?.schema ?? { type: "object" }),
+                        type,
+                    })),
+                };
+            },
+            randomLegacy() {
+                const response = operation.responses[this.status ?? "default"] ??
+                    operation.responses.default;
+                if (response === undefined) {
+                    return unknownStatusCodeResponse(this.status);
+                }
+                const body = response.examples
+                    ? oneOf(response.examples)
+                    : JSONSchemaFaker.generate(response.schema ?? { type: "object" });
+                return {
+                    ...this,
+                    content: operation.produces?.map((type) => ({
+                        body,
+                        type,
+                    })),
+                };
+            },
+            status: Number.parseInt(statusCode, 10),
+            text(body) {
+                return this.match("text/plain", body);
+            },
+        }),
+    });
+}