@o1-labs/mina-archive-node-graphql 0.0.6 → 2.0.0

package/src/server/cors.ts

@@ -0,0 +1,97 @@
+export { resolveCorsOptions, warnIfCorsDisabled };
+export type { CorsResult };
+
+const CORS_METHODS = ['GET', 'POST'];
+// Pinned rather than echoed from Access-Control-Request-Headers: echoing makes
+// the adapter drop Vary: Origin on preflight responses while ACAO is per-origin.
+const CORS_HEADERS = ['content-type'];
+
+/**
+ * Either a Yoga CORS configuration object or `false` to disable CORS entirely
+ * (no `Access-Control-Allow-Origin` header → same-origin only).
+ */
+type CorsResult =
+  | false
+  | {
+      origin: string | string[];
+      methods: string[];
+      allowedHeaders: string[];
+      // This API takes no cookies or Authorization header. Leaving this
+      // undefined makes the adapter send Access-Control-Allow-Credentials: true
+      // alongside an echoed origin.
+      credentials: false;
+    };
+
+const corsBase = {
+  methods: CORS_METHODS,
+  allowedHeaders: CORS_HEADERS,
+  credentials: false,
+} as const;
+
+/**
+ * Resolve the Yoga `cors` option from `CORS_ORIGIN`.
+ *
+ * Secure by default: when `CORS_ORIGIN` is unset, cross-origin browser access is
+ * disabled rather than allowed from anywhere. Wide-open access (`*`) is still
+ * available, but only as a deliberate opt-in. Server-to-server clients and curl
+ * are unaffected by CORS; this only governs browsers calling from another origin.
+ *
+ * Accepted values:
+ *   - unset / empty  → `false` (same-origin only)
+ *   - `*`            → allow any origin (explicit opt-in)
+ *   - one or more comma-separated origins → allowlist
+ */
+function resolveCorsOptions(
+  env: Record<string, string | undefined> = process.env
+): CorsResult {
+  const raw = env.CORS_ORIGIN?.trim();
+  if (!raw) return false;
+  if (raw === '*') return { origin: '*', ...corsBase };
+
+  const origins = raw
+    .split(',')
+    .map((origin) => origin.trim())
+    .filter((origin) => origin.length > 0);
+
+  // A value that was non-empty but parsed to nothing (e.g. just commas) falls
+  // back to the secure default rather than an empty, surprising allowlist.
+  if (origins.length === 0) return false;
+
+  for (const origin of origins) {
+    if (
+      origin.endsWith('/') ||
+      origin !== origin.toLowerCase() ||
+      origin.includes('*')
+    ) {
+      console.warn(
+        `[cors] CORS_ORIGIN entry "${origin}" is unlikely to ever match: ` +
+          "origins are compared byte-for-byte against the browser's Origin " +
+          'header, which is lowercase scheme://host[:port] with no trailing ' +
+          'slash. Wildcard subdomains are not supported.'
+      );
+    }
+  }
+
+  return { origin: origins, ...corsBase };
+}
+
+/**
+ * Announce the secure default at startup.
+ *
+ * When CORS is disabled, a browser client's requests fail in the browser — the
+ * server answers normally and logs nothing, so the only symptom is a blank page
+ * on someone else's screen. Saying so once at boot turns that into a glance at
+ * the logs.
+ */
+function warnIfCorsDisabled(
+  cors: CorsResult,
+  warn: (message: string) => void = console.warn
+): void {
+  if (cors !== false) return;
+  warn(
+    '[cors] CORS_ORIGIN is unset — cross-origin browser requests are blocked ' +
+      '(same-origin only), and they will fail silently from this server\'s side. ' +
+      'Set CORS_ORIGIN to your frontend origin(s), or to "*" for a public API ' +
+      'any browser may call.'
+  );
+}

package/src/server/graceful-shutdown.ts

@@ -0,0 +1,76 @@
+export { createGracefulShutdown };
+export type { GracefulShutdownOptions };
+
+interface GracefulShutdownOptions {
+  /** Stop accepting connections and resolve once in-flight requests drain. */
+  closeServer: () => Promise<void>;
+  /** Resource teardown to run after the server closes (flush traces, close DB). */
+  closers?: Array<() => Promise<void>>;
+  /** Hard deadline; if draining/teardown exceeds it, force exit. */
+  timeoutMs: number;
+  /** Process exit hook — injectable for tests. */
+  onExit?: (code: number) => void;
+  /** Log sink — injectable for tests. */
+  log?: (message: string, error?: unknown) => void;
+}
+
+/**
+ * Build an idempotent shutdown handler. On the first invocation it drains the
+ * server, runs each closer (a failing closer is logged but doesn't abort the
+ * rest), then exits with the caller's code. A hard timeout guarantees the
+ * process exits even if a connection or teardown step hangs, and `onExit` is
+ * invoked at most once.
+ *
+ * Subsequent invocations (e.g. a second signal) are ignored.
+ */
+function createGracefulShutdown(options: GracefulShutdownOptions) {
+  const {
+    closeServer,
+    closers = [],
+    timeoutMs,
+    onExit = (code) => process.exit(code),
+    log = (message, error) =>
+      error !== undefined ? console.error(message, error) : console.info(message),
+  } = options;
+
+  let started = false;
+
+  /**
+   * `exitCode` is the code used when the drain succeeds; a crash-initiated
+   * shutdown must pass non-zero so supervisors still see a failed exit.
+   */
+  return async function shutdown(reason: string, exitCode = 0): Promise<void> {
+    if (started) return;
+    started = true;
+    log(`Shutting down (${reason})…`);
+
+    let exited = false;
+    const exitOnce = (code: number) => {
+      if (exited) return;
+      exited = true;
+      onExit(code);
+    };
+
+    const forceTimer = setTimeout(() => {
+      log('Graceful shutdown timed out; forcing exit.');
+      exitOnce(1);
+    }, timeoutMs);
+
+    try {
+      await closeServer();
+      for (const close of closers) {
+        try {
+          await close();
+        } catch (error) {
+          log('Error during shutdown step', error);
+        }
+      }
+      exitOnce(exitCode);
+    } catch (error) {
+      log('Error closing server', error);
+      exitOnce(1);
+    } finally {
+      clearTimeout(forceTimer);
+    }
+  };
+}

package/src/server/graphql-armor.ts

@@ -0,0 +1,78 @@
+import { maxDepthPlugin } from '@escape.tech/graphql-armor-max-depth';
+import { maxAliasesPlugin } from '@escape.tech/graphql-armor-max-aliases';
+import { maxTokensPlugin } from '@escape.tech/graphql-armor-max-tokens';
+import { costLimitPlugin } from '@escape.tech/graphql-armor-cost-limit';
+import { blockFieldSuggestionsPlugin } from '@escape.tech/graphql-armor-block-field-suggestions';
+
+export { buildArmorPlugins, resolveArmorConfig, ARMOR_DEFAULTS };
+export type { ArmorConfig };
+
+/**
+ * Query-cost protections for the public GraphQL endpoint. Without these a single
+ * deeply-nested, heavily-aliased, or otherwise expensive query can be turned into
+ * a denial-of-service against the backing Postgres. The limits are deliberately
+ * conservative — they comfortably allow every query this API legitimately serves
+ * (the deepest known downstream probe is 7 levels) while rejecting abusive shapes before execution — and
+ * each is tunable via the environment.
+ */
+interface ArmorConfig {
+  /** Max selection-set nesting depth. */
+  maxDepth: number;
+  /** Max number of aliases in a single operation. */
+  maxAliases: number;
+  /** Max number of lexical tokens in a document. */
+  maxTokens: number;
+  /** Max estimated query cost (graphql-armor's depth/field heuristic). */
+  maxCost: number;
+}
+
+const ARMOR_DEFAULTS: ArmorConfig = {
+  // Deepest query in production use is 7 (mina-explorer's SearchTransaction
+  // FULL-tier probe). Keep the default comfortably above that: an armor depth
+  // rejection aborts validation before clients see the `Cannot query field`
+  // message they use for schema-tier fallback.
+  maxDepth: 12,
+  maxAliases: 15,
+  maxTokens: 1000,
+  maxCost: 5000,
+};
+
+type EnvSource = Record<string, string | undefined>;
+
+/**
+ * Parse a positive integer from an env value, falling back to `fallback` when it
+ * is missing or malformed. We never throw, so a stray typo can't silently remove
+ * a protection — it just reverts to the safe default.
+ */
+function intFromEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined || value.trim() === '') return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) return fallback;
+  return parsed;
+}
+
+function resolveArmorConfig(env: EnvSource = process.env): ArmorConfig {
+  return {
+    maxDepth: intFromEnv(env.GRAPHQL_MAX_DEPTH, ARMOR_DEFAULTS.maxDepth),
+    maxAliases: intFromEnv(env.GRAPHQL_MAX_ALIASES, ARMOR_DEFAULTS.maxAliases),
+    maxTokens: intFromEnv(env.GRAPHQL_MAX_TOKENS, ARMOR_DEFAULTS.maxTokens),
+    maxCost: intFromEnv(env.GRAPHQL_MAX_COST, ARMOR_DEFAULTS.maxCost),
+  };
+}
+
+/**
+ * Build the graphql-armor envelop plugins that enforce the configured limits.
+ * Introspection is ignored by the depth/cost rules so the GraphiQL explorer keeps
+ * working when it is explicitly enabled; field suggestions are always blocked so
+ * error messages don't leak schema shape (complementing `useDisableIntrospection`).
+ */
+function buildArmorPlugins(env: EnvSource = process.env) {
+  const config = resolveArmorConfig(env);
+  return [
+    maxDepthPlugin({ n: config.maxDepth, ignoreIntrospection: true }),
+    maxAliasesPlugin({ n: config.maxAliases }),
+    maxTokensPlugin({ n: config.maxTokens }),
+    costLimitPlugin({ maxCost: config.maxCost, ignoreIntrospection: true }),
+    blockFieldSuggestionsPlugin(),
+  ];
+}

package/src/server/logger.ts

@@ -0,0 +1,72 @@
+import { hostname } from 'node:os';
+import pino from 'pino';
+import type { LogLevel } from 'graphql-yoga';
+
+export { createLogger, logger, resolveLogLevel, resolveYogaLogLevel };
+export type { Logger };
+
+type Logger = pino.Logger;
+type PinoLogLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal'
+  | 'silent';
+
+const VALID_LEVELS = new Set<PinoLogLevel>([
+  'trace',
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'fatal',
+  'silent',
+]);
+
+function resolveLogLevel(
+  env: Record<string, string | undefined> = process.env
+): PinoLogLevel {
+  const requested = (env.LOG_LEVEL ?? 'info').toLowerCase();
+  return VALID_LEVELS.has(requested as PinoLogLevel)
+    ? (requested as PinoLogLevel)
+    : 'info';
+}
+
+function resolveYogaLogLevel(
+  env: Record<string, string | undefined> = process.env
+): LogLevel | false {
+  const level = resolveLogLevel(env);
+  if (level === 'trace') return 'debug';
+  if (level === 'fatal') return 'error';
+  if (level === 'silent') return false;
+  return level;
+}
+
+/**
+ * Build the application logger. Emits structured JSON (one object per line) with
+ * ISO timestamps, suitable for log aggregation, and is independent of the
+ * optional Jaeger tracing. The level comes from `LOG_LEVEL`; an unrecognised
+ * value falls back to `info` rather than throwing at startup.
+ */
+function createLogger(
+  env: Record<string, string | undefined> = process.env
+): Logger {
+  const level = resolveLogLevel(env);
+  return pino({
+    level,
+    base: {
+      pid: process.pid,
+      hostname: hostname(),
+      service: env.JAEGER_SERVICE_NAME ?? 'archive-api',
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    formatters: {
+      // Log the level name ("info") instead of its numeric code.
+      level: (label) => ({ level: label }),
+    },
+  });
+}
+
+const logger = createLogger();

package/src/server/metrics.ts

@@ -0,0 +1,104 @@
+import type { Plugin } from 'graphql-yoga';
+import {
+  Registry,
+  collectDefaultMetrics,
+  Counter,
+  Histogram,
+  Gauge,
+} from 'prom-client';
+
+export { createMetrics, useMetrics, METRICS_PATH };
+export type { Metrics };
+
+const METRICS_PATH = '/metrics';
+
+/** Known routes — anything else is bucketed as `other` to bound label cardinality. */
+const KNOWN_ROUTES = new Set(['/', '/healthcheck', '/readiness', METRICS_PATH]);
+
+interface Metrics {
+  registry: Registry;
+  requestsTotal: Counter<'method' | 'route' | 'status'>;
+  requestDuration: Histogram<'method' | 'route' | 'status'>;
+  inFlight: Gauge;
+}
+
+/**
+ * Build a Prometheus registry with RED HTTP metrics (rate, errors, duration) and,
+ * unless disabled, the standard Node process metrics (CPU, memory, event loop,
+ * GC). `collectDefault` is off in tests to avoid leaving background collectors.
+ */
+function createMetrics({ collectDefault = true } = {}): Metrics {
+  const registry = new Registry();
+  if (collectDefault) collectDefaultMetrics({ register: registry });
+
+  const requestsTotal = new Counter({
+    name: 'http_requests_total',
+    help: 'Total HTTP requests',
+    labelNames: ['method', 'route', 'status'] as const,
+    registers: [registry],
+  });
+  const requestDuration = new Histogram({
+    name: 'http_request_duration_seconds',
+    help: 'HTTP request duration in seconds',
+    labelNames: ['method', 'route', 'status'] as const,
+    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+    registers: [registry],
+  });
+  const inFlight = new Gauge({
+    name: 'http_requests_in_flight',
+    help: 'HTTP requests currently being processed',
+    registers: [registry],
+  });
+
+  return { registry, requestsTotal, requestDuration, inFlight };
+}
+
+function routeOf(rawUrl: string): string {
+  let path: string;
+  try {
+    path = new URL(rawUrl).pathname;
+  } catch {
+    return 'other';
+  }
+  return KNOWN_ROUTES.has(path) ? path : 'other';
+}
+
+/**
+ * Yoga plugin that serves the Prometheus exposition at `/metrics` and records RED
+ * metrics for every other request. The `/metrics` scrape itself is not counted.
+ */
+function useMetrics(metrics: Metrics = createMetrics()): Plugin {
+  const startTimes = new WeakMap<Request, number>();
+  return {
+    async onRequest({ request, url, endResponse, fetchAPI }) {
+      if (url.pathname === METRICS_PATH) {
+        endResponse(
+          new fetchAPI.Response(await metrics.registry.metrics(), {
+            status: 200,
+            headers: { 'content-type': metrics.registry.contentType },
+          })
+        );
+        return;
+      }
+      metrics.inFlight.inc();
+      startTimes.set(request, Date.now());
+    },
+    onResponse({ request, response }) {
+      const route = routeOf(request.url);
+      if (route === METRICS_PATH) return;
+
+      const labels = {
+        method: request.method,
+        route,
+        status: String(response.status),
+      };
+      metrics.requestsTotal.inc(labels);
+      const start = startTimes.get(request);
+      if (start === undefined) return;
+
+      startTimes.delete(request);
+      metrics.inFlight.dec();
+      metrics.requestDuration.observe(labels, (Date.now() - start) / 1000);
+    },
+  };
+}

package/src/server/plugins.ts

@@ -2,19 +2,45 @@ import { useLogger } from '@envelop/core';
 import { useGraphQlJit } from '@envelop/graphql-jit';
 import { useDisableIntrospection } from '@envelop/disable-introspection';
 import { useOpenTelemetry } from '@envelop/opentelemetry';
-import { inspect } from 'node:util';
+import type { GraphQLError } from 'graphql';
 
+import type { BasicTracerProvider } from '@opentelemetry/sdk-trace-base';
 import { initJaegerProvider } from '../tracing/jaeger-tracing.js';
+import { parseBoolean } from '../config.js';
+import { useMetrics } from './metrics.js';
+import { useRateLimit } from './rate-limit.js';
+import { buildArmorPlugins } from './graphql-armor.js';
+import { logger } from './logger.js';
+import { useRequestLogging, requestIdFor } from './request-logging.js';
 
 export { buildPlugins };
 
 async function buildPlugins() {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const plugins: any[] = [];
+
+  // Structured per-request access logging with correlation ids.
+  plugins.push(useRequestLogging());
+
+  // Per-IP request rate limiting. Runs on every request before GraphQL parsing,
+  // so over-limit traffic is rejected as cheaply as possible.
+  plugins.push(useRateLimit());
+
+  // Query-cost protections (depth / aliases / tokens / cost). These reject
+  // abusive query shapes before execution.
+  plugins.push(...buildArmorPlugins());
+
+  if (parseBoolean(process.env.ENABLE_METRICS)) {
+    // Prometheus /metrics endpoint + RED metrics for every request.
+    plugins.push(useMetrics());
+  }
+
   plugins.push(useGraphQlJit());
 
-  if (process.env.ENABLE_LOGGING) {
-    const provider = await initJaegerProvider();
+  // Returned so the entry point can flush spans on shutdown.
+  let provider: BasicTracerProvider | undefined;
+  if (parseBoolean(process.env.ENABLE_LOGGING)) {
+    provider = await initJaegerProvider();
     plugins.push(
       useOpenTelemetry(
         {
@@ -22,35 +48,43 @@ async function buildPlugins() {
           variables: true, // Includes the operation variables values as part of the metadata collected
           result: true, // Includes execution result object as part of the metadata collected
         },
-        provider
+        // BasicTracerProvider satisfies the TracerProvider interface; the cast
+        // bridges duplicate @opentelemetry/api copies across packages by
+        // targeting the exact parameter type useOpenTelemetry expects.
+        provider as unknown as Parameters<typeof useOpenTelemetry>[1]
       )
     );
   }
 
-  if (!process.env.ENABLE_INTROSPECTION) {
+  if (!parseBoolean(process.env.ENABLE_INTROSPECTION)) {
     plugins.push(useDisableIntrospection());
   }
 
   plugins.push(
     useLogger({
-      logFn: (eventName, args) => {
+      logFn: (_eventName, args) => {
         if (args?.result?.errors) {
-          console.debug(
-            eventName,
-            inspect(args.args.contextValue.params, {
-              showHidden: false,
-              depth: null,
-              colors: true,
-            }),
-            inspect(args.result.errors, {
-              showHidden: false,
-              depth: null,
-              colors: true,
-            })
+          const request = args?.args?.contextValue?.request as
+            | Request
+            | undefined;
+          logger.error(
+            {
+              requestId: request ? requestIdFor(request) : undefined,
+              variables: args?.args?.variableValues,
+              errors: args.result.errors.map((error: GraphQLError) => ({
+                message: error.message,
+                path: error.path,
+                locations: error.locations,
+                stack: error.originalError?.stack ?? error.stack,
+                code: (error.originalError as { code?: string } | undefined)
+                  ?.code,
+              })),
+            },
+            'graphql execution errors'
           );
         }
       },
     })
   );
-  return plugins;
+  return { plugins, provider };
 }