@prisma-next/sql-runtime 0.3.0-pr.99.6 → 0.3.0

package/src/lower-sql-plan.ts

@@ -1,23 +1,23 @@
-import type { ExecutionPlan } from '@prisma-next/contract/types';
+import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+import type { Adapter, AnyQueryAst, LoweredStatement } from '@prisma-next/sql-relational-core/ast';
 import type { SqlQueryPlan } from '@prisma-next/sql-relational-core/plan';
-import type { RuntimeContext } from './sql-context';
 
 /**
  * Lowers a SQL query plan to an executable Plan by calling the adapter's lower method.
  *
- * This function is responsible for converting a lane-produced SqlQueryPlan (which contains
- * AST and params but no SQL) into a fully executable Plan (which includes SQL string).
- *
- * @param context - Runtime context containing the adapter
+ * @param adapter - Adapter to lower AST to SQL
+ * @param contract - Contract for lowering context
  * @param queryPlan - SQL query plan from a lane (contains AST, params, meta, but no SQL)
  * @returns Fully executable Plan with SQL string
  */
 export function lowerSqlPlan<Row>(
-  context: RuntimeContext,
+  adapter: Adapter<AnyQueryAst, Contract<SqlStorage>, LoweredStatement>,
+  contract: Contract<SqlStorage>,
   queryPlan: SqlQueryPlan<Row>,
 ): ExecutionPlan<Row> {
-  const lowered = context.adapter.lower(queryPlan.ast, {
-    contract: context.contract,
+  const lowered = adapter.lower(queryPlan.ast, {
+    contract,
     params: queryPlan.params,
   });
 

package/src/middleware/budgets.ts

@@ -0,0 +1,256 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import { type RuntimeErrorEnvelope, runtimeError } from '@prisma-next/framework-components/runtime';
+import type {
+  AfterExecuteResult,
+  Middleware,
+  MiddlewareContext,
+} from '@prisma-next/runtime-executor';
+import { isQueryAst, type SelectAst } from '@prisma-next/sql-relational-core/ast';
+
+export interface BudgetsOptions {
+  readonly maxRows?: number;
+  readonly defaultTableRows?: number;
+  readonly tableRows?: Record<string, number>;
+  readonly maxLatencyMs?: number;
+  readonly severities?: {
+    readonly rowCount?: 'warn' | 'error';
+    readonly latency?: 'warn' | 'error';
+  };
+}
+
+function hasAggregateWithoutGroupBy(ast: SelectAst): boolean {
+  if (ast.groupBy !== undefined) {
+    return false;
+  }
+  return ast.projection.some((item) => item.expr.kind === 'aggregate');
+}
+
+function estimateRowsFromAst(
+  ast: SelectAst,
+  tableRows: Record<string, number>,
+  defaultTableRows: number,
+  refs: { tables?: readonly string[] } | undefined,
+  hasAggregateWithoutGroup: boolean,
+): number | null {
+  if (hasAggregateWithoutGroup) {
+    return 1;
+  }
+
+  const table = refs?.tables?.[0];
+  if (!table) {
+    return null;
+  }
+
+  const tableEstimate = tableRows[table] ?? defaultTableRows;
+
+  if (ast.limit !== undefined) {
+    return Math.min(ast.limit, tableEstimate);
+  }
+
+  return tableEstimate;
+}
+
+function estimateRowsFromHeuristics(
+  plan: ExecutionPlan,
+  tableRows: Record<string, number>,
+  defaultTableRows: number,
+): number | null {
+  const table = plan.meta.refs?.tables?.[0];
+  if (!table) {
+    return null;
+  }
+
+  const tableEstimate = tableRows[table] ?? defaultTableRows;
+
+  const limit = plan.meta.annotations?.['limit'];
+  if (typeof limit === 'number') {
+    return Math.min(limit, tableEstimate);
+  }
+
+  return tableEstimate;
+}
+
+function hasDetectableLimitFromHeuristics(plan: ExecutionPlan): boolean {
+  return typeof plan.meta.annotations?.['limit'] === 'number';
+}
+
+function emitBudgetViolation(
+  error: RuntimeErrorEnvelope,
+  shouldBlock: boolean,
+  ctx: MiddlewareContext<unknown>,
+): void {
+  if (shouldBlock) {
+    throw error;
+  }
+  ctx.log.warn({
+    code: error.code,
+    message: error.message,
+    details: error.details,
+  });
+}
+
+export function budgets<TContract = unknown>(options?: BudgetsOptions): Middleware<TContract> {
+  const maxRows = options?.maxRows ?? 10_000;
+  const defaultTableRows = options?.defaultTableRows ?? 10_000;
+  const tableRows = options?.tableRows ?? {};
+  const maxLatencyMs = options?.maxLatencyMs ?? 1_000;
+  const rowSeverity = options?.severities?.rowCount ?? 'error';
+
+  const observedRowsByPlan = new WeakMap<ExecutionPlan, { count: number }>();
+
+  return Object.freeze({
+    name: 'budgets',
+    familyId: 'sql' as const,
+
+    async beforeExecute(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+      observedRowsByPlan.set(plan, { count: 0 });
+
+      if (isQueryAst(plan.ast)) {
+        if (plan.ast.kind === 'select') {
+          return evaluateSelectAst(plan, plan.ast, ctx);
+        }
+        return;
+      }
+
+      return evaluateWithHeuristics(plan, ctx);
+    },
+
+    async onRow(
+      _row: Record<string, unknown>,
+      plan: ExecutionPlan,
+      _ctx: MiddlewareContext<TContract>,
+    ) {
+      const state = observedRowsByPlan.get(plan);
+      if (!state) return;
+      state.count += 1;
+      if (state.count > maxRows) {
+        throw runtimeError('BUDGET.ROWS_EXCEEDED', 'Observed row count exceeds budget', {
+          source: 'observed',
+          observedRows: state.count,
+          maxRows,
+        });
+      }
+    },
+
+    async afterExecute(
+      _plan: ExecutionPlan,
+      result: AfterExecuteResult,
+      ctx: MiddlewareContext<TContract>,
+    ) {
+      const latencyMs = result.latencyMs;
+      if (latencyMs > maxLatencyMs) {
+        const shouldBlock = ctx.mode === 'strict';
+        emitBudgetViolation(
+          runtimeError('BUDGET.TIME_EXCEEDED', 'Query latency exceeds budget', {
+            latencyMs,
+            maxLatencyMs,
+          }),
+          shouldBlock,
+          ctx as MiddlewareContext<unknown>,
+        );
+      }
+    },
+  });
+
+  function evaluateSelectAst(
+    plan: ExecutionPlan,
+    ast: SelectAst,
+    ctx: MiddlewareContext<TContract>,
+  ) {
+    const hasAggNoGroup = hasAggregateWithoutGroupBy(ast);
+    const estimated = estimateRowsFromAst(
+      ast,
+      tableRows,
+      defaultTableRows,
+      plan.meta.refs,
+      hasAggNoGroup,
+    );
+    const isUnbounded = ast.limit === undefined && !hasAggNoGroup;
+    const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+
+    if (isUnbounded) {
+      if (estimated !== null && estimated >= maxRows) {
+        emitBudgetViolation(
+          runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
+            source: 'ast',
+            estimatedRows: estimated,
+            maxRows,
+          }),
+          shouldBlock,
+          ctx as MiddlewareContext<unknown>,
+        );
+        return;
+      }
+
+      emitBudgetViolation(
+        runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
+          source: 'ast',
+          maxRows,
+        }),
+        shouldBlock,
+        ctx as MiddlewareContext<unknown>,
+      );
+      return;
+    }
+
+    if (estimated !== null && estimated > maxRows) {
+      emitBudgetViolation(
+        runtimeError('BUDGET.ROWS_EXCEEDED', 'Estimated row count exceeds budget', {
+          source: 'ast',
+          estimatedRows: estimated,
+          maxRows,
+        }),
+        shouldBlock,
+        ctx as MiddlewareContext<unknown>,
+      );
+    }
+  }
+
+  async function evaluateWithHeuristics(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+    const estimated = estimateRowsFromHeuristics(plan, tableRows, defaultTableRows);
+    const isUnbounded = !hasDetectableLimitFromHeuristics(plan);
+    const sqlUpper = plan.sql.trimStart().toUpperCase();
+    const isSelect = sqlUpper.startsWith('SELECT');
+    const shouldBlock = rowSeverity === 'error' || ctx.mode === 'strict';
+
+    if (isSelect && isUnbounded) {
+      if (estimated !== null && estimated >= maxRows) {
+        emitBudgetViolation(
+          runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
+            source: 'heuristic',
+            estimatedRows: estimated,
+            maxRows,
+          }),
+          shouldBlock,
+          ctx as MiddlewareContext<unknown>,
+        );
+        return;
+      }
+
+      emitBudgetViolation(
+        runtimeError('BUDGET.ROWS_EXCEEDED', 'Unbounded SELECT query exceeds budget', {
+          source: 'heuristic',
+          maxRows,
+        }),
+        shouldBlock,
+        ctx as MiddlewareContext<unknown>,
+      );
+      return;
+    }
+
+    if (estimated !== null) {
+      if (estimated > maxRows) {
+        emitBudgetViolation(
+          runtimeError('BUDGET.ROWS_EXCEEDED', 'Estimated row count exceeds budget', {
+            source: 'heuristic',
+            estimatedRows: estimated,
+            maxRows,
+          }),
+          shouldBlock,
+          ctx as MiddlewareContext<unknown>,
+        );
+      }
+      return;
+    }
+  }
+}

package/src/middleware/lints.ts

@@ -0,0 +1,192 @@
+import type { ExecutionPlan } from '@prisma-next/contract/types';
+import { runtimeError } from '@prisma-next/framework-components/runtime';
+import type { Middleware, MiddlewareContext } from '@prisma-next/runtime-executor';
+import { evaluateRawGuardrails } from '@prisma-next/runtime-executor';
+import {
+  type AnyFromSource,
+  type AnyQueryAst,
+  isQueryAst,
+} from '@prisma-next/sql-relational-core/ast';
+import { ifDefined } from '@prisma-next/utils/defined';
+
+export interface LintsOptions {
+  readonly severities?: {
+    readonly selectStar?: 'warn' | 'error';
+    readonly noLimit?: 'warn' | 'error';
+    readonly deleteWithoutWhere?: 'warn' | 'error';
+    readonly updateWithoutWhere?: 'warn' | 'error';
+    readonly readOnlyMutation?: 'warn' | 'error';
+    readonly unindexedPredicate?: 'warn' | 'error';
+  };
+  readonly fallbackWhenAstMissing?: 'raw' | 'skip';
+}
+
+export interface LintFinding {
+  readonly code: `LINT.${string}`;
+  readonly severity: 'error' | 'warn';
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+}
+
+function getFromSourceTableDetail(source: AnyFromSource): string | undefined {
+  switch (source.kind) {
+    case 'table-source':
+      return source.name;
+    case 'derived-table-source':
+      return source.alias;
+    // v8 ignore next 4
+    default:
+      throw new Error(
+        `Unsupported source kind: ${(source satisfies never as { kind: string }).kind}`,
+      );
+  }
+}
+
+function evaluateAstLints(ast: AnyQueryAst): LintFinding[] {
+  const findings: LintFinding[] = [];
+
+  switch (ast.kind) {
+    case 'delete':
+      if (ast.where === undefined) {
+        findings.push({
+          code: 'LINT.DELETE_WITHOUT_WHERE',
+          severity: 'error',
+          message:
+            'DELETE without WHERE clause blocks execution to prevent accidental full-table deletion',
+          details: { table: ast.table.name },
+        });
+      }
+      break;
+
+    case 'update':
+      if (ast.where === undefined) {
+        findings.push({
+          code: 'LINT.UPDATE_WITHOUT_WHERE',
+          severity: 'error',
+          message:
+            'UPDATE without WHERE clause blocks execution to prevent accidental full-table update',
+          details: { table: ast.table.name },
+        });
+      }
+      break;
+
+    case 'select':
+      if (ast.limit === undefined) {
+        const table = getFromSourceTableDetail(ast.from);
+        findings.push({
+          code: 'LINT.NO_LIMIT',
+          severity: 'warn',
+          message: 'Unbounded SELECT may return large result sets',
+          ...ifDefined('details', table !== undefined ? { table } : undefined),
+        });
+      }
+      if (ast.selectAllIntent !== undefined) {
+        const table = ast.selectAllIntent.table;
+        findings.push({
+          code: 'LINT.SELECT_STAR',
+          severity: 'warn',
+          message: 'Query selects all columns via selectAll intent',
+          ...ifDefined('details', table !== undefined ? { table } : undefined),
+        });
+      }
+      break;
+
+    case 'insert':
+      break;
+
+    // v8 ignore next 2
+    default:
+      throw new Error(`Unsupported AST kind: ${(ast satisfies never as { kind: string }).kind}`);
+  }
+
+  return findings;
+}
+
+function getConfiguredSeverity(code: string, options?: LintsOptions): 'warn' | 'error' | undefined {
+  const severities = options?.severities;
+  if (!severities) return undefined;
+
+  switch (code) {
+    case 'LINT.SELECT_STAR':
+      return severities.selectStar;
+    case 'LINT.NO_LIMIT':
+      return severities.noLimit;
+    case 'LINT.DELETE_WITHOUT_WHERE':
+      return severities.deleteWithoutWhere;
+    case 'LINT.UPDATE_WITHOUT_WHERE':
+      return severities.updateWithoutWhere;
+    case 'LINT.READ_ONLY_MUTATION':
+      return severities.readOnlyMutation;
+    case 'LINT.UNINDEXED_PREDICATE':
+      return severities.unindexedPredicate;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * AST-first lint middleware for SQL plans. When `plan.ast` is a SQL QueryAst, inspects
+ * the AST structurally. When `plan.ast` is missing, falls back to raw heuristic
+ * guardrails or skips linting depending on `fallbackWhenAstMissing`.
+ *
+ * Rules (AST-based):
+ * - DELETE without WHERE: blocks execution (configurable severity, default error)
+ * - UPDATE without WHERE: blocks execution (configurable severity, default error)
+ * - Unbounded SELECT: warn/error (severity from noLimit)
+ * - SELECT * intent: warn/error (severity from selectStar)
+ *
+ * Fallback: When ast is missing, `fallbackWhenAstMissing: 'raw'` uses heuristic
+ * SQL parsing; `'skip'` skips all lints. Default is `'raw'`.
+ */
+export function lints<TContract = unknown>(options?: LintsOptions): Middleware<TContract> {
+  const fallback = options?.fallbackWhenAstMissing ?? 'raw';
+
+  return Object.freeze({
+    name: 'lints',
+    familyId: 'sql' as const,
+
+    async beforeExecute(plan: ExecutionPlan, ctx: MiddlewareContext<TContract>) {
+      if (isQueryAst(plan.ast)) {
+        const findings = evaluateAstLints(plan.ast);
+
+        for (const lint of findings) {
+          const configuredSeverity = getConfiguredSeverity(lint.code, options);
+          const effectiveSeverity = configuredSeverity ?? lint.severity;
+
+          if (effectiveSeverity === 'error') {
+            throw runtimeError(lint.code, lint.message, lint.details);
+          }
+          if (effectiveSeverity === 'warn') {
+            ctx.log.warn({
+              code: lint.code,
+              message: lint.message,
+              details: lint.details,
+            });
+          }
+        }
+        return;
+      }
+
+      if (fallback === 'skip') {
+        return;
+      }
+
+      const evaluation = evaluateRawGuardrails(plan);
+      for (const lint of evaluation.lints) {
+        const configuredSeverity = getConfiguredSeverity(lint.code, options);
+        const effectiveSeverity = configuredSeverity ?? lint.severity;
+
+        if (effectiveSeverity === 'error') {
+          throw runtimeError(lint.code, lint.message, lint.details);
+        }
+        if (effectiveSeverity === 'warn') {
+          ctx.log.warn({
+            code: lint.code,
+            message: lint.message,
+            details: lint.details,
+          });
+        }
+      }
+    },
+  });
+}

package/src/middleware/sql-middleware.ts

@@ -0,0 +1,26 @@
+import type { Contract, ExecutionPlan } from '@prisma-next/contract/types';
+import type {
+  AfterExecuteResult,
+  RuntimeMiddleware,
+  RuntimeMiddlewareContext,
+} from '@prisma-next/framework-components/runtime';
+import type { SqlStorage } from '@prisma-next/sql-contract/types';
+
+export interface SqlMiddlewareContext extends RuntimeMiddlewareContext {
+  readonly contract: Contract<SqlStorage>;
+}
+
+export interface SqlMiddleware extends RuntimeMiddleware {
+  readonly familyId: 'sql';
+  beforeExecute?(plan: ExecutionPlan, ctx: SqlMiddlewareContext): Promise<void>;
+  onRow?(
+    row: Record<string, unknown>,
+    plan: ExecutionPlan,
+    ctx: SqlMiddlewareContext,
+  ): Promise<void>;
+  afterExecute?(
+    plan: ExecutionPlan,
+    result: AfterExecuteResult,
+    ctx: SqlMiddlewareContext,
+  ): Promise<void>;
+}