@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/project/load-helpers.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What core's loader and every protocol's `storage.load` share when they read a project folder:
+ * YAML from a relative path, the `undefined`-dropping helpers, authentication as loaded, a
+ * request's scripts, and the request tree an API (of any protocol) and the webhook collection keep
+ * under `requests/`.
+ *
+ * A protocol's storage imports this file and never `load.ts`, which imports the protocols.
+ */
+import type { z } from 'zod';
+import type { KeyValueEntry } from '../http/entries.js';
+import type { RequestScripts } from '../script/model.js';
+import type { FsLike } from './fs.js';
+import type { ProjectProblem } from './load.js';
+import type { AuthConfig, DefinitionAuth } from './model.js';
+import type { KeyValueEntryFile, scriptsSchema } from './schema-parts.js';
+/** The absolute path of a `/`-separated path relative to the project root. */
+export declare function abs(root: string, relative: string): string;
+/** Reads and parses one YAML file of the project; undefined when the file does not exist. */
+export declare function readYaml(fs: FsLike, root: string, relative: string): Promise<unknown>;
+/** Orders entities by their persisted `order`, falling back to a stable name comparison. */
+export declare function byOrder<T extends {
+    readonly order: number;
+    readonly name: string;
+}>(a: T, b: T): number;
+/** `{ [key]: value }`, or nothing at all when the value is undefined (`exactOptionalPropertyTypes`). */
+export declare function optional<T>(key: string, value: T | undefined): Record<string, T>;
+/**
+ * Drops `undefined`-valued keys from a zod result, so an absent optional field
+ * is truly absent rather than present-and-undefined (`exactOptionalPropertyTypes`).
+ */
+export declare function exact<T extends object>(value: {
+    readonly [K in keyof T]: T[K] | undefined;
+}): T;
+/**
+ * A request's scripts and the text of each script file (#63). The file read is always the name
+ * derived from the slug, never the one the request file records. A missing or oversized file is a
+ * problem on the request; an oversized one keeps its text so a save writes it back untouched.
+ */
+export declare function loadScripts(fs: FsLike, root: string, dir: string, slug: string, document: z.infer<typeof scriptsSchema> | undefined, requestName: string, problems: ProjectProblem[], claim: (fileName: string) => void): Promise<RequestScripts | undefined>;
+/**
+ * Authentication as loaded: the same `undefined`-key drop {@link exact} performs, expressed
+ * separately because `AuthConfig` is a union and so has no single mapped shape to hand `exact`.
+ * The cast is safe for the same reason `exact`'s is: the schema has already established the
+ * arm's own fields, and this only removes keys whose value is absent.
+ */
+export declare function authConfig(parsed: Record<string, unknown>): AuthConfig;
+/**
+ * A definition's fetch credentials as loaded, through {@link authConfig}. `definitionAuthSchema` has
+ * already refused every scheme but Basic, Bearer and API key, so the narrowing cast only restates
+ * what parsing proved.
+ */
+export declare function definitionAuth(parsed: Record<string, unknown> | undefined): DefinitionAuth | undefined;
+/** A table row as loaded: `enabled` defaults to true, an absent description stays absent. */
+export declare function keyValueEntries(rows: readonly KeyValueEntryFile[]): KeyValueEntry[];
+/** A folder of either protocol's tree: the same node, holding one kind of request. */
+export interface FolderNode<R> {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    readonly auth?: AuthConfig;
+    readonly folders: readonly FolderNode<R>[];
+    readonly requests: readonly R[];
+}
+/** What one directory of an API's request tree holds. */
+export interface FolderContents<R> {
+    readonly folders: FolderNode<R>[];
+    readonly requests: R[];
+}
+/**
+ * Reads one `*.request.yaml` of a tree into a request of the API's protocol, claiming the files it
+ * owns (its own, and its body file) out of `unclaimed` so they are not reported as orphans.
+ */
+export type RequestReader<R> = (dir: string, fileName: string, unclaimed: Set<string>) => Promise<R>;
+/**
+ * Loads one directory of an API's request tree: its `*.request.yaml` files as requests (through
+ * the protocol's reader), its subdirectories as folders, recursively.
+ *
+ * A directory with no `folder.yaml` is still a folder — named after the directory, ordered after
+ * the ones that do have a file, and given a file of its own on the next save — because a folder
+ * someone created with `mkdir` in a checked-out project is a folder, not a fault. A directory
+ * deeper than {@link MAX_FOLDER_DEPTH} becomes a problem and is skipped whole, so nothing is ever
+ * written to a path that might not open on Windows.
+ */
+export declare function loadFolderContents<R extends {
+    readonly order: number;
+    readonly name: string;
+}>(fs: FsLike, root: string, dir: string, depth: number, problems: ProjectProblem[], readRequest: RequestReader<R>, folderExtra?: (document: unknown, relative: string) => Record<string, unknown>): Promise<FolderContents<R>>;

package/dist/project/load-helpers.js

@@ -0,0 +1,177 @@
+/**
+ * What core's loader and every protocol's `storage.load` share when they read a project folder:
+ * YAML from a relative path, the `undefined`-dropping helpers, authentication as loaded, a
+ * request's scripts, and the request tree an API (of any protocol) and the webhook collection keep
+ * under `requests/`.
+ *
+ * A protocol's storage imports this file and never `load.ts`, which imports the protocols.
+ */
+import { join } from 'node:path';
+import { scriptFileName } from '../script/model.js';
+import { SCRIPT_LIMITS } from '../script/sandbox/model.js';
+import { readFileIfExists, readdirIfExists } from './fs.js';
+import { FOLDER_FILE, MAX_FOLDER_DEPTH, REQUEST_SUFFIX } from './paths.js';
+import { parseFile, restFolderFileSchema } from './schema-parts.js';
+import { parseYaml } from './yaml.js';
+/** The absolute path of a `/`-separated path relative to the project root. */
+export function abs(root, relative) {
+    return join(root, ...relative.split('/'));
+}
+/** Reads and parses one YAML file of the project; undefined when the file does not exist. */
+export async function readYaml(fs, root, relative) {
+    const buffer = await readFileIfExists(fs, abs(root, relative));
+    return buffer === undefined ? undefined : parseYaml(buffer.toString('utf8'), relative);
+}
+/** Orders entities by their persisted `order`, falling back to a stable name comparison. */
+export function byOrder(a, b) {
+    return a.order - b.order || a.name.localeCompare(b.name);
+}
+/** `{ [key]: value }`, or nothing at all when the value is undefined (`exactOptionalPropertyTypes`). */
+export function optional(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/**
+ * Drops `undefined`-valued keys from a zod result, so an absent optional field
+ * is truly absent rather than present-and-undefined (`exactOptionalPropertyTypes`).
+ */
+export function exact(value) {
+    const out = {};
+    for (const key of Object.keys(value)) {
+        const entry = value[key];
+        if (entry !== undefined) {
+            out[key] = entry;
+        }
+    }
+    return out;
+}
+/**
+ * A request's scripts and the text of each script file (#63). The file read is always the name
+ * derived from the slug, never the one the request file records. A missing or oversized file is a
+ * problem on the request; an oversized one keeps its text so a save writes it back untouched.
+ */
+export async function loadScripts(fs, root, dir, slug, document, requestName, problems, claim) {
+    if (document === undefined) {
+        return undefined;
+    }
+    const read = async (phase) => {
+        if ((phase === 'pre' ? document.pre : document.post) === undefined) {
+            return undefined;
+        }
+        const name = scriptFileName(slug, phase, document.api);
+        claim(name);
+        const relative = `${dir}/${name}`;
+        const buffer = await readFileIfExists(fs, abs(root, relative));
+        if (buffer === undefined) {
+            problems.push({
+                code: 'script-file-missing',
+                message: `Request "${requestName}" names a ${phase === 'pre' ? 'pre-request' : 'post-response'} script whose file is missing`,
+                file: relative,
+            });
+            return { text: '', problem: 'script-file-missing' };
+        }
+        const text = buffer.toString('utf8');
+        if (buffer.byteLength > SCRIPT_LIMITS.fileBytes) {
+            problems.push({
+                code: 'script-too-large',
+                message: `Request "${requestName}" has a script over ${String(SCRIPT_LIMITS.fileBytes / 1024)} KiB, which will not run`,
+                file: relative,
+            });
+            return { text, problem: 'script-too-large' };
+        }
+        return { text };
+    };
+    const pre = await read('pre');
+    const post = await read('post');
+    return {
+        ...(pre !== undefined ? { pre } : {}),
+        ...(post !== undefined ? { post } : {}),
+        api: document.api,
+        enabled: document.enabled,
+        secrets: [...document.secrets],
+        ...(document.timeoutMs !== undefined ? { timeoutMs: document.timeoutMs } : {}),
+    };
+}
+/**
+ * Authentication as loaded: the same `undefined`-key drop {@link exact} performs, expressed
+ * separately because `AuthConfig` is a union and so has no single mapped shape to hand `exact`.
+ * The cast is safe for the same reason `exact`'s is: the schema has already established the
+ * arm's own fields, and this only removes keys whose value is absent.
+ */
+export function authConfig(parsed) {
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * A definition's fetch credentials as loaded, through {@link authConfig}. `definitionAuthSchema` has
+ * already refused every scheme but Basic, Bearer and API key, so the narrowing cast only restates
+ * what parsing proved.
+ */
+export function definitionAuth(parsed) {
+    return parsed === undefined ? undefined : authConfig(parsed);
+}
+/** A table row as loaded: `enabled` defaults to true, an absent description stays absent. */
+export function keyValueEntries(rows) {
+    return rows.map((row) => exact({ name: row.name, value: row.value, enabled: row.enabled, description: row.description }));
+}
+/**
+ * Loads one directory of an API's request tree: its `*.request.yaml` files as requests (through
+ * the protocol's reader), its subdirectories as folders, recursively.
+ *
+ * A directory with no `folder.yaml` is still a folder — named after the directory, ordered after
+ * the ones that do have a file, and given a file of its own on the next save — because a folder
+ * someone created with `mkdir` in a checked-out project is a folder, not a fault. A directory
+ * deeper than {@link MAX_FOLDER_DEPTH} becomes a problem and is skipped whole, so nothing is ever
+ * written to a path that might not open on Windows.
+ */
+export async function loadFolderContents(fs, root, dir, depth, problems, readRequest, folderExtra) {
+    const entries = await readdirIfExists(fs, abs(root, dir));
+    const unclaimed = new Set(entries.filter((e) => e.isFile && e.name !== FOLDER_FILE).map((e) => e.name));
+    const requests = [];
+    const folders = [];
+    for (const entry of [...entries].sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isFile && entry.name.endsWith(REQUEST_SUFFIX)) {
+            requests.push(await readRequest(dir, entry.name, unclaimed));
+            continue;
+        }
+        if (!entry.isDirectory) {
+            continue;
+        }
+        const childDir = `${dir}/${entry.name}`;
+        if (depth + 1 > MAX_FOLDER_DEPTH) {
+            problems.push({
+                code: 'folder-too-deep',
+                message: `Folder "${entry.name}" is nested more than ${String(MAX_FOLDER_DEPTH)} deep and was skipped`,
+                file: childDir,
+            });
+            continue;
+        }
+        const contents = await loadFolderContents(fs, root, childDir, depth + 1, problems, readRequest, folderExtra);
+        const relative = `${childDir}/${FOLDER_FILE}`;
+        const document = await readYaml(fs, root, relative);
+        const parsed = document === undefined ? undefined : parseFile(restFolderFileSchema, document, relative);
+        folders.push({
+            id: parsed?.id ?? `folder:${entry.name}`,
+            name: parsed?.name ?? entry.name,
+            slug: entry.name,
+            order: parsed?.order ?? Number.MAX_SAFE_INTEGER,
+            ...optional('description', parsed?.description),
+            ...(parsed?.auth !== undefined ? { auth: authConfig(parsed.auth) } : {}),
+            folders: contents.folders,
+            requests: contents.requests,
+            ...(folderExtra?.(document, relative) ?? {}),
+        });
+    }
+    for (const orphan of [...unclaimed].sort()) {
+        problems.push({
+            code: 'orphan-request-file',
+            message: `"${orphan}" does not belong to any request`,
+            file: `${dir}/${orphan}`,
+        });
+    }
+    return { folders: folders.sort(byOrder), requests: requests.sort(byOrder) };
+}

package/dist/project/load.d.ts

@@ -7,9 +7,14 @@
  * recoverable inconsistency (an orphaned envelope, an operation folder no
  * interface declares) becomes a {@link ProjectProblem} rather than an error, so
  * a slightly damaged project still opens.
+ *
+ * Core reads the manifest, environments, sequences, keystores, WS-Security references and the
+ * webhook collection. A container is read by its protocol's `storage.load` (`soap/storage.ts`,
+ * `rest/storage.ts`, `grpc/storage.ts`, `ws/storage.ts`), found through the registry.
  */
-import type { Project } from './model.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
 import type { FsLike } from './fs.js';
+import type { Project } from './model.js';
 /** A recoverable inconsistency found while loading a project. */
 export interface ProjectProblem {
     readonly code: 'missing-envelope' | 'orphan-operation-folder' | 'orphan-request-file' | 'missing-interface-file'
@@ -20,10 +25,24 @@ export interface ProjectProblem {
     /** A folder nested deeper than {@link MAX_FOLDER_DEPTH}; it and everything below it is skipped. */
      | 'folder-too-deep'
     /** An API and an interface sharing a slug, which would make an endpoint override ambiguous. */
-     | 'api-slug-conflict';
+     | 'api-slug-conflict'
+    /** A sequence file that is malformed, over a limit, or not a sequence; it is skipped and left as it is. */
+     | 'sequence-file-invalid'
+    /** A sequence file written by a newer build; it is skipped and left as it is. */
+     | 'sequence-version-too-new'
+    /** A sequence file whose id another file already has; it is skipped and left as it is. */
+     | 'sequence-duplicate-id'
+    /** A script the request names whose file is gone; the request refuses to send until it is back (#63). */
+     | 'script-file-missing'
+    /** A script file over the size limit; kept as it is, and the request refuses to send (#63). */
+     | 'script-too-large'
+    /** A container whose kind has no enabled module; it is a placeholder and is left as it is (spec §6). */
+     | 'container-unsupported';
     readonly message: string;
     /** Path relative to the project root. */
     readonly file: string;
+    /** For `container-unsupported`: `kind`, `reason`, `dir` and `slug`. */
+    readonly details?: Readonly<Record<string, unknown>>;
 }
 /** The result of {@link loadProject}: the model plus anything odd about the folder. */
 export interface LoadResult {
@@ -33,12 +52,19 @@ export interface LoadResult {
 /** Options for {@link loadProject}. */
 export interface LoadProjectOptions {
     readonly fs?: FsLike;
+    /** The protocols the project may hold. Defaults to the built-in ones, all switched on. */
+    readonly registry?: ProtocolRegistry;
 }
 /**
- * Loads the project stored in the directory `root`.
+ * Loads the project stored in the directory `root`. Each container directory under `interfaces/`
+ * and `apis/` is read by the protocol module its container file's `kind` names (spec §5.1). A
+ * container whose kind has no enabled module in that directory becomes a placeholder in
+ * `project.unsupported` and a `container-unsupported` problem; nothing below its directory is read
+ * but its container file, and a save leaves all of it as it is (spec §6).
  *
  * @throws ProjectError `project-not-found` when there is no `wirebench.yaml`,
  * `project-format-too-new` for a newer format version, `project-file-invalid`
- * for malformed or schema-violating YAML (with the offending file in `details`).
+ * for malformed or schema-violating YAML (with the offending file in `details`),
+ * `project-kind-not-supported` for a request file of a kind this build has no module for.
  */
 export declare function loadProject(root: string, options?: LoadProjectOptions): Promise<LoadResult>;