envio 3.14.0 → 3.14.1-resolvers.2

package/src/resolvers/db.js

@@ -0,0 +1,363 @@
+// The `db` handle a resolver's handler is given.
+//
+// Three things it owns that a bare postgres client does not:
+//
+//   1. A `statement_timeout` on every query, taken from the resolver's own
+//      `timeoutMs`. It is the only thing that actually bounds a runaway query
+//      -- a pooler's `query_timeout`, where there is one, drops the client
+//      without cancelling the backend -- so a handle cannot be made without
+//      one.
+//   2. A bounded pool with a bounded *wait*, sized as concurrent heavy
+//      requests x per-request fan-out rather than by CPU count: a single
+//      resolver holding four connections at once is the shape this exists for.
+//   3. Entity loaders that go through the indexer's own table definitions, so
+//      what a resolver reads matches what a handler wrote.
+//
+// SQL construction and row decoding live in `ResolverQuery.res` because both
+// are driven by those table definitions.
+
+import postgres from "postgres";
+import { Db as DbEnv, Resolvers as ResolversEnv } from "../Env.res.mjs";
+import { ResolverError } from "./errors.js";
+import { warn as logWarn } from "../Logging.res.mjs";
+import {
+  decodeChainHeights,
+  decodeRows,
+  makeChainHeightsQuery,
+  makeFindQuery,
+  makeGetQuery,
+} from "./ResolverQuery.res.mjs";
+
+// Design §7.7: concurrent heavy requests x per-request fan-out, not serve's
+// `min(cpus*2, 10)`. The fan-out arithmetic is sound; the tail latency it
+// assumes is not measured, so the first real workload should re-derive it.
+const DEFAULT_POOL_SIZE = 25;
+
+const DEFAULT_POOL_WAIT_TIMEOUT_MS = 10_000;
+
+/**
+ * A failure of the resolver's own database access — the pool being saturated,
+ * a query hitting its statement_timeout, an entity that isn't in the schema.
+ *
+ * A `ResolverError`, so its code reaches the client: §7.4 asks for pool
+ * exhaustion to surface as "a clean per-field error", and a caller that cannot
+ * tell saturation from a bug cannot back off and retry. None of these carry
+ * driver internals; a raw Postgres error still has its message withheld.
+ */
+export class ResolverDbError extends ResolverError {
+  constructor(message, code, options = {}) {
+    super(message, { code, httpStatus: options.httpStatus ?? 503 });
+    this.name = "ResolverDbError";
+    // The driver's own error, kept so a handler that wants the SQLSTATE can
+    // still reach it. It is not put on the wire.
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+// Bounds concurrency in front of the driver rather than inside it. postgres.js
+// queues indefinitely once its pool is full; a resolver answering a request
+// needs the wait itself bounded, so a saturated pool fails that field cleanly
+// instead of holding the whole operation open.
+class Gate {
+  constructor(size) {
+    this.size = size;
+    this.inUse = 0;
+    this.peakInUse = 0;
+    this.queue = [];
+  }
+
+  take() {
+    this.inUse++;
+    if (this.inUse > this.peakInUse) {
+      this.peakInUse = this.inUse;
+    }
+  }
+
+  acquire(waitMs) {
+    if (this.inUse < this.size) {
+      this.take();
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const entry = { resolve, timer: null };
+      entry.timer = setTimeout(() => {
+        const index = this.queue.indexOf(entry);
+        if (index !== -1) {
+          this.queue.splice(index, 1);
+        }
+        reject(
+          new ResolverDbError(
+            `Timed out after ${waitMs}ms waiting for one of the resolver pool's ${this.size} connections.`,
+            "POOL_WAIT_TIMEOUT"
+          )
+        );
+      }, waitMs);
+      this.queue.push(entry);
+    });
+  }
+
+  release() {
+    this.inUse--;
+    const next = this.queue.shift();
+    if (next) {
+      clearTimeout(next.timer);
+      this.take();
+      next.resolve();
+    }
+  }
+}
+
+function requirePositiveInt(value, describe) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ResolverDbError(describe, "INVALID_OPTION");
+  }
+  return value;
+}
+
+/**
+ * Opens the resolver process's database pool. One per process: the handles
+ * `forResolver` hands out share its connections and its bound on them.
+ */
+export function createResolverPool(options) {
+  if (!options || typeof options !== "object") {
+    throw new ResolverDbError(
+      "createResolverPool expects an options object",
+      "INVALID_OPTION"
+    );
+  }
+  const { connection, entities, pgSchema, poolerBacked, onWarn } = options;
+
+  if (!connection || typeof connection !== "object") {
+    throw new ResolverDbError(
+      "createResolverPool requires a `connection` with host, port, username, password and database",
+      "INVALID_OPTION"
+    );
+  }
+  if (!entities || typeof entities !== "object") {
+    throw new ResolverDbError(
+      "createResolverPool requires `entities`, the project's entity configs keyed by name",
+      "INVALID_OPTION"
+    );
+  }
+  if (typeof pgSchema !== "string" || pgSchema.length === 0) {
+    throw new ResolverDbError(
+      "createResolverPool requires a `pgSchema`",
+      "INVALID_OPTION"
+    );
+  }
+
+  const poolSize = requirePositiveInt(
+    options.poolSize ?? DEFAULT_POOL_SIZE,
+    "createResolverPool `poolSize` must be a positive whole number"
+  );
+  const poolWaitTimeoutMs = requirePositiveInt(
+    options.poolWaitTimeoutMs ?? DEFAULT_POOL_WAIT_TIMEOUT_MS,
+    "createResolverPool `poolWaitTimeoutMs` must be a positive whole number"
+  );
+
+  // A transaction-mode pooler (PgBouncer and friends) rejects named prepared
+  // statements, so that path gives up plan reuse; connecting straight to
+  // Postgres keeps it. The per-query timeout is `SET LOCAL` on *both* paths: a
+  // single pool serves every resolver, and each brings its own `timeoutMs`.
+  const prepare = poolerBacked !== true;
+
+  const sql = postgres({
+    host: connection.host,
+    port: connection.port,
+    username: connection.username,
+    password: connection.password,
+    database: connection.database,
+    ssl: connection.ssl,
+    max: poolSize,
+    // `statement_timeout` bounds a query, not the TCP connect and handshake in
+    // front of it, so an unreachable database would otherwise hold a request
+    // open far longer than the resolver's own `timeoutMs`. Seconds, and matched
+    // to the pool wait so a request fails at roughly the same point either way.
+    connect_timeout: Math.ceil(poolWaitTimeoutMs / 1000),
+    prepare,
+    transform: { undefined: null },
+    onnotice: () => {},
+  });
+
+  const warn = typeof onWarn === "function" ? onWarn : logWarn;
+  const gate = new Gate(poolSize);
+  // Kept on the pool, not the handle: a handle is per request, so warning
+  // there would repeat the same line for every request a wide resolver serves.
+  const warnedResolvers = new Set();
+  // One resolver holding a quarter of the pool is the fan-out that breaks
+  // naive sizing, and it is silent otherwise: the queries all succeed, right
+  // up until concurrent requests turn it into pool-wait timeouts.
+  const fanOutWarnAt = Math.max(1, Math.floor(poolSize / 4));
+
+  const entityOrThrow = (entityName) => {
+    if (typeof entityName !== "string" || !Object.hasOwn(entities, entityName)) {
+      throw new ResolverDbError(
+        `Unknown entity '${entityName}'. This project has ${Object.keys(entities)
+          .sort()
+          .join(", ")}.`,
+        "UNKNOWN_ENTITY"
+      );
+    }
+    return entities[entityName];
+  };
+
+  const forResolver = (resolver) => {
+    const name = resolver?.name;
+    if (typeof name !== "string" || name.length === 0) {
+      throw new ResolverDbError(
+        "forResolver requires the resolver's `name`",
+        "INVALID_OPTION"
+      );
+    }
+    const { timeoutMs } = resolver;
+    if (
+      typeof timeoutMs !== "number" ||
+      !Number.isSafeInteger(timeoutMs) ||
+      timeoutMs <= 0
+    ) {
+      throw new ResolverDbError(
+        `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.`,
+        "MISSING_TIMEOUT"
+      );
+    }
+
+    // No point waiting longer for a connection than the resolver has left to
+    // spend on the query it would run.
+    const waitMs = Math.min(poolWaitTimeoutMs, timeoutMs);
+    let inFlight = 0;
+
+    const run = async (work) => {
+      await gate.acquire(waitMs);
+      inFlight++;
+      if (inFlight > fanOutWarnAt && !warnedResolvers.has(name)) {
+        warnedResolvers.add(name);
+        warn(
+          `Resolver '${name}' held ${inFlight} of the pool's ${poolSize} connections at once. The pool is sized as concurrent heavy requests x per-request fan-out, so a fan-out this wide needs a larger pool or fewer concurrent queries.`
+        );
+      }
+      try {
+        return await runInTransaction();
+      } catch (error) {
+        if (error?.code === "57014") {
+          throw new ResolverDbError(
+            `Query exceeded resolver '${name}'s ${timeoutMs}ms statement_timeout`,
+            "STATEMENT_TIMEOUT",
+            { cause: error }
+          );
+        }
+        throw error;
+      } finally {
+        inFlight--;
+        gate.release();
+      }
+
+      async function runInTransaction() {
+        return await sql.begin(async (tx) => {
+          // `SET LOCAL` rather than a startup option so the bound is this
+          // resolver's own, and so it cannot outlive the transaction onto the
+          // next query that checks the connection out.
+          await tx.unsafe(`SET LOCAL statement_timeout = ${timeoutMs}`);
+          return await work(tx);
+        });
+      }
+    };
+
+    const tagged = (strings, ...values) => run((tx) => tx(strings, ...values));
+    tagged.unsafe = (text, params = [], queryOptions) =>
+      run((tx) => tx.unsafe(text, params, queryOptions));
+
+    return {
+      /** Entities matching `where`, decoded as the handlers see them. */
+      find: async (entityName, findOptions) => {
+        const entityConfig = entityOrThrow(entityName);
+        const query = makeFindQuery({
+          entityConfig,
+          pgSchema,
+          where: findOptions?.where,
+          orderBy: findOptions?.orderBy,
+          limit: findOptions?.limit,
+          offset: findOptions?.offset,
+        });
+        const rows = await run((tx) =>
+          tx.unsafe(query.text, query.params, { prepare })
+        );
+        return decodeRows(entityConfig, rows);
+      },
+
+      /** One entity by id, or null. */
+      get: async (entityName, id) => {
+        const entityConfig = entityOrThrow(entityName);
+        const query = makeGetQuery(entityConfig, pgSchema, id);
+        const rows = await run((tx) =>
+          tx.unsafe(query.text, query.params, { prepare })
+        );
+        const decoded = decodeRows(entityConfig, rows);
+        return decoded.length === 0 ? null : decoded[0];
+      },
+
+      /**
+       * The per-chain indexed height, for resolvers that refuse to answer from
+       * a stale index. `progressBlock` is what has been processed;
+       * `sourceBlock` is where the chain was last seen.
+       */
+      chainHeights: async () => {
+        const query = makeChainHeightsQuery(pgSchema);
+        const rows = await run((tx) =>
+          tx.unsafe(query.text, query.params, { prepare })
+        );
+        return decodeChainHeights(rows);
+      },
+
+      /** Raw SQL: ``db.sql`select ...` `` or `db.sql.unsafe(text, params)`. */
+      sql: tagged,
+
+      /**
+       * The Postgres schema the indexer's tables live in. Raw SQL has to
+       * qualify table names with it, and it is not always "public".
+       */
+      pgSchema,
+
+      /**
+       * Several queries on one connection, under one timeout. The `sql` handed
+       * to the callback is postgres.js's own, so a fragment built from it can
+       * be used in a later query of the same block.
+       */
+      transaction: (work) => run(work),
+    };
+  };
+
+  return {
+    forResolver,
+    stats: () => ({
+      poolSize,
+      inUse: gate.inUse,
+      peakInUse: gate.peakInUse,
+      waiting: gate.queue.length,
+    }),
+    end: () => sql.end(),
+  };
+}
+
+/**
+ * The pool for the running resolver process: the indexer's ENVIO_PG_* target,
+ * with sizing of its own.
+ */
+export function createResolverPoolFromEnv(options) {
+  return createResolverPool({
+    connection: {
+      host: DbEnv.host,
+      port: DbEnv.port,
+      username: DbEnv.user,
+      password: DbEnv.password,
+      database: DbEnv.database,
+      ssl: DbEnv.ssl,
+    },
+    pgSchema: options?.pgSchema ?? DbEnv.publicSchema,
+    entities: options?.entities ?? {},
+    poolSize: options?.poolSize ?? ResolversEnv.poolSize(),
+    poolWaitTimeoutMs:
+      options?.poolWaitTimeoutMs ?? ResolversEnv.poolWaitTimeoutMs(),
+    poolerBacked: options?.poolerBacked ?? ResolversEnv.poolerBacked(),
+    onWarn: options?.onWarn,
+  });
+}

package/src/resolvers/dispatch.js

@@ -0,0 +1,259 @@
+// Turns one `/resolve` request into one response body.
+//
+// The wire contract is envio-serve's, which already implements and tests it:
+// a request names a field, its already-coerced arguments, the selection the
+// caller asked for, and the role the operation runs under; the answer is
+// `{ data }` or `{ errors }`, and `errors` wins when both could apply.
+//
+// Two things happen here that look like validation but are not optional.
+// Arguments are parsed through their declared schemas, because that is what
+// turns serve's JSON into the values the handler declared -- a BigInt argument
+// arrives as a string -- and what runs the user's own refinements, which serve
+// cannot. Results are converted back through the output schema for the mirror
+// reason: a handler returning a bigint would otherwise throw inside
+// JSON.stringify, and the conversion drops anything not declared, so an
+// over-fetching resolver cannot leak through even before serve projects.
+
+import * as S from "rescript-schema";
+import { unwrapNullableOutput } from "./manifest.js";
+import { ResolverError } from "./errors.js";
+import { PRIVATE_KEY_HEADER } from "./hasuraMetadata.js";
+
+// Built once per resolver, from a copy: `S.schema` replaces the schema values
+// in the object it is handed, which would gut the declaration the manifest is
+// derived from.
+const argsSchemas = new WeakMap();
+const outputSchemas = new WeakMap();
+
+function argsSchemaOf(resolver) {
+  let schema = argsSchemas.get(resolver);
+  if (schema === undefined) {
+    schema = S.schema({ ...resolver.args });
+    argsSchemas.set(resolver, schema);
+  }
+  return schema;
+}
+
+function outputSchemaOf(resolver) {
+  let unwrapped = outputSchemas.get(resolver);
+  if (unwrapped === undefined) {
+    unwrapped = unwrapNullableOutput(resolver.output);
+    outputSchemas.set(resolver, unwrapped);
+  }
+  return unwrapped;
+}
+
+function errorBody(message, code, extra) {
+  return {
+    errors: [{ message, extensions: { code, ...extra } }],
+  };
+}
+
+const isPlainObject = (value) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Validates a decoded request body against the wire contract.
+ * Returns null when it is well formed.
+ */
+export function badRequest(request) {
+  if (!isPlainObject(request)) {
+    return "expected a JSON object";
+  }
+  if (typeof request.field !== "string" || request.field.length === 0) {
+    return "`field` must be a non-empty string";
+  }
+  if (request.args !== undefined && !isPlainObject(request.args)) {
+    return "`args` must be an object";
+  }
+  if (request.selection !== undefined && !isPlainObject(request.selection)) {
+    return "`selection` must be an object";
+  }
+  if (request.role !== "public" && request.role !== "admin") {
+    return '`role` must be "public" or "admin"';
+  }
+  if (typeof request.requestId !== "string") {
+    return "`requestId` must be a string";
+  }
+  return null;
+}
+
+/**
+ * Builds the dispatcher the HTTP server calls per request.
+ *
+ * `exposeErrors` puts an unexpected error's own message on the wire. Off by
+ * default: a driver error can carry a connection string, and the caller is the
+ * public internet. `envio dev` turns it on.
+ */
+// How long a chain-height read is reused for. Staleness is measured in blocks
+// and moves at block time, so re-reading it per request would cost a query to
+// learn the same answer.
+const STALENESS_CACHE_MS = 2_000;
+
+export function createDispatcher({ resolvers, pool, exposeErrors = false, onError }) {
+  const byName = new Map();
+  for (const resolver of resolvers) {
+    byName.set(resolver.name, resolver);
+  }
+
+  let cachedAt = 0;
+  let cachedChains = null;
+  let inFlight = null;
+
+  const readChainsBehindHead = async () => {
+    try {
+      const heights = await pool
+        .forResolver({ name: "staleness", timeoutMs: 2_000 })
+        .chainHeights();
+      return Object.values(heights).map((chain) => ({
+        chainId: chain.chainId,
+        behind: Math.max(0, chain.sourceBlock - chain.progressBlock),
+      }));
+    } catch {
+      return null;
+    }
+  };
+
+  /**
+   * Every chain's distance from head, or null when that cannot be read. Null
+   * means "do not know", and a gate that cannot read the answer lets the
+   * request through: refusing everything because the freshness probe itself
+   * failed would turn one broken query into a total outage.
+   *
+   * A burst that arrives on a cold cache shares one read rather than each
+   * taking a connection to learn the same answer -- the probes alone can
+   * saturate the pool, and then every request pays the pool wait and the gate
+   * fails open, under exactly the load that makes staleness worth checking.
+   * A failed read is remembered for the same window and for the same reason:
+   * repeating it per request costs each one the probe's full timeout while the
+   * gate is open regardless.
+   */
+  const chainsBehindHead = () => {
+    if (cachedAt !== 0 && Date.now() - cachedAt < STALENESS_CACHE_MS) {
+      return Promise.resolve(cachedChains);
+    }
+    if (inFlight !== null) return inFlight;
+    inFlight = readChainsBehindHead().then((chains) => {
+      cachedAt = Date.now();
+      cachedChains = chains;
+      inFlight = null;
+      return chains;
+    });
+    return inFlight;
+  };
+
+  /**
+   * The first chain past its limit, or null when all of them are inside it.
+   *
+   * A bare number applies to every chain; an object gives a limit per chain
+   * and covers only the chains it names. That distinction matters on a
+   * multichain indexer, because "blocks behind" is not comparable between
+   * chains — a few hundred blocks is seconds on Arbitrum and hours on
+   * Ethereum — and because a resolver reading one chain's tables should not be
+   * refused for another chain's lag.
+   */
+  const chainPastLimit = (chains, limit) => {
+    for (const chain of chains) {
+      const cap = typeof limit === "number" ? limit : limit[chain.chainId];
+      if (cap === undefined) continue;
+      if (chain.behind > cap) return { ...chain, cap };
+    }
+    return null;
+  };
+
+  return async function dispatch(request, { privateKeyOk = false } = {}) {
+    const invalid = badRequest(request);
+    if (invalid !== null) {
+      return errorBody(`Malformed resolve request: ${invalid}`, "BAD_REQUEST");
+    }
+
+    const { field, role } = request;
+    const resolver = byName.get(field);
+    if (resolver === undefined) {
+      return errorBody(
+        `No resolver named '${field}' is registered`,
+        "RESOLVER_NOT_FOUND"
+      );
+    }
+    // A private resolver is on the public schema so Hasura will route to it,
+    // which makes this check the only thing standing in front of it. An admin
+    // caller still passes: reaching here as `admin` means the shared secret was
+    // presented, which an unauthenticated caller cannot do.
+    if (resolver.private && !privateKeyOk && role !== "admin") {
+      return errorBody(
+        `Resolver '${field}' is private. Present its key in the ${PRIVATE_KEY_HEADER} header.`,
+        "FORBIDDEN"
+      );
+    }
+
+    let args;
+    try {
+      args = S.parseOrThrow(request.args ?? {}, argsSchemaOf(resolver));
+    } catch (error) {
+      return errorBody(
+        `Invalid arguments for '${field}': ${error.message}`,
+        "BAD_USER_INPUT"
+      );
+    }
+
+    // After the arguments parse and before any handler runs: answering from an
+    // index that is behind head is worse than not answering, because the
+    // numbers look real.
+    if (resolver.maxBlocksBehind !== undefined) {
+      const chains = await chainsBehindHead();
+      const stale = chains === null ? null : chainPastLimit(chains, resolver.maxBlocksBehind);
+      if (stale !== null) {
+        return errorBody(
+          `Chain ${stale.chainId} is ${stale.behind} blocks behind head, past this resolver's limit of ${stale.cap}; refusing to answer from a stale index`,
+          "SERVICE_UNAVAILABLE",
+          // Without this the action path answers 400, which a client cannot
+          // tell from a malformed request -- and backing off and retrying is
+          // the only useful response to an index that is merely behind.
+          { http: { status: 503 } }
+        );
+      }
+    }
+
+    let result;
+    try {
+      result = await resolver.handler({
+        args,
+        db: pool.forResolver({ name: field, timeoutMs: resolver.timeoutMs }),
+        selection: request.selection ?? {},
+        ctx: {
+          role,
+          requestId: request.requestId,
+          traceparent: request.traceparent,
+        },
+      });
+    } catch (error) {
+      if (error instanceof ResolverError) {
+        return { errors: [{ message: error.message, extensions: error.toExtensions() }] };
+      }
+      onError?.(error, { field, requestId: request.requestId });
+      return errorBody(
+        exposeErrors
+          ? `Resolver '${field}' failed: ${error?.message ?? String(error)}`
+          : `Resolver '${field}' failed`,
+        "INTERNAL_SERVER_ERROR"
+      );
+    }
+
+    try {
+      const { inner, nullable } = outputSchemaOf(resolver);
+      if (nullable && (result === undefined || result === null)) {
+        return { data: null };
+      }
+      return { data: S.reverseConvertToJsonOrThrow(result, inner) };
+    } catch (error) {
+      // Reported rather than nulled: serve's projection would make a missing
+      // field read as absent, which in a dashboard is a wrong number with no
+      // explanation anywhere.
+      onError?.(error, { field, requestId: request.requestId });
+      return errorBody(
+        `Resolver '${field}' returned a result that doesn't match its declared output: ${error.message}`,
+        "INVALID_RESULT"
+      );
+    }
+  };
+}

package/src/resolvers/errors.js

@@ -0,0 +1,30 @@
+// The error a resolver throws when it wants the client to see something
+// specific. Anything else a handler throws is reported as an internal failure
+// with its message withheld, so this is the way to say more than that.
+//
+// envio-serve carries these extensions through to the operation's `errors`
+// array unchanged, and a resolver's own `code` wins over serve's.
+
+export class ResolverError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ code?: string, httpStatus?: number, extensions?: Record<string, unknown> }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ResolverError";
+    this.code = options.code ?? "INTERNAL_SERVER_ERROR";
+    this.httpStatus = options.httpStatus;
+    this.extensions = options.extensions;
+  }
+
+  toExtensions() {
+    return {
+      code: this.code,
+      ...(this.httpStatus === undefined
+        ? {}
+        : { http: { status: this.httpStatus } }),
+      ...this.extensions,
+    };
+  }
+}