@graphty/graph-io 0.3.47 → 0.3.49

package/src/sources/cypher/transports/neptune-https.ts

@@ -0,0 +1,122 @@
+/**
+ * The `neptune-https` transport (design section 12.4): Neptune Database's `POST /openCypher`
+ * (port 8182, TLS only), form fields `query` and `parameters`, signed with `credentials.awsSigV4`
+ * (service "neptune-db") or unsigned inside the VPC. Node only: Neptune Database sends no CORS
+ * headers, so a browser is refused before any request (E_SOURCE_RUNTIME, reason "cors").
+ *
+ * An error after the first chunk of a 200 answer is appended to the body; the tail is read for it.
+ */
+
+import { originOf } from "../../credentials.js";
+import { failOn } from "../../fail.js";
+import { type SourceContext } from "../../types.js";
+import { type QueryResult } from "../flatten.js";
+import { type CypherProfile, neptuneProfile } from "../profiles.js";
+import { fromNeptune } from "../types-map.js";
+import { objectRows, parseJson, serverError, type Transport, type TransportInput } from "./transport.js";
+
+/** Neptune's error body. */
+interface NeptuneError {
+    readonly code?: string;
+    readonly detailedMessage?: string;
+    readonly message?: string;
+}
+
+/**
+ * Refuse a Neptune transport where it cannot run.
+ * @param ctx - the context
+ * @param transport - the transport name
+ */
+export function nodeOnly(ctx: SourceContext, transport: string): void {
+    if (ctx.runtime === "browser" || ctx.runtime === "worker") {
+        failOn(ctx.report, "E_SOURCE_RUNTIME", `the ${transport} transport cannot run in a browser`, {
+            runtime: ctx.runtime,
+            reason: "cors",
+        });
+    }
+}
+
+/**
+ * The error a body ends with, when a 200 answer was cut short by one.
+ * @param text - the body
+ * @returns the error, or null
+ */
+function trailingError(text: string): NeptuneError | null {
+    for (let at = text.lastIndexOf("{"); at > 0; at = text.lastIndexOf("{", at - 1)) {
+        const tail = parseJson(text.slice(at)) as NeptuneError | null;
+        if (tail !== null && typeof tail.code === "string") {
+            return tail;
+        }
+    }
+    return null;
+}
+
+/**
+ * Turn a Neptune answer into a result, or raise its error.
+ * @param input - the transport input
+ * @param response - the answer
+ * @returns the mapped result
+ */
+export async function neptuneResult(input: TransportInput, response: Response): Promise<QueryResult> {
+    const { ctx, m } = input;
+    const origin = ctx.endpoint === null ? "" : originOf(ctx.endpoint);
+    const text = await response.text();
+    const body = parseJson(text) as ({ results?: readonly Record<string, unknown>[] } & NeptuneError) | null;
+    let error: NeptuneError | null = typeof body?.code === "string" ? body : null;
+    if (body === null) {
+        error = trailingError(text);
+    }
+    if (error !== null) {
+        serverError(
+            ctx.report,
+            {
+                code: error.code ?? null,
+                message: error.detailedMessage ?? error.message ?? "",
+                status: response.status,
+                showable: body !== null && response.status >= 400 && response.status < 500,
+            },
+            origin,
+            undefined,
+        );
+    }
+    if (!response.ok) {
+        failOn(ctx.report, "E_FETCH", `${origin} answered ${String(response.status)}`, {
+            url: origin,
+            status: response.status,
+        });
+    }
+    if (body === null || !Array.isArray(body.results)) {
+        failOn(ctx.report, "E_SOURCE_RESPONSE", "the Neptune answer has no results", {
+            expected: "json",
+            contentType: response.headers.get("content-type"),
+        });
+    }
+    return objectRows(body.results, (v, column) => fromNeptune(v, column, m));
+}
+
+/**
+ * Make the transport.
+ * @param input - the context, params and mapper
+ * @returns the transport
+ */
+export function neptuneHttpsTransport(input: TransportInput): Transport {
+    const { ctx } = input;
+    nodeOnly(ctx, "neptune-https");
+    return {
+        async run(statement, parameters): Promise<QueryResult> {
+            const response = await ctx.fetch("openCypher", {
+                method: "POST",
+                idempotent: true,
+                allowStatus: [400, 500],
+                body: new URLSearchParams({ query: statement, parameters: JSON.stringify(parameters) }),
+            });
+            return neptuneResult(input, response);
+        },
+        profile: () => Promise.resolve(neptuneProfile()),
+        probe: async (): Promise<CypherProfile> => {
+            const status = await ctx.fetchJson<{ dbEngineVersion?: string }>("status");
+            return neptuneProfile(typeof status.dbEngineVersion === "string" ? status.dbEngineVersion : null);
+        },
+        close: () => Promise.resolve(),
+    };
+}

package/src/sources/cypher/transports/query-api.ts

@@ -0,0 +1,100 @@
+/**
+ * The `query-api` transport (design section 12.2): Neo4j's `POST /db/{database}/query/v2`, on by
+ * default since Neo4j 5.26 and on Aura, with no driver. It asks for typed JSON, so integers keep
+ * every digit, and sends `accessMode: "Read"`, which the server enforces. CORS is open by default,
+ * so it works from a page on https.
+ */
+
+import { originOf } from "../../credentials.js";
+import { failOn } from "../../fail.js";
+import { type QueryResult } from "../flatten.js";
+import { type CypherProfile, neo4jProfile } from "../profiles.js";
+import { fromTypedJson } from "../types-map.js";
+import { parseJson, serverError, type Transport, type TransportInput } from "./transport.js";
+
+/** The media type of Neo4j's typed JSON. */
+const TYPED_JSON = "application/vnd.neo4j.query.v1.1";
+
+/** The statuses whose JSON body says what went wrong. */
+const ERROR_STATUSES = [400, 404, 500];
+
+/** The shape of a Query API answer. */
+interface QueryApiBody {
+    readonly data?: { readonly fields: readonly string[]; readonly values: readonly (readonly unknown[])[] };
+    readonly errors?: readonly { readonly code?: string; readonly message?: string }[];
+}
+
+/**
+ * Make the transport.
+ * @param input - the context, params and mapper
+ * @returns the transport
+ */
+export function queryApiTransport(input: TransportInput): Transport {
+    const { ctx, params, m } = input;
+    const database = params.database ?? "neo4j";
+    const path = `db/${encodeURIComponent(database)}/query/v2`;
+    const origin = ctx.endpoint === null ? "" : originOf(ctx.endpoint);
+
+    const run = async (statement: string, parameters: Readonly<Record<string, unknown>>): Promise<QueryResult> => {
+        const response = await ctx.fetch(path, {
+            method: "POST",
+            idempotent: true,
+            allowStatus: ERROR_STATUSES,
+            headers: { "Content-Type": "application/json", Accept: TYPED_JSON },
+            body: JSON.stringify({ statement, parameters, accessMode: "Read" }),
+        });
+        const body = parseJson(await response.text()) as QueryApiBody | null;
+        const first = body?.errors?.[0];
+        if (first !== undefined) {
+            serverError(
+                ctx.report,
+                {
+                    code: first.code ?? null,
+                    message: first.message ?? "",
+                    status: response.status,
+                    showable: response.status >= 400 && response.status < 500,
+                },
+                origin,
+                params.database,
+            );
+        }
+        if (response.status === 404) {
+            // no Query API here: a Neo4j before 5.26 answers 404, and speaks only Bolt
+            failOn(ctx.report, "E_SOURCE_NOT_FOUND", `${origin} has no Query API at ${path}`, {
+                what: "url",
+                value: `${origin}/${path}`,
+            });
+        }
+        if (!response.ok) {
+            failOn(ctx.report, "E_FETCH", `${origin} answered ${String(response.status)}`, {
+                url: `${origin}/${path}`,
+                status: response.status,
+            });
+        }
+        if (body?.data === undefined) {
+            failOn(ctx.report, "E_SOURCE_RESPONSE", "the Query API answer has no data", {
+                expected: "json",
+                contentType: response.headers.get("content-type"),
+            });
+        }
+        const { fields, values } = body.data;
+        return { fields, rows: values.map((row) => row.map((v, i) => fromTypedJson(v, fields[i] ?? "", m))) };
+    };
+
+    return {
+        run,
+        // the Query API exists from Neo4j 5.26, so ids are elementId()
+        profile: () => Promise.resolve(neo4jProfile(null)),
+        probe: async (): Promise<CypherProfile> => {
+            const res = await run(
+                "CALL dbms.components() YIELD name, versions, edition RETURN name, versions, edition",
+                {},
+            );
+            const kernel = res.rows.find((r) => r[0] === "Neo4j Kernel") ?? res.rows[0];
+            const versions = kernel?.[1];
+            const version = Array.isArray(versions) && typeof versions[0] === "string" ? versions[0] : null;
+            return neo4jProfile(version);
+        },
+        close: () => Promise.resolve(),
+    };
+}

package/src/sources/cypher/transports/transport.ts

@@ -0,0 +1,139 @@
+/**
+ * What every Cypher transport is (design section 12.2): something that runs one statement with
+ * its parameters and returns mapped rows, knows the server's profile, and closes. Also the one
+ * place a server's own error code becomes a source issue code.
+ */
+
+import { type ImportReportBuilder } from "../../../common/report.js";
+import { failOn } from "../../fail.js";
+import { type SourceContext } from "../../types.js";
+import { type QueryResult } from "../flatten.js";
+import { type CypherParams } from "../params.js";
+import { type CypherProfile } from "../profiles.js";
+import { type MapContext } from "../types-map.js";
+
+/** One way a Cypher statement travels to a server. Internal. */
+export interface Transport {
+    /**
+     * Run one read-only statement.
+     * @param statement - the statement
+     * @param parameters - its parameters, sent separately
+     * @returns the mapped result
+     */
+    run(statement: string, parameters: Readonly<Record<string, unknown>>): Promise<QueryResult>;
+    /**
+     * The server's profile, detected once.
+     * @returns the profile
+     */
+    profile(): Promise<CypherProfile>;
+    /**
+     * The server facts `probe` reports, which may cost a request.
+     * @returns the profile with its version filled in where the server says it
+     */
+    probe(): Promise<CypherProfile>;
+    /** Release the connection. */
+    close(): Promise<void>;
+}
+
+/** What a transport is made from. */
+export interface TransportInput {
+    /** The load's context. */
+    readonly ctx: SourceContext;
+    /** The params, with defaults. */
+    readonly params: CypherParams;
+    /** The type mapper's context. */
+    readonly m: MapContext;
+}
+
+/** The longest server message a report keeps. */
+const MAX_SERVER_MESSAGE = 500;
+
+/** What a server said about a failed statement. */
+interface ServerError {
+    /** The service's own code, or null. */
+    readonly code: string | null;
+    /** Its message, or "". */
+    readonly message: string;
+    /** The HTTP status, or null over Bolt. */
+    readonly status: number | null;
+    /** Whether the message came from a JSON 4xx body (or a Bolt client error), so a report may keep it. */
+    readonly showable: boolean;
+}
+
+/**
+ * Raise the source issue a server error is: a login failure, a refusal, a server timeout, a
+ * missing database, or E_SOURCE_QUERY with the line and column the message names.
+ * @param report - the load's report
+ * @param err - what the server said
+ * @param origin - the origin that answered
+ * @param database - the database asked for, if any
+ * @returns never; it throws
+ */
+export function serverError(
+    report: ImportReportBuilder,
+    err: ServerError,
+    origin: string,
+    database: string | undefined,
+): never {
+    const code = err.code ?? "";
+    if (/Security\.Unauthorized|AuthenticationRateLimit|UnauthorizedException/i.test(code)) {
+        return failOn(report, "E_SOURCE_AUTH", `${origin} refused the login`, {
+            origin,
+            status: err.status,
+            scheme: null,
+            serverCode: err.code,
+        });
+    }
+    if (/Security\.Forbidden|AccessMode|AccessDenied/i.test(code)) {
+        return failOn(report, "E_SOURCE_FORBIDDEN", `${origin} refused the statement`, {
+            status: err.status,
+            serverCode: err.code,
+        });
+    }
+    if (/TimedOut|Timeout|TimeLimitExceeded/i.test(code)) {
+        return failOn(report, "E_SOURCE_TIMEOUT", `${origin} timed the statement out`, {
+            timeoutMs: null,
+            serverSide: true,
+        });
+    }
+    if (/DatabaseNotFound/i.test(code)) {
+        return failOn(report, "E_SOURCE_NOT_FOUND", `${origin} has no database ${String(database)}`, {
+            what: "database",
+            value: database ?? null,
+        });
+    }
+    const where = /line (\d+), column (\d+)/i.exec(err.message);
+    return failOn(report, "E_SOURCE_QUERY", `${origin} refused the query: ${code}`, {
+        serverCode: err.code,
+        line: where === null ? null : Number(where[1]),
+        column: where === null ? null : Number(where[2]),
+        serverMessage: err.showable && err.message !== "" ? err.message.slice(0, MAX_SERVER_MESSAGE) : null,
+    });
+}
+
+/**
+ * The value of a response body as JSON, or null when it is not JSON.
+ * @param text - the body
+ * @returns the parsed value, or null
+ */
+export function parseJson(text: string): unknown {
+    try {
+        return JSON.parse(text) as unknown;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The fields and rows of a result given as one object per row (Neptune's `results`).
+ * @param results - the row objects
+ * @param map - maps one value, given its column
+ * @returns the result
+ */
+export function objectRows(
+    results: readonly Readonly<Record<string, unknown>>[],
+    map: (v: unknown, column: string) => unknown,
+): QueryResult {
+    const fields = [...new Set(results.flatMap((r) => Object.keys(r)))];
+    return { fields, rows: results.map((r) => fields.map((f) => map(r[f], f))) };
+}