@adtl/gateway 0.0.0-stage → 0.1.0

package/src/invoker.ts

@@ -0,0 +1,175 @@
+/**
+ * Runs interceptors in the order SEP-2624 requires:
+ *
+ * - Sending (request phase, gateway → upstream): Mutate (sequential, by
+ *   priorityHint then name) → Validate (parallel).
+ * - Receiving (response phase, upstream → gateway): Validate (parallel) →
+ *   Mutate (sequential).
+ *
+ * Only `severity: "error"` blocks. Audit-mode interceptors never block, and
+ * their mutations are not applied. An interceptor that fails (error or
+ * timeout) blocks the message unless it declares `failOpen: true`.
+ */
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  DECISION_INFO_KEY,
+  INVOKE_METHOD,
+  LIST_METHOD,
+  type InterceptorDefinition,
+  type InterceptorResult,
+  type InvocationContext,
+  type MutationResult,
+  type Phase,
+  type ValidationResult,
+} from "@adtl/interceptors";
+import type { Decision } from "@adtl/labels";
+import { z } from "zod";
+
+const AnyResult = z.object({}).passthrough();
+
+type Loose = Record<string, unknown>;
+
+/** Untyped request: interceptor methods are extension methods the SDK does not type. */
+function request(client: Client, method: string, params: unknown, timeout: number): Promise<Loose> {
+  const r = client.request as unknown as (req: unknown, schema: unknown, opts: unknown) => Promise<Loose>;
+  return r.call(client, { method, params }, AnyResult, { timeout });
+}
+
+export interface BoundInterceptor {
+  client: Client;
+  definition: InterceptorDefinition;
+}
+
+export interface Blocked {
+  interceptor: string;
+  decision: Decision;
+  reason: string;
+}
+
+export interface ChainOutcome {
+  payload: unknown;
+  blocked?: Blocked;
+  results: InterceptorResult[];
+  /** Interceptors that failed but were allowed to (failOpen or audit mode). */
+  warnings: string[];
+}
+
+export interface InvokeOptions {
+  event: string;
+  payload: unknown;
+  config: Record<string, unknown>;
+  context: InvocationContext;
+}
+
+function priority(def: InterceptorDefinition, phase: Phase): number {
+  const p = def.priorityHint;
+  if (p === undefined) return 0;
+  if (typeof p === "number") return p;
+  return p[phase] ?? 0;
+}
+
+function hooks(def: InterceptorDefinition, event: string, phase: Phase): boolean {
+  return def.hooks.some((h) => h.phase === phase && (h.events.includes(event) || h.events.includes("*")));
+}
+
+export class InterceptorInvoker {
+  constructor(
+    private readonly interceptors: BoundInterceptor[],
+    private readonly timeoutMs = 5000,
+  ) {}
+
+  /** Discover the interceptors an interceptor server offers. */
+  static async discover(client: Client): Promise<BoundInterceptor[]> {
+    const res = await request(client, LIST_METHOD, {}, 10_000);
+    const defs = (res.interceptors ?? []) as InterceptorDefinition[];
+    return defs.map((definition) => ({ client, definition }));
+  }
+
+  get definitions(): InterceptorDefinition[] {
+    return this.interceptors.map((i) => i.definition);
+  }
+
+  async runRequest(opts: InvokeOptions): Promise<ChainOutcome> {
+    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+    if (!(await this.mutate("request", opts, out))) return out;
+    await this.validate("request", opts, out);
+    return out;
+  }
+
+  async runResponse(opts: InvokeOptions): Promise<ChainOutcome> {
+    const out: ChainOutcome = { payload: opts.payload, results: [], warnings: [] };
+    if (!(await this.validate("response", opts, out))) return out;
+    await this.mutate("response", opts, out);
+    return out;
+  }
+
+  private select(type: InterceptorDefinition["type"], event: string, phase: Phase): BoundInterceptor[] {
+    return this.interceptors.filter((i) => i.definition.type === type && hooks(i.definition, event, phase));
+  }
+
+  private async invoke(i: BoundInterceptor, phase: Phase, opts: InvokeOptions, payload: unknown): Promise<InterceptorResult> {
+    const res = await request(
+      i.client,
+      INVOKE_METHOD,
+      { name: i.definition.name, event: opts.event, phase, payload, config: opts.config, timeoutMs: this.timeoutMs, context: opts.context },
+      this.timeoutMs,
+    );
+    return res as unknown as InterceptorResult;
+  }
+
+  /** Handle an interceptor failure. Returns false if the chain must stop. */
+  private failed(i: BoundInterceptor, err: unknown, out: ChainOutcome): boolean {
+    const msg = `${i.definition.name} failed: ${err instanceof Error ? err.message : String(err)}`;
+    if (i.definition.mode === "audit" || i.definition.failOpen === true) {
+      out.warnings.push(msg);
+      return true;
+    }
+    out.blocked = { interceptor: i.definition.name, decision: "block", reason: msg };
+    return false;
+  }
+
+  /** Sequential mutations, atomic: on failure the original payload is kept. */
+  private async mutate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
+    const chain = this.select("mutation", opts.event, phase).sort(
+      (a, b) => priority(a.definition, phase) - priority(b.definition, phase) || a.definition.name.localeCompare(b.definition.name),
+    );
+    let payload = out.payload;
+    for (const i of chain) {
+      let r: MutationResult;
+      try {
+        r = (await this.invoke(i, phase, opts, payload)) as MutationResult;
+      } catch (err) {
+        if (!this.failed(i, err, out)) return false;
+        continue;
+      }
+      out.results.push(r);
+      if (i.definition.mode !== "audit" && r.modified) payload = r.payload;
+    }
+    out.payload = payload;
+    return true;
+  }
+
+  /** Parallel validations. Only severity "error" blocks. */
+  private async validate(phase: Phase, opts: InvokeOptions, out: ChainOutcome): Promise<boolean> {
+    const chain = this.select("validation", opts.event, phase);
+    const settled = await Promise.allSettled(chain.map((i) => this.invoke(i, phase, opts, out.payload)));
+    let ok = true;
+    settled.forEach((s, idx) => {
+      const i = chain[idx]!;
+      if (s.status === "rejected") {
+        if (!this.failed(i, s.reason, out)) ok = false;
+        return;
+      }
+      const r = s.value as ValidationResult;
+      out.results.push(r);
+      if (r.valid || r.severity !== "error" || i.definition.mode === "audit") return;
+      if (!out.blocked) {
+        const decision = (r.info?.[DECISION_INFO_KEY] as Decision | undefined) ?? "block";
+        const reason = r.messages?.map((m) => m.message).join("; ") || `${i.definition.name} rejected the call`;
+        out.blocked = { interceptor: i.definition.name, decision, reason };
+      }
+      ok = false;
+    });
+    return ok;
+  }
+}

package/src/startup.ts

@@ -0,0 +1,159 @@
+/**
+ * Build a running gateway from an adtl.yaml file: start the interceptor
+ * server, connect every upstream, and check that ADTL's interceptors are there.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { INTERCEPTORS_EXTENSION, LABEL_INTERCEPTOR, POLICY_INTERCEPTOR, parseConfigText } from "@adtl/interceptors";
+import type { AdtlConfig } from "@adtl/labels";
+import { parse as parseYaml } from "yaml";
+import { ZodError } from "zod";
+import { JsonlAuditLog } from "./audit.js";
+import {
+  GatewayConfigSchema,
+  expandUpstream,
+  isHttpUpstream,
+  type GatewayConfig,
+  type StdioUpstream,
+  type Upstream,
+} from "./config.js";
+import { AdtlGateway, GATEWAY_VERSION, type GatewayLogger } from "./gateway.js";
+import { InterceptorInvoker } from "./invoker.js";
+
+export class GatewayConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GatewayConfigError";
+  }
+}
+
+export interface LoadedConfig {
+  path: string;
+  labels: AdtlConfig;
+  gateway: GatewayConfig;
+}
+
+export async function loadGatewayConfig(path: string): Promise<LoadedConfig> {
+  const abs = resolve(path);
+  let text: string;
+  try {
+    text = await readFile(abs, "utf8");
+  } catch (err) {
+    throw new GatewayConfigError(`Cannot read config file ${abs}: ${(err as Error).message}`);
+  }
+  let labels: AdtlConfig;
+  try {
+    labels = parseConfigText(text, abs);
+  } catch (err) {
+    throw new GatewayConfigError((err as Error).message);
+  }
+  const raw = (parseYaml(text) ?? {}) as { gateway?: unknown };
+  if (raw.gateway === undefined) {
+    throw new GatewayConfigError(`${abs}: missing "gateway:" section (at least one upstream under gateway.upstreams)`);
+  }
+  try {
+    return { path: abs, labels, gateway: GatewayConfigSchema.parse(raw.gateway) };
+  } catch (err) {
+    if (err instanceof ZodError) {
+      const problems = err.issues.map((i) => `  - gateway.${i.path.join(".")}: ${i.message}`).join("\n");
+      throw new GatewayConfigError(`${abs}: invalid gateway config\n${problems}`);
+    }
+    throw err;
+  }
+}
+
+/** Path of the bundled adtl-interceptors CLI. */
+export function bundledInterceptorsCli(): string {
+  // Resolve via package.json: works in plain Node and under tools that lack import.meta.resolve.
+  const pkg = createRequire(import.meta.url).resolve("@adtl/interceptors/package.json");
+  return resolve(dirname(pkg), "dist", "cli.js");
+}
+
+function stdioTransport(u: StdioUpstream, baseDir: string): StdioClientTransport {
+  return new StdioClientTransport({
+    command: u.command,
+    args: u.args,
+    // The SDK passes only `env` when given, which would drop PATH; start from its safe defaults.
+    env: { ...getDefaultEnvironment(), ...u.env },
+    ...(u.cwd !== undefined ? { cwd: isAbsolute(u.cwd) ? u.cwd : resolve(baseDir, u.cwd) } : {}),
+    stderr: "inherit",
+  });
+}
+
+async function connect(id: string, u: Upstream, baseDir: string): Promise<Client> {
+  const client = new Client({ name: `adtl-gateway→${id}`, version: GATEWAY_VERSION });
+  const transport = isHttpUpstream(u)
+    ? new StreamableHTTPClientTransport(new URL(u.url), { requestInit: { headers: u.headers } })
+    : stdioTransport(u, baseDir);
+  await client.connect(transport);
+  return client;
+}
+
+export interface StartedGateway {
+  gateway: AdtlGateway;
+  close(): Promise<void>;
+}
+
+export async function startGateway(
+  loaded: LoadedConfig,
+  opts: { env?: NodeJS.ProcessEnv; logger?: GatewayLogger } = {},
+): Promise<StartedGateway> {
+  const env = opts.env ?? process.env;
+  const baseDir = dirname(loaded.path);
+  const log = opts.logger ?? { info: (m: string) => console.error(`[adtl-gateway] ${m}`), warn: (m: string) => console.error(`[adtl-gateway] warning: ${m}`) };
+  const clients: Client[] = [];
+  const closeAll = () => Promise.allSettled(clients.map((c) => c.close())).then(() => undefined);
+
+  try {
+    // 1. Interceptor server (out of process, per the Interceptors WG).
+    const icfg: StdioUpstream = loaded.gateway.interceptors
+      ? expandUpstream("interceptors", loaded.gateway.interceptors, env)
+      : { command: process.execPath, args: [bundledInterceptorsCli(), "--config", loaded.path], env: {} };
+    const interceptors = await connect("interceptors", icfg, baseDir);
+    clients.push(interceptors);
+    if (!interceptors.getServerCapabilities()?.extensions?.[INTERCEPTORS_EXTENSION]) {
+      throw new GatewayConfigError(`The interceptor server does not declare the ${INTERCEPTORS_EXTENSION} extension`);
+    }
+    const bound = await InterceptorInvoker.discover(interceptors);
+    const names = bound.map((b) => b.definition.name);
+    for (const required of [POLICY_INTERCEPTOR, LABEL_INTERCEPTOR]) {
+      if (!names.includes(required)) {
+        throw new GatewayConfigError(`The interceptor server does not offer ${required}; refusing to start without it`);
+      }
+    }
+    const invoker = new InterceptorInvoker(bound, loaded.gateway.interceptorTimeoutMs);
+    log.info(`interceptors: ${names.join(", ")}`);
+
+    // 2. Upstream servers. One failing upstream does not stop the others.
+    const upstreams = new Map<string, Client>();
+    const ids = Object.keys(loaded.gateway.upstreams);
+    const settled = await Promise.allSettled(
+      ids.map((id) => connect(id, expandUpstream(id, loaded.gateway.upstreams[id]!, env), baseDir)),
+    );
+    settled.forEach((s, i) => {
+      const id = ids[i]!;
+      if (s.status === "fulfilled") {
+        clients.push(s.value);
+        upstreams.set(id, s.value);
+        if (!loaded.labels.servers[id]) {
+          log.warn(`upstream "${id}" has no entry under servers: in the label config; its results get the default label`);
+        }
+      } else {
+        log.warn(`could not connect to upstream "${id}": ${(s.reason as Error).message}`);
+      }
+    });
+    if (upstreams.size === 0) throw new GatewayConfigError("No upstream server could be connected");
+    log.info(`upstreams: ${[...upstreams.keys()].join(", ")}`);
+
+    const audit = loaded.gateway.audit ? new JsonlAuditLog(resolve(baseDir, loaded.gateway.audit)) : undefined;
+    const gateway = new AdtlGateway({ upstreams, invoker, ...(audit ? { audit } : {}), logger: log });
+    return { gateway, close: closeAll };
+  } catch (err) {
+    await closeAll();
+    throw err;
+  }
+}