Skip to content

Build your personal knowledge base with Trilium Notes

15.0 KB
Raw Blame
import { Writable } from "node:stream";

import { HttpError } from "../errors";
import type { ResponseLocals } from "../http_interface";
import * as routes from "../routes";
import { getContext } from "../services/context";
import entityChanges from "../services/entity_changes";
import { getSql } from "../services/sql/index";

/**
 * In-process, transport-agnostic test driver for the **shared core API routes**
 * (the ones registered by `routes.buildSharedApiRoutes`). Think of it as
 * "supertest for core": it drives the exact same handlers that the Express
 * server (`apps/server`) and the standalone browser router
 * (`apps/standalone/.../browser_routes.ts`) expose, but without an HTTP server,
 * Express, or a socket — so the same spec runs under **both** the node
 * (better-sqlite3) and the standalone (sql.js WASM) test suites.
 *
 * It exercises the real request lifecycle around each handler:
 *   - path/param + query parsing (Express-style `:param`)
 *   - the execution context (cls) and SQL transaction wrapping
 *   - `convertEntitiesToPojo` + the `[statusCode, body]` / `undefined → 204`
 *     result-handler conventions
 *   - `HttpError` → status mapping (404 / 400 / 403 …)
 *   - JSON round-tripping of the response body (so e.g. dates surface as the
 *     strings an HTTP client would actually receive)
 *
 * It deliberately does **not** run the platform middleware (auth, CSRF, rate
 * limiting, multipart parsing) — those are server/Express concerns and are
 * covered by the supertest specs in `apps/server`. Auth/CSRF are treated as
 * always-passing here, mirroring the standalone browser adapter.
 */

type HttpMethod = "get" | "post" | "put" | "patch" | "delete";

type Handler = (req: ApiRequest, res?: MockResponse) => unknown;
type ResultHandler = (req: ApiRequest, res: CaptureResponse, result: unknown) => void;

interface ApiRequest {
    params: Record<string, string>;
    query: Record<string, string | undefined>;
    body: unknown;
    headers: Record<string, string>;
    method: string;
    file?: unknown;
    originalUrl: string;
    /** Express-style case-insensitive header accessor (used by e.g. the sync routes). */
    get(name: string): string | undefined;
}

interface RegisteredRoute {
    method: string;
    pattern: RegExp;
    paramNames: string[];
    run: (req: ApiRequest) => Promise<TestResponse>;
}

export interface TestResponse<T = unknown> {
    status: number;
    headers: Record<string, string>;
    body: T;
    /** The file a handler asked Express to send rather than write itself, if it did. */
    sentFile?: string;
    /** What an `apiRoute` handler left in `res.locals`. */
    locals?: ResponseLocals;
}

export interface RequestOptions {
    body?: unknown;
    query?: Record<string, string | number | boolean | undefined>;
    headers?: Record<string, string>;
    /**
     * A fake uploaded file, mirroring the `req.file` that the Express multipart
     * middleware would populate. Lets handlers that read `req.file` (image
     * update, import) be exercised in-process without a real multipart request.
     */
    file?: unknown;
}

function pathToRegex(path: string): { pattern: RegExp; paramNames: string[] } {
    const paramNames: string[] = [];
    // Drop a trailing slash from the registered path and allow an optional one
    // when matching, mirroring Express's default (non-strict) routing — several
    // core routes are registered with a trailing slash (e.g. /api/attribute-names/).
    const normalized = path.replace(/\/$/, "");
    const regexPattern = normalized
        .replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
        .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName) => {
            paramNames.push(paramName);
            return "([^/]+)";
        });
    return { pattern: new RegExp(`^${regexPattern}\\/?$`), paramNames };
}

function jsonRoundTrip(value: unknown): unknown {
    if (value === undefined || typeof value === "string") {
        return value;
    }
    return JSON.parse(JSON.stringify(value));
}

/** Mirrors the server's `apiResultHandler` / browser `formatResult` conventions. */
function formatApiResult(result: unknown): TestResponse {
    const headers: Record<string, string> = {
        "trilium-max-entity-change-id": String(entityChanges.getMaxEntityChangeId())
    };
    const pojo = routes.convertEntitiesToPojo(result);

    if (Array.isArray(pojo) && pojo.length > 0 && Number.isInteger(pojo[0])) {
        const [ status, response ] = pojo as [number, unknown];
        return { status, headers, body: jsonRoundTrip(response) };
    }
    if (pojo === undefined) {
        return { status: 204, headers, body: undefined };
    }
    return { status: 200, headers, body: jsonRoundTrip(pojo) };
}

/** Captures what a result handler writes, for the `route(..., resultHandler)` path. */
interface CaptureResponse {
    captured?: TestResponse;
    setHeader(name: string, value: string): void;
}

/** Preserves strings and raw bytes as-is; JSON round-trips everything else. */
function normalizeResponseBody(body: unknown): unknown {
    if (body === undefined || typeof body === "string") {
        return body;
    }
    if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
        return Buffer.from(body as Uint8Array);
    }
    return jsonRoundTrip(body);
}

/**
 * A faithful in-process stand-in for the Express `res` that handlers write to
 * directly (image routes, file downloads, the streaming export). It extends a
 * Node {@link Writable} so the **server** export path works exactly as in
 * production — `archive.pipe(res)` with the `archiver` package needs a real
 * writable stream — while also supporting the **browser** export path, where
 * `BrowserZipArchive.finalize()` calls `res.send(zipBytes)` (and falls back to
 * `res.write()`/`res.end()`). Both vitest suites (server + standalone) run on
 * Node, so a real stream is available under either runtime.
 *
 * On top of the stream it exposes the small Express surface the handlers use
 * and captures a `{ status, headers, body }` snapshot, keeping the body as raw
 * bytes for streamed/binary responses so tests can inspect them.
 */
class MockResponse extends Writable {

    used = false;
    statusCode = 200;
    headers: Record<string, string> = {};
    locals: ResponseLocals = {};

    sentFile?: string;

    private chunks: Buffer[] = [];
    private sendBody: unknown;
    private hasSendBody = false;

    status(code: number) { this.statusCode = code; return this; }
    set(name: string, value: string) { this.headers[name] = value; return this; }
    setHeader(name: string, value: string) { this.headers[name] = value; return this; }
    removeHeader(name: string) { delete this.headers[name]; return this; }
    send(body: unknown) { this.used = true; this.hasSendBody = true; this.sendBody = body; return this; }
    /**
     * Express sends the file itself from here, so nothing passes through this object. Recorded
     * rather than read, which is the whole point of a handler choosing this over `send`.
     */
    download(filePath: string, fileName?: string) {
        this.used = true;
        this.sentFile = filePath;
        this.headers["Content-Disposition"] = `attachment; filename="${fileName ?? filePath}"`;
        return this;
    }
    json(body: unknown) { return this.send(body); }
    sendStatus(code: number) { this.used = true; this.statusCode = code; return this; }

    override _write(chunk: Buffer | Uint8Array | string, _encoding: BufferEncoding, callback: (error?: Error | null) => void) {
        this.used = true;
        this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
        callback();
    }

    snapshot(): TestResponse {
        let body: unknown;
        if (this.chunks.length > 0) {
            body = Buffer.concat(this.chunks);
        } else if (this.hasSendBody) {
            body = normalizeResponseBody(this.sendBody);
        }
        return { status: this.statusCode, headers: this.headers, body, sentFile: this.sentFile };
    }

}

function createMockResponse(): MockResponse {
    return new MockResponse();
}

export class CoreApiTester {

    private routes: RegisteredRoute[] = [];

    private add(method: string, path: string, run: (req: ApiRequest) => Promise<TestResponse>) {
        const { pattern, paramNames } = pathToRegex(path);
        this.routes.push({ method: method.toUpperCase(), pattern, paramNames, run });
    }

    /** Builds a tester with every shared core route registered. */
    static build(): CoreApiTester {
        const tester = new CoreApiTester();
        tester.registerAll();
        return tester;
    }

    private registerAll() {
        const apiRoute = (method: HttpMethod, path: string, handler: Handler) =>
            this.add(method, path, async (req) => {
                const mockRes = createMockResponse();
                const result = await getContext().init(() => {
                    seedContext(req);
                    return getSql().transactional(() => handler(req, mockRes));
                });
                return { ...formatApiResult(result), locals: mockRes.locals };
            });

        const asyncApiRoute = (method: HttpMethod, path: string, handler: Handler) =>
            this.add(method, path, async (req) => {
                const result = await getContext().init(async () => {
                    seedContext(req);
                    return await handler(req);
                });
                return formatApiResult(result);
            });

        const buildRoute = (transactional: boolean) =>
            (
                method: HttpMethod,
                path: string,
                _mw: unknown[],
                handler: Handler,
                resultHandler?: ResultHandler | null
            ) =>
                this.add(method, path, async (req) => {
                    const mockRes = createMockResponse();
                    const invoke = () => handler(req, mockRes);
                    const result = transactional
                        ? await getContext().init(() => {
                            seedContext(req);
                            return getSql().transactional(invoke);
                        })
                        : await getContext().init(async () => {
                            seedContext(req);
                            return await invoke();
                        });

                    if (mockRes.used) {
                        return mockRes.snapshot();
                    }
                    if (resultHandler) {
                        const captureHeaders: Record<string, string> = {};
                        const capture: CaptureResponse = {
                            setHeader(name, value) { captureHeaders[name] = value; }
                        };
                        resultHandler(req, capture, result);
                        const base = capture.captured ?? formatApiResult(result);
                        return { ...base, headers: { ...captureHeaders, ...base.headers } };
                    }
                    return formatApiResult(result);
                });

        const apiResultHandler: ResultHandler = (_req, res, result) => {
            res.captured = formatApiResult(result);
        };
        const noop = () => {};

        routes.buildSharedApiRoutes({
            route: buildRoute(true),
            asyncRoute: buildRoute(false),
            asyncRouteWithoutTransaction: buildRoute(false),
            apiRoute,
            asyncApiRoute,
            apiResultHandler,
            checkApiAuth: noop,
            checkApiAuthOrElectron: noop,
            checkAppNotInitialized: noop,
            checkSetupAuth: noop,
            checkCredentials: noop,
            loginRateLimiter: noop,
            uploadMiddlewareWithErrorHandling: noop,
            importMiddlewareWithErrorHandling: noop,
            csrfMiddleware: noop
        });
    }

    async request<T = unknown>(
        method: HttpMethod,
        path: string,
        opts: RequestOptions = {}
    ): Promise<TestResponse<T>> {
        const url = new URL(path, "http://core.test");
        for (const [ key, value ] of Object.entries(opts.query ?? {})) {
            if (value !== undefined) {
                url.searchParams.set(key, String(value));
            }
        }

        const query: Record<string, string | undefined> = {};
        for (const [ key, value ] of url.searchParams) {
            query[key] = value;
        }

        const upperMethod = method.toUpperCase();
        for (const route of this.routes) {
            if (route.method !== upperMethod) {
                continue;
            }
            const match = url.pathname.match(route.pattern);
            if (!match) {
                continue;
            }

            const params: Record<string, string> = {};
            route.paramNames.forEach((name, i) => {
                params[name] = decodeURIComponent(match[i + 1]);
            });

            const headers = opts.headers ?? {};
            const lowerHeaders: Record<string, string> = {};
            for (const [ key, value ] of Object.entries(headers)) {
                lowerHeaders[key.toLowerCase()] = value;
            }

            const req: ApiRequest = {
                params,
                query,
                body: opts.body,
                headers,
                method: upperMethod,
                originalUrl: url.pathname + url.search,
                file: opts.file,
                get: (name: string) => lowerHeaders[name.toLowerCase()]
            };

            try {
                return (await route.run(req)) as TestResponse<T>;
            } catch (e) {
                const status = e instanceof HttpError ? e.statusCode : 500;
                const message = e instanceof Error ? e.message : String(e);
                return { status, headers: {}, body: { message } as T };
            }
        }

        const message = `No route for ${upperMethod} ${url.pathname}`;
        return { status: 404, headers: {}, body: { message } as T };
    }

    get<T = unknown>(path: string, opts?: RequestOptions) {
        return this.request<T>("get", path, opts);
    }

    post<T = unknown>(path: string, opts?: RequestOptions) {
        return this.request<T>("post", path, opts);
    }

    put<T = unknown>(path: string, opts?: RequestOptions) {
        return this.request<T>("put", path, opts);
    }

    patch<T = unknown>(path: string, opts?: RequestOptions) {
        return this.request<T>("patch", path, opts);
    }

    delete<T = unknown>(path: string, opts?: RequestOptions) {
        return this.request<T>("delete", path, opts);
    }

}

/**
 * Seeds the execution context from the `trilium-*` request headers, the way both real adapters do
 * (`route_api.ts` on Express, `browser_routes.ts` in standalone). Routes that read the hoisted note
 * through `cls.getHoistedNoteId()` need this to see anything other than "root".
 */
function seedContext(req: ApiRequest) {
    const ctx = getContext();
    ctx.set("componentId", req.get("trilium-component-id"));
    ctx.set("localNowDateTime", req.get("trilium-local-now-datetime"));
    ctx.set("hoistedNoteId", req.get("trilium-hoisted-note-id") || "root");
}