@friggframework/admin-scripts 2.0.0-next.103 → 2.0.0-next.105

package/src/application/report-runner.js

@@ -0,0 +1,273 @@
+const { createAdminScriptContext } = require('./admin-script-context');
+const { validateParams } = require('./validate-script-input');
+
+const ARTIFACT_CONTENT_TYPES = {
+    csv: 'text/csv',
+    json: 'application/json',
+    pdf: 'application/pdf',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    html: 'text/html',
+    txt: 'text/plain',
+    xml: 'application/xml',
+    zip: 'application/zip',
+};
+
+// The run mode decides persistence: live computes inline and records nothing,
+// recorded persists an execution record, snapshot additionally tags the run
+// into a named series. Reports read only through the injected frigg command
+// bundle (exposed as context.commands).
+class ReportRunner {
+    constructor(params = {}) {
+        if (!params.reportFactory) {
+            throw new Error('ReportRunner requires a reportFactory');
+        }
+        this.reportFactory = params.reportFactory;
+        this.reportCommands = params.reportCommands || null;
+        this.friggCommands = params.friggCommands || null;
+        this.integrationFactory = params.integrationFactory || null;
+        this.artifactRepository = params.artifactRepository || null;
+    }
+
+    _getArtifactRepository() {
+        if (!this.artifactRepository) {
+            const {
+                createArtifactRepository,
+            } = require('@friggframework/core/artifacts/repositories/artifact-repository-factory');
+            this.artifactRepository = createArtifactRepository();
+        }
+        return this.artifactRepository;
+    }
+
+    async execute(reportName, params = {}, options = {}) {
+        const ReportClass = this.reportFactory.get(reportName);
+        const definition = ReportClass.Definition;
+
+        const runModes =
+            Array.isArray(definition.runModes) && definition.runModes.length
+                ? definition.runModes
+                : ['live'];
+        const mode = options.mode || runModes[0];
+        if (!runModes.includes(mode)) {
+            const error = new Error(
+                `Report "${reportName}" does not support mode "${mode}". Allowed: ${runModes.join(
+                    ', '
+                )}`
+            );
+            error.code = 'INVALID_MODE';
+            throw error;
+        }
+
+        const validation = validateParams(definition, params);
+        if (!validation.valid) {
+            const error = new Error(
+                `Invalid input: ${validation.errors.join(', ')}`
+            );
+            error.code = 'INVALID_INPUT';
+            throw error;
+        }
+
+        const format = definition.output?.format || 'json';
+
+        if (mode === 'live') {
+            // Non-JSON can't be returned inline as a response body; it needs an
+            // artifact, so it must run recorded/snapshot.
+            if (format !== 'json') {
+                const error = new Error(
+                    `Report "${reportName}" output format "${format}" cannot be returned inline; run it in recorded or snapshot mode`
+                );
+                error.code = 'ARTIFACT_STORAGE_UNAVAILABLE';
+                throw error;
+            }
+            return this._runLive(reportName, params);
+        }
+
+        return this._runRecorded(reportName, definition, params, mode, options);
+    }
+
+    async _runLive(reportName, params) {
+        const startTime = new Date();
+        // executionId null: live persists nothing, so record-dependent logging
+        // and chaining are intentionally inert.
+        const context = createAdminScriptContext({
+            executionId: null,
+            integrationFactory: this.integrationFactory,
+            commands: this.friggCommands,
+        });
+
+        const report = this.reportFactory.createInstance(reportName, {
+            context,
+            executionId: null,
+            integrationFactory: this.integrationFactory,
+        });
+
+        const output = await report.execute(context.commands, params, context);
+
+        return {
+            status: 'COMPLETED',
+            reportName,
+            mode: 'live',
+            output,
+            metrics: { durationMs: new Date() - startTime },
+        };
+    }
+
+    // Completion is written OUTSIDE the try on success so a persistence failure
+    // is never misreported as a report failure.
+    async _runRecorded(reportName, definition, params, mode, options = {}) {
+        let executionId = options.executionId;
+
+        if (!executionId) {
+            const execution = await this.reportCommands.createExecution({
+                reportName,
+                reportVersion: definition.version,
+                trigger: options.trigger || 'MANUAL',
+                mode,
+                input: params,
+                audit: options.audit,
+                seriesName:
+                    mode === 'snapshot'
+                        ? options.seriesName || reportName
+                        : undefined,
+                parentExecutionId: options.parentExecutionId,
+            });
+            if (execution.error) {
+                throw new Error(
+                    execution.reason ||
+                        'Failed to create report execution record'
+                );
+            }
+            executionId = execution.id;
+        }
+
+        const startTime = new Date();
+        const context = createAdminScriptContext({
+            executionId,
+            integrationFactory: this.integrationFactory,
+            commands: this.friggCommands,
+            lambdaContext: options.lambdaContext,
+        });
+
+        const format = definition.output?.format || 'json';
+        let output;
+        let artifact = null;
+        let summary;
+        try {
+            await this.reportCommands.updateExecutionState(
+                executionId,
+                'RUNNING'
+            );
+
+            const report = this.reportFactory.createInstance(reportName, {
+                context,
+                executionId,
+                integrationFactory: this.integrationFactory,
+            });
+
+            output = await report.execute(context.commands, params, context);
+
+            // Store non-JSON output as an artifact inside the try so a put
+            // failure marks the run FAILED (a continuation yield has none yet).
+            if (format !== 'json' && !(output && output.__continuation)) {
+                const stamp = new Date()
+                    .toISOString()
+                    .replace(/[:.]/g, '-');
+                const fileType = output.fileType || format;
+                const key = `reports/${executionId}/${reportName}-${stamp}.${fileType}`;
+                const contentType =
+                    ARTIFACT_CONTENT_TYPES[fileType] ||
+                    'application/octet-stream';
+                artifact = await this._getArtifactRepository().put(
+                    key,
+                    output.file,
+                    contentType
+                );
+                summary = output.summary;
+            }
+        } catch (error) {
+            const durationMs = new Date() - startTime;
+            await this.reportCommands.completeExecution(executionId, {
+                state: 'FAILED',
+                error: {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                },
+                metrics: {
+                    startTime: startTime.toISOString(),
+                    endTime: new Date().toISOString(),
+                    durationMs,
+                },
+                logs: context.getLogs(),
+            });
+
+            return {
+                executionId,
+                status: 'FAILED',
+                reportName,
+                mode,
+                error: { name: error.name, message: error.message },
+                metrics: { durationMs },
+            };
+        }
+
+        // Opt-in self-requeue: a report yields by returning a truthy
+        // `__continuation` (its resume state) instead of a final result. The
+        // execution stays RUNNING and the executor re-enqueues the SAME id, so
+        // the report resumes from the marker on the next invocation.
+        if (output && output.__continuation) {
+            const resumeState = output.__continuation;
+            if (typeof this.reportCommands.appendExecutionLog === 'function') {
+                await this.reportCommands.appendExecutionLog(executionId, {
+                    level: 'info',
+                    message: 'report yielded a continuation; re-queueing',
+                    data: { resumeAt: new Date().toISOString() },
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return {
+                executionId,
+                status: 'CONTINUE',
+                reportName,
+                mode,
+                continuation: resumeState,
+                metrics: { durationMs: new Date() - startTime },
+            };
+        }
+
+        const durationMs = new Date() - startTime;
+        const isArtifact = format !== 'json';
+        const result = {
+            executionId,
+            status: 'COMPLETED',
+            reportName,
+            mode,
+            ...(isArtifact ? { summary, artifact } : { output }),
+            metrics: { durationMs },
+        };
+
+        const completion = await this.reportCommands.completeExecution(
+            executionId,
+            {
+                state: 'COMPLETED',
+                ...(isArtifact ? { summary, artifact } : { output }),
+                metrics: {
+                    startTime: startTime.toISOString(),
+                    endTime: new Date().toISOString(),
+                    durationMs,
+                },
+                logs: context.getLogs(),
+            }
+        );
+        if (completion?.error) {
+            result.stateUpdateFailed = true;
+        }
+
+        return result;
+    }
+}
+
+function createReportRunner(params = {}) {
+    return new ReportRunner(params);
+}
+
+module.exports = { ReportRunner, createReportRunner };

package/src/infrastructure/__tests__/report-executor-handler.test.js

@@ -0,0 +1,314 @@
+jest.mock('../bootstrap');
+jest.mock('../../application/report-runner');
+jest.mock('@friggframework/core/application/commands/report-commands');
+jest.mock('@friggframework/core/queues', () => ({
+    QueuerUtil: { send: jest.fn().mockResolvedValue({}) },
+}));
+
+const { bootstrapAdminScripts } = require('../bootstrap');
+const { createReportRunner } = require('../../application/report-runner');
+const {
+    createReportCommands,
+} = require('@friggframework/core/application/commands/report-commands');
+const { QueuerUtil } = require('@friggframework/core/queues');
+const { handler } = require('../report-executor-handler');
+
+describe('Report Executor Handler', () => {
+    let mockReportFactory;
+    let mockIntegrationFactory;
+    let mockReportFriggCommands;
+    let mockRunner;
+    let mockCommands;
+
+    beforeEach(() => {
+        mockReportFactory = { id: 'report-factory' };
+        mockIntegrationFactory = { id: 'integration-factory' };
+        mockReportFriggCommands = { id: 'report-frigg-commands' };
+        mockRunner = { execute: jest.fn() };
+        mockCommands = {
+            completeExecution: jest.fn().mockResolvedValue({}),
+        };
+
+        bootstrapAdminScripts.mockReturnValue({
+            reportFactory: mockReportFactory,
+            reportCommands: { id: 'report-commands' },
+            reportFriggCommands: mockReportFriggCommands,
+            integrationFactory: mockIntegrationFactory,
+        });
+        createReportRunner.mockReturnValue(mockRunner);
+        createReportCommands.mockReturnValue(mockCommands);
+
+        jest.spyOn(console, 'log').mockImplementation(() => {});
+        jest.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        console.log.mockRestore();
+        console.error.mockRestore();
+        jest.clearAllMocks();
+    });
+
+    describe('EventBridge Scheduler direct invoke (no Records)', () => {
+        it('injects the bootstrapped factory into the runner and reports the result', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-1',
+            });
+
+            const response = await handler({
+                reportName: 'my-report',
+                trigger: 'SCHEDULED',
+                mode: 'snapshot',
+                seriesName: 'daily',
+                params: { foo: 'bar' },
+            });
+
+            expect(createReportRunner).toHaveBeenCalledWith({
+                reportFactory: mockReportFactory,
+                reportCommands: { id: 'report-commands' },
+                friggCommands: mockReportFriggCommands,
+                integrationFactory: mockIntegrationFactory,
+            });
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-report',
+                { foo: 'bar' },
+                expect.objectContaining({
+                    trigger: 'SCHEDULED',
+                    mode: 'snapshot',
+                    seriesName: 'daily',
+                })
+            );
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(1);
+            expect(body.results[0]).toEqual({
+                reportName: 'my-report',
+                status: 'COMPLETED',
+                executionId: 'exec-1',
+            });
+        });
+
+        it('defaults mode to recorded and trigger to QUEUE', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-d',
+            });
+
+            await handler({ reportName: 'my-report', params: {} });
+
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-report',
+                {},
+                expect.objectContaining({ mode: 'recorded', trigger: 'QUEUE' })
+            );
+        });
+
+        it('marks the execution FAILED when the runner throws', async () => {
+            mockRunner.execute.mockRejectedValue(new Error('boom'));
+
+            const response = await handler({
+                reportName: 'my-report',
+                executionId: 'exec-2',
+                trigger: 'SCHEDULED',
+            });
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.results[0].status).toBe('FAILED');
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
+                'exec-2',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+        });
+    });
+
+    describe('SQS batch (Records[])', () => {
+        it('injects the bootstrapped factory and processes each record', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-3',
+            });
+
+            const response = await handler({
+                Records: [
+                    {
+                        body: JSON.stringify({
+                            reportName: 'my-report',
+                            executionId: 'exec-3',
+                            mode: 'recorded',
+                            params: {},
+                        }),
+                    },
+                ],
+            });
+
+            expect(createReportRunner).toHaveBeenCalledWith({
+                reportFactory: mockReportFactory,
+                reportCommands: { id: 'report-commands' },
+                friggCommands: mockReportFriggCommands,
+                integrationFactory: mockIntegrationFactory,
+            });
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-report',
+                {},
+                expect.objectContaining({
+                    trigger: 'QUEUE',
+                    mode: 'recorded',
+                    executionId: 'exec-3',
+                })
+            );
+
+            expect(response.statusCode).toBe(200);
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(1);
+            expect(body.results[0].status).toBe('COMPLETED');
+        });
+
+        it('isolates a bad record without dropping the rest of the batch', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-4',
+            });
+
+            const response = await handler({
+                Records: [
+                    // Missing reportName -> runMessage throws before the runner
+                    { body: JSON.stringify({ executionId: 'exec-bad' }) },
+                    {
+                        body: JSON.stringify({
+                            reportName: 'my-report',
+                            executionId: 'exec-4',
+                            params: {},
+                        }),
+                    },
+                ],
+            });
+
+            const body = JSON.parse(response.body);
+            expect(body.processed).toBe(2);
+            expect(body.results[0].status).toBe('FAILED');
+            expect(body.results[1].status).toBe('COMPLETED');
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
+                'exec-bad',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+        });
+    });
+
+    describe('self-requeue on CONTINUE', () => {
+        afterEach(() => {
+            delete process.env.REPORT_QUEUE_URL;
+        });
+
+        it('passes the Lambda context to the runner', async () => {
+            mockRunner.execute.mockResolvedValue({
+                status: 'COMPLETED',
+                executionId: 'exec-ctx',
+            });
+            const lambdaContext = {
+                getRemainingTimeInMillis: () => 12345,
+            };
+
+            await handler(
+                { reportName: 'my-report', executionId: 'exec-ctx', params: {} },
+                lambdaContext
+            );
+
+            expect(mockRunner.execute).toHaveBeenCalledWith(
+                'my-report',
+                {},
+                expect.objectContaining({ lambdaContext })
+            );
+        });
+
+        it('re-enqueues the same execution with a resume marker when the runner returns CONTINUE', async () => {
+            process.env.REPORT_QUEUE_URL = 'https://sqs.local/report-queue';
+            mockRunner.execute.mockResolvedValue({
+                status: 'CONTINUE',
+                executionId: 'exec-cont',
+                continuation: { cursor: 7 },
+            });
+
+            const response = await handler(
+                {
+                    reportName: 'my-report',
+                    executionId: 'exec-cont',
+                    mode: 'recorded',
+                    params: { since: '2026-01-01' },
+                },
+                { getRemainingTimeInMillis: () => 5000 }
+            );
+
+            expect(QueuerUtil.send).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    reportName: 'my-report',
+                    executionId: 'exec-cont',
+                    mode: 'recorded',
+                    trigger: 'QUEUE',
+                    params: {
+                        since: '2026-01-01',
+                        __resume: { cursor: 7 },
+                    },
+                    resumeAt: expect.any(String),
+                }),
+                'https://sqs.local/report-queue'
+            );
+
+            const body = JSON.parse(response.body);
+            expect(body.results[0].status).toBe('CONTINUE');
+        });
+
+        it('fails the record when a continuation is yielded but REPORT_QUEUE_URL is unset', async () => {
+            delete process.env.REPORT_QUEUE_URL;
+            mockRunner.execute.mockResolvedValue({
+                status: 'CONTINUE',
+                executionId: 'exec-noqueue',
+                continuation: { cursor: 1 },
+            });
+
+            const response = await handler({
+                reportName: 'my-report',
+                executionId: 'exec-noqueue',
+                params: {},
+            });
+
+            expect(QueuerUtil.send).not.toHaveBeenCalled();
+            const body = JSON.parse(response.body);
+            expect(body.results[0].status).toBe('FAILED');
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
+                'exec-noqueue',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+        });
+
+        it('compensates with the RUNNER-created id on a scheduled first run that cannot re-queue (no inbound executionId)', async () => {
+            // A real EventBridge scheduled event carries NO executionId — the
+            // runner creates the record. If the continuation can't be re-queued,
+            // the record must still be marked FAILED using the runner-created id,
+            // not the absent inbound one.
+            delete process.env.REPORT_QUEUE_URL;
+            mockRunner.execute.mockResolvedValue({
+                status: 'CONTINUE',
+                executionId: 'runner-created-exec',
+                continuation: { cursor: 1 },
+            });
+
+            const response = await handler({
+                reportName: 'my-report',
+                trigger: 'SCHEDULED',
+                mode: 'snapshot',
+                params: {},
+                // note: no executionId, matching the scheduler's buildInput
+            });
+
+            expect(QueuerUtil.send).not.toHaveBeenCalled();
+            expect(mockCommands.completeExecution).toHaveBeenCalledWith(
+                'runner-created-exec',
+                expect.objectContaining({ state: 'FAILED' })
+            );
+            const body = JSON.parse(response.body);
+            expect(body.results[0].status).toBe('FAILED');
+        });
+    });
+});