@malloy-publisher/server 0.0.382-dev → 0.2.0

package/src/instrumentation.ts

@@ -1,148 +0,0 @@
-import { metrics } from "@opentelemetry/api";
-import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-proto";
-import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
-import {
-   ExpressInstrumentation,
-   ExpressLayerType,
-} from "@opentelemetry/instrumentation-express";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { BatchLogRecordProcessor } from "@opentelemetry/sdk-logs";
-import { NodeSDK } from "@opentelemetry/sdk-node";
-import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
-import {
-   ATTR_SERVICE_NAME,
-   ATTR_SERVICE_VERSION,
-} from "@opentelemetry/semantic-conventions";
-import type { NextFunction, Request, Response } from "express";
-import { logger } from "./logger";
-
-let prometheusExporter: PrometheusExporter | null = null;
-let sdk: NodeSDK | null = null;
-
-export function getPrometheusMetricsHandler() {
-   if (!prometheusExporter) {
-      throw new Error("Prometheus exporter not initialized");
-   }
-   return (req: Request, res: Response) => {
-      prometheusExporter!.getMetricsRequestHandler(req, res);
-   };
-}
-
-/**
- * Shuts down the OpenTelemetry SDK gracefully.
- * Should be called during application shutdown.
- */
-export async function shutdownSDK(): Promise<void> {
-   if (sdk) {
-      await sdk.shutdown();
-      sdk = null;
-   }
-}
-
-function instrument() {
-   const otelCollectorUrl = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
-
-   prometheusExporter = new PrometheusExporter({
-      preventServerStart: true,
-   });
-
-   const instrumentations = [
-      getNodeAutoInstrumentations(),
-      new ExpressInstrumentation({
-         ignoreLayersType: [ExpressLayerType.MIDDLEWARE],
-         ignoreLayers: [/\/health/, /\/metrics/],
-      }),
-   ];
-
-   sdk = new NodeSDK({
-      resource: resourceFromAttributes({
-         [ATTR_SERVICE_NAME]: "publisher",
-         [ATTR_SERVICE_VERSION]: "1.0.0",
-      }),
-      autoDetectResources: true,
-      metricReader: prometheusExporter,
-      instrumentations,
-      ...(otelCollectorUrl && {
-         spanProcessors: [
-            new BatchSpanProcessor(
-               new OTLPTraceExporter({
-                  url: `${otelCollectorUrl}/v1/traces`,
-               }),
-            ),
-         ],
-         logRecordProcessors: [
-            new BatchLogRecordProcessor(
-               new OTLPLogExporter({
-                  url: `${otelCollectorUrl}/v1/logs`,
-               }),
-            ),
-         ],
-      }),
-   });
-
-   sdk.start();
-
-   if (otelCollectorUrl) {
-      logger.info(
-         `OpenTelemetry SDK initialized with OTLP collector at ${otelCollectorUrl}`,
-      );
-   } else {
-      logger.info("OpenTelemetry SDK initialized with Prometheus metrics only");
-   }
-}
-
-instrument();
-
-// --- HTTP metrics middleware ---
-
-const meter = metrics.getMeter("publisher");
-
-const httpRequestDuration = meter.createHistogram(
-   "http_server_request_duration_ms",
-   {
-      description: "Duration of HTTP requests in milliseconds",
-      unit: "ms",
-      advice: {
-         explicitBucketBoundaries: [
-            5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 60000,
-         ],
-      },
-   },
-);
-
-const httpRequestCount = meter.createCounter("http_server_requests_total", {
-   description: "Total number of HTTP requests",
-});
-
-const IGNORED_PATHS = new Set([
-   "/health",
-   "/health/liveness",
-   "/health/readiness",
-   "/metrics",
-]);
-
-export function httpMetricsMiddleware(
-   req: Request,
-   res: Response,
-   next: NextFunction,
-) {
-   const start = performance.now();
-
-   res.on("finish", () => {
-      if (IGNORED_PATHS.has(req.path)) return;
-
-      const duration = performance.now() - start;
-      const attrs = {
-         "http.method": req.method,
-         "http.route": req.route?.path ?? req.path,
-         "http.status_code": res.statusCode,
-      };
-
-      httpRequestDuration.record(duration, attrs);
-      httpRequestCount.add(1, attrs);
-   });
-
-   next();
-}

package/src/logger.ts

@@ -1,154 +0,0 @@
-import { AxiosError } from "axios";
-import { RequestHandler } from "express";
-import winston from "winston";
-
-const isTelemetryEnabled = Boolean(process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
-
-// Determine log level from environment variable
-// Valid levels: error, warn, info, verbose, debug, silly
-// Default: 'debug'
-const VALID_LOG_LEVELS = ["error", "warn", "info", "verbose", "debug", "silly"];
-const getLogLevel = (): string => {
-   if (process.env.LOG_LEVEL) {
-      const logLevel = process.env.LOG_LEVEL.toLowerCase();
-      if (VALID_LOG_LEVELS.includes(logLevel)) {
-         return logLevel;
-      } else {
-         console.error(
-            `Invalid log level: ${process.env.LOG_LEVEL}. Valid log levels are: ${VALID_LOG_LEVELS.join(", ")}. Defaulting to "debug".`,
-         );
-      }
-   }
-   return "debug";
-};
-
-export const logger = winston.createLogger({
-   level: getLogLevel(),
-   format: isTelemetryEnabled
-      ? winston.format.combine(
-           winston.format.uncolorize(),
-           winston.format.timestamp(),
-           winston.format.metadata({
-              fillExcept: ["message", "level", "timestamp"],
-           }),
-           winston.format.json(),
-        )
-      : winston.format.combine(
-           winston.format.colorize(),
-           winston.format.simple(),
-        ),
-   transports: [new winston.transports.Console()],
-});
-
-//-
-/**
- * Extracts the trace ID from a W3C traceparent header.
- * Format: version-trace-id-parent-id-trace-flags
- * Example: 00-81f2264f363f1b5596c84ab29e6be171-83ef39df12ab6bab-01
- *
- * @param traceparent The traceparent header value
- * @returns The trace ID (32 hex characters) or undefined if invalid
- */
-function extractTraceIdFromTraceparent(
-   traceparent: string | undefined,
-): string | undefined {
-   if (!traceparent) {
-      return undefined;
-   }
-
-   // format of traceparent can either be: version-traceId-parentId-traceFlags or traceId
-   const parts = traceparent.split("-");
-   const traceId =
-      parts.length >= 2 ? parts[1] : parts.length == 1 ? parts[0] : undefined;
-   // Validate that the traceId is 32 hex characters
-   if (traceId && traceId.length === 32 && /^[0-9a-fA-F]{32}$/.test(traceId)) {
-      return traceId;
-   }
-
-   return undefined;
-}
-
-const DISABLE_RESPONSE_LOGGING =
-   process.env.DISABLE_RESPONSE_LOGGING === "true" ||
-   process.env.DISABLE_RESPONSE_LOGGING === "1";
-
-/**
- * Format duration in milliseconds to a human-readable string with unit
- * @param durationMs Duration in milliseconds
- * @returns Formatted string with 2 decimal places and unit (s or ms)
- */
-export function formatDuration(durationMs: number): string {
-   // If duration is >= 1000ms, show in seconds, otherwise show in milliseconds
-   if (durationMs >= 1000) {
-      const seconds = durationMs / 1000;
-      return `${seconds.toFixed(2)}s`;
-   }
-   return `${durationMs.toFixed(2)}ms`;
-}
-
-export const loggerMiddleware: RequestHandler = (req, res, next) => {
-   const startTime = performance.now();
-   const resJson = res.json;
-   res.json = (body: unknown) => {
-      res.locals.body = body;
-      return resJson.call(res, body);
-   };
-   res.on("finish", () => {
-      const endTime = performance.now();
-      const durationMs = endTime - startTime;
-
-      // Extract trace ID from traceparent header if present
-      const traceparent = req.headers["traceparent"] as string | undefined;
-      const traceId = extractTraceIdFromTraceparent(traceparent);
-
-      const logMetadata: Record<string, unknown> = {
-         statusCode: res.statusCode,
-         duration: formatDuration(durationMs),
-         payload: req.body,
-         params: req.params,
-         query: req.query,
-      };
-
-      // Only include response body if response logging is enabled
-      if (!DISABLE_RESPONSE_LOGGING) {
-         logMetadata.response = res.locals.body;
-      }
-
-      // Add traceId to log metadata if present
-      if (traceId) {
-         logMetadata.traceId = traceId;
-      }
-
-      // Skip logging for metrics and health endpoints to reduce log noise
-      if (
-         req.url !== "/metrics" &&
-         req.url !== "/health" &&
-         req.url !== "/health/liveness" &&
-         req.url !== "/health/readiness"
-      ) {
-         logger.info(`${req.method} ${req.url}`, logMetadata);
-      }
-   });
-   next();
-};
-
-export const logAxiosError = (error: AxiosError) => {
-   if (error.response) {
-      // The request was made and the server responded with a status code
-      // that falls out of the range of 2xx
-      logger.error("Axios server-side error", {
-         url: error.response.config.url,
-         status: error.response.status,
-         headers: error.response.headers,
-         data: error.response.data,
-      });
-   } else if (error.request) {
-      // The request was made but no response was received
-      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
-      // http.ClientRequest in node.js
-      logger.error("Axios client-side error", { error: error.request });
-   } else {
-      // Something happened in setting up the request that triggered an Error
-      logger.error("Axios unknown error", { error });
-   }
-};

package/src/mcp/error_messages.ts

@@ -1,199 +0,0 @@
-export interface ErrorDetails {
-   message: string;
-   suggestions: string[];
-}
-
-export interface InvalidParamDetail {
-   name: string;
-   reason: string;
-   value?: unknown;
-}
-
-export function getInvalidParamsError(
-   params: InvalidParamDetail[],
-): ErrorDetails {
-   const reasons = params
-      .map(
-         (p) =>
-            `${p.name}: ${p.reason}${p.value !== undefined ? ` (value: ${JSON.stringify(p.value)})` : ""}`,
-      )
-      .join("; ");
-   return {
-      message: `Invalid parameter(s) provided. ${reasons}`,
-      suggestions: [
-         "Check the parameter names and values against the prompt's argument definition.",
-         "Ensure all required parameters are provided and have the correct data types.",
-         "For URI parameters, ensure they are correctly formatted.",
-      ],
-   };
-}
-
-/**
- * Generates error details for a resource not found scenario.
- * @param resourceUriOrContext The URI that was not found, or a context string (e.g., "Package 'X'", "Model 'Y' in package 'X'").
- * @returns ErrorDetails object with message and suggestions.
- */
-export function getNotFoundError(resourceUriOrContext: string): ErrorDetails {
-   const baseMessage = `Resource not found: ${resourceUriOrContext}`;
-   const suggestions: string[] = [
-      `Verify the identifier or URI (${resourceUriOrContext}) is spelled correctly and exists. Check capitalization and path separators.`,
-      `If using a URI, ensure it follows the correct format (e.g., malloy://project/...) and includes the right path segments (e.g., /models/, /sources/, /queries/, /views/).`,
-   ];
-
-   suggestions.push(
-      "Check if the resource exists and is correctly named in your Malloy project structure or the specific model file.",
-   );
-
-   return {
-      message: baseMessage,
-      suggestions: suggestions,
-   };
-}
-
-/**
- * Generates generic error details for internal server errors.
- * @param operation The operation that failed (e.g., 'GetResource', 'ListResources').
- * @param error Optional: The underlying error object or message.
- * @returns ErrorDetails object.
- */
-export function getInternalError(
-   operation: string,
-   error?: unknown,
-): ErrorDetails {
-   const baseMessage = `An unexpected internal error occurred during ${operation}.`;
-   const errorMessage = error instanceof Error ? error.message : String(error);
-   return {
-      message: error ? `${baseMessage}: ${errorMessage}` : baseMessage,
-      suggestions: [
-         "Try the request again later.",
-         "If the problem persists, check server logs or contact support.",
-      ],
-   };
-}
-
-/**
- * Generates detailed error information for Malloy compilation or query execution errors.
- * @param operation The operation that failed (e.g., 'GetResource (model)', 'executeQuery').
- * @param modelIdentifier A path or URI identifying the model/notebook involved.
- * @param error The underlying Malloy error object or other error.
- * @returns ErrorDetails object.
- */
-export function getMalloyErrorDetails(
-   operation: string,
-   modelIdentifier: string,
-   error: unknown,
-): ErrorDetails {
-   let baseMessage = `Error during ${operation} for resource '${modelIdentifier}'.`;
-   const initialSuggestions: string[] = [
-      `Verify the structure and syntax within the Malloy file: ${modelIdentifier}. Check for typos in source, query, or view names (e.g., 'source: my_source is ...', 'query: my_query is ...', 'view: my_view is { ... }'). See Model Structure: https://docs.malloydata.dev/documentation/language/statement`,
-      "Ensure all referenced sources, queries, or views are correctly defined within the model or imported files using expected keywords (e.g., 'source:', 'query:', 'view:'). See Sources: https://docs.malloydata.dev/documentation/language/source",
-      "Check the database connection configuration used by the model, if applicable.",
-      "Consult the Malloy language documentation for syntax rules: https://docs.malloydata.dev/documentation/",
-   ];
-
-   let suggestions: string[] = [...initialSuggestions]; // Clone initial suggestions
-   let refined = false; // Flag to track if specific suggestions were added
-
-   // Attempt to extract more specific info if it's a MalloyError or similar
-   if (error instanceof Error) {
-      // Prepend the specific error message
-      baseMessage = `Error during ${operation} for resource '${modelIdentifier}': ${error.message}`;
-
-      // --- Add more specific suggestions based on common Malloy error patterns ---
-      // Note: Order matters, check for more specific patterns first.
-
-      const viewNotFoundMatch = error.message.match(
-         /View '([^']+)' not found in source '([^']+)'/i,
-      );
-      const sourceNotFoundMatch = error.message.match(
-         /Source '([^']+)' not found/i,
-      );
-      const queryNotFoundMatch = error.message.match(
-         /Query '([^']+)' not found/i,
-      );
-      const referenceErrorMatch = error.message.match(
-         /Reference to undefined object(?: '([^']+)')?/i,
-      );
-      const syntaxErrorMatch = error.message.match(
-         /no viable alternative at input/i,
-      );
-      const connectionErrorMatch = error.message.match(
-         /Cannot connect to database/i,
-      );
-      const fieldNotFoundMatch = error.message.match(
-         /Field '([^']+)' not found in (source|query|view) '([^']+)'/i,
-      );
-      const invalidRequestMatch = error.message.match(
-         /Invalid query request\\. Query OR queryName must be defined/i,
-      );
-
-      if (viewNotFoundMatch) {
-         refined = true;
-         const [, viewName, sourceName] = viewNotFoundMatch;
-         suggestions.unshift(
-            `Suggestion: View '${viewName}' was not found in source '${sourceName}'. Check the view name spelling or try requesting the resource details for the source URI (e.g., 'malloy://.../sources/${sourceName}') to see the list of available views. Views are defined within sources like 'source: ${sourceName} is ... extend { view: ${viewName} is { ... } }'.`,
-         );
-      } else if (sourceNotFoundMatch) {
-         refined = true;
-         const [, sourceName] = sourceNotFoundMatch;
-         suggestions.unshift(
-            `Suggestion: Source '${sourceName}' was not found or could not be accessed. Verify its definition (e.g., \`source: ${sourceName} is table('...')\` or \`duckdb.sql("...")\`) and ensure any associated connections are valid.`,
-            `Suggestion: Check the spelling of '${sourceName}'. You can list sources in the model using ListResources('malloy://.../${modelIdentifier}').`,
-         );
-      } else if (queryNotFoundMatch) {
-         refined = true;
-         const [, queryName] = queryNotFoundMatch;
-         suggestions.unshift(
-            `Suggestion: Named query '${queryName}' was not found. Verify its definition (e.g., \`query: ${queryName} is source_name -> { ... }\`) within the model '${modelIdentifier}'.`,
-            `Suggestion: Check the spelling of '${queryName}'. Ensure it's a named query (defined with \`query:\`), not a view. You can list named queries using ListResources('malloy://.../${modelIdentifier}').`,
-         );
-      } else if (fieldNotFoundMatch) {
-         refined = true;
-         const [, fieldName, fieldContextType, fieldContextName] =
-            fieldNotFoundMatch;
-         suggestions.unshift(
-            `Suggestion: Field '${fieldName}' was not found in ${fieldContextType} '${fieldContextName}'. Check the spelling of the field name within the definition of '${fieldContextName}'.`,
-            `Suggestion: Ensure the field is defined directly or inherited correctly in the '${fieldContextName}' ${fieldContextType}. You can inspect the ${fieldContextType} definition using GetResource.`,
-         );
-      } else if (referenceErrorMatch) {
-         refined = true;
-         const objectName = referenceErrorMatch[1] || "[unknown object]";
-         suggestions.unshift(
-            `Suggestion: Check if the referenced object '${objectName}' (source, query, view, field, dimension, measure) is defined correctly and spelled correctly (e.g., 'source: my_source is ...', 'query: my_query is ...'). Ensure it's defined *before* being used in the model file.`,
-         );
-      } else if (syntaxErrorMatch) {
-         refined = true;
-         suggestions.unshift(
-            "Suggestion: There seems to be a syntax error near the location indicated in the error message. Check for misplaced/missing keywords (like 'is', '->', 'extend', 'where', 'aggregate', 'group_by', 'nest'), commas, brackets '{ }', or parentheses '( )'. See Query Syntax: https://docs.malloydata.dev/documentation/language/query",
-         );
-      } else if (connectionErrorMatch) {
-         refined = true;
-         suggestions.unshift(
-            "Suggestion: Verify the database connection details (credentials, host, database name, connection name in Malloy) associated with this model.",
-         );
-         suggestions.push(
-            "Ensure the database server is running and accessible from the publisher server.",
-         );
-      } else if (invalidRequestMatch) {
-         refined = true;
-         suggestions.unshift(
-            "Suggestion: This error can occur when specifying a view using 'sourceName' and 'queryName'. Try providing the full query string directly in the 'query' parameter instead (e.g., 'query': 'run: your_source_name->your_view_name').",
-            "Suggestion: Also verify you are providing either the 'query' parameter OR the correct combination of 'queryName' (and optionally 'sourceName' for views).",
-         );
-      }
-
-      // If no specific pattern matched, keep the initial suggestions
-      if (!refined) {
-         suggestions = initialSuggestions;
-      }
-   } else {
-      // Generic message if it's not a standard Error object
-      baseMessage += `: ${String(error)}`;
-      suggestions = initialSuggestions; // Use initial for non-errors too
-   }
-
-   return {
-      message: baseMessage,
-      suggestions: suggestions,
-   };
-}