@bilal-fazlani/mock-server 0.2.1 → 0.3.0

package/.next/standalone/src/lib/environment.ts

@@ -0,0 +1,155 @@
+import type { Catalog } from './catalog/types'
+
+export type EnvironmentStatus = 'set' | 'default' | 'unset'
+
+export interface EnvironmentDefinition {
+  name: string
+  category: string
+  description: string
+  defaultValue?: string
+  possibleValues?: string[]
+  hideValue?: boolean
+  display: boolean
+}
+
+export interface EnvironmentRow {
+  name: string
+  value: string
+  status: EnvironmentStatus
+  category: string
+  description: string
+  possibleValues?: string[]
+  valueHidden?: boolean
+}
+
+export const APP_ENVIRONMENT: EnvironmentDefinition[] = [
+  {
+    name: 'CATALOG_PATH',
+    category: 'System',
+    description:
+      'Path to the catalog directory. Relative paths resolve against the server working directory; absolute paths are used as-is.',
+    defaultValue: './catalog',
+    display: true,
+  },
+  {
+    name: 'MONGODB_CONNECTION_STRING',
+    category: 'System',
+    description: 'MongoDB connection URI for profiles, global mocks, mappings, and logs.',
+    hideValue: true,
+    display: true,
+  },
+  {
+    name: 'MONGODB_DB',
+    category: 'System',
+    description: 'MongoDB database name for mock data.',
+    defaultValue: 'mockDB',
+    display: true,
+  },
+  {
+    name: 'PASSTHROUGH_AS_DEFAULT',
+    category: 'Routing',
+    description: 'Selects passthrough as the implicit scenario when true.',
+    defaultValue: 'false',
+    possibleValues: ['true', 'false'],
+    display: true,
+  },
+  {
+    name: 'UNMOCKED_USERS',
+    category: 'Routing',
+    description: 'Controls fallback behavior for unknown profile IDs.',
+    defaultValue: 'ERROR',
+    possibleValues: ['ERROR', 'DEFAULT_MOCK', 'REAL'],
+    display: true,
+  },
+  {
+    name: 'MOCK_CONSOLE_LOG_LEVEL',
+    category: 'System',
+    description: 'Console request log threshold.',
+    defaultValue: 'info',
+    possibleValues: ['info', 'warn', 'error'],
+    display: true,
+  },
+  {
+    name: 'PASSTHROUGH_TIMEOUT_MS',
+    category: 'Routing',
+    description: 'Timeout for real upstream passthrough requests.',
+    defaultValue: '30000',
+    display: true,
+  },
+  {
+    name: 'RESOLVER_HISTORY_LIMIT',
+    category: 'Routing',
+    description: 'Number of past returned slugs passed to scenario resolvers (<slug>.ts) as history.',
+    defaultValue: '10',
+    display: true,
+  },
+  {
+    name: 'NODE_ENV',
+    category: 'Runtime',
+    description: 'Runtime mode reported by Next.js and Node.',
+    display: false,
+  },
+]
+
+export function buildEnvironmentRows(
+  catalog: Catalog,
+  env: Record<string, string | undefined>,
+): EnvironmentRow[] {
+  return [
+    ...APP_ENVIRONMENT.filter((definition) => definition.display).map((definition) =>
+      rowForDefinition(definition, env),
+    ),
+    ...catalogBaseUrlRows(catalog, env),
+  ]
+}
+
+function catalogBaseUrlRows(
+  catalog: Catalog,
+  env: Record<string, string | undefined>,
+): EnvironmentRow[] {
+  const systemsByEnv = new Map<string, string[]>()
+  for (const system of catalog.systems) {
+    const systems = systemsByEnv.get(system.baseUrlEnv) ?? []
+    systems.push(system.name)
+    systemsByEnv.set(system.baseUrlEnv, systems)
+  }
+
+  return [...systemsByEnv.entries()].map(([name, systems]) =>
+    rowForDefinition(
+      {
+        name,
+        category: 'Upstream',
+        description: `Base URL for ${systems.join(', ')} passthrough.`,
+        display: true,
+      },
+      env,
+    ),
+  )
+}
+
+function rowForDefinition(
+  definition: EnvironmentDefinition,
+  env: Record<string, string | undefined>,
+): EnvironmentRow {
+  const raw = env[definition.name]
+  const value =
+    definition.hideValue && raw !== undefined
+      ? 'Hidden'
+      : raw === undefined
+      ? definition.defaultValue === undefined
+        ? '(not set)'
+        : `(default: ${definition.defaultValue})`
+      : raw === ''
+        ? '(empty string)'
+        : raw
+
+  return {
+    name: definition.name,
+    value,
+    status: raw === undefined ? (definition.defaultValue === undefined ? 'unset' : 'default') : 'set',
+    category: definition.category,
+    description: definition.description,
+    ...(definition.possibleValues ? { possibleValues: definition.possibleValues } : {}),
+    ...(definition.hideValue && raw !== undefined ? { valueHidden: true } : {}),
+  }
+}

package/.next/standalone/src/lib/format.ts

@@ -0,0 +1,3 @@
+export function formatUtc(date: Date): string {
+  return `${date.toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}

package/.next/standalone/src/lib/logs/admin-log.ts

@@ -0,0 +1,27 @@
+import type { Db } from 'mongodb'
+import { insertLogEntry, newLogId } from './store'
+
+/**
+ * Records an admin action (profile save / progress reset) as a log entry so it
+ * shows in the logs view, regardless of whether the UI or the /ui/api routes
+ * drove the change. Failures are swallowed — an admin action must not fail
+ * because logging failed.
+ */
+export async function writeAdminLog(
+  db: Db,
+  profileId: string,
+  adminAction: 'profile_saved' | 'progress_reset',
+  adminEndpoint?: string,
+): Promise<void> {
+  try {
+    await insertLogEntry(db, {
+      logId: newLogId(),
+      ts: new Date(),
+      kind: 'admin',
+      profileId,
+      trace: { adminAction, ...(adminEndpoint && { adminEndpoint }) },
+    })
+  } catch (err) {
+    console.warn('[mock-log] failed to write admin log entry:', err)
+  }
+}

package/.next/standalone/src/lib/logs/store.ts

@@ -0,0 +1,153 @@
+import type { Db } from 'mongodb'
+
+export type LogOutcome = 'fixture' | 'passthrough' | 'error'
+
+export type ScenarioSource = 'pin' | 'sequence' | 'implicit' | 'global' | 'unmocked_policy'
+
+export interface LogPayload {
+  headers: Record<string, string>
+  body: unknown
+  truncated: boolean
+}
+
+export interface LogResponsePayload extends LogPayload {
+  status: number
+}
+
+export interface ProfileResolutionTrace {
+  selector: string
+  value: string
+  via: 'direct' | { namespace: string; key: string }
+}
+
+export interface LogTraceData {
+  profileResolution?: ProfileResolutionTrace
+  scenario?: string
+  scenarioSource?: ScenarioSource
+  sequence?: { step: number; of: number; served: number }
+  /** Present when a resolver-backed scenario ran: the picked slug and what it returned. */
+  resolver?: { slug: string; returned: string }
+  captures?: Array<{ namespace: string; key: string }>
+  placeholders?: Record<string, string>
+  validation?: { request?: 'ok' | 'failed'; response?: 'ok' | 'failed' | 'drift_warning' }
+  upstream?: { url: string; status: number; durationMs: number }
+  adminAction?: 'profile_saved' | 'progress_reset'
+  adminEndpoint?: string
+}
+
+export interface LogEntry {
+  logId: string
+  ts: Date
+  durationMs?: number
+  kind: 'request' | 'admin'
+  profileId?: string
+  system?: string
+  endpoint?: string
+  method?: string
+  path?: string
+  query?: string
+  request?: LogPayload
+  response?: LogResponsePayload
+  outcome?: LogOutcome
+  error?: { code: string; message: string }
+  trace: LogTraceData
+}
+
+export interface ListLogsOptions {
+  profileId?: string
+  endpoint?: string
+  errorsOnly?: boolean
+  /** Case-insensitive prefix match on logId (paste from x-mock-log-id). */
+  logIdQuery?: string
+  sinceId?: string
+  beforeId?: string
+  limit?: number
+}
+
+export type LogSummary = Omit<LogEntry, 'request' | 'response'> & {
+  response?: { status: number }
+}
+
+const DEFAULT_LIMIT = 100
+
+const SUMMARY_PROJECTION = {
+  _id: 0,
+  request: 0,
+  'response.headers': 0,
+  'response.body': 0,
+  'response.truncated': 0,
+} as const
+
+async function buildLogFilter(
+  collection: import('mongodb').Collection<LogEntry>,
+  options: ListLogsOptions,
+): Promise<Record<string, unknown>> {
+  const filter: Record<string, unknown> = {}
+  if (options.profileId) filter.profileId = options.profileId
+  if (options.endpoint) filter.endpoint = options.endpoint
+  if (options.errorsOnly) filter.outcome = 'error'
+  if (options.logIdQuery) {
+    filter.logId = { $regex: `^${escapeRegex(options.logIdQuery)}`, $options: 'i' }
+  }
+  // Keyset cursors respect the { ts: -1, logId: -1 } sort so entries sharing a
+  // millisecond are never skipped. `before` (older) takes precedence over
+  // `since` (newer) if both are somehow supplied; the UI only sends one.
+  const cursorId = options.beforeId ?? options.sinceId
+  if (cursorId) {
+    const cursor = await collection.findOne(
+      { logId: cursorId },
+      { projection: { _id: 0, ts: 1, logId: 1 } },
+    )
+    if (cursor) {
+      const op = options.beforeId ? '$lt' : '$gt'
+      filter.$or = [{ ts: { [op]: cursor.ts } }, { ts: cursor.ts, logId: { [op]: cursor.logId } }]
+    } else if (options.beforeId) {
+      // Unknown/expired `before` cursor → "no older entries". `$and` with an
+      // impossible clause guarantees empty without clobbering a logId regex.
+      filter.$and = [{ logId: { $in: [] } }]
+    }
+  }
+  return filter
+}
+
+export async function insertLogEntry(db: Db, entry: LogEntry): Promise<void> {
+  await db.collection<LogEntry>('requestLogs').insertOne({ ...entry })
+}
+
+export async function listLogEntries(db: Db, options: ListLogsOptions): Promise<LogEntry[]> {
+  const collection = db.collection<LogEntry>('requestLogs')
+  const filter = await buildLogFilter(collection, options)
+  return collection
+    .find(filter, { projection: { _id: 0 } })
+    .sort({ ts: -1, logId: -1 })
+    .limit(options.limit ?? DEFAULT_LIMIT)
+    .toArray()
+}
+
+export async function listLogSummaries(db: Db, options: ListLogsOptions): Promise<LogSummary[]> {
+  const collection = db.collection<LogEntry>('requestLogs')
+  const filter = await buildLogFilter(collection, options)
+  return collection
+    .find<LogSummary>(filter, { projection: SUMMARY_PROJECTION })
+    .sort({ ts: -1, logId: -1 })
+    .limit(options.limit ?? DEFAULT_LIMIT)
+    .toArray()
+}
+
+export async function getLogEntry(db: Db, logId: string): Promise<LogEntry | null> {
+  return db.collection<LogEntry>('requestLogs').findOne({ logId }, { projection: { _id: 0 } })
+}
+
+export async function clearLogs(db: Db, profileId?: string): Promise<void> {
+  await db
+    .collection<LogEntry>('requestLogs')
+    .deleteMany(profileId === undefined ? {} : { profileId })
+}
+
+export function newLogId(): string {
+  return `lg_${crypto.randomUUID().replaceAll('-', '').slice(0, 12)}`
+}
+
+function escapeRegex(raw: string): string {
+  return raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/.next/standalone/src/lib/mock-engine/fixtures.ts

@@ -0,0 +1,38 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export interface Fixture {
+  description?: string
+  summary?: string
+  status: number
+  headers?: Record<string, string>
+  body: unknown
+}
+
+export class FixtureError extends Error {}
+
+export function fixtureFilePath(
+  catalogDir: string,
+  systemSlug: string,
+  endpointName: string,
+  scenario: string,
+): string {
+  return path.join(catalogDir, systemSlug, endpointName, `${scenario}.json`)
+}
+
+export function loadFixture(
+  catalogDir: string,
+  systemSlug: string,
+  endpointName: string,
+  scenario: string,
+): Fixture {
+  const file = fixtureFilePath(catalogDir, systemSlug, endpointName, scenario)
+  if (!fs.existsSync(file)) {
+    throw new FixtureError(`fixture not found: ${file}`)
+  }
+  const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Fixture
+  if (typeof parsed.status !== 'number' || !('body' in parsed)) {
+    throw new FixtureError(`invalid fixture (requires numeric "status" and "body"): ${file}`)
+  }
+  return parsed
+}

package/.next/standalone/src/lib/mock-engine/resolver.ts

@@ -0,0 +1,110 @@
+import path from 'node:path'
+import vm from 'node:vm'
+import { transformSync } from 'esbuild'
+
+export const DEFAULT_DYNAMIC_TIMEOUT_MS = 100
+
+export interface ResolverInput {
+  request: {
+    method: string
+    path: string
+    pathParams: Record<string, string>
+    query: Record<string, string[]>
+    headers: Record<string, string>
+    body: unknown
+  }
+  history: string[]
+  profileId: string | null
+}
+
+export interface CompiledResolver {
+  /** Optional `export const description = '…'` from the resolver source — its UI label. */
+  description?: string
+  /** Optional `export const summary = '…'` — secondary line shown under the label. */
+  summary?: string
+  invoke(input: ResolverInput, timeoutMs: number): unknown
+}
+
+export class ResolverCompileError extends Error {}
+export class ResolverRuntimeError extends Error {}
+export class ResolverTimeoutError extends Error {}
+
+export function resolverFilePath(
+  catalogDir: string,
+  systemSlug: string,
+  endpointName: string,
+  slug: string,
+): string {
+  return path.join(catalogDir, systemSlug, endpointName, `${slug}.ts`)
+}
+
+export function compileResolver(source: string, label: string): CompiledResolver {
+  let code: string
+  try {
+    code = transformSync(source, { loader: 'ts', format: 'cjs', target: 'node18' }).code
+  } catch (err) {
+    throw new ResolverCompileError(`${label}: failed to transpile resolver: ${message(err)}`)
+  }
+
+  // Empty context: no require / process / fetch / console leak from the host.
+  const sandbox: Record<string, unknown> = { module: { exports: {} } }
+  sandbox.exports = (sandbox.module as { exports: unknown }).exports
+  const context = vm.createContext(sandbox)
+  try {
+    new vm.Script(code, { filename: label }).runInContext(context, { timeout: 1000 })
+  } catch (err) {
+    throw new ResolverCompileError(`${label}: failed to evaluate resolver: ${message(err)}`)
+  }
+
+  const mod = (sandbox.module as { exports: Record<string, unknown> }).exports
+  const fn = typeof mod === 'function' ? mod : (mod?.default as unknown)
+  if (typeof fn !== 'function') {
+    throw new ResolverCompileError(`${label}: resolver must default-export a function`)
+  }
+  const rawDescription = (mod as Record<string, unknown> | undefined)?.description
+  const description = typeof rawDescription === 'string' ? rawDescription : undefined
+  const rawSummary = (mod as Record<string, unknown> | undefined)?.summary
+  const summary = typeof rawSummary === 'string' ? rawSummary : undefined
+  sandbox.__resolver = fn
+  const invokeScript = new vm.Script('__resolver(__input)', { filename: `${label}#invoke` })
+
+  return {
+    ...(description !== undefined ? { description } : {}),
+    ...(summary !== undefined ? { summary } : {}),
+    invoke(input: ResolverInput, timeoutMs: number): unknown {
+      sandbox.__input = input
+      try {
+        return invokeScript.runInContext(context, { timeout: timeoutMs })
+      } catch (err) {
+        if (isTimeout(err)) {
+          throw new ResolverTimeoutError(`${label}: resolver exceeded ${timeoutMs}ms`)
+        }
+        throw new ResolverRuntimeError(`${label}: resolver threw: ${message(err)}`)
+      }
+    },
+  }
+}
+
+// Real vm timeouts carry Node's documented, stable error code
+// `ERR_SCRIPT_EXECUTION_TIMEOUT`. Detect them by code rather than by matching
+// the message text, so a resolver that legitimately throws an error whose
+// message merely contains "timed out" is still surfaced as a runtime error
+// with its original message intact. Like `.message`, this own-property `code`
+// survives the vm realm crossing, and regular thrown errors do not have it.
+function isTimeout(err: unknown): boolean {
+  return (
+    err !== null &&
+    typeof err === 'object' &&
+    (err as { code?: unknown }).code === 'ERR_SCRIPT_EXECUTION_TIMEOUT'
+  )
+}
+
+// Errors thrown by vm timeouts are constructed in the sandbox's realm, so
+// `err instanceof Error` is false even though `err.message` is a normal
+// string. Check for a `message` property instead of relying on `instanceof`.
+function message(err: unknown): string {
+  if (err && typeof err === 'object' && typeof (err as { message?: unknown }).message === 'string') {
+    return (err as { message: string }).message
+  }
+  return String(err)
+}

package/.next/standalone/src/lib/mock-engine/template.ts

@@ -0,0 +1,71 @@
+import {
+  extractValue,
+  parseSelector,
+  RequestContext,
+  SelectorParseError,
+} from '../catalog/selector'
+
+export class PlaceholderError extends Error {}
+
+const PLACEHOLDER_RE = /\{\{(.+?)\}\}/g
+
+function resolvePlaceholder(expr: string, ctx: RequestContext, now: Date): string {
+  if (expr === 'now:iso') return now.toISOString()
+  if (expr === 'now:YYYYMMDD') return now.toISOString().slice(0, 10).replace(/-/g, '')
+  if (expr.startsWith('now:')) {
+    throw new PlaceholderError(`unknown now formatter in "{{${expr}}}" (use now:iso or now:YYYYMMDD)`)
+  }
+  let selector: ReturnType<typeof parseSelector>
+  try {
+    selector = parseSelector(expr)
+  } catch (err) {
+    if (err instanceof SelectorParseError) {
+      throw new PlaceholderError(`invalid placeholder "{{${expr}}}": ${err.message}`)
+    }
+    throw err
+  }
+  const value = extractValue(selector, ctx)
+  if (value === null) {
+    throw new PlaceholderError(`placeholder "{{${expr}}}" did not resolve against the request`)
+  }
+  return String(value)
+}
+
+export function resolveTemplate(
+  node: unknown,
+  ctx: RequestContext,
+  now: Date,
+  resolutions?: Record<string, string>,
+): unknown {
+  if (typeof node === 'string') {
+    return node.replace(PLACEHOLDER_RE, (_, expr: string) => {
+      const value = resolvePlaceholder(expr, ctx, now)
+      if (resolutions) resolutions[`{{${expr}}}`] = value
+      return value
+    })
+  }
+  if (Array.isArray(node)) {
+    return node.map((item) => resolveTemplate(item, ctx, now, resolutions))
+  }
+  if (node !== null && typeof node === 'object') {
+    return Object.fromEntries(
+      Object.entries(node).map(([k, v]) => [k, resolveTemplate(v, ctx, now, resolutions)]),
+    )
+  }
+  return node
+}
+
+export function listPlaceholders(node: unknown): string[] {
+  const found: string[] = []
+  const walk = (n: unknown): void => {
+    if (typeof n === 'string') {
+      for (const m of n.matchAll(PLACEHOLDER_RE)) found.push(m[1])
+    } else if (Array.isArray(n)) {
+      n.forEach(walk)
+    } else if (n !== null && typeof n === 'object') {
+      Object.values(n).forEach(walk)
+    }
+  }
+  walk(node)
+  return found
+}

package/.next/standalone/src/lib/mongo/embedded.ts

@@ -0,0 +1,40 @@
+import type { MongoMemoryServer } from 'mongodb-memory-server'
+
+// A single embedded mongod, booted lazily and shared process-wide. The boot is
+// memoized as a promise so concurrent callers await the same instance rather
+// than racing to start two servers. Data is ephemeral by design: this path is
+// only taken when no external MONGODB_CONNECTION_STRING is configured.
+let embeddedPromise: Promise<string> | null = null
+let server: MongoMemoryServer | null = null
+
+async function bootEmbedded(): Promise<string> {
+  // Dynamic import keeps mongodb-memory-server out of the hot path when an
+  // external connection string is configured.
+  const { MongoMemoryServer } = await import('mongodb-memory-server')
+  console.log(
+    '[mock-server] MONGODB_CONNECTION_STRING not set; starting embedded in-memory MongoDB (data is ephemeral)…',
+  )
+  server = await MongoMemoryServer.create()
+  return server.getUri()
+}
+
+export async function resolveMongoUri(): Promise<string> {
+  const configured = process.env.MONGODB_CONNECTION_STRING
+  if (configured) return configured
+  if (!embeddedPromise) {
+    embeddedPromise = bootEmbedded().catch((err) => {
+      // A failed boot must not poison the singleton — clear it so the next
+      // call retries a fresh start rather than returning the dead rejection.
+      embeddedPromise = null
+      throw err
+    })
+  }
+  return embeddedPromise
+}
+
+export async function stopEmbeddedMongo(): Promise<void> {
+  const running = server
+  server = null
+  embeddedPromise = null
+  if (running) await running.stop()
+}

package/.next/standalone/src/lib/profiles/api-scenarios.ts

@@ -0,0 +1,69 @@
+import type { Catalog, EndpointDef } from '../catalog/types'
+import { isScenarioDeclared } from '../scenarios'
+import type { ScenarioSelection } from './store'
+
+export class InvalidScenarioSelectionError extends Error {}
+
+/**
+ * JSON-body counterpart to parseEndpointScenarios (form.ts). Validates every
+ * endpoint name and scenario key against the catalog and applies the same
+ * delta-save normalization: selections equal to the implicit scenario are
+ * dropped, and a one-step sequence collapses to a single selection.
+ */
+export function parseEndpointScenariosFromJson(
+  input: unknown,
+  catalog: Catalog,
+  implicit: string,
+): Record<string, ScenarioSelection> {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    throw new InvalidScenarioSelectionError('endpointScenarios must be an object')
+  }
+
+  const byName = new Map<string, EndpointDef>()
+  for (const system of catalog.systems) {
+    for (const endpoint of system.endpoints) byName.set(endpoint.name, endpoint)
+  }
+
+  const result: Record<string, ScenarioSelection> = {}
+  for (const [name, raw] of Object.entries(input as Record<string, unknown>)) {
+    const endpoint = byName.get(name)
+    if (!endpoint) throw new InvalidScenarioSelectionError(`unknown endpoint "${name}"`)
+    const selection = normalizeSelection(endpoint, raw, implicit)
+    if (selection !== undefined) result[name] = selection
+  }
+  return result
+}
+
+function normalizeSelection(
+  endpoint: EndpointDef,
+  raw: unknown,
+  implicit: string,
+): ScenarioSelection | undefined {
+  if (Array.isArray(raw)) {
+    if (!raw.every((step) => typeof step === 'string')) {
+      throw new InvalidScenarioSelectionError(
+        `endpoint "${endpoint.name}": scenario sequence must be an array of strings`,
+      )
+    }
+    for (const step of raw) assertDeclared(endpoint, step)
+    if (raw.length === 0) return undefined
+    if (raw.length > 1) return raw
+    return raw[0] === implicit ? undefined : raw[0]
+  }
+  if (typeof raw !== 'string') {
+    throw new InvalidScenarioSelectionError(
+      `endpoint "${endpoint.name}": scenario must be a string or array of strings`,
+    )
+  }
+  if (raw === '' || raw === implicit) return undefined
+  assertDeclared(endpoint, raw)
+  return raw
+}
+
+function assertDeclared(endpoint: EndpointDef, scenario: string): void {
+  if (!isScenarioDeclared(endpoint, scenario)) {
+    throw new InvalidScenarioSelectionError(
+      `endpoint "${endpoint.name}": scenario "${scenario}" is not declared`,
+    )
+  }
+}