emailengine-app 2.68.1 → 2.70.0

package/lib/api-routes/outbox-routes.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const Boom = require('@hapi/boom');
+const Joi = require('joi');
+const logger = require('../logger');
+const outbox = require('../outbox');
+const { failAction } = require('../tools');
+const { handleError } = require('./route-helpers');
+const { outboxEntrySchema, errorResponses } = require('../schemas');
+
+async function init(args) {
+    const { server, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'GET',
+        path: '/v1/outbox',
+
+        async handler(request) {
+            try {
+                return await outbox.list(Object.assign({ logger }, request.query));
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List queued messages',
+            notes: 'Lists messages in the Outbox',
+            tags: ['api', 'Outbox'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                query: Joi.object({
+                    page: Joi.number()
+                        .integer()
+                        .min(0)
+                        .max(1024 * 1024)
+                        .default(0)
+                        .example(0)
+                        .description('Page number (zero indexed, so use 0 for first page)')
+                        .label('PageNumber'),
+                    pageSize: Joi.number().integer().min(1).max(1000).default(20).example(20).description('How many entries per page').label('PageSize')
+                }).label('OutbixListFilter')
+            },
+
+            response: {
+                schema: Joi.object({
+                    total: Joi.number().integer().example(120).description('How many matching entries').label('TotalNumber'),
+                    page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
+                    pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
+
+                    messages: Joi.array().items(outboxEntrySchema).label('OutboxListEntries')
+                }).label('OutboxListResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'GET',
+        path: '/v1/outbox/{queueId}',
+
+        async handler(request) {
+            try {
+                let outboxEntry = await outbox.get({ queueId: request.params.queueId, logger });
+                if (!outboxEntry) {
+                    let message = 'Requested queue entry was not found';
+                    let error = Boom.boomify(new Error(message), { statusCode: 404 });
+                    throw error;
+                }
+                return outboxEntry;
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'Get queued message',
+            notes: 'Gets a queued message in the Outbox',
+            tags: ['api', 'Outbox'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 404, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    queueId: Joi.string().max(100).example('d41f0423195f271f').description('Queue identifier for scheduled email').required()
+                }).label('OutboxEntryParams')
+            },
+
+            response: {
+                schema: outboxEntrySchema,
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'DELETE',
+        path: '/v1/outbox/{queueId}',
+
+        async handler(request) {
+            try {
+                return {
+                    deleted: await outbox.del({ queueId: request.params.queueId, logger })
+                };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Remove a message',
+            notes: 'Remove a message from the outbox',
+            tags: ['api', 'Outbox'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    queueId: Joi.string().max(100).example('d41f0423195f271f').description('Queue identifier for scheduled email').required()
+                }).label('OutboxEntryParams')
+            },
+
+            response: {
+                schema: Joi.object({
+                    deleted: Joi.boolean().truthy('Y', 'true', '1').falsy('N', 'false', 0).default(true).description('Was the message deleted')
+                }).label('DeleteOutboxEntryResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;

package/lib/api-routes/pubsub-routes.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const Joi = require('joi');
+const { failAction } = require('../tools');
+const { oauth2Apps } = require('../oauth2-apps');
+const { pubSubErrorSchema, errorResponses } = require('../schemas');
+const { handleError, flattenOAuthAppMeta } = require('./route-helpers');
+
+async function init(args) {
+    const { server, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'GET',
+        path: '/v1/pubsub/status',
+
+        async handler(request) {
+            try {
+                let response = await oauth2Apps.list(request.query.page, request.query.pageSize, { pubsub: true });
+
+                let apps = response.apps.map(app => {
+                    flattenOAuthAppMeta(app);
+                    return { id: app.id, name: app.name || null, lastError: app.lastError || null, pubSubError: app.pubSubError || null };
+                });
+
+                return {
+                    total: response.total,
+                    page: response.page,
+                    pages: response.pages,
+                    apps
+                };
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+
+        options: {
+            description: 'List Pub/Sub status',
+            notes: 'Lists Pub/Sub enabled OAuth2 applications and their subscription status',
+            tags: ['api', 'OAuth2 Applications'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                query: Joi.object({
+                    page: Joi.number()
+                        .integer()
+                        .min(0)
+                        .max(1024 * 1024)
+                        .default(0)
+                        .example(0)
+                        .description('Page number (zero indexed, so use 0 for first page)')
+                        .label('PageNumber'),
+                    pageSize: Joi.number().integer().min(1).max(1000).default(20).example(20).description('How many entries per page').label('PageSize')
+                }).label('PubSubStatusFilter')
+            },
+
+            response: {
+                schema: Joi.object({
+                    total: Joi.number().integer().example(120).description('How many matching entries').label('TotalNumber'),
+                    page: Joi.number().integer().example(0).description('Current page (0-based index)').label('PageNumber'),
+                    pages: Joi.number().integer().example(24).description('Total page count').label('PagesNumber'),
+
+                    apps: Joi.array()
+                        .items(
+                            Joi.object({
+                                id: Joi.string().max(256).required().example('AAABhaBPHscAAAAH').description('OAuth2 application ID'),
+                                name: Joi.string().allow(null).max(256).example('My Gmail App').description('Display name for the app'),
+                                lastError: Joi.object({
+                                    response: Joi.string().example('Enable the Cloud Pub/Sub API').description('Error message')
+                                })
+                                    .allow(null)
+                                    .description('Last Pub/Sub related error for this app - either a setup error or an OAuth2 token renewal failure')
+                                    .label('PubSubSetupError'),
+                                pubSubError: pubSubErrorSchema.allow(null)
+                            }).label('PubSubAppStatus')
+                        )
+                        .label('PubSubAppStatusList')
+                }).label('PubSubStatusResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;

package/lib/api-routes/route-helpers.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const Boom = require('@hapi/boom');
+
+// Shared helpers for the extracted API route modules under lib/api-routes/.
+
+// Standard API error handler. Logs the failure, passes Boom errors through unchanged, and converts
+// plain errors into a Boom error while preserving the original statusCode and an optional
+// machine-readable err.code. This function ALWAYS throws and never returns a value, so callers use it
+// as the final statement inside a catch block: `catch (err) { handleError(request, err); }`.
+function handleError(request, err) {
+    request.logger.error({ msg: 'API request failed', err });
+    if (Boom.isBoom(err)) {
+        throw err;
+    }
+    // Lower-level libraries (e.g. ImapFlow) flag "this server lacks the required capability" with a
+    // machine code but no HTTP status. Surface it as a 422 client error instead of a generic 500 - the
+    // request is well-formed, the account just cannot satisfy it (e.g. label search on non-Gmail IMAP).
+    let statusCode = err.statusCode || (err.code === 'MissingServerExtension' ? 422 : 500);
+    const error = Boom.boomify(err, { statusCode });
+    if (err.code) {
+        error.output.payload.code = err.code;
+    }
+    if (err.details) {
+        error.output.payload.details = err.details;
+    }
+    throw error;
+}
+
+// Throws the canonical 404 error used when an entity getter returns a falsy value. Matches the
+// error shape that the lib-level update() methods (templates, webhooks, oauth2-apps) already throw
+// for missing documents, so API clients see the same error for both code paths.
+function throwNotFound(message = 'Document was not found') {
+    let err = new Error(message);
+    err.code = 'NotFound';
+    err.statusCode = 404;
+    throw err;
+}
+
+// Strips the internal `meta` field from an OAuth2 application object before returning it to the API
+// client, surfacing any authentication or Pub/Sub error messages as `lastError`/`pubSubError`.
+// Pure function: it mutates the passed object and closes over no module state.
+function flattenOAuthAppMeta(app) {
+    if (!app.meta) {
+        return;
+    }
+    let authFlag = app.meta.authFlag;
+    let pubSubFlag = app.meta.pubSubFlag;
+    delete app.meta;
+    if (authFlag && authFlag.message) {
+        app.lastError = { response: authFlag.message };
+    }
+    if (pubSubFlag && pubSubFlag.message) {
+        app.pubSubError = { message: pubSubFlag.message, description: pubSubFlag.description || null };
+    }
+}
+
+module.exports = { handleError, throwNotFound, flattenOAuthAppMeta };

package/lib/api-routes/settings-routes.js

@@ -0,0 +1,357 @@
+'use strict';
+
+const Joi = require('joi');
+const { redis, documentsQueue, notifyQueue, submitQueue } = require('../db');
+const settings = require('../settings');
+const consts = require('../consts');
+const { REDIS_PREFIX } = consts;
+const { failAction } = require('../tools');
+const { handleError } = require('./route-helpers');
+const { settingsSchema, settingsQuerySchema, errorResponses } = require('../schemas');
+
+// Response variant of the settings schema. Secret values are masked and returned as booleans,
+// any setting that has never been set is returned as null, and the virtual eventTypes key is
+// not part of the stored settings.
+const settingsOutputSchema = {};
+for (let key of Object.keys(settingsSchema)) {
+    if (settings.encryptedKeys.includes(key)) {
+        settingsOutputSchema[key] = Joi.boolean()
+            .allow(null)
+            .example(true)
+            .description('Whether a value is set for this setting. Secret values are never returned, only a boolean marker');
+    } else {
+        // Use a distinct label for the nullable response variant, otherwise the generated
+        // OpenAPI spec would contain suffixed duplicates of the request-side components
+        settingsOutputSchema[key] = settingsSchema[key].allow(null).label(`${key}Response`);
+    }
+}
+settingsOutputSchema.eventTypes = Joi.array()
+    .items(Joi.string().example('messageNew').label('EventTypeEntry'))
+    .description('Supported webhook event types')
+    .label('EventTypesList');
+
+async function init(args) {
+    const { server, notify, CORS_CONFIG } = args;
+
+    server.route({
+        method: 'GET',
+        path: '/v1/settings',
+
+        async handler(request) {
+            let values = {};
+            for (let key of Object.keys(request.query)) {
+                if (request.query[key]) {
+                    if (key === 'eventTypes') {
+                        values[key] = Object.keys(consts)
+                            .filter(key => /_NOTIFY?/.test(key))
+                            .map(key => consts[key]);
+                        continue;
+                    }
+
+                    let value = await settings.get(key);
+
+                    if (settings.encryptedKeys.includes(key)) {
+                        // do not reveal secret values
+                        // instead show boolean value true if value is set, or false if it's not
+                        value = value ? true : false;
+                    }
+
+                    values[key] = value;
+                }
+            }
+            return values;
+        },
+        options: {
+            description: 'List specific settings',
+            notes: 'List setting values for specific keys',
+            tags: ['api', 'Settings'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                query: Joi.object(settingsQuerySchema).label('SettingsQuery')
+            },
+
+            response: {
+                schema: Joi.object(settingsOutputSchema).label('SettingsQueryResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'POST',
+        path: '/v1/settings',
+
+        async handler(request) {
+            let updated = [];
+            for (let key of Object.keys(request.payload)) {
+                if (key === 'webhooksEnabled' && !request.payload.webhooksEnabled) {
+                    // clear error message (if exists)
+                    await settings.clear('webhookErrorFlag');
+                }
+
+                await settings.set(key, request.payload[key]);
+                updated.push(key);
+            }
+
+            // Broadcast to all workers (including this one); each reloads its HTTP proxy agent via
+            // the 'settings' message handler, so no inline reload is needed here.
+            notify('settings', request.payload);
+            return { updated };
+        },
+        options: {
+            description: 'Set setting values',
+            notes: 'Set setting values for specific keys',
+            tags: ['api', 'Settings'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                payload: Joi.object(settingsSchema).label('Settings')
+            },
+
+            response: {
+                schema: Joi.object({
+                    updated: Joi.array().items(Joi.string().example('notifyHeaders')).description('List of updated setting keys').label('UpdatedSettings')
+                }).label('SettingsUpdatedResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'GET',
+        path: '/v1/settings/queue/{queue}',
+
+        async handler(request) {
+            try {
+                let queue = request.params.queue;
+                let values = {
+                    queue
+                };
+
+                const [resActive, resDelayed, resPaused, resWaiting, resMeta] = await redis
+                    .multi()
+                    .llen(`${REDIS_PREFIX}bull:${queue}:active`)
+                    .zcard(`${REDIS_PREFIX}bull:${queue}:delayed`)
+                    .llen(`${REDIS_PREFIX}bull:${queue}:paused`)
+                    .llen(`${REDIS_PREFIX}bull:${queue}:wait`)
+                    .hget(`${REDIS_PREFIX}bull:${queue}:meta`, 'paused')
+                    .exec();
+
+                if (resActive[0] || resDelayed[0] || resPaused[0] || resWaiting[0]) {
+                    // counting failed
+                    let err = new Error('Failed to count queue length');
+                    err.statusCode = 500;
+                    throw err;
+                }
+
+                values.jobs = {
+                    active: Number(resActive[1]) || 0,
+                    delayed: Number(resDelayed[1]) || 0,
+                    paused: Number(resPaused[1]) || 0,
+                    waiting: Number(resWaiting[1]) || 0
+                };
+
+                values.paused = !!Number(resMeta[1]) || false;
+
+                return values;
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Show queue information',
+            notes: 'Show queue status and current state',
+            tags: ['api', 'Settings'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    queue: Joi.string()
+                        .empty('')
+                        .trim()
+                        .valid('notify', 'submit', 'documents')
+                        .required()
+                        .example('notify')
+                        .description('Queue ID')
+                        .label('QueueId')
+                })
+            },
+
+            response: {
+                schema: Joi.object({
+                    queue: Joi.string()
+                        .empty('')
+                        .trim()
+                        .valid('notify', 'submit', 'documents')
+                        .required()
+                        .example('notify')
+                        .description('Queue ID')
+                        .label('QueueIdResponse'),
+                    jobs: Joi.object({
+                        active: Joi.number().integer().example(123).description('Jobs that are currently being processed'),
+                        delayed: Joi.number().integer().example(123).description('Jobs that are processed in the future'),
+                        paused: Joi.number().integer().example(123).description('Jobs that would be processed once queue processing is resumed'),
+                        waiting: Joi.number()
+                            .integer()
+                            .example(123)
+                            .description('Jobs that should be processed, but are waiting until there are any free handlers')
+                    }).label('QueueJobs'),
+                    paused: Joi.boolean().example(false).description('Is the queue paused or not')
+                }).label('SettingsQueueResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+
+    server.route({
+        method: 'PUT',
+        path: '/v1/settings/queue/{queue}',
+
+        async handler(request) {
+            try {
+                let queue = request.params.queue;
+
+                let queueObj = {
+                    documents: documentsQueue,
+                    notify: notifyQueue,
+                    submit: submitQueue
+                }[queue];
+
+                let values = {
+                    queue
+                };
+
+                for (let key of Object.keys(request.payload)) {
+                    switch (key) {
+                        case 'paused':
+                            if (request.payload[key]) {
+                                await queueObj.pause();
+                            } else {
+                                await queueObj.resume();
+                            }
+                            break;
+                    }
+                }
+
+                values.paused = await queueObj.isPaused();
+
+                return values;
+            } catch (err) {
+                handleError(request, err);
+            }
+        },
+        options: {
+            description: 'Set queue settings',
+            notes: 'Set queue settings',
+            tags: ['api', 'Settings'],
+
+            plugins: {
+                'hapi-swagger': {
+                    responses: errorResponses(400, 401, 403, 429, 500)
+                }
+            },
+
+            auth: {
+                strategy: 'api-token',
+                mode: 'required'
+            },
+            cors: CORS_CONFIG,
+
+            validate: {
+                options: {
+                    stripUnknown: false,
+                    abortEarly: false,
+                    convert: true
+                },
+                failAction,
+
+                params: Joi.object({
+                    queue: Joi.string()
+                        .empty('')
+                        .trim()
+                        .valid('notify', 'submit', 'documents')
+                        .required()
+                        .example('notify')
+                        .description('Queue ID')
+                        .label('QueueIdParam')
+                }),
+
+                payload: Joi.object({
+                    paused: Joi.boolean().empty('').example(false).description('Set queue state to paused')
+                }).label('SettingsPutQueuePayload')
+            },
+
+            response: {
+                schema: Joi.object({
+                    queue: Joi.string()
+                        .empty('')
+                        .trim()
+                        .valid('notify', 'submit', 'documents')
+                        .required()
+                        .example('notify')
+                        .description('Queue ID')
+                        .label('QueueIdPutResponse'),
+                    paused: Joi.boolean().example(false).description('Is the queue paused or not')
+                }).label('SettingsPutQueueResponse'),
+                failAction: 'log'
+            }
+        }
+    });
+}
+
+module.exports = init;