@malloy-publisher/server 0.0.198-dev → 0.0.198-dev1

package/src/service/model.spec.ts

@@ -234,6 +234,111 @@ describe("service/model", () => {
 
             sinon.restore();
          });
+
+         it("forwards givens to runnable.getPreparedResult and .run", async () => {
+            const givensArg = { region: "EU" };
+            const preparedResultStub = sinon
+               .stub()
+               .resolves({ resultExplore: { limit: 10 } });
+            const runStub = sinon
+               .stub()
+               .rejects(new MalloyError("stub-stop", []));
+            const modelMaterializer = {
+               loadQuery: sinon.stub().returns({
+                  getPreparedResult: preparedResultStub,
+                  run: runStub,
+               }),
+            };
+
+            const model = new Model(
+               packageName,
+               mockModelPath,
+               {},
+               "model",
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               modelMaterializer as any,
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               { contents: {}, exports: [], queryList: [] } as any,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+            );
+
+            await expect(
+               model.getQueryResults(
+                  undefined,
+                  undefined,
+                  "run: orders -> summary",
+                  undefined,
+                  undefined,
+                  givensArg,
+               ),
+            ).rejects.toThrow(MalloyError);
+
+            expect(preparedResultStub.calledOnce).toBe(true);
+            expect(preparedResultStub.firstCall.args[0]).toEqual({
+               givens: givensArg,
+            });
+            expect(runStub.firstCall.args[0]).toMatchObject({
+               givens: givensArg,
+            });
+
+            sinon.restore();
+         });
+      });
+
+      describe("executeNotebookCell", () => {
+         it("forwards givens to runnable.getPreparedResult and .run", async () => {
+            const givensArg = { target_code: "AA" };
+            const preparedResultStub = sinon
+               .stub()
+               .resolves({ resultExplore: { limit: 10 } });
+            const runStub = sinon
+               .stub()
+               .rejects(new MalloyError("stub-stop", []));
+            const cellRunnable = {
+               getPreparedResult: preparedResultStub,
+               run: runStub,
+            };
+            const runnableCells = [
+               {
+                  type: "code" as const,
+                  text: "run: orders -> by_code",
+                  runnable: cellRunnable,
+               },
+            ];
+
+            const model = new Model(
+               packageName,
+               "test.malloynb",
+               {},
+               "notebook",
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               undefined,
+               // eslint-disable-next-line @typescript-eslint/no-explicit-any
+               runnableCells as any,
+               undefined,
+            );
+
+            await expect(
+               model.executeNotebookCell(0, undefined, undefined, givensArg),
+            ).rejects.toThrow(MalloyError);
+
+            expect(preparedResultStub.calledOnce).toBe(true);
+            expect(preparedResultStub.firstCall.args[0]).toEqual({
+               givens: givensArg,
+            });
+            expect(runStub.firstCall.args[0]).toMatchObject({
+               givens: givensArg,
+            });
+
+            sinon.restore();
+         });
       });
    });
 

package/src/service/model.ts

@@ -3,6 +3,7 @@ import {
    API,
    Connection,
    FixedConnectionMap,
+   GivenValue,
    isSourceDef,
    MalloyConfig,
    MalloyError,
@@ -28,6 +29,7 @@ import * as fs from "fs/promises";
 import { createRequire } from "module";
 import * as path from "path";
 import { components } from "../api";
+import { getCompilePool } from "../compile/compile_pool";
 import {
    MODEL_FILE_SUFFIX,
    NOTEBOOK_FILE_SUFFIX,
@@ -56,6 +58,7 @@ type ApiNotebookCell = components["schemas"]["NotebookCell"];
 type ApiRawNotebook = components["schemas"]["RawNotebook"];
 type ApiSource = components["schemas"]["Source"];
 type ApiFilter = components["schemas"]["Filter"];
+type ApiGiven = components["schemas"]["Given"];
 type ApiView = components["schemas"]["View"];
 type ApiQuery = components["schemas"]["Query"];
 export type ApiConnection = components["schemas"]["Connection"];
@@ -73,6 +76,61 @@ const MALLOY_VERSION = (
 export type ModelType = "model" | "notebook";
 type ModelConnectionInput = MalloyConfig | Map<string, Connection>;
 
+/**
+ * Structural type for a Malloy SDK `Given` instance (the value type of
+ * `Model.givens`). The `Given` class is declared in
+ * `@malloydata/malloy/dist/api/foundation/core.d.ts` but is not re-exported
+ * from the package root, so we duck-type against the surface we use rather
+ * than importing it.
+ */
+interface MalloyGiven {
+   readonly name: string;
+   readonly type: { type: string; filterType?: string };
+   getTaglines(prefix?: RegExp): string[];
+}
+
+/**
+ * Convert a Malloy SDK `Given` (returned from `Model.givens`) to the wire
+ * shape declared in `api-doc.yaml`. Two fields are deliberately not surfaced:
+ *
+ * - `location` — Malloy's `DocumentLocation.url` is an absolute `file://`
+ *   path on the publisher's filesystem. Surfacing it would leak the OS user,
+ *   install directory, and internal layout. Existing `Filter` introspection
+ *   does not expose location either; matching that floor. A future PR can
+ *   add a sanitized package-relative path if a client needs it.
+ *
+ * - `default` / `defaultText` — Malloy's API only exposes the parsed
+ *   `ConstantExpr` AST, not a rendered source string. Rendering it here
+ *   would duplicate the Malloy printer. Add when Malloy surfaces a
+ *   stringified accessor.
+ *
+ * `annotations` is restricted to `#(...)` declaration annotations (the
+ * caller-facing kind, e.g. `#(doc)`). `getTaglines()` with no prefix would
+ * also return `##` doc-comment lines and the model-level `##!` pragma,
+ * which aren't part of the given's surface contract.
+ *
+ * Type rendering: `GivenTypeDef` is typed as `AtomicTypeDef |
+ * FilterExpressionParamTypeDef`, but Malloy's grammar only emits the
+ * scalar parameter types (`string` | `number` | `boolean` | `date` |
+ * `timestamp` | `timestamptz` | `filter expression` | `error`) for
+ * given declarations today. If the grammar expands to allow array or
+ * record givens, the bare `type.type` discriminator (`'array'`,
+ * `'record'`) will land in the wire response with no element info —
+ * revisit when that happens.
+ */
+function malloyGivenToApi(given: MalloyGiven): ApiGiven {
+   const type = given.type;
+   const renderedType =
+      type.type === "filter expression"
+         ? `filter<${type.filterType}>`
+         : type.type;
+   return {
+      name: given.name,
+      type: renderedType,
+      annotations: given.getTaglines(/^#\(/),
+   };
+}
+
 interface RunnableNotebookCell {
    type: "code" | "markdown";
    text: string;
@@ -83,12 +141,31 @@ interface RunnableNotebookCell {
    queryInfo?: Malloy.QueryInfo;
 }
 
+/**
+ * Lazily produces a `ModelMaterializer` on demand. Used by the worker-
+ * compile path: the worker returns a fully-built `modelDef` but cannot
+ * ship the materializer (it binds to a Runtime that holds live native
+ * connection handles and would not survive a structured-clone). The
+ * first query that actually needs to execute calls this builder,
+ * which constructs the materializer in-process. After construction
+ * Malloy caches the compiled model internally on the materializer,
+ * so subsequent queries pay no recompile cost.
+ */
+type MaterializerBuilder = () => Promise<ModelMaterializer>;
+
 export class Model {
    private packageName: string;
    private modelPath: string;
    private dataStyles: DataStyles;
    private modelType: ModelType;
    private modelMaterializer: ModelMaterializer | undefined;
+   /**
+    * Lazy builder used when the model was compiled in a worker_threads
+    * worker. The first `getQueryResults`/`executeNotebookCell` call
+    * invokes this and caches the result in `modelMaterializer`.
+    */
+   private materializerBuilder: MaterializerBuilder | undefined;
+   private materializerBuildPromise: Promise<ModelMaterializer> | undefined;
    private modelDef: ModelDef | undefined;
    private modelInfo: Malloy.ModelInfo | undefined;
    private sources: ApiSource[] | undefined;
@@ -98,6 +175,12 @@ export class Model {
    private compilationError: MalloyError | Error | undefined;
    /** Parsed #(filter) definitions keyed by source name. */
    private filterMap: Map<string, FilterDefinition[]>;
+   /** Givens declared on the model, in declaration order. Malloy's
+    *  `Model.givens` already collapses inheritance; we just stash the list
+    *  for surfacing on the compiled-model response. */
+   private givens: ApiGiven[] | undefined;
+   /** Cached responses from `getStandardModel()` so we don't re-stringify a multi-MB modelDef on every GET. */
+   private cachedStandardModel: ApiCompiledModel | undefined;
    private meter = metrics.getMeter("publisher");
    private queryExecutionHistogram = this.meter.createHistogram(
       "malloy_model_query_duration",
@@ -121,6 +204,8 @@ export class Model {
       runnableNotebookCells: RunnableNotebookCell[] | undefined,
       compilationError: MalloyError | Error | undefined,
       filterMap?: Map<string, FilterDefinition[]>,
+      givens?: ApiGiven[],
+      materializerBuilder?: MaterializerBuilder,
    ) {
       this.packageName = packageName;
       this.modelPath = modelPath;
@@ -128,17 +213,41 @@ export class Model {
       this.modelType = modelType;
       this.modelDef = modelDef;
       this.modelMaterializer = modelMaterializer;
+      this.materializerBuilder = materializerBuilder;
       this.sources = sources;
       this.queries = queries;
       this.sourceInfos = sourceInfos;
       this.runnableNotebookCells = runnableNotebookCells;
       this.compilationError = compilationError;
       this.filterMap = filterMap ?? new Map();
+      this.givens = givens;
       this.modelInfo = this.modelDef
          ? modelDefToModelInfo(this.modelDef)
          : undefined;
    }
 
+   /**
+    * Resolve the in-process `ModelMaterializer`, building it lazily if
+    * the model was compiled in a worker_threads worker. Memoizes both
+    * the materializer and the in-flight build promise so concurrent
+    * queries on the same model share a single construction.
+    */
+   private async ensureMaterializer(): Promise<ModelMaterializer> {
+      if (this.modelMaterializer) return this.modelMaterializer;
+      if (!this.materializerBuilder) {
+         throw new BadRequestError("Model has no queryable entities.");
+      }
+      if (!this.materializerBuildPromise) {
+         this.materializerBuildPromise = this.materializerBuilder().then(
+            (mm) => {
+               this.modelMaterializer = mm;
+               return mm;
+            },
+         );
+      }
+      return this.materializerBuildPromise;
+   }
+
    /**
     * Get the parsed filter definitions for a given source name.
     * Returns an empty array if no filters are declared.
@@ -164,6 +273,158 @@ export class Model {
       modelPath: string,
       malloyConfig: ModelConnectionInput,
       options?: { buildManifest?: BuildManifest["entries"] },
+   ): Promise<Model> {
+      // Worker-pool fast path for plain `.malloy` files. Notebooks
+      // stay in-process for v1 — their per-cell ModelMaterializer
+      // chain is too entangled to ship across a worker boundary.
+      // The MALLOY_COMPILE_WORKERS=0 kill switch / pool.enabled check
+      // funnels everything through the legacy in-process path when
+      // the pool is disabled, so this is safe to land dark.
+      const pool = getCompilePool();
+      if (pool.enabled && modelPath.endsWith(MODEL_FILE_SUFFIX)) {
+         try {
+            return await Model.createViaWorker(
+               packageName,
+               packagePath,
+               modelPath,
+               malloyConfig,
+               pool,
+               options,
+            );
+         } catch (poolError) {
+            // Real compile errors propagate to the caller as a Model
+            // with `compilationError` populated, matching the
+            // in-process path's contract.
+            if (
+               poolError instanceof ModelCompilationError ||
+               poolError instanceof MalloyError
+            ) {
+               return Model.makeErrorModel(
+                  packageName,
+                  modelPath,
+                  poolError instanceof MalloyError
+                     ? new ModelCompilationError(poolError)
+                     : poolError,
+               );
+            }
+            // Anything else (worker exited, RPC timeout) — fall back
+            // to in-process compile so a transient pool failure
+            // doesn't take a package down.
+            logger.warn(
+               "Compile worker failed; falling back to in-process compile",
+               { packageName, modelPath, error: poolError },
+            );
+         }
+      }
+      return Model.createInProcess(
+         packageName,
+         packagePath,
+         modelPath,
+         malloyConfig,
+         options,
+      );
+   }
+
+   /**
+    * Compile via the {@link CompileWorkerPool}. Builds a `Model` whose
+    * `modelDef` / `sources` / `queries` / `sourceInfos` / `givens` are
+    * populated up-front, but whose `ModelMaterializer` is constructed
+    * lazily on the first query through {@link ensureMaterializer}.
+    * This keeps the heavy CPU work (parse, type-check, IR build) off
+    * the main event loop so the K8s liveness probe stays responsive.
+    */
+   private static async createViaWorker(
+      packageName: string,
+      packagePath: string,
+      modelPath: string,
+      malloyConfig: ModelConnectionInput,
+      pool: ReturnType<typeof getCompilePool>,
+      options?: { buildManifest?: BuildManifest["entries"] },
+   ): Promise<Model> {
+      const resolvedConfig = Model.toMalloyConfig(malloyConfig);
+      const outcome = await pool.compile({
+         packagePath,
+         modelPath,
+         malloyConfig: resolvedConfig,
+         // Package-level configs wrap a "duckdb" default; matches
+         // Package.buildPackageMalloyConfig.
+         defaultConnectionName: "duckdb",
+         urlReader: URL_READER,
+         buildManifest: options?.buildManifest,
+      });
+
+      // Materializer construction is deferred until a query actually
+      // runs. Build it the same way the in-process path does so
+      // execution semantics stay identical.
+      const materializerBuilder: MaterializerBuilder = async () => {
+         const { runtime, modelURL, importBaseURL } =
+            await Model.getModelRuntime(
+               packagePath,
+               modelPath,
+               malloyConfig,
+               options,
+            );
+         return Model.getStandardModelMaterializer(
+            runtime,
+            importBaseURL,
+            modelURL,
+            modelPath,
+         );
+      };
+
+      return new Model(
+         packageName,
+         modelPath,
+         {} as DataStyles,
+         "model",
+         undefined, // modelMaterializer — built lazily
+         outcome.modelDef,
+         outcome.sources as ApiSource[],
+         outcome.queries as ApiQuery[],
+         outcome.sourceInfos.length > 0 ? outcome.sourceInfos : undefined,
+         undefined, // runnableNotebookCells — .malloy is not a notebook
+         undefined, // compilationError
+         outcome.filterMap,
+         outcome.givens as ApiGiven[] | undefined,
+         materializerBuilder,
+      );
+   }
+
+   private static makeErrorModel(
+      packageName: string,
+      modelPath: string,
+      error: Error,
+   ): Model {
+      const isNotebook = modelPath.endsWith(NOTEBOOK_FILE_SUFFIX);
+      return new Model(
+         packageName,
+         modelPath,
+         {} as DataStyles,
+         isNotebook ? "notebook" : "model",
+         undefined,
+         undefined,
+         undefined,
+         undefined,
+         undefined,
+         undefined,
+         error,
+      );
+   }
+
+   /**
+    * Legacy in-process compile path. Retained for:
+    *   - notebooks (`.malloynb`), whose per-cell materializer chain
+    *     is too coupled to the Runtime to ship to a worker for v1.
+    *   - environments where MALLOY_COMPILE_WORKERS=0.
+    *   - fallback when the worker pool encounters a non-compile
+    *     failure (worker exit, RPC timeout).
+    */
+   private static async createInProcess(
+      packageName: string,
+      packagePath: string,
+      modelPath: string,
+      malloyConfig: ModelConnectionInput,
+      options?: { buildManifest?: BuildManifest["entries"] },
    ): Promise<Model> {
       // getModelRuntime might throw a ModelNotFoundError. It's the callers responsibility
       // to pass a valid model path or handle the error.
@@ -188,10 +449,19 @@ export class Model {
          let sources = undefined;
          let queries = undefined;
          let filterMap: Map<string, FilterDefinition[]> | undefined;
+         let givens: ApiGiven[] | undefined;
          const sourceInfos: Malloy.SourceInfo[] = [];
          if (modelMaterializer) {
-            modelDef = (await modelMaterializer.getModel())._modelDef;
-            const sourceResult = Model.getSources(modelPath, modelDef);
+            const compiledModel = await modelMaterializer.getModel();
+            modelDef = compiledModel._modelDef;
+            // Malloy's `Model.givens` already collapses inheritance from imports
+            // and applies any `finalizeGivens` runtime config. Just read it.
+            const malloyGivens = Array.from(compiledModel.givens.values());
+            givens =
+               malloyGivens.length > 0
+                  ? malloyGivens.map(malloyGivenToApi)
+                  : undefined;
+            const sourceResult = Model.getSources(modelPath, modelDef, givens);
             sources = sourceResult.sources;
             filterMap = sourceResult.filterMap;
             queries = Model.getQueries(modelPath, modelDef);
@@ -255,6 +525,7 @@ export class Model {
             runnableNotebookCells,
             undefined,
             filterMap,
+            givens,
          );
       } catch (error) {
          let computedError = error;
@@ -342,6 +613,7 @@ export class Model {
       query?: string,
       filterParams?: FilterParams,
       bypassFilters?: boolean,
+      givens?: Record<string, GivenValue>,
    ): Promise<{
       result: Malloy.Result;
       compactResult: QueryData;
@@ -363,9 +635,25 @@ export class Model {
          );
       }
       let runnable: QueryMaterializer;
-      if (!this.modelMaterializer || !this.modelDef || !this.modelInfo)
+      if (!this.modelDef || !this.modelInfo)
          throw new BadRequestError("Model has no queryable entities.");
 
+      // Resolve the materializer — either already-built (in-process
+      // create path, or a previous query on this Model) or lazily
+      // constructed now (worker-compile path on first query).
+      let materializer: ModelMaterializer;
+      try {
+         materializer = await this.ensureMaterializer();
+      } catch (error) {
+         if (error instanceof BadRequestError) throw error;
+         if (error instanceof MalloyError) throw error;
+         throw new BadRequestError(
+            error instanceof Error
+               ? `Failed to prepare model: ${error.message}`
+               : "Failed to prepare model.",
+         );
+      }
+
       // Wrap loadQuery calls in try-catch to handle query parsing errors
       try {
          let queryString: string;
@@ -406,7 +694,7 @@ export class Model {
             }
          }
 
-         runnable = this.modelMaterializer.loadQuery(queryString);
+         runnable = materializer.loadQuery(queryString);
       } catch (error) {
          // Re-throw BadRequestError as-is
          if (error instanceof BadRequestError) {
@@ -436,13 +724,14 @@ export class Model {
       }
 
       const rowLimit =
-         (await runnable.getPreparedResult()).resultExplore.limit || ROW_LIMIT;
+         (await runnable.getPreparedResult({ givens })).resultExplore.limit ||
+         ROW_LIMIT;
       const endTime = performance.now();
       const executionTime = endTime - startTime;
 
       let queryResults;
       try {
-         queryResults = await runnable.run({ rowLimit });
+         queryResults = await runnable.run({ rowLimit, givens });
       } catch (error) {
          // Record error metrics
          const errorEndTime = performance.now();
@@ -494,7 +783,14 @@ export class Model {
    }
 
    private getStandardModel(): ApiCompiledModel {
-      return {
+      // modelDef is immutable for the lifetime of this Model, so the
+      // (potentially multi-MB) JSON.stringify result can be memoised.
+      // Without this cache every `GET /environments/:e/packages/:p/
+      // models/:m` re-stringifies the whole tree on the main thread —
+      // a known source of multi-hundred-ms event-loop pauses that
+      // chips away at the K8s liveness budget.
+      if (this.cachedStandardModel) return this.cachedStandardModel;
+      const compiled: ApiCompiledModel = {
          type: "source",
          packageName: this.packageName,
          modelPath: this.modelPath,
@@ -509,7 +805,10 @@ export class Model {
          ),
          sources: this.sources,
          queries: this.queries,
+         givens: this.givens,
       } as ApiCompiledModel;
+      this.cachedStandardModel = compiled;
+      return compiled;
    }
 
    private async getNotebookModel(): Promise<ApiRawNotebook> {
@@ -568,6 +867,7 @@ export class Model {
       cellIndex: number,
       filterParams?: FilterParams,
       bypassFilters?: boolean,
+      givens?: Record<string, GivenValue>,
    ): Promise<{
       type: "code" | "markdown";
       text: string;
@@ -629,9 +929,9 @@ export class Model {
             }
 
             const rowLimit =
-               (await runnableToExecute.getPreparedResult()).resultExplore
-                  .limit || ROW_LIMIT;
-            const result = await runnableToExecute.run({ rowLimit });
+               (await runnableToExecute.getPreparedResult({ givens }))
+                  .resultExplore.limit || ROW_LIMIT;
+            const result = await runnableToExecute.run({ rowLimit, givens });
             const query = (await runnableToExecute.getPreparedQuery())._query;
             queryName = (query as NamedQueryDef).as || query.name;
             queryResult =
@@ -758,6 +1058,7 @@ export class Model {
    private static getSources(
       modelPath: string,
       modelDef: ModelDef,
+      givens?: ApiGiven[],
    ): {
       sources: ApiSource[];
       filterMap: Map<string, FilterDefinition[]>;
@@ -846,6 +1147,12 @@ export class Model {
                annotations,
                views,
                filters,
+               // Malloy exposes givens at the model level, not per-source.
+               // First pass: surface the full model-level list on every source
+               // — matches how filter introspection already collapses
+               // inheritance into the per-source list. Refine to view-scoped
+               // filtering if a customer asks.
+               givens,
             } as ApiSource;
          });