envio 3.14.0 → 3.14.1-resolvers.2

package/src/resolvers/hasuraApply.js

@@ -0,0 +1,333 @@
+// 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,
+    // Compared, so turning forwarding on for an action that already exists is
+    // seen as drift and actually applied. Without it the flag would only ever
+    // be right on a freshly created action.
+    forward_client_headers: definition.forward_client_headers === true,
+    // The value Hasura presents is what the service checks, so a rotated secret
+    // that is not written through leaves Hasura vouching with the old one while
+    // every resolver refuses every request.
+    headers: (definition.headers ?? [])
+      .map((header) => ({ name: header.name.toLowerCase(), value: header.value ?? null }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    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);
+}

package/src/resolvers/hasuraMetadata.js

@@ -0,0 +1,137 @@
+// The manifest, expressed as the Hasura metadata that makes each resolver a
+// queryable root field.
+//
+// Hasura cannot execute user code, so an action is a declaration: the field's
+// name, its arguments, its result type, and a URL to POST to. Everything here
+// is derived from the manifest `envio codegen` already writes, so the schema
+// Hasura publishes and the code that answers it come from one source.
+//
+// Pure on purpose -- manifest in, JSON out, no network. Applying it is
+// `hasuraApply.js`; keeping the two apart is what makes the shape testable
+// without a Hasura to point at.
+
+// Hasura's own; anything else a resolver names has to be declared.
+const BUILTIN_SCALARS = new Set(["String", "Int", "Float", "Boolean", "ID"]);
+
+/** The header Hasura presents so the handler can tell it apart from anyone else
+ *  who can reach the socket.
+ *
+ *  `x-hasura-` prefixed on purpose. A private action forwards the caller's
+ *  headers, and a forwarded header replaces the action's static one of the same
+ *  name rather than merging with it -- so under any other name a caller could
+ *  set this and the handler would refuse every request. Hasura takes a client
+ *  `x-hasura-*` header as a session variable and strips it before forwarding,
+ *  so under this one the caller's copy never arrives as a header at all. It
+ *  does arrive in `session_variables`, which is why the secret is only ever
+ *  read from the header. */
+export const RESOLVER_SECRET_HEADER = "x-hasura-envio-resolver-secret";
+
+/** Where a caller presents the key that unlocks a `private` resolver. */
+export const PRIVATE_KEY_HEADER = "x-envio-private-key";
+
+/**
+ * @param manifest the parsed `.envio/resolvers.json`
+ * @param handlerUrl the URL *Hasura* posts to -- reachable from Hasura, which
+ *   is not necessarily the address the service binds
+ * @param publicRole the role a non-admin caller runs as (Hasura's
+ *   `unauthorized_role`)
+ */
+export function buildHasuraMetadata(manifest, { handlerUrl, publicRole = "public", actionSecret }) {
+  if (!handlerUrl) {
+    throw new Error(
+      "buildHasuraMetadata requires a handlerUrl: it is baked into every action, and Hasura has no other way to reach the resolvers."
+    );
+  }
+
+  const scalars = [];
+  const enums = [];
+  const objects = [];
+  const inputObjects = [];
+
+  for (const type of manifest.types ?? []) {
+    switch (type.kind) {
+      case "scalar":
+        // A resolver declaring `String` as a custom scalar would shadow
+        // Hasura's own and make the metadata inconsistent.
+        if (BUILTIN_SCALARS.has(type.name)) {
+          throw new Error(
+            `Custom scalar '${type.name}' collides with a GraphQL built-in scalar.`
+          );
+        }
+        scalars.push({ name: type.name });
+        break;
+      case "enum":
+        enums.push({
+          name: type.name,
+          // The manifest names an enum value `name`; Hasura calls it `value`.
+          values: type.values.map(({ name }) => ({ value: name })),
+        });
+        break;
+      case "object":
+        objects.push({ name: type.name, fields: type.fields });
+        break;
+      case "input_object":
+        inputObjects.push({ name: type.name, fields: type.fields });
+        break;
+      default:
+        // Emitting a partial set would leave Hasura with an action whose types
+        // are missing, which fails at apply time with a worse message than this.
+        throw new Error(
+          `Cannot express manifest type '${type.name}' of kind '${type.kind}' as a Hasura custom type.`
+        );
+    }
+  }
+
+  const actions = [];
+  const permissions = [];
+
+  for (const resolver of manifest.resolvers ?? []) {
+    const definition = {
+      // An action is a mutation unless it says otherwise, and a resolver is a
+      // read: the manifest's own SDL says `extend type Query`.
+      type: "query",
+      kind: "synchronous",
+      handler: handlerUrl,
+      arguments: resolver.args ?? [],
+      output_type: resolver.type,
+      // Hasura's timeout is whole seconds and bounds the whole HTTP call; the
+      // resolver's own `timeoutMs` bounds only the queries inside it. Acquiring
+      // a connection, parsing arguments and serializing the result spend
+      // Hasura's budget without spending the resolver's, so the extra second is
+      // what keeps Hasura from being the first to give up on a request the
+      // resolver still considers live -- which the client would see as an
+      // unreachable webhook rather than as a timeout.
+      timeout: Math.ceil(resolver.timeoutMs / 1000) + 1,
+      // The role reaches the handler inside the request body, so on its own it
+      // is the caller's claim rather than a fact. This header is the only thing
+      // that makes it one: Hasura sends it because the action declares it, and
+      // the value is literal, so Hasura itself needs no configuration.
+      ...(actionSecret
+        ? { headers: [{ name: RESOLVER_SECRET_HEADER, value: actionSecret }] }
+        : {}),
+      // A private resolver authenticates its caller here, not at Hasura, so the
+      // caller's own headers have to survive the hop. Hasura's own default
+      // ignore list is left alone: naming any header here would replace that
+      // default wholesale and pin it to whatever this version happens to ignore.
+      ...(resolver.private ? { forward_client_headers: true } : {}),
+    };
+    const action = { name: resolver.name, definition };
+    if (resolver.description) {
+      action.comment = resolver.description;
+    }
+    actions.push(action);
+
+    // Every resolver is granted to the public role, private ones included:
+    // without the permission Hasura refuses to route the call at all, and then
+    // there is nothing for the key check to run against. Being routable is not
+    // being reachable -- a private resolver still refuses anyone who cannot
+    // present a key.
+    permissions.push({ action: resolver.name, role: publicRole });
+  }
+
+  return {
+    customTypes: { scalars, enums, input_objects: inputObjects, objects },
+    actions,
+    permissions,
+  };
+}

package/src/resolvers/index.js

@@ -0,0 +1,123 @@
+// The user-facing resolver API.
+//
+// Declaring a resolver registers it, the same way importing a handler module
+// registers its handlers. `envio resolvers manifest` imports the project's
+// resolver module and reads the registry back out; the runtime reads the same
+// registry to dispatch. One registration, two consumers, no separate export
+// list for the user to keep in sync.
+
+import { buildManifest, toSDL } from "./manifest.js";
+
+export { ResolverError } from "./errors.js";
+
+export {
+  buildManifest,
+  defineEnum,
+  defineInput,
+  defineScalar,
+  defineType,
+  toSDL,
+  SCHEMA_VERSION,
+} from "./manifest.js";
+
+const registry = [];
+
+/**
+ * Declares a custom GraphQL resolver.
+ *
+ * Validation happens here rather than at manifest time so the error points at
+ * the declaration that caused it, while the stack still says which file it
+ * came from.
+ */
+export function createResolver(options) {
+  if (!options || typeof options !== "object") {
+    throw new Error("createResolver expects an options object");
+  }
+  const { name, output, handler, timeoutMs } = options;
+
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error("createResolver requires a non-empty `name`");
+  }
+  if (!output || typeof output.t === "undefined") {
+    throw new Error(
+      `Resolver '${name}' requires an \`output\` schema, e.g. output: S.array(MyType)`
+    );
+  }
+  if (typeof handler !== "function") {
+    throw new Error(`Resolver '${name}' requires a \`handler\` function`);
+  }
+  if (options.maxBlocksBehind !== undefined) {
+    const whole = (value) =>
+      typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+    const limit = options.maxBlocksBehind;
+    const ok =
+      whole(limit) ||
+      (typeof limit === "object" &&
+        limit !== null &&
+        !Array.isArray(limit) &&
+        Object.keys(limit).length > 0 &&
+        // Looked up as `limit[chain.chainId]`, so only the canonical decimal
+        // spelling ever matches: " 1" and "1e3" are numbers to `Number` but
+        // name no chain, and would leave the resolver silently ungated.
+        Object.entries(limit).every(
+          ([chainId, value]) =>
+            whole(Number(chainId)) && String(Number(chainId)) === chainId && whole(value)
+        ));
+    if (!ok) {
+      throw new Error(
+        `Resolver '${name}' has an invalid \`maxBlocksBehind\`. It is how far behind head this resolver will still answer, so it is either a whole number of blocks applying to every chain, or an object of chainId to blocks naming the chains it cares about.`
+      );
+    }
+  }
+  if (typeof timeoutMs !== "number" || timeoutMs <= 0) {
+    throw new Error(
+      `Resolver '${name}' requires a positive \`timeoutMs\`. It becomes the statement_timeout on every query the resolver makes, which is the only thing bounding a runaway one.`
+    );
+  }
+  if (registry.some((r) => r.name === name)) {
+    throw new Error(`Resolver '${name}' is declared more than once`);
+  }
+
+  const resolver = {
+    name,
+    // Passed through so `buildManifest` below refuses it with a message that
+    // names the resolver, rather than it being silently dropped here.
+    cacheTtlMs: options.cacheTtlMs,
+    description: options.description,
+    args: options.args ?? {},
+    output,
+    // `admin` is the old spelling. It named a Hasura role that is no longer how
+    // these are reached, so `private` is the name now; both mean the same
+    // thing -- published so Hasura will route to it, and refused at the service
+    // unless the caller presents a key.
+    private: options.private === true || options.admin === true,
+    maxBlocksBehind: options.maxBlocksBehind,
+    timeoutMs,
+    handler,
+  };
+  // Built before registering, not after: a declaration whose schemas cannot
+  // be represented in GraphQL must leave the registry untouched, or the
+  // failure follows every later build. Doing it here at all is what surfaces
+  // the problem at the declaration rather than at the end of codegen, where
+  // the stack no longer says which resolver was at fault.
+  buildManifest([resolver]);
+
+  registry.push(resolver);
+  return resolver;
+}
+
+/** Every resolver declared so far, in declaration order. */
+export function getRegisteredResolvers() {
+  return [...registry];
+}
+
+/** Test-only: forgets every declaration. */
+export function resetResolvers() {
+  registry.length = 0;
+}
+
+/** The manifest and SDL for everything declared so far. */
+export function buildRegisteredManifest() {
+  const manifest = buildManifest(registry);
+  return { manifest, sdl: toSDL(manifest) };
+}