@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261019175049

package/src/test/msw/handlers.ts

@@ -0,0 +1,350 @@
+import { http, HttpResponse, type HttpHandler, type JsonBodyType } from "msw";
+
+import type { AnyRecord } from "@/types/anyRecord";
+import type { WorkerExecution } from "@/types/workflow";
+
+import { applyListQuery, applyTextSearch, QueryError } from "./query";
+import { parsedQuery, pathOf } from "./recorder";
+import { complete, newId, nowSeconds, type FakeApiStore } from "./store";
+
+export type Failure = { method: string; path: string; status: number; message: string };
+
+/** What the handlers read and write: the store, and the failures queued. */
+export type FakeState = {
+    store: () => FakeApiStore;
+    takeFailure: (method: string, path: string) => Failure | undefined;
+};
+
+type Answer = { status?: number; json: JsonBodyType };
+
+type Context = { url: URL; path: string; segments: string[]; body: unknown };
+
+/** The page size a text-query list answers with when none is given. Source: `ConfigDefaults.py`. */
+const TEXT_PAGE_SIZE = 10;
+
+export const errorBody = (status: number, message: string) => ({ code: status, message });
+
+const notFound = (entity: string, id: string): Answer => ({
+    status: 404,
+    json: errorBody(404, `${entity} ${id} not found`),
+});
+
+/**
+ * Wraps a responder: answers with a failure the test queued for the request,
+ * with the API's error body when the responder throws a `QueryError`, or with what it returns.
+ */
+const answering =
+    (state: FakeState, respond: (context: Context) => Answer) =>
+    async ({ request }: { request: Request }) => {
+        const url = new URL(request.url);
+        const path = pathOf(url);
+        const method = request.method.toUpperCase();
+        const body = ["POST", "PUT"].includes(method)
+            ? await request.json().catch(() => undefined)
+            : undefined;
+
+        const failure = state.takeFailure(method, path);
+        let answer: Answer;
+        if (failure) {
+            answer = { status: failure.status, json: errorBody(failure.status, failure.message) };
+        } else {
+            try {
+                answer = respond({ url, path, segments: path.split("/").filter(Boolean), body });
+            } catch (error) {
+                if (!(error instanceof QueryError)) throw error;
+                answer = { status: error.status, json: errorBody(error.status, error.message) };
+            }
+        }
+        return HttpResponse.json(answer.json, { status: answer.status ?? 200 });
+    };
+
+/** A page of a text-query list: the URL's `page_size` (10 by default) and `page_token`. */
+const textPage = (records: AnyRecord[], url: URL) => {
+    const offset = Number(url.searchParams.get("page_token") ?? 0);
+    const end = offset + Number(url.searchParams.get("page_size") ?? TEXT_PAGE_SIZE);
+    return {
+        page: records.slice(offset, end),
+        nextPageToken: end < records.length ? String(end) : null,
+    };
+};
+
+type JsonQueryEntity = {
+    /** The URL segment and the list's key: `datastores`. */
+    plural: "datastores" | "files" | "portfolios";
+    /** A single record's key: `datastore`. */
+    singular: string;
+    /** For error messages: `Datastore`. */
+    label: string;
+    create: (record: AnyRecord) => AnyRecord;
+    /** What a read by id answers, given the URL: a file leaves its data out on `with_data=false`. */
+    read?: (record: AnyRecord, url: URL) => AnyRecord;
+};
+
+/**
+ * The five routes of an entity listed by JSON query: list, read, create, update and delete,
+ * each answered from the store with the API's envelopes — the plural key with
+ * `next_page_token` for a list, the singular key for one record, and a delete by id answering
+ * one `{ id, name, deleted }`.
+ */
+const jsonQueryEntity = (state: FakeState, entity: JsonQueryEntity): HttpHandler[] => {
+    const { plural, singular, label } = entity;
+    const records = () => state.store()[plural] as unknown as AnyRecord[];
+    const replace = (next: AnyRecord[]) => {
+        (state.store() as unknown as Record<string, AnyRecord[]>)[plural] = next;
+    };
+
+    return [
+        http.get(
+            `*/api/${plural}`,
+            answering(state, ({ url }) => {
+                const query = parsedQuery(url.searchParams.get("query"));
+                if (typeof query === "object") {
+                    const { page, nextPageToken } = applyListQuery(records(), query, {
+                        pageSize: url.searchParams.get("page_size"),
+                        pageToken: url.searchParams.get("page_token"),
+                    });
+                    return { json: { [plural]: page, next_page_token: nextPageToken } };
+                }
+                const { page, nextPageToken } = textPage(
+                    applyTextSearch(records(), query ?? ""),
+                    url,
+                );
+                return { json: { [plural]: page, next_page_token: nextPageToken } };
+            }),
+        ),
+        http.get(
+            `*/api/${plural}/:id`,
+            answering(state, ({ url, segments }) => {
+                const id = segments[1] ?? "";
+                if (url.searchParams.get("workspace") === "") {
+                    return { status: 403, json: errorBody(403, "An empty workspace is refused.") };
+                }
+                const found = records().find((r) => r.id === id);
+                if (!found) return notFound(label, id);
+                return { json: { [singular]: entity.read ? entity.read(found, url) : found } };
+            }),
+        ),
+        http.post(
+            `*/api/${plural}`,
+            answering(state, ({ body }) => {
+                const now = nowSeconds();
+                const created = entity.create({
+                    ...(body as AnyRecord),
+                    id: undefined,
+                    created: now,
+                    updated: now,
+                });
+                records().push(created);
+                return { json: { [singular]: created } };
+            }),
+        ),
+        http.put(
+            `*/api/${plural}/:id`,
+            answering(state, ({ segments, body }) => {
+                const id = segments[1] ?? "";
+                const index = records().findIndex((r) => r.id === id);
+                if (index === -1) return notFound(label, id);
+                const updated = {
+                    ...records()[index],
+                    ...(body as AnyRecord),
+                    id,
+                    updated: nowSeconds(),
+                };
+                records()[index] = updated;
+                return { json: { [singular]: updated } };
+            }),
+        ),
+        http.delete(
+            `*/api/${plural}/:id`,
+            answering(state, ({ segments }) => {
+                const id = segments[1] ?? "";
+                const found = records().find((r) => r.id === id);
+                if (!found) return notFound(label, id);
+                replace(records().filter((r) => r.id !== id));
+                return { json: { [singular]: { id, name: found.name, deleted: true } } };
+            }),
+        ),
+    ];
+};
+
+/**
+ * Worker executions as `GET /workflows/:id/worker_executions` groups them: one group per worker,
+ * in the order the workers first appear, a worker with several runs as a parallel group.
+ */
+const groupWorkerExecutions = (executions: WorkerExecution[]) => {
+    const byWorker = new Map<string, WorkerExecution[]>();
+    for (const execution of executions) {
+        byWorker.set(execution.worker_id, [
+            ...(byWorker.get(execution.worker_id) ?? []),
+            execution,
+        ]);
+    }
+    const groups = [...byWorker.values()].map((runs) => {
+        const base = { worker_id: runs[0]!.worker_id, worker_name: runs[0]!.worker_name };
+        return runs.length > 1
+            ? { ...base, is_parallel_execution: true, executions: runs }
+            : { ...base, is_parallel_execution: false, execution: runs[0] };
+    });
+    const parallel = [...byWorker.values()].filter((runs) => runs.length > 1);
+    return {
+        worker_executions: groups,
+        parallel_index_max:
+            parallel.length > 0 ? Math.max(...parallel.map((r) => r.length - 1)) : -1,
+    };
+};
+
+const workflowHandlers = (state: FakeState): HttpHandler[] => [
+    // The workflow list takes only a text search, under the `workspace` it is given.
+    http.get(
+        "*/api/workflows",
+        answering(state, ({ url }) => {
+            const workspace = url.searchParams.get("workspace") ?? "main";
+            const inWorkspace = state.store().workflows.filter((w) => w.workspace === workspace);
+            const { page, nextPageToken } = textPage(
+                applyTextSearch(inWorkspace, url.searchParams.get("query") ?? ""),
+                url,
+            );
+            return { json: { workflows: page, next_page_token: nextPageToken } };
+        }),
+    ),
+    http.get(
+        "*/api/workflows/:id",
+        answering(state, ({ segments }) => {
+            const id = segments[1] ?? "";
+            const found = state.store().workflows.find((w) => w.id === id);
+            return found ? { json: { workflow: found } } : notFound("Workflow", id);
+        }),
+    ),
+    // 202 with the execution it started, still RUNNING, and a `result` that is always null.
+    http.post(
+        "*/api/workflows/:id/run",
+        answering(state, ({ segments, body }) => {
+            const id = segments[1] ?? "";
+            const workflow = state.store().workflows.find((w) => w.id === id);
+            if (!workflow) return notFound("Workflow", id);
+            const now = nowSeconds();
+            const execution = complete.workflowExecution({
+                id: newId("wfex"),
+                workflow_id: id,
+                workflow_name: workflow.name,
+                workspace: (body as AnyRecord | undefined)?.workspace ?? workflow.workspace,
+                status: "RUNNING",
+                run_status: "RUNNING",
+                started: now,
+                created: now,
+                updated: now,
+            });
+            state.store().workflowExecutions.push(execution);
+            return { status: 202, json: { workflow_execution: execution, result: null } };
+        }),
+    ),
+    // Ignores a JSON query: reads `workflow_execution_id`, `worker_id`, `page_size` and
+    // `page_token` from the URL. With `workflow_execution_id` it answers that one execution.
+    http.get(
+        "*/api/workflows/:id/workflow_executions",
+        answering(state, ({ url, segments }) => {
+            const workflowId = segments[1] ?? "";
+            const executions = state
+                .store()
+                .workflowExecutions.filter((e) => e.workflow_id === workflowId);
+            const executionId = url.searchParams.get("workflow_execution_id");
+            if (executionId) {
+                const found = executions.find((e) => e.id === executionId);
+                return found
+                    ? { json: { workflow_execution: found } }
+                    : notFound("Workflow execution", executionId);
+            }
+            const workerId = url.searchParams.get("worker_id");
+            const ran = workerId
+                ? executions.filter((e) =>
+                      state
+                          .store()
+                          .workerExecutions.some(
+                              (w) => w.workflow_execution_id === e.id && w.worker_id === workerId,
+                          ),
+                  )
+                : executions;
+            const { page, nextPageToken } = textPage(ran, url);
+            return { json: { workflow_executions: page, next_page_token: nextPageToken } };
+        }),
+    ),
+    // Not paginated. With `worker_execution_id` it answers that one run; with
+    // `workflow_execution_id`, every worker of that execution, grouped.
+    http.get(
+        "*/api/workflows/:id/worker_executions",
+        answering(state, ({ url, segments }) => {
+            const workflowId = segments[1] ?? "";
+            const runs = state.store().workerExecutions.filter((w) => w.workflow_id === workflowId);
+            const workerExecutionId = url.searchParams.get("worker_execution_id");
+            if (workerExecutionId) {
+                const found = runs.find((w) => w.id === workerExecutionId);
+                return found
+                    ? { json: { worker_execution: found } }
+                    : notFound("Worker execution", workerExecutionId);
+            }
+            const executionId = url.searchParams.get("workflow_execution_id");
+            return {
+                json: groupWorkerExecutions(
+                    runs.filter((w) => w.workflow_execution_id === executionId),
+                ),
+            };
+        }),
+    ),
+];
+
+const workspaceHandlers = (state: FakeState): HttpHandler[] => [
+    http.get(
+        "*/api/workspaces",
+        answering(state, ({ url }) => {
+            const { page, nextPageToken } = textPage(
+                applyTextSearch(state.store().workspaces, url.searchParams.get("query") ?? ""),
+                url,
+            );
+            return { json: { workspaces: page, next_page_token: nextPageToken } };
+        }),
+    ),
+    // A workspace is identified by its name.
+    http.get(
+        "*/api/workspaces/:name",
+        answering(state, ({ segments }) => {
+            const name = decodeURIComponent(segments[1] ?? "");
+            const found = state.store().workspaces.find((w) => w.name === name);
+            return found ? { json: { workspace: found } } : notFound("Workspace", name);
+        }),
+    ),
+];
+
+/** Every route the SDK's request functions call. */
+export const fakeApiHandlers = (state: FakeState): HttpHandler[] => [
+    ...jsonQueryEntity(state, {
+        plural: "datastores",
+        singular: "datastore",
+        label: "Datastore",
+        create: (r) => complete.datastore(r),
+    }),
+    ...jsonQueryEntity(state, {
+        plural: "files",
+        singular: "file",
+        label: "File",
+        create: (r) => complete.file({ ...r, hash: undefined, url: undefined }),
+        read: (file, url) =>
+            url.searchParams.get("with_data") === "false" ? { ...file, data: null } : file,
+    }),
+    ...jsonQueryEntity(state, {
+        plural: "portfolios",
+        singular: "portfolio",
+        label: "Portfolio",
+        create: (r) => complete.portfolio(r),
+    }),
+    ...workflowHandlers(state),
+    ...workspaceHandlers(state),
+    // An app-only route; the SDK reads only `profile` from it.
+    http.get(
+        "*/api/profile",
+        answering(state, () => ({ json: { status: "OK", profile: state.store().profile } })),
+    ),
+    http.get(
+        "*/api/websockets_config",
+        answering(state, () => ({ json: state.store().websocketsConfig })),
+    ),
+];

package/src/test/msw/index.ts

@@ -0,0 +1,9 @@
+// `@everysk/apps-sdk/test/msw` — a fake of the API behind `/api`, for an app's tests.
+//
+// Its own subpath because `msw` is an optional peer: an app that only renders components with
+// `@everysk/apps-sdk/test` does not need it installed.
+
+export * from "./fakeApi";
+export type { RecordedRequest } from "./recorder";
+export type { FakeApiSeed, FakeApiStore } from "./store";
+export type { ListQuery } from "./query";

package/src/test/msw/query.ts

@@ -0,0 +1,134 @@
+import type { AnyRecord } from "@/types/anyRecord";
+import type { FilterOperator } from "@/types/entityQuery";
+
+/** The JSON query a list read sends in `?query=`, as `buildQueryObject` writes it. */
+export type ListQuery = {
+    filters?: unknown[][];
+    order?: string[];
+    projection?: string | string[];
+    page_size?: number;
+    page_token?: string;
+};
+
+/** The page size a JSON-query list answers with when none is given. Source: `ConfigDefaults.py`. */
+const DEFAULT_PAGE_SIZE = 20;
+
+const compare = (a: unknown, b: unknown): number => {
+    if (a === b) return 0;
+    if (a === undefined || a === null) return -1;
+    if (b === undefined || b === null) return 1;
+    return (a as string | number) < (b as string | number) ? -1 : 1;
+};
+
+/**
+ * Each operator the SDK can send, as the API applies it. Keyed by `FilterOperator`, so an
+ * operator added to the SDK does not compile until the fake knows it, rather than failing inside
+ * an app's test.
+ */
+const OPERATORS: Record<FilterOperator, (actual: unknown, value: unknown) => boolean> = {
+    "=": (actual, value) => actual === value,
+    "!=": (actual, value) => actual !== value,
+    ">": (actual, value) => compare(actual, value) > 0,
+    ">=": (actual, value) => compare(actual, value) >= 0,
+    "<": (actual, value) => compare(actual, value) < 0,
+    "<=": (actual, value) => compare(actual, value) <= 0,
+    IN: (actual, value) => Array.isArray(value) && value.includes(actual),
+    NOT_IN: (actual, value) => Array.isArray(value) && !value.includes(actual),
+};
+
+const isOperator = (op: unknown): op is FilterOperator =>
+    typeof op === "string" && Object.hasOwn(OPERATORS, op);
+
+/** A filter tuple as the API reads it: two items are `=`, three name the operator. */
+const matches = (record: AnyRecord, tuple: unknown[]): boolean => {
+    const [field, op, value] = tuple.length === 2 ? [tuple[0], "=", tuple[1]] : tuple;
+    if (!isOperator(op)) throw new QueryError(`Unknown filter operator: ${String(op)}`);
+
+    return OPERATORS[op](record[field as string], value);
+};
+
+/** A query the API refuses: the handler answers it with the API's error body and status. */
+export class QueryError extends Error {
+    status: number;
+
+    constructor(message: string, status = 400) {
+        super(message);
+        this.name = "QueryError";
+        this.status = status;
+    }
+}
+
+const ordered = (records: AnyRecord[], order: string[] = []): AnyRecord[] =>
+    [...records].sort((a, b) => {
+        for (const key of order) {
+            const desc = key.startsWith("-");
+            const field = desc ? key.slice(1) : key;
+            const result = compare(a[field], b[field]);
+            if (result !== 0) return desc ? -result : result;
+        }
+        return 0;
+    });
+
+/**
+ * One field or an array, never a comma-joined string, and never inclusions mixed with
+ * exclusions: the API answers both with a 500 (`_normalize_projection`).
+ */
+const project = (records: AnyRecord[], projection?: string | string[]): AnyRecord[] => {
+    if (projection === undefined || projection === "") return records;
+    const fields = Array.isArray(projection) ? projection : [projection];
+    if (fields.some((f) => f.includes(","))) {
+        throw new QueryError("A projection is one field or an array, not a list in a string.", 500);
+    }
+    const excluded = fields.filter((f) => f.startsWith("-")).map((f) => f.slice(1));
+    if (excluded.length > 0 && excluded.length < fields.length) {
+        throw new QueryError("A projection cannot mix inclusions with exclusions.", 500);
+    }
+
+    return records.map((record) =>
+        excluded.length > 0
+            ? Object.fromEntries(Object.entries(record).filter(([k]) => !excluded.includes(k)))
+            : Object.fromEntries(
+                  Object.entries(record).filter(([k]) => k === "id" || fields.includes(k)),
+              ),
+    );
+};
+
+/**
+ * applyListQuery — a JSON-query list read, as the API answers it: the query's filters (the
+ * `workspace` URL parameter is ignored on this path), its order and projection, and a page.
+ * The URL's `page_size` and `page_token` win over the query's.
+ *
+ * The page token is an offset here, opaque to the caller as the API's is.
+ */
+export const applyListQuery = (
+    records: AnyRecord[],
+    query: ListQuery,
+    url: { pageSize?: string | null; pageToken?: string | null } = {},
+): { page: AnyRecord[]; nextPageToken: string | null } => {
+    const filtered = records.filter((record) =>
+        (query.filters ?? []).every((tuple) => matches(record, tuple)),
+    );
+    const sorted = ordered(filtered, query.order);
+
+    const pageSize = Number(url.pageSize ?? query.page_size ?? DEFAULT_PAGE_SIZE);
+    const offset = Number(url.pageToken ?? query.page_token ?? 0);
+    const end = offset + pageSize;
+
+    return {
+        page: project(sorted.slice(offset, end), query.projection),
+        nextPageToken: end < sorted.length ? String(end) : null,
+    };
+};
+
+/**
+ * A text search, the other form a list's `query` takes: an id, `#tag`, `&link_uid`, or a name
+ * prefix. The workflow and workspace lists take only this form.
+ */
+export const applyTextSearch = (records: AnyRecord[], text: string): AnyRecord[] => {
+    if (text === "") return records;
+    if (text.startsWith("#")) {
+        return records.filter((r) => Array.isArray(r.tags) && r.tags.includes(text.slice(1)));
+    }
+    if (text.startsWith("&")) return records.filter((r) => r.link_uid === text.slice(1));
+    return records.filter((r) => r.id === text || String(r.name ?? "").startsWith(text));
+};

package/src/test/msw/recorder.ts

@@ -0,0 +1,88 @@
+import type { SetupServer } from "msw/node";
+
+import type { ListQuery } from "./query";
+
+/** A request the app sent, as a test asserts on it. */
+export type RecordedRequest = {
+    method: string;
+    /** After `/api`: `/datastores`, `/datastores/dats_1`. */
+    path: string;
+    /** The URL's parameters other than `query`. */
+    params: Record<string, string>;
+    /** The `query` parameter, parsed when it is a JSON query; a text search stays a string. */
+    query?: ListQuery | string;
+    body?: unknown;
+    /** `0` for a network error a handler answered with `HttpResponse.error()`. */
+    status: number;
+};
+
+const API_PATH = /^.*?\/api(?=\/)/;
+
+export const pathOf = (url: URL) => url.pathname.replace(API_PATH, "");
+
+export const parsedQuery = (raw: string | null): ListQuery | string | undefined => {
+    if (raw === null) return undefined;
+    try {
+        const parsed: unknown = JSON.parse(raw);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? (parsed as ListQuery)
+            : raw;
+    } catch {
+        return raw;
+    }
+};
+
+const parsedBody = (text: string): unknown => {
+    if (text === "") return undefined;
+    try {
+        return JSON.parse(text);
+    } catch {
+        return text;
+    }
+};
+
+/**
+ * Records every request to `/api` the server answers, from MSW's own events rather than from the
+ * fake's handlers: a handler a test adds with `server.use` answers in their place, and a request
+ * it answered went missing from the log, as if the page had never sent it.
+ *
+ * The body is read from a clone taken when the request starts, before a handler consumes it. The
+ * entry is logged when the response goes out, in the order the responses do.
+ *
+ * @param {SetupServer} server - The server whose requests to record.
+ * @param {() => RecordedRequest[]} log - The current log; a getter, as it is replaced per test.
+ */
+export const recordRequests = (server: SetupServer, log: () => RecordedRequest[]) => {
+    const started = new Map<string, RecordedRequest>();
+
+    server.events.on("request:start", ({ request, requestId }) => {
+        const url = new URL(request.url);
+        if (!API_PATH.test(url.pathname)) return;
+
+        const entry: RecordedRequest = {
+            method: request.method.toUpperCase(),
+            path: pathOf(url),
+            params: Object.fromEntries([...url.searchParams].filter(([key]) => key !== "query")),
+            query: parsedQuery(url.searchParams.get("query")),
+            body: undefined,
+            status: 0,
+        };
+        started.set(requestId, entry);
+        if (["POST", "PUT", "PATCH"].includes(entry.method)) {
+            void request
+                .clone()
+                .text()
+                .then((text) => {
+                    entry.body = parsedBody(text);
+                });
+        }
+    });
+
+    server.events.on("response:mocked", ({ response, requestId }) => {
+        const entry = started.get(requestId);
+        if (!entry) return;
+        started.delete(requestId);
+        entry.status = response.status;
+        log().push(entry);
+    });
+};