@malloy-publisher/server 0.0.235 → 0.0.236

package/src/query_timeout.ts

@@ -1,179 +0,0 @@
-import { type Counter } from "@opentelemetry/api";
-import { publisherMeter } from "./telemetry";
-
-import { getQueryTimeoutMs } from "./config";
-import { QueryTimeoutError } from "./errors";
-
-/**
- * Lazy-initialized telemetry. Instruments are created on first use
- * rather than at module load so unit tests that install a real
- * MeterProvider AFTER the module is imported still record their
- * data — OTel JS's `ProxyMeter` binds counters created before
- * `setGlobalMeterProvider` to NoOp instruments (see
- * https://github.com/open-telemetry/opentelemetry-js/issues/3505).
- * In production the first request triggers initialization, which
- * is well after `server.ts` boot and any OTel SDK setup, so the
- * lazy-init has no observable latency cost.
- */
-let queryTimeoutCounter: Counter | null = null;
-let timeoutTelemetryInitialized = false;
-/**
- * Idempotent installer for the timeout counter + config gauge.
- * Called at the top of {@link runWithQueryTimeout} (every path,
- * including the opt-out branch) so the gauge is registered with
- * the OTel SDK as soon as the publisher serves its first query —
- * not just on the first timeout firing. Returns the counter for
- * convenience.
- */
-function ensureTimeoutTelemetry(): Counter {
-   if (queryTimeoutCounter && timeoutTelemetryInitialized) {
-      return queryTimeoutCounter;
-   }
-   const meter = publisherMeter();
-   if (!queryTimeoutCounter) {
-      queryTimeoutCounter = meter.createCounter(
-         "publisher_query_timeout_total",
-         {
-            description:
-               "Queries aborted because PUBLISHER_QUERY_TIMEOUT_MS elapsed before the underlying SDK call completed",
-         },
-      );
-   }
-   if (!timeoutTelemetryInitialized) {
-      // Observable gauge so dashboards can render the *configured*
-      // timeout alongside actual query durations from
-      // `malloy_model_query_duration` /
-      // `http_server_request_duration_ms`. Read live on each
-      // scrape so an env-var change between scrapes is visible
-      // without a restart.
-      meter
-         .createObservableGauge("publisher_query_timeout_ms", {
-            description:
-               "Current effective PUBLISHER_QUERY_TIMEOUT_MS (0 = disabled)",
-            unit: "ms",
-         })
-         .addCallback((observation) => {
-            try {
-               observation.observe(getQueryTimeoutMs());
-            } catch {
-               // A misconfigured env var should fail the request
-               // that observes it, not the metric scrape. Surface
-               // as -1 so dashboards reveal the misconfig rather
-               // than silently dropping the sample.
-               observation.observe(-1);
-            }
-         });
-      timeoutTelemetryInitialized = true;
-   }
-   return queryTimeoutCounter;
-}
-
-/**
- * Visible for tests so they can re-trigger lazy init against a
- * freshly-installed MeterProvider between cases. Do NOT call from
- * production code.
- */
-export function resetQueryTimeoutTelemetryForTesting(): void {
-   queryTimeoutCounter = null;
-   timeoutTelemetryInitialized = false;
-}
-
-/**
- * Per-query wall-clock guard. Hands an {@link AbortSignal} to `fn`
- * and arms a `setTimeout` for `timeoutMs`. When the timer fires the
- * signal is aborted with reason `Symbol.for("publisher.queryTimeout")`
- * so downstream catch blocks can distinguish a publisher-issued
- * timeout from a caller cancel or a driver-internal abort.
- *
- * Contract:
- * - `fn` MUST forward `signal` into the underlying SDK call
- *   (`runSQLOptions.abortSignal`, `runnable.run({ abortSignal })`,
- *   etc.) so the abort actually cancels the work — not just unblocks
- *   the awaiter. Failure to forward leaks the query for `timeoutMs`
- *   beyond the 504 response.
- * - `timeoutMs === 0` opts out (no timer is armed); the signal is
- *   still passed for consistency. Use when an operator deliberately
- *   sets `PUBLISHER_QUERY_TIMEOUT_MS=0`.
- * - On timeout AND a subsequent rejection from `fn`, this throws
- *   {@link QueryTimeoutError}. If `fn` happens to resolve cleanly
- *   between "timer fired" and "we entered the catch" (a race that
- *   any driver can win), the success value is returned to the
- *   caller — a query that completed is more useful than a 504 with
- *   an already-materialized result. The timeout counter ticks only
- *   when 504 is actually emitted.
- * - On non-timeout error, the underlying error is re-thrown
- *   unmodified.
- */
-export async function runWithQueryTimeout<T>(
-   fn: (signal: AbortSignal) => Promise<T>,
-   timeoutMs: number,
-): Promise<T> {
-   // Install telemetry on every call (idempotent) so the
-   // `publisher_query_timeout_ms` gauge shows up in `/metrics` as
-   // soon as the publisher serves its first query, even if no
-   // timeout ever fires. Without this, the gauge would be absent
-   // until the first 504 — useless for "tune the timeout BEFORE
-   // you get paged" workflows.
-   ensureTimeoutTelemetry();
-
-   if (timeoutMs <= 0) {
-      // Opt-out path: no timer, no abort. We still pass a never-aborts
-      // signal so `fn`'s signature is uniform and forwarding stays
-      // mechanical — no per-call branching for "did we get a timeout?".
-      const ac = new AbortController();
-      return fn(ac.signal);
-   }
-
-   const ac = new AbortController();
-   const reason = PUBLISHER_QUERY_TIMEOUT_REASON;
-   let timedOut = false;
-   const timer = setTimeout(() => {
-      timedOut = true;
-      // `abort(reason)` propagates the reason through `signal.reason`
-      // so a downstream catch can `signal.reason === reason` to tell
-      // "publisher timeout" from "client disconnect" from "driver
-      // internal error" without string-matching error messages.
-      ac.abort(reason);
-   }, timeoutMs);
-   // Match HTTP request lifecycle: don't keep the event loop alive
-   // just for the timer. If the process is shutting down and the
-   // query has already resolved, we don't want this hanging the
-   // graceful-shutdown.
-   timer.unref?.();
-
-   try {
-      return await fn(ac.signal);
-   } catch (error) {
-      if (timedOut) {
-         // Increment before throwing so the counter ticks even if
-         // the controller swallows the error (the MCP tool's catch
-         // surfaces failures as content payloads, for instance).
-         // Carry the configured timeout as a label so dashboards
-         // can pivot a flapping pod between "we tuned the env var
-         // down" and "queries got slower".
-         ensureTimeoutTelemetry().add(1, { timeout_ms: timeoutMs });
-         throw new QueryTimeoutError(
-            `Query exceeded PUBLISHER_QUERY_TIMEOUT_MS (${timeoutMs}ms) and was aborted. Refine the query (add a more selective WHERE, lower LIMIT, or simplify joins) or raise the timeout.`,
-         );
-      }
-      throw error;
-   } finally {
-      clearTimeout(timer);
-   }
-}
-
-/**
- * Sentinel attached to `AbortSignal.reason` when a publisher-issued
- * query timeout fires. Currently consumed by `runWithQueryTimeout`
- * itself (and by tests verifying the wiring); exported so future
- * call sites composing this signal with their own (e.g. a custom
- * driver wrapper) can write `if (signal.reason === PUBLISHER_QUERY_TIMEOUT_REASON)`
- * to detect "this was the publisher's timeout, not the cap" without
- * coupling to error-message strings. `runWithQueryTimeout`'s own
- * timeout-vs-other-error distinction uses the local `timedOut`
- * flag rather than this symbol, so consumers can rely on the
- * symbol being attached even if the implementation changes.
- */
-export const PUBLISHER_QUERY_TIMEOUT_REASON = Symbol.for(
-   "publisher.queryTimeout",
-);

package/src/runtime/publisher.js

@@ -1,328 +0,0 @@
-// Publisher runtime helper for in-package HTML dashboards.
-// Served by the Publisher server at /sdk/publisher.js. Hand-authored vanilla
-// JS — no bundler. Loaded via <script src="/sdk/publisher.js">.
-//
-// Exposes window.Publisher with:
-//   - Publisher.query(model, malloy, opts?)     → Promise<rows[]>
-//   - Publisher.queryFull(model, malloy, opts?) → Promise<MalloyResult>  (envelope for <malloy-render>)
-//       opts: { environment?, package?, sourceName?, queryName?, filterParams?,
-//               bypassFilters?, givens? }. givens is a name→value map bound as
-//               Malloy given: runtime parameters for this query (safe parameterization,
-//               not string interpolation) — see the malloy-html-data-app-runtime skill.
-//   - Publisher.embed(selector, { src, height?, token? })
-//   - Publisher.context  ({ environment, package } inferred from URL)
-//   - Publisher.setToken(token)  (override Bearer token; default uses cookies)
-//
-// When loaded inside an iframe served from /environments/<env>/packages/<pkg>/...,
-// the runtime auto-subscribes to a Server-Sent Events live-reload stream
-// (GET .../events) and reloads the page on file changes. It also posts size
-// updates to the parent window so Publisher.embed() in the host can resize
-// the iframe.
-//
-// The "publisher:resize" postMessage protocol below is the SAME contract the
-// SPA host consumes. Its canonical definition lives in
-// packages/sdk/src/utils/pageEmbed.ts (PUBLISHER_RESIZE_MESSAGE_TYPE /
-// PublisherResizeMessage). This file is build-step-free vanilla JS and can't
-// import it, so keep the message type/shape here in sync with that module.
-
-(function () {
-   "use strict";
-
-   // --- Context inference -------------------------------------------------
-   // URL shape: /environments/<env>/packages/<pkg>/<file>
-   //
-   // location.pathname is URL-encoded, so we MUST decode the captured
-   // segments here. Without this step, a name with a space (e.g.
-   // "demo env") would arrive as "demo%20env" — and the encodeURIComponent
-   // we apply when building API URLs (below) would produce "demo%2520env",
-   // which Publisher then 404s on.
-   var pathMatch = location.pathname.match(
-      /^\/environments\/([^/]+)\/packages\/([^/]+)\//,
-   );
-   function safeDecode(s) {
-      try {
-         return decodeURIComponent(s);
-      } catch (_e) {
-         return s;
-      }
-   }
-   var ctx = pathMatch
-      ? {
-           environment: safeDecode(pathMatch[1]),
-           package: safeDecode(pathMatch[2]),
-        }
-      : {};
-
-   var apiBase = location.origin + "/api/v0";
-   var bearerToken = null;
-
-   function authHeaders() {
-      return bearerToken ? { Authorization: "Bearer " + bearerToken } : {};
-   }
-
-   // --- Query helpers -----------------------------------------------------
-   function resolveTarget(opts) {
-      var env = (opts && opts.environment) || ctx.environment;
-      var pkg = (opts && opts.package) || ctx.package;
-      if (!env || !pkg) {
-         throw new Error(
-            "Publisher: no environment/package; either serve the page from " +
-               "/environments/<env>/packages/<pkg>/... or pass { environment, package } in opts.",
-         );
-      }
-      return { env: env, pkg: pkg };
-   }
-
-   async function rawQuery(modelPath, malloyQuery, opts, compactJson) {
-      opts = opts || {};
-      var target = resolveTarget(opts);
-      var url =
-         apiBase +
-         "/environments/" +
-         encodeURIComponent(target.env) +
-         "/packages/" +
-         encodeURIComponent(target.pkg) +
-         "/models/" +
-         // Encode the whole model path as ONE path segment (slashes -> %2F). A model
-         // in a subfolder ("model/x.malloy") must not become two URL segments: some
-         // servers only match a single-segment {path} and would 405 a multi-segment
-         // path. This matches the typed SDK (encodeURIComponent) and the server's
-         // encoded-slash handling.
-         encodeURIComponent(modelPath) +
-         "/query";
-      var body = { compactJson: compactJson };
-      if (malloyQuery) body.query = malloyQuery;
-      if (opts.sourceName) body.sourceName = opts.sourceName;
-      if (opts.queryName) body.queryName = opts.queryName;
-      if (opts.filterParams) body.filterParams = opts.filterParams;
-      if (opts.bypassFilters) body.bypassFilters = true;
-      if (opts.givens) body.givens = opts.givens;
-
-      var headers = Object.assign(
-         { "content-type": "application/json" },
-         authHeaders(),
-      );
-      var res = await fetch(url, {
-         method: "POST",
-         credentials: "include",
-         headers: headers,
-         body: JSON.stringify(body),
-      });
-      var json;
-      try {
-         json = await res.json();
-      } catch (_e) {
-         throw new Error(
-            "Publisher: server returned non-JSON response (" + res.status + ")",
-         );
-      }
-      if (!res.ok) {
-         var msg = (json && json.message) || res.statusText || "Query failed";
-         var err = new Error("Publisher.query: " + msg);
-         err.response = json;
-         err.status = res.status;
-         throw err;
-      }
-      // The server's QueryResult always has `result` as a JSON-encoded string.
-      // Parse it before handing it back so callers see real JS values.
-      return JSON.parse(json.result);
-   }
-
-   function query(modelPath, malloyQuery, opts) {
-      return rawQuery(modelPath, malloyQuery, opts, true);
-   }
-   function queryFull(modelPath, malloyQuery, opts) {
-      return rawQuery(modelPath, malloyQuery, opts, false);
-   }
-
-   // --- Embed helper (host page) -----------------------------------------
-   function embed(selector, options) {
-      options = options || {};
-      var host =
-         typeof selector === "string"
-            ? document.querySelector(selector)
-            : selector;
-      if (!host) {
-         throw new Error("Publisher.embed: selector did not match an element");
-      }
-      if (!options.src) {
-         throw new Error("Publisher.embed: opts.src is required");
-      }
-      var iframe = document.createElement("iframe");
-      iframe.src = options.token
-         ? options.src +
-           (options.src.indexOf("?") === -1 ? "?" : "&") +
-           "embed_token=" +
-           encodeURIComponent(options.token)
-         : options.src;
-      iframe.style.border = "0";
-      iframe.style.width = "100%";
-      iframe.style.display = "block";
-      if (options.height) {
-         iframe.style.height =
-            typeof options.height === "number"
-               ? options.height + "px"
-               : options.height;
-      } else {
-         iframe.style.height = "0px"; // will be sized via postMessage
-      }
-      if (options.allow) iframe.allow = options.allow;
-      iframe.setAttribute(
-         "sandbox",
-         "allow-scripts allow-same-origin allow-forms",
-      );
-
-      // Resize listener
-      function onMessage(e) {
-         if (!e.data || e.data.type !== "publisher:resize") return;
-         if (e.source !== iframe.contentWindow) return;
-         if (typeof e.data.height === "number") {
-            iframe.style.height = Math.max(0, e.data.height) + "px";
-         }
-      }
-      window.addEventListener("message", onMessage);
-      // Best-effort cleanup if the host removes the iframe
-      var observer = new MutationObserver(function () {
-         if (!host.contains(iframe)) {
-            window.removeEventListener("message", onMessage);
-            observer.disconnect();
-         }
-      });
-      observer.observe(host, { childList: true, subtree: false });
-
-      host.appendChild(iframe);
-      return {
-         iframe: iframe,
-         destroy: function () {
-            window.removeEventListener("message", onMessage);
-            observer.disconnect();
-            if (iframe.parentNode) iframe.parentNode.removeChild(iframe);
-         },
-      };
-   }
-
-   // --- When this runtime is itself inside an iframe ---------------------
-   // Post size updates upstream + listen for live-reload SSE events.
-   function setUpEmbeddedSelfBehaviors() {
-      var inIframe = (function () {
-         try {
-            return window.self !== window.top;
-         } catch (_e) {
-            return true; // cross-origin parent — assume embedded
-         }
-      })();
-
-      if (inIframe) {
-         var lastHeight = -1;
-         function measureContentHeight() {
-            // We want the "ink height" — where the last piece of visible
-            // content ends. NOT document.body.scrollHeight: any rule like
-            // `body { min-height: 100vh }` (extremely common in dashboards
-            // that look nice standalone) inflates scrollHeight to match
-            // whatever the iframe's current viewport is, creating a
-            // feedback loop where the iframe ratchets up but never shrinks.
-            //
-            // Sum the lowest bottom edge across body's children, in
-            // document coordinates. This ignores body padding, min-height,
-            // and CSS that just fills the viewport.
-            var body = document.body;
-            if (!body) return document.documentElement.scrollHeight;
-            var maxBottom = 0;
-            var kids = body.children;
-            for (var i = 0; i < kids.length; i++) {
-               var rect = kids[i].getBoundingClientRect();
-               if (rect.bottom > maxBottom) maxBottom = rect.bottom;
-            }
-            if (maxBottom <= 0) {
-               // Fallback for empty body / hidden children
-               return document.documentElement.scrollHeight;
-            }
-            var scrollTop =
-               window.scrollY ||
-               document.documentElement.scrollTop ||
-               document.body.scrollTop ||
-               0;
-            // Add body bottom padding (rect.bottom is content-box bottom,
-            // body padding isn't part of any child's rect).
-            var bodyStyle = window.getComputedStyle(body);
-            var pad = parseFloat(bodyStyle.paddingBottom) || 0;
-            return Math.ceil(maxBottom + scrollTop + pad);
-         }
-         function postSize() {
-            var h = measureContentHeight();
-            if (h !== lastHeight) {
-               lastHeight = h;
-               try {
-                  window.parent.postMessage(
-                     { type: "publisher:resize", height: h },
-                     "*",
-                  );
-               } catch (_e) {
-                  /* ignore */
-               }
-            }
-         }
-         // Initial + observe content changes
-         if (document.readyState === "loading") {
-            document.addEventListener("DOMContentLoaded", postSize);
-         } else {
-            postSize();
-         }
-         window.addEventListener("load", postSize);
-         if (typeof ResizeObserver !== "undefined") {
-            var ro = new ResizeObserver(postSize);
-            // Observe documentElement so we catch any layout change
-            ro.observe(document.documentElement);
-         } else {
-            // Fallback: poll once a second
-            setInterval(postSize, 1000);
-         }
-      }
-   }
-
-   // --- SSE live reload --------------------------------------------------
-   function setUpLiveReload() {
-      if (!ctx.environment || !ctx.package) return;
-      if (typeof EventSource === "undefined") return;
-      var url =
-         apiBase +
-         "/environments/" +
-         encodeURIComponent(ctx.environment) +
-         "/packages/" +
-         encodeURIComponent(ctx.package) +
-         "/events";
-      try {
-         var es = new EventSource(url, { withCredentials: true });
-         var pending = false;
-         es.addEventListener("changed", function () {
-            if (pending) return;
-            pending = true;
-            // Tiny debounce to coalesce a flurry of saves
-            setTimeout(function () {
-               location.reload();
-            }, 100);
-         });
-         es.onerror = function () {
-            // Browser will auto-reconnect; nothing to do.
-         };
-      } catch (_e) {
-         // SSE may be blocked (e.g. corp proxy) — non-fatal.
-      }
-   }
-
-   // --- Public API --------------------------------------------------------
-   window.Publisher = {
-      query: query,
-      queryFull: queryFull,
-      embed: embed,
-      context: ctx,
-      setToken: function (token) {
-         bearerToken = token || null;
-      },
-   };
-
-   // Auto-init the in-iframe behaviors and live-reload subscription.
-   // Both are no-ops if not applicable.
-   setUpEmbeddedSelfBehaviors();
-   setUpLiveReload();
-})();