@open-mercato/cli 0.6.6-develop.5509.1.006f4d4f24 → 0.6.6-develop.5523.1.e223ca1915

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.6.6-develop.5509.1.006f4d4f24",
+  "version": "0.6.6-develop.5523.1.e223ca1915",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.1.4",
     "@mikro-orm/migrations": "^7.1.4",
     "@mikro-orm/postgresql": "^7.1.4",
-    "@open-mercato/queue": "0.6.6-develop.5509.1.006f4d4f24",
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24",
+    "@open-mercato/queue": "0.6.6-develop.5523.1.e223ca1915",
+    "@open-mercato/shared": "0.6.6-develop.5523.1.e223ca1915",
     "cross-spawn": "^7.0.6",
     "pg": "8.21.0",
     "semver": "^7.8.3",
@@ -70,10 +70,10 @@
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24"
+    "@open-mercato/shared": "0.6.6-develop.5523.1.e223ca1915"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.6-develop.5509.1.006f4d4f24",
+    "@open-mercato/shared": "0.6.6-develop.5523.1.e223ca1915",
     "@types/jest": "^30.0.0",
     "jest": "^30.4.2",
     "ts-jest": "^29.4.11"

package/src/lib/__tests__/single-instance-strategy-guard.test.ts

@@ -0,0 +1,138 @@
+import {
+  assertSingleInstanceStrategies,
+  evaluateSingleInstanceGuard,
+  SingleInstanceStrategyError,
+  type InfraStrategySnapshot,
+} from '../single-instance-strategy-guard'
+
+const singleInstanceSnapshot: InfraStrategySnapshot = {
+  cacheStrategy: 'memory',
+  queueStrategy: 'local',
+  rateLimitStrategy: 'memory',
+}
+
+const multiInstanceSafeSnapshot: InfraStrategySnapshot = {
+  cacheStrategy: 'redis',
+  queueStrategy: 'async',
+  rateLimitStrategy: 'redis',
+}
+
+describe('evaluateSingleInstanceGuard', () => {
+  it('is a no-op outside production even with single-instance strategies', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'development',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('ok')
+    expect(result.offenders).toHaveLength(3)
+  })
+
+  it('is a no-op in production when all strategies are multi-instance safe', () => {
+    const result = evaluateSingleInstanceGuard(multiInstanceSafeSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('ok')
+    expect(result.offenders).toHaveLength(0)
+  })
+
+  it('fails in production when a multi-instance topology is declared via OM_MULTI_INSTANCE', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+    })
+    expect(result.action).toBe('fail')
+    expect(result.offenders.map((offender) => offender.envVar)).toEqual([
+      'CACHE_STRATEGY',
+      'QUEUE_STRATEGY',
+      'RATE_LIMIT_STRATEGY',
+    ])
+  })
+
+  it('treats OM_INSTANCE_COUNT > 1 as a multi-instance topology', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_INSTANCE_COUNT: '3',
+    })
+    expect(result.action).toBe('fail')
+  })
+
+  it('does not treat OM_INSTANCE_COUNT=1 as multi-instance', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_INSTANCE_COUNT: '1',
+    })
+    expect(result.action).toBe('warn')
+  })
+
+  it('only warns in production when no multi-instance topology is declared', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+    })
+    expect(result.action).toBe('warn')
+    expect(result.multiInstance).toBe(false)
+  })
+
+  it('downgrades a hard failure to a warning when the override is set', () => {
+    const result = evaluateSingleInstanceGuard(singleInstanceSnapshot, {
+      NODE_ENV: 'production',
+      OM_MULTI_INSTANCE: '1',
+      OM_ALLOW_SINGLE_INSTANCE_STRATEGIES: '1',
+    })
+    expect(result.action).toBe('warn')
+    expect(result.overridden).toBe(true)
+  })
+
+  it('flags only the offending strategy when others are safe', () => {
+    const result = evaluateSingleInstanceGuard(
+      { cacheStrategy: 'redis', queueStrategy: 'local', rateLimitStrategy: 'redis' },
+      { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+    )
+    expect(result.action).toBe('fail')
+    expect(result.offenders).toHaveLength(1)
+    expect(result.offenders[0].component).toBe('queue')
+  })
+})
+
+describe('assertSingleInstanceStrategies', () => {
+  function createLogger() {
+    return {
+      warn: jest.fn(),
+      error: jest.fn(),
+    }
+  }
+
+  it('throws and logs when the guard fails', () => {
+    const logger = createLogger()
+    expect(() =>
+      assertSingleInstanceStrategies(
+        { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+        { snapshot: singleInstanceSnapshot, logger },
+      ),
+    ).toThrow(SingleInstanceStrategyError)
+    expect(logger.error).toHaveBeenCalled()
+    expect(logger.warn).not.toHaveBeenCalled()
+  })
+
+  it('logs a warning but does not throw when only warning', () => {
+    const logger = createLogger()
+    const result = assertSingleInstanceStrategies(
+      { NODE_ENV: 'production' },
+      { snapshot: singleInstanceSnapshot, logger },
+    )
+    expect(result.action).toBe('warn')
+    expect(logger.warn).toHaveBeenCalled()
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+
+  it('stays silent and does not throw when everything is safe', () => {
+    const logger = createLogger()
+    const result = assertSingleInstanceStrategies(
+      { NODE_ENV: 'production', OM_MULTI_INSTANCE: '1' },
+      { snapshot: multiInstanceSafeSnapshot, logger },
+    )
+    expect(result.action).toBe('ok')
+    expect(logger.warn).not.toHaveBeenCalled()
+    expect(logger.error).not.toHaveBeenCalled()
+  })
+})

package/src/lib/single-instance-strategy-guard.ts

@@ -0,0 +1,172 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import { resolveQueueStrategy } from '@open-mercato/queue'
+
+/**
+ * Boot-time guard that refuses to start (or warns) when an infrastructure
+ * strategy that is only safe for a single process/instance is configured under
+ * a declared multi-instance topology.
+ *
+ * Background: `CACHE_STRATEGY`, `RATE_LIMIT_STRATEGY` and `QUEUE_STRATEGY` all
+ * default to single-instance modes (`memory`/`memory`/`local`). Running more
+ * than one app instance against those defaults silently breaks three
+ * correctness invariants at once — stale RBAC caches after a privilege
+ * revocation, rate limits multiplied by the instance count, and duplicate job
+ * processing from the leaderless local file queue. None of them warn.
+ *
+ * Only strategies that coordinate across processes via shared external state
+ * are considered multi-instance safe. Everything else (the in-process memory
+ * strategies, the local file queue, and disk-backed caches that are not shared
+ * across hosts) is treated as single-instance.
+ */
+const MULTI_INSTANCE_SAFE_STRATEGIES = {
+  cache: ['redis'],
+  queue: ['async'],
+  rateLimit: ['redis'],
+} as const
+
+export type SingleInstanceGuardComponent = 'cache' | 'queue' | 'rateLimit'
+
+export type SingleInstanceGuardOffender = {
+  component: SingleInstanceGuardComponent
+  envVar: string
+  configured: string
+  safeValues: readonly string[]
+}
+
+export type SingleInstanceGuardAction = 'ok' | 'warn' | 'fail'
+
+export type SingleInstanceGuardResult = {
+  action: SingleInstanceGuardAction
+  offenders: SingleInstanceGuardOffender[]
+  production: boolean
+  multiInstance: boolean
+  overridden: boolean
+}
+
+export type InfraStrategySnapshot = {
+  cacheStrategy: string
+  queueStrategy: string
+  rateLimitStrategy: string
+}
+
+const COMPONENT_ENV_VARS: Record<SingleInstanceGuardComponent, string> = {
+  cache: 'CACHE_STRATEGY',
+  queue: 'QUEUE_STRATEGY',
+  rateLimit: 'RATE_LIMIT_STRATEGY',
+}
+
+export class SingleInstanceStrategyError extends Error {
+  readonly offenders: SingleInstanceGuardOffender[]
+
+  constructor(result: SingleInstanceGuardResult) {
+    super(
+      `Refusing to start: single-instance infrastructure strategies (${result.offenders
+        .map((offender) => `${offender.envVar}=${offender.configured}`)
+        .join(', ')}) are configured under a declared multi-instance topology. ` +
+        'Switch to a multi-instance-safe strategy or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override.',
+    )
+    this.name = 'SingleInstanceStrategyError'
+    this.offenders = result.offenders
+  }
+}
+
+/**
+ * Read the configured infrastructure strategies. Queue resolution reuses the
+ * canonical `resolveQueueStrategy()` so the default stays single-sourced; cache
+ * and rate-limit values are read directly with their documented defaults
+ * (`packages/cache/src/service.ts`, `packages/shared/src/lib/ratelimit/config.ts`)
+ * because the guard's safe-set policy — not the resolver default — decides what
+ * counts as single-instance.
+ */
+export function readInfraStrategySnapshot(env: NodeJS.ProcessEnv = process.env): InfraStrategySnapshot {
+  return {
+    cacheStrategy: env.CACHE_STRATEGY?.trim() || 'memory',
+    queueStrategy: resolveQueueStrategy(),
+    rateLimitStrategy: env.RATE_LIMIT_STRATEGY?.trim() || 'memory',
+  }
+}
+
+function resolveMultiInstanceHint(env: NodeJS.ProcessEnv): boolean {
+  if (parseBooleanWithDefault(env.OM_MULTI_INSTANCE, false)) return true
+  const instanceCount = Number.parseInt(env.OM_INSTANCE_COUNT ?? '', 10)
+  return Number.isFinite(instanceCount) && instanceCount > 1
+}
+
+export function evaluateSingleInstanceGuard(
+  snapshot: InfraStrategySnapshot,
+  env: NodeJS.ProcessEnv = process.env,
+): SingleInstanceGuardResult {
+  const configured: Record<SingleInstanceGuardComponent, string> = {
+    cache: snapshot.cacheStrategy,
+    queue: snapshot.queueStrategy,
+    rateLimit: snapshot.rateLimitStrategy,
+  }
+
+  const offenders: SingleInstanceGuardOffender[] = []
+  for (const component of Object.keys(configured) as SingleInstanceGuardComponent[]) {
+    const safeValues: readonly string[] = MULTI_INSTANCE_SAFE_STRATEGIES[component]
+    if (!safeValues.includes(configured[component])) {
+      offenders.push({
+        component,
+        envVar: COMPONENT_ENV_VARS[component],
+        configured: configured[component],
+        safeValues,
+      })
+    }
+  }
+
+  const production = (env.NODE_ENV ?? '').trim() === 'production'
+  const multiInstance = resolveMultiInstanceHint(env)
+  const overridden = parseBooleanWithDefault(env.OM_ALLOW_SINGLE_INSTANCE_STRATEGIES, false)
+
+  let action: SingleInstanceGuardAction = 'ok'
+  if (offenders.length > 0 && production) {
+    action = multiInstance && !overridden ? 'fail' : 'warn'
+  }
+
+  return { action, offenders, production, multiInstance, overridden }
+}
+
+export function formatSingleInstanceGuardMessage(result: SingleInstanceGuardResult): string[] {
+  const offenderLines = result.offenders.map(
+    (offender) =>
+      `  - ${offender.envVar}=${offender.configured} (multi-instance-safe: ${offender.safeValues.join(', ')})`,
+  )
+  const header =
+    result.action === 'fail'
+      ? '[server] Refusing to start: single-instance infrastructure strategies under a multi-instance topology.'
+      : '[server] WARNING: single-instance infrastructure strategies detected in production.'
+  const guidance =
+    result.action === 'fail'
+      ? '[server] Switch each strategy above to a multi-instance-safe value, or set OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 to override (accepting duplicate jobs, stale ACLs, and weakened rate limits).'
+      : result.multiInstance
+        ? '[server] OM_ALLOW_SINGLE_INSTANCE_STRATEGIES=1 is set — proceeding despite the risks above (duplicate jobs, stale ACLs, weakened rate limits).'
+        : '[server] Running multiple instances against these strategies will cause duplicate jobs, stale ACLs, and weakened rate limits. Set OM_MULTI_INSTANCE=1 to make this a hard failure once you scale out.'
+  return [header, ...offenderLines, guidance]
+}
+
+export type SingleInstanceGuardLogger = Pick<Console, 'warn' | 'error'>
+
+/**
+ * Evaluate the guard and enforce it: throw on `fail`, log prominently on
+ * `warn`, and stay silent on `ok`. Safe to call on every `start`; it never
+ * fires for dev boots or single-instance production deployments.
+ */
+export function assertSingleInstanceStrategies(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: { snapshot?: InfraStrategySnapshot; logger?: SingleInstanceGuardLogger },
+): SingleInstanceGuardResult {
+  const snapshot = options?.snapshot ?? readInfraStrategySnapshot(env)
+  const result = evaluateSingleInstanceGuard(snapshot, env)
+  const logger = options?.logger ?? console
+
+  if (result.action === 'fail') {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.error(line)
+    throw new SingleInstanceStrategyError(result)
+  }
+  if (result.action === 'warn') {
+    for (const line of formatSingleInstanceGuardMessage(result)) logger.warn(line)
+  }
+
+  return result
+}

package/src/mercato.ts

@@ -32,6 +32,7 @@ import {
 import { parseModuleInstallArgs } from './lib/module-install-args'
 import { resolveNextBuildIdCandidate } from './lib/next-build-id'
 import { acquireServerStartLock } from './lib/server-start-lock'
+import { assertSingleInstanceStrategies } from './lib/single-instance-strategy-guard'
 import { createDevEnvReloader, watchDevEnvFiles } from './lib/dev-env-reload'
 // Lazy-imported to avoid pulling in `testcontainers` (devDependency) at startup
 const lazyIntegration = () => import('./lib/testing/integration')
@@ -2154,6 +2155,9 @@ export async function run(argv = process.argv) {
           const autoSpawnSchedulerMode = resolveAutoSpawnSchedulerMode(process.env)
           const queueStrategy = process.env.QUEUE_STRATEGY || 'local'
           const runtimeEnv = buildServerProcessEnvironment(process.env)
+          // Throws on single-instance strategies under a multi-instance topology,
+          // aborting before the start lock is acquired or any process is spawned.
+          assertSingleInstanceStrategies(runtimeEnv)
           const schedulerCommand = lookupModuleCommand(getCliModules(), 'scheduler', 'start')
           const serverStartLock = acquireServerStartLock(appDir, {
             port: runtimeEnv.PORT ?? process.env.PORT ?? null,