envio 3.7.0 → 3.9.0-resolvers.0

package/src/resolvers/graphqlSelection.js

@@ -0,0 +1,292 @@
+// Recovers a resolver's selection tree from the operation text Hasura sends.
+//
+// Hasura hands an action handler `request_query`, the raw GraphQL document,
+// and nothing else about what the caller asked for -- there is no parsed
+// selection in the payload. A resolver that skips expensive work when a field
+// is not requested therefore needs the document read back, which is what this
+// does: names and nesting, aliases resolved to the declared name, fragments
+// inlined, which is the same shape envio-serve resolves against the output
+// type.
+//
+// The selection is an optimisation and never correctness -- a resolver that
+// ignores it is still right, only slower. So every failure here answers with an
+// empty tree, which means "assume everything was asked for", and no request is
+// ever refused because its query could not be read.
+
+// A document this size is not a client query. Bailing keeps a pathological
+// body from being lexed token by token before the request is answered.
+const MAX_QUERY_BYTES = 128 * 1024;
+
+const NAME_START = /[_A-Za-z]/;
+const NAME_CHAR = /[_0-9A-Za-z]/;
+const DIGIT = /[0-9]/;
+
+const PUNCTUATORS = new Set(["!", "$", "&", "(", ")", ":", "=", "@", "[", "]", "{", "|", "}"]);
+
+// Lexed, so a brace inside a string argument is a character and not structure.
+function lex(source) {
+  const tokens = [];
+  let i = 0;
+  const length = source.length;
+
+  while (i < length) {
+    const char = source[i];
+
+    if (char === "" || char === " " || char === "\t" || char === "\n" || char === "\r" || char === ",") {
+      i += 1;
+      continue;
+    }
+
+    if (char === "#") {
+      while (i < length && source[i] !== "\n" && source[i] !== "\r") i += 1;
+      continue;
+    }
+
+    if (char === "." && source.startsWith("...", i)) {
+      tokens.push({ kind: "...", value: "..." });
+      i += 3;
+      continue;
+    }
+
+    if (PUNCTUATORS.has(char)) {
+      tokens.push({ kind: char, value: char });
+      i += 1;
+      continue;
+    }
+
+    if (NAME_START.test(char)) {
+      let end = i + 1;
+      while (end < length && NAME_CHAR.test(source[end])) end += 1;
+      tokens.push({ kind: "name", value: source.slice(i, end) });
+      i = end;
+      continue;
+    }
+
+    if (char === '"') {
+      if (source.startsWith('"""', i)) {
+        let end = i + 3;
+        while (end < length) {
+          if (source[end] === "\\" && source.startsWith('\\"""', end)) {
+            end += 4;
+            continue;
+          }
+          if (source.startsWith('"""', end)) break;
+          end += 1;
+        }
+        if (end >= length) throw new Error("Unterminated block string");
+        tokens.push({ kind: "value", value: source.slice(i, end + 3) });
+        i = end + 3;
+        continue;
+      }
+      let end = i + 1;
+      while (end < length && source[end] !== '"') {
+        end += source[end] === "\\" ? 2 : 1;
+      }
+      if (end >= length) throw new Error("Unterminated string");
+      tokens.push({ kind: "value", value: source.slice(i, end + 1) });
+      i = end + 1;
+      continue;
+    }
+
+    if (DIGIT.test(char) || (char === "-" && DIGIT.test(source[i + 1] ?? ""))) {
+      let end = i + 1;
+      while (end < length && /[0-9eE.+-]/.test(source[end])) end += 1;
+      tokens.push({ kind: "value", value: source.slice(i, end) });
+      i = end;
+      continue;
+    }
+
+    throw new Error(`Unexpected character '${char}'`);
+  }
+
+  return tokens;
+}
+
+const OPERATIONS = new Set(["query", "mutation", "subscription"]);
+
+class Parser {
+  constructor(tokens) {
+    this.tokens = tokens;
+    this.at = 0;
+    this.fragments = new Map();
+    this.operations = [];
+  }
+
+  peek(offset = 0) {
+    return this.tokens[this.at + offset];
+  }
+
+  next() {
+    const token = this.tokens[this.at];
+    if (token === undefined) throw new Error("Unexpected end of document");
+    this.at += 1;
+    return token;
+  }
+
+  expect(kind) {
+    const token = this.next();
+    if (token.kind !== kind) throw new Error(`Expected ${kind}, found ${token.kind}`);
+    return token;
+  }
+
+  parseDocument() {
+    while (this.at < this.tokens.length) {
+      const token = this.peek();
+      if (token.kind === "{") {
+        this.operations.push(this.parseSelectionSet());
+      } else if (token.kind === "name" && OPERATIONS.has(token.value)) {
+        this.next();
+        if (this.peek()?.kind === "name") this.next();
+        this.skipParens();
+        this.skipDirectives();
+        this.operations.push(this.parseSelectionSet());
+      } else if (token.kind === "name" && token.value === "fragment") {
+        this.next();
+        const name = this.expect("name").value;
+        this.expect("name"); // `on`
+        this.parseTypeCondition();
+        this.skipDirectives();
+        this.fragments.set(name, this.parseSelectionSet());
+      } else {
+        throw new Error(`Unexpected ${token.kind} at top level`);
+      }
+    }
+    return this;
+  }
+
+  // A type condition is a single name, but `[T!]!`-shaped tokens appear in
+  // variable definitions handled by skipParens, so only the name form is here.
+  parseTypeCondition() {
+    this.expect("name");
+  }
+
+  skipParens() {
+    if (this.peek()?.kind !== "(") return;
+    let depth = 0;
+    do {
+      const token = this.next();
+      if (token.kind === "(") depth += 1;
+      else if (token.kind === ")") depth -= 1;
+      else if (token.kind === "{") depth += 1;
+      else if (token.kind === "}") depth -= 1;
+    } while (depth > 0);
+  }
+
+  skipDirectives() {
+    while (this.peek()?.kind === "@") {
+      this.next();
+      this.expect("name");
+      this.skipParens();
+    }
+  }
+
+  parseSelectionSet() {
+    this.expect("{");
+    const selections = [];
+    while (this.peek()?.kind !== "}") {
+      selections.push(this.parseSelection());
+    }
+    this.expect("}");
+    return selections;
+  }
+
+  parseSelection() {
+    if (this.peek().kind === "...") {
+      this.next();
+      const token = this.peek();
+      if (token?.kind === "name" && token.value !== "on") {
+        this.next();
+        this.skipDirectives();
+        return { kind: "spread", name: token.value };
+      }
+      if (token?.kind === "name") {
+        this.next();
+        this.parseTypeCondition();
+      }
+      this.skipDirectives();
+      return { kind: "inline", selections: this.parseSelectionSet() };
+    }
+
+    let name = this.expect("name").value;
+    if (this.peek()?.kind === ":") {
+      // An alias renames the field for the caller; the resolver only knows the
+      // name it declared, so the alias is dropped rather than reported.
+      this.next();
+      name = this.expect("name").value;
+    }
+    this.skipParens();
+    this.skipDirectives();
+    const selections = this.peek()?.kind === "{" ? this.parseSelectionSet() : null;
+    return { kind: "field", name, selections };
+  }
+}
+
+function collectFields(selections, fragments, seenFragments, into) {
+  for (const selection of selections) {
+    if (selection.kind === "field") {
+      if (selection.name === "__typename") continue;
+      const existing = into[selection.name] ?? {};
+      into[selection.name] = existing;
+      if (selection.selections !== null) {
+        collectFields(selection.selections, fragments, seenFragments, existing);
+      }
+    } else if (selection.kind === "inline") {
+      collectFields(selection.selections, fragments, seenFragments, into);
+    } else if (!seenFragments.has(selection.name)) {
+      const fragment = fragments.get(selection.name);
+      if (fragment !== undefined) {
+        seenFragments.add(selection.name);
+        collectFields(fragment, fragments, seenFragments, into);
+        seenFragments.delete(selection.name);
+      }
+    }
+  }
+  return into;
+}
+
+function findField(selections, fragments, fieldName, seenFragments, into) {
+  for (const selection of selections) {
+    if (selection.kind === "field") {
+      if (selection.name === fieldName && selection.selections !== null) {
+        collectFields(selection.selections, fragments, new Set(), into);
+      } else if (selection.selections !== null) {
+        findField(selection.selections, fragments, fieldName, seenFragments, into);
+      }
+    } else if (selection.kind === "inline") {
+      findField(selection.selections, fragments, fieldName, seenFragments, into);
+    } else if (!seenFragments.has(selection.name)) {
+      const fragment = fragments.get(selection.name);
+      if (fragment !== undefined) {
+        seenFragments.add(selection.name);
+        findField(fragment, fragments, fieldName, seenFragments, into);
+        seenFragments.delete(selection.name);
+      }
+    }
+  }
+  return into;
+}
+
+/**
+ * The selection tree for `fieldName`, as names and nesting.
+ *
+ * Hasura sends no operation name, so a document with more than one operation
+ * cannot be narrowed to the one that ran. Every field of that name is merged
+ * instead: a superset means a resolver does work it could have skipped, where
+ * a subset would have it skip work that was asked for.
+ */
+export function selectionFromRequestQuery(requestQuery, fieldName) {
+  if (typeof requestQuery !== "string" || requestQuery.length === 0) return {};
+  if (requestQuery.length > MAX_QUERY_BYTES) return {};
+  try {
+    const document = new Parser(lex(requestQuery)).parseDocument();
+    return findField(
+      document.operations.flat(),
+      document.fragments,
+      fieldName,
+      new Set(),
+      {}
+    );
+  } catch {
+    return {};
+  }
+}

package/src/resolvers/hasuraAction.js

@@ -0,0 +1,84 @@
+// Hasura's action contract, translated to and from the dispatcher's.
+//
+// The two differ in the ways that matter to a client. Hasura splices the
+// response body straight in as the field's value, so a result is returned bare
+// rather than under `data`, and a failure is a status code rather than an
+// `errors` array -- a 200 is taken as success whatever the body says.
+//
+// Pure, so the mapping is testable without a socket; `server.js` does the I/O.
+
+// Hasura documents 4xx as *the* way a handler reports failure. A 5xx risks
+// being reported as an unreachable webhook instead of the message below, so a
+// resolver's intended status travels in `extensions.http.status` and every
+// error leaves here as a 4xx.
+const STATUS_BY_CODE = {
+  BAD_REQUEST: 400,
+  BAD_USER_INPUT: 400,
+  FORBIDDEN: 403,
+  RESOLVER_NOT_FOUND: 404,
+};
+
+const DEFAULT_ERROR_STATUS = 400;
+
+import { selectionFromRequestQuery } from "./graphqlSelection.js";
+
+const isPlainObject = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Validates a decoded action payload.
+ * Returns null when it is well formed.
+ */
+export function badActionRequest(payload) {
+  if (!isPlainObject(payload)) {
+    return "expected a JSON object";
+  }
+  if (!isPlainObject(payload.action) || typeof payload.action.name !== "string" || payload.action.name.length === 0) {
+    return "`action.name` must be a non-empty string";
+  }
+  if (payload.input !== undefined && !isPlainObject(payload.input)) {
+    return "`input` must be an object";
+  }
+  if (payload.session_variables !== undefined && !isPlainObject(payload.session_variables)) {
+    return "`session_variables` must be an object";
+  }
+  return null;
+}
+
+/**
+ * Turns a validated action payload into the dispatcher's request.
+ *
+ * `requestId` is minted by the caller: Hasura sends none, and without one a
+ * failure in the logs cannot be tied back to the request that caused it.
+ */
+export function toResolveRequest(payload, requestId) {
+  const role = payload.session_variables?.["x-hasura-role"];
+  return {
+    field: payload.action.name,
+    args: payload.input ?? {},
+    selection: selectionFromRequestQuery(payload.request_query, payload.action.name),
+    // Hasura roles are arbitrary strings, and the dispatcher's are not. Only
+    // `admin` grants admin, so an unrecognised role is treated as public
+    // rather than rejected -- the same answer an anonymous caller would get.
+    role: role === "admin" ? "admin" : "public",
+    requestId,
+  };
+}
+
+/** Turns a dispatcher answer into the status and body Hasura expects. */
+export function toActionResponse(answer) {
+  const failure = answer.errors?.[0];
+  if (failure !== undefined) {
+    const extensions = failure.extensions ?? {};
+    return {
+      status: STATUS_BY_CODE[extensions.code] ?? DEFAULT_ERROR_STATUS,
+      body: { message: failure.message, extensions },
+    };
+  }
+  return { status: 200, body: answer.data ?? null };
+}
+
+/** The error body for a request that never reached the dispatcher. */
+export function actionErrorBody(message, code) {
+  return { message, extensions: { code } };
+}

package/src/resolvers/hasuraApply.js

@@ -0,0 +1,323 @@
+// Puts the resolver metadata into Hasura, and keeps it there.
+//
+// Applying is a read then, only if something differs, one write. The write
+// reloads Hasura's schema cache, so a re-assert that fired every minute
+// regardless would disrupt a busy Hasura sixty times an hour to change nothing.
+//
+// Re-asserting at all is not defensive. `Hasura.trackDatabase` opens with a
+// wholesale `clear_metadata`, so any re-initialised indexer silently deletes
+// these actions while this service keeps running and Hasura keeps answering
+// that the field does not exist.
+
+// Hasura's own defaults, applied when reading its metadata back: `export_metadata`
+// omits whatever matches them, so a comparison against what we sent has to put
+// them back or every read reports drift.
+const DEFAULT_TIMEOUT_SECONDS = 30;
+
+// Well inside the 60s re-assert interval: an apply that outlived that would
+// have the loop skip ticks it can never catch up on.
+const DEFAULT_METADATA_TIMEOUT_MS = 30_000;
+
+const byName = (a, b) => a.name.localeCompare(b.name);
+
+function normaliseAction(action) {
+  const definition = action.definition ?? {};
+  return {
+    comment: action.comment ?? null,
+    // Absent means mutation, which is never what a resolver wants -- so an
+    // action missing it is drift, not a match.
+    type: definition.type ?? "mutation",
+    kind: definition.kind ?? "synchronous",
+    handler: definition.handler ?? null,
+    output_type: definition.output_type ?? null,
+    timeout: definition.timeout ?? DEFAULT_TIMEOUT_SECONDS,
+    arguments: (definition.arguments ?? []).map((argument) => ({
+      name: argument.name,
+      type: argument.type,
+    })),
+  };
+}
+
+const normaliseFields = (types = []) =>
+  types
+    .map((type) => ({
+      name: type.name,
+      fields: (type.fields ?? []).map((field) => ({ name: field.name, type: field.type })),
+    }))
+    .sort(byName);
+
+function normaliseCustomTypes(customTypes = {}) {
+  return {
+    scalars: (customTypes.scalars ?? []).map(({ name }) => ({ name })).sort(byName),
+    enums: (customTypes.enums ?? [])
+      .map((type) => ({
+        name: type.name,
+        // Hasura hands enum values back with a null description and
+        // is_deprecated it was never given.
+        values: (type.values ?? []).map(({ value }) => value),
+      }))
+      .sort(byName),
+    input_objects: normaliseFields(customTypes.input_objects),
+    objects: normaliseFields(customTypes.objects),
+  };
+}
+
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+const actionArgs = (action) => ({
+  name: action.name,
+  ...(action.comment === undefined ? {} : { comment: action.comment }),
+  definition: action.definition,
+});
+
+/**
+ * The single metadata call that moves Hasura from `exported` to `metadata`,
+ * and the reasons it is needed. `bulk` is null when nothing differs.
+ *
+ * `healOnly` restricts it to restoring what has been *deleted*, leaving
+ * anything that merely differs alone. A rolling update runs two versions at
+ * once: the new one updates the actions to its definitions, and a periodic
+ * re-assert that called that drift would write the old ones straight back,
+ * flapping the published schema until the rollout finished. Reconciling
+ * definitions is startup's job, where only one version is speaking.
+ */
+export function planApply(metadata, exported, { healOnly = false } = {}) {
+  const current = new Map((exported?.actions ?? []).map((action) => [action.name, action]));
+
+  if (healOnly) {
+    const wanted = metadata.actions;
+    // Only a Hasura holding *none* of ours is the `clear_metadata` this heals.
+    // Some present and some not is what a newer deployment looks like mid-roll:
+    // it renamed one, and restoring our whole set over it would trade the
+    // published schema back and forth for the length of the rollout. A single
+    // action dropped by hand is therefore not healed until the next start,
+    // which is the price of never fighting a deployment that is ahead of us.
+    if (wanted.length === 0 || wanted.some((action) => current.has(action.name))) {
+      return { bulk: null, reasons: [] };
+    }
+  }
+
+  const desired = new Map(metadata.actions.map((action) => [action.name, action]));
+  const desiredRoles = new Map(metadata.actions.map((action) => [action.name, new Set()]));
+  for (const permission of metadata.permissions) {
+    desiredRoles.get(permission.action)?.add(permission.role);
+  }
+
+  const reasons = [];
+  const drops = [];
+  const writes = [];
+  const permissionDrops = [];
+  const permissionCreates = [];
+
+  for (const [name, action] of current) {
+    if (!desired.has(name)) {
+      // Left in place, Hasura keeps publishing a field whose handler no longer
+      // knows the name -- every call to it fails at the resolver instead of
+      // being absent from the schema. This service is the only thing that
+      // creates actions on an indexer's Hasura, so an action it does not
+      // declare is one it removed.
+      reasons.push(`action '${name}' is no longer declared`);
+      drops.push({ type: "drop_action", args: { name } });
+    }
+  }
+
+  for (const [name, action] of desired) {
+    const existing = current.get(name);
+    if (existing === undefined) {
+      reasons.push(`action '${name}' is missing`);
+      writes.push({ type: "create_action", args: actionArgs(action) });
+    } else if (!same(normaliseAction(existing), normaliseAction(action))) {
+      reasons.push(`action '${name}' differs`);
+      writes.push({ type: "update_action", args: actionArgs(action) });
+    }
+
+    const wanted = desiredRoles.get(name) ?? new Set();
+    const held = new Set((existing?.permissions ?? []).map((permission) => permission.role));
+    for (const role of held) {
+      if (!wanted.has(role)) {
+        reasons.push(`action '${name}' should not be readable by '${role}'`);
+        // Asymmetric with create_action_permission, which calls it `action`.
+        permissionDrops.push({ type: "drop_action_permission", args: { name, role } });
+      }
+    }
+    for (const role of wanted) {
+      if (!held.has(role)) {
+        reasons.push(`action '${name}' is not readable by '${role}'`);
+        permissionCreates.push({
+          type: "create_action_permission",
+          args: { action: name, role },
+        });
+      }
+    }
+  }
+
+  const desiredTypes = metadata.customTypes;
+  const currentTypes = exported?.custom_types ?? {};
+  const typesDiffer = !same(
+    normaliseCustomTypes(currentTypes),
+    normaliseCustomTypes(desiredTypes)
+  );
+  if (typesDiffer) {
+    reasons.push("custom types differ");
+  }
+
+  if (reasons.length === 0) {
+    return { bulk: null, reasons };
+  }
+
+  // `set_custom_types` replaces the whole block and is validated the moment it
+  // runs, not at the end of the bulk. A type being added has to exist before
+  // the action that names it, and a type being removed has to outlive the
+  // action that named it -- opposite orders. The union satisfies both: it is
+  // asserted first, so it adds everything new while keeping everything old,
+  // and the desired set follows the actions only when something is dropped.
+  const union = unionCustomTypes(currentTypes, desiredTypes);
+  const args = [];
+  if (typesDiffer) {
+    args.push({ type: "set_custom_types", args: union });
+  }
+  args.push(...drops, ...writes, ...permissionDrops, ...permissionCreates);
+  if (typesDiffer && !same(normaliseCustomTypes(union), normaliseCustomTypes(desiredTypes))) {
+    args.push({ type: "set_custom_types", args: desiredTypes });
+  }
+
+  return { bulk: { type: "bulk", args }, reasons };
+}
+
+function unionCustomTypes(current, desired) {
+  const merge = (key) => {
+    const wanted = desired[key] ?? [];
+    const names = new Set(wanted.map((type) => type.name));
+    const kept = (current[key] ?? []).filter((type) => !names.has(type.name));
+    return [...wanted, ...kept];
+  };
+  return {
+    scalars: merge("scalars"),
+    enums: merge("enums"),
+    input_objects: merge("input_objects"),
+    objects: merge("objects"),
+  };
+}
+
+async function metadataCall({ endpoint, adminSecret, role = "admin", signal }, body) {
+  try {
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-hasura-role": role,
+        "x-hasura-admin-secret": adminSecret,
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+    let answer = null;
+    let unreadable = null;
+    try {
+      answer = await response.json();
+    } catch (error) {
+      unreadable = error;
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Hasura metadata call '${body.type}' failed with ${response.status}: ${JSON.stringify(answer)}`
+      );
+    }
+    // A 2xx whose body could not be read is not an empty Hasura. Answering
+    // `null` here would have `planApply` see metadata holding none of our
+    // actions and recreate the lot against a Hasura that already has them.
+    if (unreadable !== null) {
+      throw new Error(
+        `Hasura metadata call '${body.type}' answered ${response.status} with a body that could not be read: ${unreadable.message}`
+      );
+    }
+    return answer;
+  } catch (error) {
+    if (error?.name === "AbortError") {
+      throw new Error(`Hasura metadata call '${body.type}' gave up on an unfinished response`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * Brings Hasura's metadata in line with the manifest.
+ *
+ * Idempotent by construction: what to write is decided from what Hasura reports
+ * it already has, so applying twice makes one call the second time and changes
+ * nothing.
+ */
+export async function applyResolverMetadata({
+  endpoint,
+  adminSecret,
+  role,
+  metadata,
+  healOnly = false,
+  timeoutMs = DEFAULT_METADATA_TIMEOUT_MS,
+}) {
+  // One deadline for the apply, not one per call: an apply is an export and
+  // then a bulk, so a per-call bound lets a slow Hasura hold this for twice
+  // the number the caller passed. The re-assert loop skips every tick while it
+  // runs, so the guard against overlapping applies would stop them happening.
+  // The signal covers reading each body too, not just its headers -- a Hasura
+  // that writes a 200 and then stops leaves `response.json()` pending for good.
+  const controller = new AbortController();
+  const expiry = setTimeout(() => controller.abort(), timeoutMs);
+  const connection = { endpoint, adminSecret, role, signal: controller.signal };
+  try {
+    const exported = await metadataCall(connection, { type: "export_metadata", args: {} });
+    const { bulk, reasons } = planApply(metadata, exported, { healOnly });
+    if (bulk === null) {
+      return { applied: false, reasons };
+    }
+    await metadataCall(connection, bulk);
+    return { applied: true, reasons };
+  } finally {
+    clearTimeout(expiry);
+  }
+}
+
+/**
+ * Re-asserts the metadata on an interval, returning a function that stops it.
+ *
+ * `intervalMs: 0` disables it, for a deployment where something else owns the
+ * metadata.
+ */
+export function startMetadataReassert({
+  endpoint,
+  adminSecret,
+  role,
+  metadata,
+  intervalMs,
+  timeoutMs,
+  onApplied,
+  onError,
+}) {
+  if (!intervalMs || intervalMs <= 0) {
+    return () => {};
+  }
+  let running = false;
+  const timer = setInterval(async () => {
+    // A slow Hasura must not stack up overlapping applies.
+    if (running) return;
+    running = true;
+    try {
+      const { applied, reasons } = await applyResolverMetadata({
+        endpoint,
+        adminSecret,
+        role,
+        metadata,
+        healOnly: true,
+        timeoutMs,
+      });
+      if (applied) onApplied?.(reasons);
+    } catch (error) {
+      onError?.(error);
+    } finally {
+      running = false;
+    }
+  }, intervalMs);
+  // The loop must never be the reason the process stays alive.
+  timer.unref?.();
+  return () => clearInterval(timer);
+}