@open-mercato/scheduler 0.7.1-develop.7113.1.9d83dca10c → 0.7.1-develop.7121.1.734c263bda

package/src/modules/scheduler/__integration__/TC-SCHED-009.spec.ts

@@ -0,0 +1,98 @@
+import { expect, test, type APIRequestContext } from '@playwright/test'
+import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+import { ACTIONS_PATH as AUDIT_ACTIONS_PATH } from '@open-mercato/core/modules/audit_logs/__integration__/helpers/auditLogsApi'
+import {
+  SCHEDULER_TRIGGER_PATH,
+  createScheduleJob,
+  deleteScheduleJob,
+  uniqueScheduleName,
+} from './helpers/scheduler'
+
+const TRIGGER_COMMAND_ID = 'scheduler.jobs.trigger'
+
+type ActionLogItem = {
+  commandId: string
+  actionLabel: string | null
+  actorUserId: string | null
+  resourceKind: string | null
+  resourceId: string | null
+  undoToken: string | null
+}
+
+async function findTriggerLogEntry(
+  request: APIRequestContext,
+  token: string,
+  resourceId: string,
+): Promise<ActionLogItem | null> {
+  const query = new URLSearchParams({ resourceKind: 'scheduler.job', resourceId })
+  const response = await apiRequest(request, 'GET', `${AUDIT_ACTIONS_PATH}?${query.toString()}`, {
+    token,
+  })
+  expect(response.status()).toBe(200)
+  const body = await readJsonSafe<{ items?: ActionLogItem[] }>(response)
+  return (body?.items ?? []).find((item) => item.commandId === TRIGGER_COMMAND_ID) ?? null
+}
+
+/**
+ * TC-SCHED-009: every authenticated manual trigger of a schedule is recorded in
+ * the action log against the calling user — including refusals.
+ *
+ * Manual triggering is an authorised-looking way to make an automated job run at
+ * a moment of the actor's choosing, so the attempt itself is the auditable event.
+ * Both assertions below are therefore independent of QUEUE_STRATEGY: under the
+ * async strategy the trigger is enqueued, under the local strategy it is refused
+ * with "async required", and either way the attempt must leave an entry.
+ */
+test.describe('TC-SCHED-009: manual schedule triggers are written to the action log', () => {
+  test('records a trigger attempt against the calling user', async ({ request }) => {
+    const token = await getAuthToken(request, 'admin')
+    let scheduleId: string | null = null
+
+    try {
+      scheduleId = await createScheduleJob(request, token, {
+        name: uniqueScheduleName('Trigger-Audit'),
+        scheduleType: 'interval',
+        scheduleValue: '1h',
+      })
+
+      const response = await apiRequest(request, 'POST', SCHEDULER_TRIGGER_PATH, {
+        token,
+        data: { id: scheduleId },
+      })
+      // 200 under the async strategy, 400 "async required" under local — the
+      // attempt is audited either way.
+      expect([200, 400]).toContain(response.status())
+
+      const entry = await findTriggerLogEntry(request, token, scheduleId)
+      expect(entry, 'a manual trigger writes an action-log entry').not.toBeNull()
+      expect(entry?.resourceKind).toBe('scheduler.job')
+      expect(entry?.resourceId).toBe(scheduleId)
+      expect(entry?.actorUserId, 'the entry names the caller').toBeTruthy()
+      expect(entry?.actionLabel ?? '').toMatch(/trigger/i)
+      // The enqueued run is reversed through the entries the run itself writes,
+      // so the trigger exposes no undo affordance (see TC-UNDO-001 §4).
+      expect(entry?.undoToken).toBeNull()
+    } finally {
+      await deleteScheduleJob(request, token, scheduleId)
+    }
+  })
+
+  test('records a refused trigger for a schedule id that does not exist', async ({ request }) => {
+    const token = await getAuthToken(request, 'admin')
+    // A well-formed UUID that no schedule uses: the request passes validation and
+    // is refused on lookup, which is exactly the probing attempt worth recording.
+    const missingScheduleId = '00000000-0000-4000-8000-0000000009de'
+
+    const response = await apiRequest(request, 'POST', SCHEDULER_TRIGGER_PATH, {
+      token,
+      data: { id: missingScheduleId },
+    })
+    expect(response.status()).toBe(404)
+
+    const entry = await findTriggerLogEntry(request, token, missingScheduleId)
+    expect(entry, 'a refused trigger still writes an action-log entry').not.toBeNull()
+    expect(entry?.resourceId).toBe(missingScheduleId)
+    expect(entry?.actorUserId, 'the refusal names the caller').toBeTruthy()
+  })
+})

package/src/modules/scheduler/api/trigger/__tests__/route.test.ts

@@ -0,0 +1,154 @@
+import { NextRequest } from 'next/server'
+import { CommandInterceptorError } from '@open-mercato/shared/lib/commands/errors'
+import type { TriggerScheduleResult } from '../../../commands/trigger'
+
+const scheduleId = '44444444-4444-4444-8444-444444444444'
+const userId = '33333333-3333-4333-8333-333333333333'
+const tenantId = '11111111-1111-4111-8111-111111111111'
+const organizationId = '22222222-2222-4222-8222-222222222222'
+
+const commandBusExecuteMock = jest.fn()
+const getAuthFromRequestMock = jest.fn()
+
+const container = {
+  resolve: jest.fn((token: string) => {
+    if (token === 'commandBus') return { execute: commandBusExecuteMock }
+    return {}
+  }),
+}
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: jest.fn(async () => container),
+}))
+
+jest.mock('@open-mercato/shared/lib/auth/server', () => ({
+  getAuthFromRequest: (...args: unknown[]) => getAuthFromRequestMock(...args),
+}))
+
+jest.mock('@open-mercato/shared/lib/i18n/server', () => ({
+  resolveTranslations: async () => ({
+    translate: (key: string, fallback?: string) => fallback ?? key,
+  }),
+}))
+
+import { POST } from '../route'
+
+function request(body: unknown = { id: scheduleId }): NextRequest {
+  return new NextRequest('http://localhost/api/scheduler/trigger', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+}
+
+function outcome(partial: Partial<TriggerScheduleResult>): TriggerScheduleResult {
+  return {
+    scheduleId,
+    scheduleName: null,
+    targetType: null,
+    target: null,
+    outcome: 'enqueued',
+    queueJobId: null,
+    error: null,
+    ...partial,
+  }
+}
+
+describe('POST /api/scheduler/trigger', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    getAuthFromRequestMock.mockResolvedValue({ sub: userId, tenantId, orgId: organizationId })
+  })
+
+  it('answers 401 without dispatching the command when there is no actor', async () => {
+    getAuthFromRequestMock.mockResolvedValue(null)
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(401)
+    expect(commandBusExecuteMock).not.toHaveBeenCalled()
+  })
+
+  it('answers 400 without dispatching the command when the body is malformed', async () => {
+    const response = await POST(request({ id: 'not-a-uuid' }))
+
+    expect(response.status).toBe(400)
+    expect(commandBusExecuteMock).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    ['enqueued' as const, 200],
+    ['not_found' as const, 404],
+    ['forbidden' as const, 403],
+    ['strategy_unsupported' as const, 400],
+    ['failed' as const, 400],
+  ])('maps the %s outcome to HTTP %i', async (value, status) => {
+    commandBusExecuteMock.mockResolvedValue({
+      result: outcome({ outcome: value, queueJobId: value === 'enqueued' ? 'job-1' : null }),
+    })
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(status)
+    expect(commandBusExecuteMock).toHaveBeenCalledWith(
+      'scheduler.jobs.trigger',
+      expect.objectContaining({ input: { id: scheduleId } }),
+    )
+  })
+
+  it('returns the queue job id on a successful enqueue', async () => {
+    commandBusExecuteMock.mockResolvedValue({
+      result: outcome({ outcome: 'enqueued', queueJobId: 'job-1' }),
+    })
+
+    const response = await POST(request())
+
+    expect(await response.json()).toEqual(expect.objectContaining({ ok: true, jobId: 'job-1' }))
+  })
+
+  it('surfaces the failure reason a failed outcome carries', async () => {
+    commandBusExecuteMock.mockResolvedValue({
+      result: outcome({ outcome: 'failed', error: 'Redis unavailable' }),
+    })
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({ error: 'Redis unavailable' })
+  })
+
+  // A `before` interceptor can block the dispatch with a deliberate status and body;
+  // flattening that to the generic 400 would make a business rejection look like a
+  // malformed request, unlike every CRUD route.
+  it('passes an interceptor rejection through with its own status and body', async () => {
+    commandBusExecuteMock.mockRejectedValue(
+      new CommandInterceptorError('Period is closed', {
+        status: 409,
+        body: { error: 'Period is closed', reason: 'locked-period' },
+      }),
+    )
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(409)
+    expect(await response.json()).toEqual({ error: 'Period is closed', reason: 'locked-period' })
+  })
+
+  it('keeps the generic 400 for an interceptor rejection that declares no status', async () => {
+    commandBusExecuteMock.mockRejectedValue(new CommandInterceptorError('Blocked'))
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({ error: 'Blocked' })
+  })
+
+  it('answers 400 when the bus throws after the enqueue, e.g. a failing audit store', async () => {
+    commandBusExecuteMock.mockRejectedValue(new Error('action log write failed'))
+
+    const response = await POST(request())
+
+    expect(response.status).toBe(400)
+    expect(await response.json()).toEqual({ error: 'action log write failed' })
+  })
+})

package/src/modules/scheduler/api/trigger/route.ts

@@ -2,14 +2,12 @@ import { NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import type { EntityManager } from '@mikro-orm/core'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
-import { createQueue } from '@open-mercato/queue'
-import { getRedisUrlOrThrow } from '@open-mercato/shared/lib/redis/connection'
-import { ScheduledJob } from '../../data/entities.js'
-import { resolveScheduleAccess } from '../../lib/scheduleAccess.js'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { getCommandInterceptorHttpRejection } from '@open-mercato/shared/lib/commands/errors'
 import { scheduleTriggerSchema } from '../../data/validators.js'
-import type { ExecuteSchedulePayload } from '../../workers/execute-schedule.worker.js'
+import type { TriggerScheduleResult } from '../../commands/trigger.js'
+import type { ScheduleTriggerInput } from '../../data/validators.js'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
@@ -23,46 +21,64 @@ export const metadata = {
 /**
  * POST /api/scheduler/trigger
  * Manually trigger a schedule
- * 
+ *
  * This enqueues the schedule execution job in BullMQ.
  * Execution history is tracked in BullMQ job state.
+ *
+ * The handler is a thin mapper: `scheduler.jobs.trigger` owns loading the
+ * schedule, deciding access, checking the queue strategy and enqueueing, so that
+ * every authenticated attempt — refusals included — leaves an action-log entry
+ * attributed to the caller. Expected refusals come back as an `outcome`, never as
+ * an exception, because a throwing handler would skip the audit write entirely.
  */
 export async function POST(req: NextRequest) {
   const { translate } = await resolveTranslations()
   const auth = await getAuthFromRequest(req)
+  // No actor means nothing to attribute, so this is the one path that
+  // legitimately leaves no action-log entry.
   if (!auth?.sub) {
     return NextResponse.json({ error: translate('scheduler.error.unauthorized', 'Unauthorized') }, { status: 401 })
   }
 
   const container = await createRequestContainer()
-  const em = container.resolve<EntityManager>('em')
 
   try {
     const body = await req.json()
+    // Parsed before the command runs, so a malformed body still answers 400 with
+    // the validation message and the command never sees unvalidated input.
     const input = scheduleTriggerSchema.parse(body)
 
-    // Load by id alone, then apply isolation to the loaded row. Folding the actor's
-    // tenant/org into the lookup would make every system-scoped schedule unmatchable.
-    const schedule = await em.findOne(ScheduledJob, { id: input.id, deletedAt: null })
-
-    if (!schedule) {
-      return NextResponse.json({ error: translate('scheduler.error.not_found', 'Schedule not found') }, { status: 404 })
+    // Null organization scope is the supported non-CRUD shape (see
+    // `ensureOrganizationScope`), and the scheduler's own worker and
+    // `localSchedulerService` build their contexts the same way. The trigger
+    // command performs its isolation through `resolveScheduleAccess` on the loaded
+    // row, so the only consumer of these fields is the action-log row's scope.
+    const ctx: CommandRuntimeContext = {
+      container,
+      auth,
+      organizationScope: null,
+      selectedOrganizationId: auth.orgId ?? null,
+      organizationIds: auth.orgId ? [auth.orgId] : null,
+      request: req,
     }
 
-    const access = resolveScheduleAccess(schedule, auth)
-    if (access === 'not_found') {
+    const commandBus = container.resolve<CommandBus>('commandBus')
+    const { result } = await commandBus.execute<ScheduleTriggerInput, TriggerScheduleResult>(
+      'scheduler.jobs.trigger',
+      { input, ctx },
+    )
+
+    if (result.outcome === 'not_found') {
       return NextResponse.json({ error: translate('scheduler.error.not_found', 'Schedule not found') }, { status: 404 })
     }
-    if (access === 'forbidden') {
+
+    if (result.outcome === 'forbidden') {
       return NextResponse.json({ error: translate('scheduler.error.access_denied', 'Access denied') }, { status: 403 })
     }
 
-    // Check if using async queue strategy
-    const queueStrategy = (process.env.QUEUE_STRATEGY || 'local') as 'local' | 'async'
-    
-    if (queueStrategy !== 'async') {
+    if (result.outcome === 'strategy_unsupported') {
       return NextResponse.json(
-        { 
+        {
           error: translate('scheduler.error.trigger_async_required', 'Manual trigger requires QUEUE_STRATEGY=async'),
           message: translate('scheduler.error.trigger_async_hint', 'Execution history and manual triggers are only available with BullMQ (async strategy)')
         },
@@ -70,37 +86,31 @@ export async function POST(req: NextRequest) {
       )
     }
 
-    // Enqueue execution job to scheduler-execution queue
-    const executionQueue = createQueue<ExecuteSchedulePayload>('scheduler-execution', queueStrategy, {
-      connection: { url: getRedisUrlOrThrow('QUEUE') },
-    })
-
-    const payload: ExecuteSchedulePayload = {
-      scheduleId: schedule.id,
-      tenantId: schedule.tenantId,
-      organizationId: schedule.organizationId,
-      scopeType: schedule.scopeType,
-      triggerType: 'manual',
-      triggeredByUserId: auth.sub,
+    if (result.outcome === 'failed') {
+      return NextResponse.json(
+        { error: result.error ?? translate('scheduler.error.trigger_failed', 'Failed to trigger schedule') },
+        { status: 400 }
+      )
     }
 
-    const jobId = await executionQueue.enqueue(payload)
-    await executionQueue.close()
-
-    logger.info('Manually triggered schedule', {
-      scheduleId: schedule.id,
-      scheduleName: schedule.name,
-      jobId,
-      triggeredBy: auth.sub,
-    })
-
     return NextResponse.json({
       ok: true,
-      jobId, // BullMQ job ID
+      jobId: result.queueJobId, // BullMQ job ID
       message: translate('scheduler.success.triggered', 'Schedule queued for execution'),
     })
 
   } catch (error) {
+    // A command interceptor that blocked with an explicit status is a deliberate
+    // business rejection, not a malformed request — surface its status and body
+    // instead of flattening it to the generic 400 below.
+    const interceptorRejection = getCommandInterceptorHttpRejection(error)
+    if (interceptorRejection) {
+      logger.warn('Manual trigger blocked by interceptor', { err: error })
+      return NextResponse.json(interceptorRejection.body, { status: interceptorRejection.status })
+    }
+    // The action log is written after the enqueue, and the bus does not guard that
+    // write, so a failing audit store surfaces here with the job already queued.
+    // Record it loudly: the run stays traceable even when its entry was lost.
     logger.error('Manual trigger failed', { err: error })
     return NextResponse.json(
       { error: error instanceof Error ? error.message : translate('scheduler.error.trigger_failed', 'Failed to trigger schedule') },
@@ -125,12 +135,12 @@ const errorResponseSchema = z.object({
 export const openApi: OpenApiRouteDoc = {
   tag: 'Scheduler',
   summary: 'Manually trigger a schedule',
-  description: 'Execute a schedule immediately by enqueueing it in the scheduler-execution queue. Requires QUEUE_STRATEGY=async.',
+  description: 'Execute a schedule immediately by enqueueing it in the scheduler-execution queue. Requires QUEUE_STRATEGY=async. Every authenticated attempt, including refusals, is recorded in the action log against the calling user; the one exception is an attempt a before command interceptor blocks, which is rejected before the command runs and therefore writes no row.',
   methods: {
     POST: {
       operationId: 'triggerScheduledJob',
       summary: 'Manually trigger a schedule',
-      description: 'Executes a scheduled job immediately, bypassing the scheduled time. Only works with async queue strategy.',
+      description: 'Executes a scheduled job immediately, bypassing the scheduled time. Only works with async queue strategy. The attempt is audited against the calling user whether it succeeds, is refused, or fails, except when a before command interceptor blocks it before the command runs.',
       requestBody: {
         schema: scheduleTriggerSchema,
         contentType: 'application/json',
@@ -147,6 +157,12 @@ export const openApi: OpenApiRouteDoc = {
         { status: 401, description: 'Unauthorized', schema: errorResponseSchema },
         { status: 403, description: 'Access denied', schema: errorResponseSchema },
         { status: 404, description: 'Schedule not found', schema: errorResponseSchema },
+        {
+          status: 409,
+          description:
+            'Trigger deliberately blocked by a before command interceptor. The interceptor chooses the status (any 4xx/5xx) and may replace the body.',
+          schema: errorResponseSchema,
+        },
       ],
     },
   },