metergraph-cli 0.0.0-stage → 0.2.0-preview.0

package/src/transport.js

@@ -0,0 +1,171 @@
+import http from "node:http";
+import https from "node:https";
+
+import { PACKAGE_NAME, READ_QUERY_KEYS, VERSION } from "./constants.js";
+import { classifyError } from "./http.js";
+
+const USER_AGENT = `${PACKAGE_NAME}/${VERSION}`;
+const MAX_QUERY_LENGTH = 2048;
+
+// Builds the request URL. Without a query the path must be a fixed path on
+// the origin with no search part. A query is accepted only as a
+// URLSearchParams the caller built, only on a path in READ_QUERY_KEYS, only
+// with that path's keys, each at most once. Anything else is a programming
+// error, so no input can choose another path, origin or header.
+function requestUrl(origin, pathname, query) {
+  const url = new URL(pathname, origin);
+  if (url.origin !== origin || url.pathname !== pathname || url.search !== "") {
+    // Paths are constants from this package, so this is a programming error.
+    throw new Error("request path is not a fixed path on the origin");
+  }
+  if (query === null) return url;
+  const allowed = Object.hasOwn(READ_QUERY_KEYS, pathname) ? READ_QUERY_KEYS[pathname] : null;
+  if (!(query instanceof URLSearchParams) || allowed === null) {
+    throw new Error("a query is not allowed on this path");
+  }
+  const seen = new Set();
+  for (const key of query.keys()) {
+    if (!allowed.includes(key) || seen.has(key)) throw new Error("query key is not allowed");
+    seen.add(key);
+  }
+  const search = query.toString();
+  if (search.length > MAX_QUERY_LENGTH) throw new Error("query is too long");
+  url.search = search;
+  if (url.origin !== origin || url.pathname !== pathname) {
+    throw new Error("request path is not a fixed path on the origin");
+  }
+  return url;
+}
+
+// Sends one request to a fixed path on an already validated origin and
+// resolves (never rejects) with either
+//   { kind: "response", status, headers, body, tooLarge }
+//   { kind: "error", reason, status, sent }
+// reason is a fixed token from classifyError. sent is true when the whole
+// request had been handed to the network before the failure, so the server
+// may have acted on it (for example consumed a refresh token).
+// Redirects are returned with a null body and never followed. Bodies of every
+// other status are read up to maxBytes; a larger body sets tooLarge and is
+// discarded. The only credential ever sent is the bearer argument, and only
+// to this origin. Nothing is taken from the environment, and no cookies are
+// sent or kept. query is null or a URLSearchParams accepted by requestUrl.
+export function send(
+  origin,
+  pathname,
+  { method = "GET", signal, maxBytes, bearer = null, form = null, json = null, query = null },
+) {
+  const url = requestUrl(origin, pathname, query);
+
+  const headers = {
+    accept: "application/json",
+    "accept-encoding": "identity",
+    "user-agent": USER_AGENT,
+  };
+  let payload = null;
+  if (form !== null) {
+    payload = Buffer.from(new URLSearchParams(form).toString());
+    headers["content-type"] = "application/x-www-form-urlencoded";
+  } else if (json !== null) {
+    payload = Buffer.from(JSON.stringify(json));
+    headers["content-type"] = "application/json";
+  }
+  if (payload !== null) headers["content-length"] = String(payload.length);
+  if (bearer !== null) headers.authorization = `Bearer ${bearer}`;
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let status = null;
+    let sent = false;
+    const finish = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const fail = (error) => finish({ kind: "error", reason: classifyError(error, signal), status, sent });
+
+    const transport = url.protocol === "https:" ? https : http;
+    let request;
+    try {
+      request = transport.request(url, { method, agent: false, signal, headers });
+    } catch (error) {
+      fail(error);
+      return;
+    }
+
+    request.on("finish", () => {
+      sent = true;
+    });
+    request.on("error", fail);
+    request.on("response", (response) => {
+      response.on("error", fail);
+      status = response.statusCode;
+      const respond = (body, tooLarge) =>
+        finish({ kind: "response", status, headers: response.headers, body, tooLarge });
+
+      if (status >= 300 && status < 400) {
+        respond(null, false);
+        response.destroy();
+        return;
+      }
+      const declared = response.headers["content-length"];
+      if (declared !== undefined && Number(declared) > maxBytes) {
+        respond(null, true);
+        response.destroy();
+        return;
+      }
+      const chunks = [];
+      let size = 0;
+      response.on("data", (chunk) => {
+        size += chunk.length;
+        if (size > maxBytes) {
+          respond(null, true);
+          response.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => respond(Buffer.concat(chunks), false));
+      // A close without end means the body was cut off.
+      response.on("close", () => fail(null));
+    });
+    request.end(payload ?? undefined);
+  });
+}
+
+// Maps a transport result that cannot be used to { outcome, reason }, or
+// returns null when the response has a status the caller should inspect.
+export function failureOf(response) {
+  if (response.kind === "error") return { outcome: "connection_failed", reason: response.reason };
+  const { status } = response;
+  if (status >= 300 && status < 400) return { outcome: "redirect_rejected", reason: "redirect" };
+  if (status === 503) return { outcome: "unhealthy", reason: "service_unavailable" };
+  if (status >= 500) return { outcome: "unhealthy", reason: "server_error" };
+  if (response.tooLarge) return { outcome: "unsupported", reason: "response_too_large" };
+  return null;
+}
+
+// A deadline for one group of requests, optionally tied to a cancel signal.
+// timedOut tells a deadline apart from a cancellation.
+export function deadline(ms, cancel = null) {
+  const timer = AbortSignal.timeout(ms);
+  const signal = cancel === null ? timer : AbortSignal.any([timer, cancel]);
+  return { signal, timedOut: () => timer.aborted };
+}
+
+// Turns SIGINT, SIGTERM and SIGHUP into a cancel signal for the duration of
+// a command, so every listener, socket and lock is cleaned up and the
+// outcome is reported truthfully instead of the process dying mid-step.
+// release() must be called on every outcome.
+export function trapSignals() {
+  const controller = new AbortController();
+  const names = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const onSignal = () => controller.abort();
+  for (const name of names) process.on(name, onSignal);
+  return {
+    signal: controller.signal,
+    release() {
+      for (const name of names) process.removeListener(name, onSignal);
+    },
+  };
+}

package/src/verify-output.js

@@ -0,0 +1,36 @@
+const MESSAGES = Object.freeze({
+  invalid_trace_identity: "Provide exactly one exact trace or request ID from your application run.",
+  invalid_invocation_window: "Provide the start and end timestamps of that application invocation.",
+  invocation_window_outside_bounds: "The invocation is outside the requested Metadata window.",
+  verification_timeout: "The exact trace was not verified before the deadline.",
+  trace_not_found_within_bounds: "The exact trace is not visible in the bounded window yet.",
+  ambiguous_trace_identity: "More than one trace matches this request ID. Supply an exact trace ID.",
+  trace_outside_invocation_window: "The trace exists outside the stated invocation window.",
+  workspace_context_mismatch: "The trace response does not belong to the signed in workspace.",
+  link_workspace_binding_unavailable: "The trace is verified, but this dashboard link cannot select its workspace automatically. Open it manually in the correct workspace.",
+  server_link_unavailable: "The trace is verified, but the service did not provide a dashboard link.",
+  identity_query_unavailable: "The service cannot query an exact trace identity through Metadata access.",
+  capability_unavailable: "Trace Metadata access is unavailable for this workspace.",
+  login_required: "Sign in to this project with a Metadata-only grant before verifying a trace.",
+  forbidden: "This grant cannot read trace Metadata for the bound workspace.",
+});
+
+export function verifyMessage(outcome, reason) {
+  return MESSAGES[reason] ?? `Trace verification stopped (${outcome}). No application traffic claim was made.`;
+}
+
+export function verifyText(result) {
+  const data = result.data;
+  const lines = ["Metergraph exact trace verification", `Outcome: ${result.outcome} (exit ${result.exit_code})`];
+  if (data) {
+    lines.push(`Workspace: ${data.workspace.id}`, `Deployment: ${data.deployment_profile}`,
+      `Invocation source: ${data.invocation.source}`, `Attempts: ${data.attempts}`,
+      `Processed: ${data.readiness.processed}`, `Metadata available: ${data.readiness.metadata_available}`,
+      `Application traffic verified: ${data.application_traffic_verified}`);
+    if (data.trace) lines.push(`Trace ID: ${data.trace.trace_id}`);
+    if (data.app_url) lines.push(`Dashboard link${data.link_workspace_bound ? " (workspace bound)" : " (select the correct workspace)"}: ${data.app_url}`);
+    if (data.browser) lines.push(`Browser: ${data.browser}`);
+  }
+  if (result.error) lines.push(result.error.message);
+  return `${lines.join("\n")}\n`;
+}

package/src/verify.js

@@ -0,0 +1,120 @@
+import { setTimeout as wait } from "node:timers/promises";
+import { verifiedSession } from "./auth-session.js";
+import { Stop } from "./auth-store.js";
+import { AUTH_PATHS, READ_MAX_BYTES } from "./constants.js";
+import { parseJsonObject } from "./http.js";
+import { capabilitySummary } from "./read-contract.js";
+import { deadline, failureOf, send, trapSignals } from "./transport.js";
+import { traceReceipt, traceSelection } from "./trace-contract.js";
+import { openTrace } from "./trace-open.js";
+
+// One total deadline includes session refresh/lock waits and every poll.
+// The fixed MCP Metadata query reuses the service's identity resolver. No
+// retained content, ingestion, classification, provider or analysis call is
+// ever made here. Dependency hooks let deterministic tests own their service.
+export async function runVerify(options, dependencies = {}) {
+  const timeoutMs = options.timeoutMs ?? 30000;
+  const pollIntervalMs = options.pollIntervalMs ?? 1000;
+  const maxAttempts = options.maxAttempts ?? 30;
+  const selected = traceSelection(options);
+  if (!selected.ok) return { outcome: selected.outcome, reason: selected.reason, data: null };
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 60000 ||
+      !Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 100 || pollIntervalMs > 10000 ||
+      !Number.isSafeInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 60) {
+    return { outcome: "invalid_input", reason: "invalid_poll_bounds", data: null };
+  }
+  const trap = trapSignals();
+  const cancel = options.cancel ? AbortSignal.any([trap.signal, options.cancel]) : trap.signal;
+  const limit = deadline(timeoutMs, cancel);
+  let known = [];
+  let receipt = null;
+  let attempts = 0;
+  const end = (outcome, reason, data = receipt) => {
+    if (holdsKnown(data, known)) return { outcome: "verification_failed", reason: "credential_in_metadata_response", data: null };
+    return { outcome, reason, data: data === null ? null : { ...data, attempts } };
+  };
+  const interrupted = () => limit.timedOut() ? end("connection_failed", "verification_timeout") : end("cancelled", "cancelled");
+  try {
+    const sessionResult = await (dependencies.session ?? verifiedSession)({ project: options.project, configDir: options.configDir, cancel: limit.signal });
+    if (limit.signal.aborted) return interrupted();
+    if (!sessionResult.ok) return end(sessionResult.outcome, sessionResult.reason);
+    known = sessionResult.knownCredentials;
+    const session = sessionResult.session;
+    const ctx = { origin: session.origin, workspaceId: session.workspaceId, profile: session.profile };
+    const capabilities = capabilitySummary(sessionResult.documents.capabilities, ctx, new Set());
+    if (!capabilities.ok) return end(capabilities.outcome, capabilities.reason);
+    if (capabilities.value.agent.trace_metadata?.available !== true) return end("capability_unavailable", "capability_unavailable");
+    if (selected.value.days > capabilities.value.bounds.max_days || capabilities.value.bounds.max_rows < 2) return end("unsupported", "exceeds_service_bounds");
+    for (attempts = 1; attempts <= maxAttempts; attempts++) {
+      if (limit.signal.aborted) return interrupted();
+      const response = await queryTrace(session, selected.value, attempts, limit.signal, dependencies.send ?? send);
+      if (limit.signal.aborted) return interrupted();
+      if (!response.ok) return end(response.outcome, response.reason);
+      const checked = traceReceipt(response.body, ctx, selected.value);
+      if (!checked.ok) return end(checked.outcome, checked.reason);
+      receipt = checked.value;
+      if (holdsKnown(receipt, known)) return end("verification_failed", "credential_in_metadata_response", null);
+      if (checked.found) {
+        if (options.open) {
+          const opened = await openTrace(receipt, { ...options, signal: limit.signal }, dependencies.launch);
+          if (limit.signal.aborted) return interrupted();
+          return end(opened.outcome, opened.reason, opened.data);
+        }
+        return end("ok", null);
+      }
+      if (attempts === maxAttempts) return end("verification_failed", "trace_not_found_within_bounds");
+      try { await wait(pollIntervalMs, null, { signal: limit.signal }); } catch { return interrupted(); }
+    }
+  } catch (error) {
+    if (limit.signal.aborted) return interrupted();
+    if (error instanceof Stop) return end(error.outcome, error.reason);
+    throw error;
+  } finally { trap.release(); }
+}
+
+async function queryTrace(session, selection, id, signal, request) {
+  const args = { days: selection.days, limit: 2, [selection.traceId === null ? "request_id" : "trace_id"]: selection.traceId ?? selection.requestId };
+  const response = await request(session.origin, AUTH_PATHS.resource, {
+    method: "POST", signal, maxBytes: READ_MAX_BYTES, bearer: session.accessToken,
+    json: { jsonrpc: "2.0", id, method: "tools/call", params: { name: "metergraph_query_traces", arguments: args } },
+  });
+  if (response.kind === "response") {
+    if (response.status === 401) return failure("login_required", "access_revoked");
+    if (response.status === 403) return failure("permission_denied", "forbidden");
+    if (response.status === 429) return failure("rate_limited", "rate_limited");
+    if (response.status === 404) return failure("unsupported", "endpoint_unavailable");
+  }
+  const fault = failureOf(response);
+  if (fault !== null) return { ok: false, ...fault };
+  if (response.status !== 200) return failure("unsupported", "unexpected_status");
+  const message = parseJsonObject(response);
+  const result = message?.result;
+  if (message?.jsonrpc === "2.0" && message.id === id && [-32601, -32602].includes(message.error?.code)) {
+    return failure("unsupported", "identity_query_unavailable");
+  }
+  if (message?.jsonrpc !== "2.0" || message.id !== id || message.error !== undefined ||
+      result === null || typeof result !== "object" || Array.isArray(result) || typeof result.isError !== "boolean") return failure("verification_failed", "trace_response_invalid");
+  if (result.isError) {
+    const code = result.structuredContent?.error?.code;
+    const errors = { forbidden: ["permission_denied", "forbidden"], unsupported_capability: ["capability_unavailable", "capability_unavailable"], not_found: ["unsupported", "identity_query_unavailable"], rate_limited: ["rate_limited", "rate_limited"], response_too_large: ["unsupported", "response_too_large"] };
+    return Object.hasOwn(errors, code) ? failure(...errors[code]) : failure("unsupported", "identity_query_unavailable");
+  }
+  return { ok: true, body: result.structuredContent };
+}
+
+const failure = (outcome, reason) => ({ ok: false, outcome, reason });
+function holdsKnown(value, known) {
+  if (typeof value === "string") {
+    // A server link can URI-encode a credential into an otherwise allowed
+    // query value. Check the decoded URL as well as its printed spelling.
+    const variants = [value];
+    try { variants.push(decodeURIComponent(value)); } catch { /* Plain metadata need not be URI encoded. */ }
+    if (value.includes("#traces?")) {
+      const query = new URLSearchParams(value.slice(value.indexOf("#traces?") + 8));
+      for (const [key, entry] of query) variants.push(key, entry);
+    }
+    return known.some((secret) => typeof secret === "string" && secret.length > 0 && variants.some((variant) => variant.includes(secret)));
+  }
+  if (value === null || typeof value !== "object") return false;
+  return Object.entries(value).some(([key, entry]) => holdsKnown(key, known) || holdsKnown(entry, known));
+}