@malloy-publisher/server 0.0.205 → 0.0.207

package/src/health.spec.ts

@@ -1,7 +1,16 @@
-import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import {
+   afterAll,
+   afterEach,
+   beforeEach,
+   describe,
+   expect,
+   it,
+   spyOn,
+} from "bun:test";
 import { Server } from "http";
 import { performGracefulShutdownAfterDrain } from "./health";
 import { logger } from "./logger";
+import { __setPackageLoadPoolForTests } from "./package_load/package_load_pool";
 
 // Regression test for the graceful-shutdown ordering bug that caused
 //   [winston] Attempt to write logs with no transports: {"message":"Waiting 50 seconds..."}
@@ -16,6 +25,18 @@ describe("performGracefulShutdownAfterDrain: shutdown ordering", () => {
    const originalExit = process.exit;
    let callOrder: string[];
 
+   afterAll(async () => {
+      // performGracefulShutdownAfterDrain drains the package-load worker pool
+      // via getPackageLoadPool().shutdown() — which lazily CREATES the global
+      // singleton and leaves it installed in its shut-down state. In prod the
+      // process exits right after, so that's fine; in this shared test process
+      // it poisons every later spec that touches the worker path
+      // (Package.create → "PackageLoadPool is shutting down"), with failures
+      // that come and go with bun's platform-dependent file order. Reset the
+      // singleton so the next user lazily creates a fresh pool.
+      await __setPackageLoadPoolForTests(null);
+   });
+
    beforeEach(() => {
       callOrder = [];
 
@@ -41,6 +62,18 @@ describe("performGracefulShutdownAfterDrain: shutdown ordering", () => {
       process.exit = originalExit;
    });
 
+   // performGracefulShutdownAfterDrain lazily creates and shuts down the
+   // module-level PackageLoadPool singleton. If we leave that shut-down
+   // pool installed, sibling specs that run later in the same Bun process
+   // (e.g. package.spec.ts, package_race.spec.ts) inherit a dead pool and
+   // fail with "PackageLoadPool is shutting down". Reset the singleton so
+   // the next getPackageLoadPool() spins up a fresh one. The leaked-pool
+   // ordering is filesystem-readdir dependent, which is why it only
+   // surfaced on Linux CI.
+   afterAll(async () => {
+      await __setPackageLoadPoolForTests(null);
+   });
+
    const fakeServer = (): Server => ({ listening: false }) as unknown as Server;
 
    it("logs the 'Waiting ...' message before closing the logger", async () => {

package/src/instrumentation.ts

@@ -121,8 +121,20 @@ const httpRequestCount = meter.createCounter("http_server_requests_total", {
 // /health/liveness probe (a pure synchronous 200 handler) can fail under K8s,
 // so we surface p50/p99/max so an operator can correlate liveness restarts
 // with sustained event-loop pressure (large Malloy compiles, GC, etc.).
-const eventLoopHistogram = monitorEventLoopDelay({ resolution: 20 });
-eventLoopHistogram.enable();
+//
+// `monitorEventLoopDelay` is a Node-only API; some runtimes (e.g. Bun on
+// certain platforms, used by the integration test suite) don't implement it.
+// Degrade gracefully there rather than crashing module load: the metrics are
+// simply not registered.
+const eventLoopHistogram = (() => {
+   try {
+      const histogram = monitorEventLoopDelay({ resolution: 20 });
+      histogram.enable();
+      return histogram;
+   } catch {
+      return null;
+   }
+})();
 
 const eventLoopLagP50 = meter.createObservableGauge(
    "publisher_event_loop_lag_p50_ms",
@@ -150,21 +162,25 @@ const eventLoopLagMax = meter.createObservableGauge(
 );
 
 // Sample all three in one batch so the histogram reset can't race the reads.
-meter.addBatchObservableCallback(
-   (observableResult) => {
-      observableResult.observe(
-         eventLoopLagP50,
-         eventLoopHistogram.percentile(50) / 1e6,
-      );
-      observableResult.observe(
-         eventLoopLagP99,
-         eventLoopHistogram.percentile(99) / 1e6,
-      );
-      observableResult.observe(eventLoopLagMax, eventLoopHistogram.max / 1e6);
-      eventLoopHistogram.reset();
-   },
-   [eventLoopLagP50, eventLoopLagP99, eventLoopLagMax],
-);
+// Skipped entirely when the runtime lacks event-loop-delay monitoring.
+if (eventLoopHistogram) {
+   const histogram = eventLoopHistogram;
+   meter.addBatchObservableCallback(
+      (observableResult) => {
+         observableResult.observe(
+            eventLoopLagP50,
+            histogram.percentile(50) / 1e6,
+         );
+         observableResult.observe(
+            eventLoopLagP99,
+            histogram.percentile(99) / 1e6,
+         );
+         observableResult.observe(eventLoopLagMax, histogram.max / 1e6);
+         histogram.reset();
+      },
+      [eventLoopLagP50, eventLoopLagP99, eventLoopLagMax],
+   );
+}
 
 const IGNORED_PATHS = new Set([
    "/health",

package/src/materialization_metrics.ts

@@ -0,0 +1,121 @@
+/**
+ * Centralized telemetry for the two-round materialization protocol.
+ *
+ * Operators need to answer "are builds completing, how long do the two
+ * rounds take, and where are they failing?" without grepping logs. The
+ * counter carries `round` (`round1`|`round2`) and `outcome`
+ * (`success`|`failed`|`cancelled`); the histogram carries `round` so a
+ * dashboard can render Round 1 (compile+plan) vs Round 2 (build) latency
+ * side by side.
+ *
+ * Lazy init for the same reason as {@link ./query_cap_metrics}: instruments
+ * created before `setGlobalMeterProvider` bind to a NoOp meter
+ * (https://github.com/open-telemetry/opentelemetry-js/issues/3505).
+ */
+
+import { metrics, type Counter, type Histogram } from "@opentelemetry/api";
+
+export type MaterializationRound = "round1" | "round2" | "auto";
+export type MaterializationOutcome = "success" | "failed" | "cancelled";
+/** Manifest bind outcome: timeout is split out from generic failure on purpose. */
+export type ManifestBindOutcome = "success" | "failure" | "timeout";
+
+let roundCounter: Counter | null = null;
+let roundDuration: Histogram | null = null;
+let manifestBindCounter: Counter | null = null;
+let sourceBuildDuration: Histogram | null = null;
+let dropTablesCounter: Counter | null = null;
+
+function ensureTelemetry(): { counter: Counter; duration: Histogram } {
+   if (roundCounter && roundDuration) {
+      return { counter: roundCounter, duration: roundDuration };
+   }
+   const meter = metrics.getMeter("publisher");
+   if (!roundCounter) {
+      roundCounter = meter.createCounter(
+         "publisher_materialization_rounds_total",
+         {
+            description:
+               "Materialization rounds completed. Labels: round ('round1'|'round2'|'auto'), outcome ('success'|'failed'|'cancelled').",
+         },
+      );
+   }
+   if (!roundDuration) {
+      roundDuration = meter.createHistogram(
+         "publisher_materialization_round_duration_ms",
+         {
+            description:
+               "Wall-clock duration of a materialization round. Label: round ('round1'|'round2'|'auto').",
+            unit: "ms",
+         },
+      );
+   }
+   return { counter: roundCounter, duration: roundDuration };
+}
+
+/** Record the outcome and duration of a materialization round. */
+export function recordMaterializationRound(
+   round: MaterializationRound,
+   outcome: MaterializationOutcome,
+   durationMs: number,
+): void {
+   const { counter, duration } = ensureTelemetry();
+   counter.add(1, { round, outcome });
+   duration.record(durationMs, { round });
+}
+
+/**
+ * Record a manifest-bind attempt (publisher binding a control-plane manifest to
+ * a package at load). `timeout` is distinguished from `failure` so operators can
+ * tell an unreachable/slow manifest store from a malformed manifest.
+ */
+export function recordManifestBind(outcome: ManifestBindOutcome): void {
+   if (!manifestBindCounter) {
+      manifestBindCounter = metrics
+         .getMeter("publisher")
+         .createCounter("publisher_materialization_manifest_bind_total", {
+            description:
+               "Manifest bind attempts. Label: outcome ('success'|'failure'|'timeout').",
+         });
+   }
+   manifestBindCounter.add(1, { outcome });
+}
+
+/** Record the wall-clock duration of building one persist source's table. */
+export function recordSourceBuildDuration(durationMs: number): void {
+   if (!sourceBuildDuration) {
+      sourceBuildDuration = metrics
+         .getMeter("publisher")
+         .createHistogram(
+            "publisher_materialization_source_build_duration_ms",
+            {
+               description:
+                  "Wall-clock duration of building a single persist source.",
+               unit: "ms",
+            },
+         );
+   }
+   sourceBuildDuration.record(durationMs);
+}
+
+/** Record a best-effort physical-table drop on materialization delete. */
+export function recordDropTables(outcome: "success" | "failure"): void {
+   if (!dropTablesCounter) {
+      dropTablesCounter = metrics
+         .getMeter("publisher")
+         .createCounter("publisher_materialization_drop_tables_total", {
+            description:
+               "Physical tables dropped on delete. Label: outcome ('success'|'failure').",
+         });
+   }
+   dropTablesCounter.add(1, { outcome });
+}
+
+/** Visible for tests. Drops cached instruments so a fresh MeterProvider can capture emissions. */
+export function resetMaterializationTelemetryForTesting(): void {
+   roundCounter = null;
+   roundDuration = null;
+   manifestBindCounter = null;
+   sourceBuildDuration = null;
+   dropTablesCounter = null;
+}

package/src/package_load/package_load_pool.ts

@@ -228,7 +228,13 @@ export interface LoadPackageJob {
  * don't allocate a Map for models the caller never looks at.
  */
 export interface LoadPackageOutcome {
-   packageMetadata: { name?: string; description?: string };
+   packageMetadata: {
+      name?: string;
+      description?: string;
+      explores?: string[];
+      queryableSources?: "declared" | "all";
+      manifestLocation?: string | null;
+   };
    models: Array<
       Omit<SerializedModel, "modelDef" | "sourceInfos"> & {
          modelDef?: ModelDef;

package/src/package_load/package_load_worker.ts

@@ -75,6 +75,7 @@ import { fileURLToPath, pathToFileURL } from "url";
 
 import {
    MODEL_FILE_SUFFIX,
+   normalizeModelPath,
    NOTEBOOK_FILE_SUFFIX,
    PACKAGE_MANIFEST_NAME,
 } from "../constants";
@@ -375,16 +376,38 @@ function buildWorkerMalloyConfig(job: LoadPackageRequest): MalloyConfig {
 // stays decoupled from the main-thread service module graph)
 // ──────────────────────────────────────────────────────────────────────
 
-async function readPackageMetadata(
-   packagePath: string,
-): Promise<{ name?: string; description?: string }> {
+async function readPackageMetadata(packagePath: string): Promise<{
+   name?: string;
+   description?: string;
+   explores?: string[];
+   queryableSources?: "declared" | "all";
+   manifestLocation?: string | null;
+}> {
    const manifestPath = path.join(packagePath, PACKAGE_MANIFEST_NAME);
    const contents = await fs.promises.readFile(manifestPath, "utf8");
    const parsed = JSON.parse(contents) as {
       name?: string;
       description?: string;
+      explores?: string[];
+      queryableSources?: unknown;
+      manifestLocation?: unknown;
+   };
+   return {
+      name: parsed.name,
+      description: parsed.description,
+      explores: Array.isArray(parsed.explores)
+         ? parsed.explores.map(normalizeModelPath)
+         : undefined,
+      // Default + invalid fall back to "declared" (fail-safe: queryable ==
+      // discoverable). Only an explicit "all" opts out of the query boundary.
+      queryableSources: parsed.queryableSources === "all" ? "all" : "declared",
+      // URI (gs://, s3://, file://, or local path) of the control-plane-computed
+      // build manifest. The main thread fetches + binds it after load.
+      manifestLocation:
+         typeof parsed.manifestLocation === "string"
+            ? parsed.manifestLocation
+            : null,
    };
-   return { name: parsed.name, description: parsed.description };
 }
 
 async function listPackageFiles(packagePath: string): Promise<string[]> {
@@ -400,6 +423,18 @@ function filterModelPaths(allRelative: string[]): string[] {
    );
 }
 
+// `normalizeModelPath` (shared, from ../constants) runs here at parse time so
+// the keys stored in Package.models are already normalized, and the API
+// publish/update path normalizes its `explores` input through the same helper —
+// so on-disk and API-written manifests share one representation.
+
+// explores validation is intentionally NOT done here. The worker is the
+// shared load path (startup, reload, AND publish), but the policy differs by
+// context — strict-reject at publish, warn-and-fail-safe at load — so it lives
+// on the main thread (see Package.getInvalidExplores / loadViaWorker and the
+// publish path in package.controller). An unmatched entry simply lists nothing
+// (listModels filters by set membership), which is the fail-safe outcome.
+
 // ──────────────────────────────────────────────────────────────────────
 // Model compile (mirrors service/model.ts but produces SerializedModel)
 // ──────────────────────────────────────────────────────────────────────
@@ -558,6 +593,10 @@ async function compileMalloyModel(
       modelDef,
       modelInfo: modelDefToModelInfo(modelDef),
       sourceInfos,
+      // `sources`/`queries` ship complete (authorize + filter enforcement and
+      // join resolution read the full set); the Model's discovery accessors
+      // filter them down to the export closure (`modelDef.exports`) to match
+      // `modelInfo`/`sourceInfos`.
       sources,
       queries,
       filterMap: Array.from(filterMap.entries()),
@@ -800,6 +839,7 @@ async function loadPackage(
 
    const allFiles = await listPackageFiles(job.packagePath);
    const modelPaths = filterModelPaths(allFiles);
+
    const models = await Promise.all(
       modelPaths.map((modelPath) =>
          compileOneModel(job, malloyConfig, modelPath),

package/src/package_load/protocol.ts

@@ -173,7 +173,13 @@ export interface SerializedNotebookCell {
 export interface LoadPackageResult {
    type: "load-package-result";
    requestId: string;
-   packageMetadata: { name?: string; description?: string };
+   packageMetadata: {
+      name?: string;
+      description?: string;
+      explores?: string[];
+      queryableSources?: "declared" | "all";
+      manifestLocation?: string | null;
+   };
    models: SerializedModel[];
    /** Wall-clock ms inside the worker for the full package load. */
    loadDurationMs: number;

package/src/server-old.ts

@@ -30,7 +30,6 @@ import { ParsedQs } from "qs";
 import { CompileController } from "./controller/compile.controller";
 import { ConnectionController } from "./controller/connection.controller";
 import { DatabaseController } from "./controller/database.controller";
-import { ManifestController } from "./controller/manifest.controller";
 import { MaterializationController } from "./controller/materialization.controller";
 import { ModelController } from "./controller/model.controller";
 import { PackageController } from "./controller/package.controller";
@@ -57,7 +56,6 @@ export interface LegacyControllerSet {
    queryController: QueryController;
    compileController: CompileController;
    materializationController: MaterializationController;
-   manifestController: ManifestController;
 }
 
 // ─── response/body field mappers ───────────────────────────────────────────
@@ -97,7 +95,6 @@ export function registerLegacyRoutes(
       queryController,
       compileController,
       materializationController,
-      manifestController,
    } = controllers;
 
    // body-parser is already registered on the main app for `${API_PREFIX}/*`
@@ -379,26 +376,7 @@ export function registerLegacyRoutes(
       },
    );
 
-   // sqlSource (deprecated GET + supported POST), per-project + per-package
-   app.get(
-      `${LEGACY_API_PREFIX}/projects/:projectName/connections/:connectionName/sqlSource`,
-      async (req, res) => {
-         try {
-            res.status(200).json(
-               await connectionController.getConnectionSqlSource(
-                  req.params.projectName,
-                  req.params.connectionName,
-                  req.query.sqlStatement as string,
-               ),
-            );
-         } catch (error) {
-            logger.error(error);
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
+   // sqlSource (POST), per-project + per-package
    app.post(
       `${LEGACY_API_PREFIX}/projects/:projectName/connections/:connectionName/sqlSource`,
       async (req, res) => {
@@ -418,26 +396,6 @@ export function registerLegacyRoutes(
       },
    );
 
-   app.get(
-      `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/connections/:connectionName/sqlSource`,
-      async (req, res) => {
-         try {
-            res.status(200).json(
-               await connectionController.getConnectionSqlSource(
-                  req.params.projectName,
-                  req.params.connectionName,
-                  req.query.sqlStatement as string,
-                  req.params.packageName,
-               ),
-            );
-         } catch (error) {
-            logger.error(error);
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
    app.post(
       `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/connections/:connectionName/sqlSource`,
       async (req, res) => {
@@ -567,48 +525,7 @@ export function registerLegacyRoutes(
       },
    );
 
-   // temporaryTable (deprecated GET) + sqlTemporaryTable (supported POST)
-   app.get(
-      `${LEGACY_API_PREFIX}/projects/:projectName/connections/:connectionName/temporaryTable`,
-      queryConcurrency(),
-      async (req, res) => {
-         try {
-            res.status(200).json(
-               await connectionController.getConnectionTemporaryTable(
-                  req.params.projectName,
-                  req.params.connectionName,
-                  req.query.sqlStatement as string,
-               ),
-            );
-         } catch (error) {
-            logger.error(error);
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
-   app.get(
-      `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/connections/:connectionName/temporaryTable`,
-      queryConcurrency(),
-      async (req, res) => {
-         try {
-            res.status(200).json(
-               await connectionController.getConnectionTemporaryTable(
-                  req.params.projectName,
-                  req.params.connectionName,
-                  req.query.sqlStatement as string,
-                  req.params.packageName,
-               ),
-            );
-         } catch (error) {
-            logger.error(error);
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
+   // sqlTemporaryTable (POST), per-project + per-package
    app.post(
       `${LEGACY_API_PREFIX}/projects/:projectName/connections/:connectionName/sqlTemporaryTable`,
       queryConcurrency(),
@@ -674,11 +591,9 @@ export function registerLegacyRoutes(
       `${LEGACY_API_PREFIX}/projects/:projectName/packages`,
       async (req, res) => {
          try {
-            const autoLoadManifest = req.query.autoLoadManifest === "true";
             const _package = await packageController.addPackage(
                req.params.projectName,
                req.body,
-               { autoLoadManifest },
             );
             res.status(200).json(_package?.getPackageMetadata());
          } catch (error) {
@@ -1024,34 +939,18 @@ export function registerLegacyRoutes(
       },
    );
 
-   app.post(
-      `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/materializations/teardown`,
-      async (req, res) => {
-         try {
-            const result = await materializationController.teardownPackage(
-               req.params.projectName,
-               req.params.packageName,
-               req.body || {},
-            );
-            res.status(200).json(result);
-         } catch (error) {
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
    app.post(
       `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/materializations/:materializationId`,
       async (req, res) => {
          try {
             const action = req.query.action;
-            if (action === "start") {
+            if (action === "build") {
                const build =
-                  await materializationController.startMaterialization(
+                  await materializationController.buildMaterialization(
                      req.params.projectName,
                      req.params.packageName,
                      req.params.materializationId,
+                     req.body || {},
                   );
                res.status(202).json(remapMaterializationResponse(build));
             } else if (action === "stop") {
@@ -1064,7 +963,7 @@ export function registerLegacyRoutes(
                res.status(200).json(remapMaterializationResponse(build));
             } else {
                throw new BadRequestError(
-                  `Unsupported action '${String(action ?? "")}'. Expected 'start' or 'stop'.`,
+                  `Unsupported action '${String(action ?? "")}'. Expected 'build' or 'stop'.`,
                );
             }
          } catch (error) {
@@ -1082,6 +981,7 @@ export function registerLegacyRoutes(
                req.params.projectName,
                req.params.packageName,
                req.params.materializationId,
+               { dropTables: req.query.dropTables === "true" },
             );
             res.status(204).send();
          } catch (error) {
@@ -1091,48 +991,6 @@ export function registerLegacyRoutes(
       },
    );
 
-   // ── manifest ────────────────────────────────────────────────────────────
-   app.get(
-      `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/manifest`,
-      async (req, res) => {
-         try {
-            const manifest = await manifestController.getManifest(
-               req.params.projectName,
-               req.params.packageName,
-            );
-            res.status(200).json(manifest);
-         } catch (error) {
-            logger.error("Get manifest error", { error });
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
-   app.post(
-      `${LEGACY_API_PREFIX}/projects/:projectName/packages/:packageName/manifest`,
-      async (req, res) => {
-         try {
-            const action = req.query.action;
-            if (action === "reload") {
-               const manifest = await manifestController.reloadManifest(
-                  req.params.projectName,
-                  req.params.packageName,
-               );
-               res.status(200).json(manifest);
-            } else {
-               throw new BadRequestError(
-                  `Unsupported action '${String(action ?? "")}'. Expected 'reload'.`,
-               );
-            }
-         } catch (error) {
-            logger.error("Manifest action error", { error });
-            const { json, status } = internalErrorToHttpError(error as Error);
-            res.status(status).json(json);
-         }
-      },
-   );
-
    logger.info(
       "Legacy /projects/* routes registered for backwards compatibility",
    );