The minimalistic document archiving platform.
feat(server): introduced event driven pattern (#665)
Corentin Thomassetca06919bb8e7
diff --git a/apps/papra-server/package.json b/apps/papra-server/package.jsonindex b30f4764..2e154f95 100644--- a/apps/papra-server/package.json+++ b/apps/papra-server/package.json@@ -47,7 +47,7 @@"@cadence-mq/driver-memory": "^0.2.0","@corentinth/chisels": "catalog:","@corentinth/friendly-ids": "^0.0.1",- "@crowlog/async-context-plugin": "^2.0.0",+ "@crowlog/async-context-plugin": "^2.1.0","@crowlog/logger": "^2.1.0","@hono/node-server": "^1.14.4","@libsql/client": "^0.14.0",diff --git a/apps/papra-server/src/index.ts b/apps/papra-server/src/index.tsindex 537bd062..68839695 100644--- a/apps/papra-server/src/index.ts+++ b/apps/papra-server/src/index.ts@@ -3,6 +3,8 @@ import process, { env } from 'node:process';import { serve } from '@hono/node-server';import { setupDatabase } from './modules/app/database/database';import { ensureLocalDatabaseDirectoryExists } from './modules/app/database/database.services';+import { registerEventHandlers } from './modules/app/events/events.handlers';+import { createEventServices } from './modules/app/events/events.services';import { createGracefulShutdownService } from './modules/app/graceful-shutdown/graceful-shutdown.services';import { createServer } from './modules/app/server';import { parseConfig } from './modules/config/config';@@ -11,6 +13,7 @@ import { createIngestionFolderWatcher } from './modules/ingestion-folders/ingestimport { addToGlobalLogContext, createLogger } from './modules/shared/logger/logger';import { registerTaskDefinitions } from './modules/tasks/tasks.definitions';import { createTaskServices } from './modules/tasks/tasks.services';+import { createTrackingServices } from './modules/tracking/tracking.services';const logger = createLogger({ namespace: 'app-server' });@@ -35,8 +38,12 @@ const documentsStorageService = createDocumentStorageService({ documentStorageCoconst taskServices = createTaskServices({ config });await taskServices.initialize();+const trackingServices = createTrackingServices({ config });+const eventServices = createEventServices();+registerEventHandlers({ eventServices, trackingServices });+if (isWebMode) {- const { app } = await createServer({ config, db, taskServices, documentsStorageService });+ const { app } = await createServer({ config, db, taskServices, documentsStorageService, eventServices, trackingServices });const server = serve({diff --git a/apps/papra-server/src/modules/app/auth/auth.services.ts b/apps/papra-server/src/modules/app/auth/auth.services.tsindex 4d6877e5..b0fbbad2 100644--- a/apps/papra-server/src/modules/app/auth/auth.services.ts+++ b/apps/papra-server/src/modules/app/auth/auth.services.ts@@ -1,6 +1,6 @@import type { Config } from '../../config/config.types';-import type { TrackingServices } from '../../tracking/tracking.services';import type { Database } from '../database/database.types';+import type { EventServices } from '../events/events.services';import type { AuthEmailsServices } from './auth.emails.services';import { expo } from '@better-auth/expo';import { betterAuth } from 'better-auth';@@ -21,12 +21,12 @@ export function getAuth({db,config,authEmailsServices,- trackingServices,+ eventServices,}: {db: Database;config: Config;authEmailsServices: AuthEmailsServices;- trackingServices: TrackingServices;+ eventServices: EventServices;}) {const { secret } = config.auth;@@ -86,9 +86,13 @@ export function getAuth({throw createForbiddenEmailDomainError();}},- after: async ({ id: userId, email }) => {+ after: async ({ id: userId, email, createdAt }) => {logger.info({ userId }, 'User signed up');- trackingServices.captureUserEvent({ userId, event: 'User signed up', properties: { $set: { email } } });++ eventServices.emitEvent({+ eventName: 'user.created',+ payload: { userId, email, createdAt },+ });},},},diff --git a/apps/papra-server/src/modules/app/auth/e2e/email-verification.e2e.test.ts b/apps/papra-server/src/modules/app/auth/e2e/email-verification.e2e.test.tsindex 51daf3ce..c92cf548 100644--- a/apps/papra-server/src/modules/app/auth/e2e/email-verification.e2e.test.ts+++ b/apps/papra-server/src/modules/app/auth/e2e/email-verification.e2e.test.ts@@ -1,6 +1,7 @@-import { describe, expect, test, vi } from 'vitest';+import { describe, expect, test } from 'vitest';import { overrideConfig } from '../../../config/config.test-utils';import { createInMemoryDatabase } from '../../database/database.test-utils';+import { createEventServices } from '../../events/events.services';import { createServer } from '../../server';import { createAuthEmailsServices } from '../auth.emails.services';import { getAuth } from '../auth.services';@@ -34,7 +35,7 @@ describe('email verification e2e', () => {});const authEmailsServices = createAuthEmailsServices({ emailsServices: mockEmailsServices });- const { auth } = getAuth({ db, config, authEmailsServices, trackingServices: { captureUserEvent: vi.fn(), shutdown: vi.fn() } });+ const { auth } = getAuth({ db, config, authEmailsServices, eventServices: createEventServices() });const { app } = await createServer({ db, config, auth });@@ -75,7 +76,7 @@ describe('email verification e2e', () => {});const authEmailsServices = createAuthEmailsServices({ emailsServices: mockEmailsServices });- const { auth } = getAuth({ db, config, authEmailsServices, trackingServices: { captureUserEvent: vi.fn(), shutdown: vi.fn() } });+ const { auth } = getAuth({ db, config, authEmailsServices, eventServices: createEventServices() });const { app } = await createServer({ db, config, auth });@@ -135,7 +136,7 @@ describe('email verification e2e', () => {});const authEmailsServices = createAuthEmailsServices({ emailsServices: mockEmailsServices });- const { auth } = getAuth({ db, config, authEmailsServices, trackingServices: { captureUserEvent: vi.fn(), shutdown: vi.fn() } });+ const { auth } = getAuth({ db, config, authEmailsServices, eventServices: createEventServices() });const { app } = await createServer({ db, config, auth });@@ -166,7 +167,7 @@ describe('email verification e2e', () => {});const authEmailsServices = createAuthEmailsServices({ emailsServices: mockEmailsServices });- const { auth } = getAuth({ db, config, authEmailsServices, trackingServices: { captureUserEvent: vi.fn(), shutdown: vi.fn() } });+ const { auth } = getAuth({ db, config, authEmailsServices, eventServices: createEventServices() });const { app } = await createServer({ db, config, auth });diff --git a/apps/papra-server/src/modules/app/events/events.handlers.ts b/apps/papra-server/src/modules/app/events/events.handlers.tsnew file mode 100644index 00000000..b83ca637--- /dev/null+++ b/apps/papra-server/src/modules/app/events/events.handlers.ts@@ -0,0 +1,7 @@+import type { TrackingServices } from '../../tracking/tracking.services';+import type { EventServices } from './events.services';+import { registerTrackingUserCreatedEventHandler } from '../../users/event-handlers/tracking.user-created';++export function registerEventHandlers(deps: { trackingServices: TrackingServices; eventServices: EventServices }) {+ registerTrackingUserCreatedEventHandler(deps);+}diff --git a/apps/papra-server/src/modules/app/events/events.services.test.ts b/apps/papra-server/src/modules/app/events/events.services.test.tsnew file mode 100644index 00000000..cbf3e4b6--- /dev/null+++ b/apps/papra-server/src/modules/app/events/events.services.test.ts@@ -0,0 +1,193 @@+import { createNoopLogger } from '@crowlog/logger';+import { describe, expect, test } from 'vitest';+import { nextTick } from '../../shared/async/defer.test-utils';+import { createEventServices } from './events.services';++type TestEvents = {+ 'user.created': { userId: string; email: string };+ 'user.deleted': { userId: string };+};++describe('events services', () => {+ describe('emitEvent', () => {+ test('registered handlers are called with the event payload when an event is emitted', async () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });+ const handlerCalls: unknown[] = [];++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'test-handler',+ handler: async (payload, meta) => {+ handlerCalls.push({ payload, meta });+ },+ });++ eventsServices.emitEvent({+ eventName: 'user.created',+ payload: { userId: '123', email: '[email protected]' },+ eventId: 'evt_test',+ now: new Date('2024-01-01'),+ });++ expect(handlerCalls).to.deep.equal([]);++ await nextTick();++ expect(handlerCalls).to.deep.equal([{+ payload: { userId: '123', email: '[email protected]' },+ meta: { emittedAt: new Date('2024-01-01'), eventId: 'evt_test' },+ }]);+ });++ test('multiple handlers registered for the same event are all called', async () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });+ const handlerCalls: unknown[] = [];++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'handler-1',+ handler: async (payload) => {+ handlerCalls.push({ handler: 'handler-1', payload });+ },+ });++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'handler-2',+ handler: async (payload) => {+ handlerCalls.push({ handler: 'handler-2', payload });+ },+ });++ eventsServices.emitEvent({+ eventName: 'user.created',+ payload: { userId: '456', email: '[email protected]' },+ eventId: 'evt_multi',+ now: new Date('2024-02-01'),+ });++ await nextTick();++ expect(handlerCalls).to.have.length(2);+ expect(handlerCalls).to.deep.include({ handler: 'handler-1', payload: { userId: '456', email: '[email protected]' } });+ expect(handlerCalls).to.deep.include({ handler: 'handler-2', payload: { userId: '456', email: '[email protected]' } });+ });++ test('emitting an event with no registered handlers does not throw an error', async () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });++ expect(async () => {+ eventsServices.emitEvent({+ eventName: 'user.deleted',+ payload: { userId: '789' },+ eventId: 'evt_no_handlers',+ now: new Date('2024-03-01'),+ });++ await nextTick();+ }).to.not.throw();+ });++ test('handlers are only called for their specific registered event', async () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });+ const handlerCalls: unknown[] = [];++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'created-handler',+ handler: async () => {+ handlerCalls.push('created');+ },+ });++ eventsServices.onEvent({+ eventName: 'user.deleted',+ handlerName: 'deleted-handler',+ handler: async () => {+ handlerCalls.push('deleted');+ },+ });++ eventsServices.emitEvent({+ eventName: 'user.created',+ payload: { userId: '111', email: '[email protected]' },+ eventId: 'evt_created',+ now: new Date('2024-04-01'),+ });++ await nextTick();++ expect(handlerCalls).to.deep.equal(['created']);+ });++ test('handler errors are caught and do not crash the application', async () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });+ const handlerCalls: unknown[] = [];++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'failing-handler',+ handler: async () => {+ throw new Error('Handler failed');+ },+ });++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'successful-handler',+ handler: async () => {+ handlerCalls.push('success');+ },+ });++ eventsServices.emitEvent({+ eventName: 'user.created',+ payload: { userId: '222', email: '[email protected]' },+ eventId: 'evt_error',+ now: new Date('2024-05-01'),+ });++ await nextTick();++ expect(handlerCalls).to.deep.equal(['success']);+ });+ });++ describe('onEvent', () => {+ test('registering a handler with a duplicate name for the same event throws an error', () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'duplicate-handler',+ handler: async () => {},+ });++ expect(() => {+ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'duplicate-handler',+ handler: async () => {},+ });+ }).to.throw('Duplicate handler name "duplicate-handler" for event "user.created"');+ });++ test('the same handler name can be used for different events', () => {+ const eventsServices = createEventServices<TestEvents>({ logger: createNoopLogger() });++ eventsServices.onEvent({+ eventName: 'user.created',+ handlerName: 'shared-handler-name',+ handler: async () => {},+ });++ expect(() => {+ eventsServices.onEvent({+ eventName: 'user.deleted',+ handlerName: 'shared-handler-name',+ handler: async () => {},+ });+ }).to.not.throw();+ });+ });+});diff --git a/apps/papra-server/src/modules/app/events/events.services.ts b/apps/papra-server/src/modules/app/events/events.services.tsnew file mode 100644index 00000000..fd759351--- /dev/null+++ b/apps/papra-server/src/modules/app/events/events.services.ts@@ -0,0 +1,85 @@+import type { Logger } from '../../shared/logger/logger';+import type { UserEvents } from '../../users/users.events.types';+import { safely } from '@corentinth/chisels';+import { createError } from '../../shared/errors/errors';+import { createLogger, wrapWithLoggerContext } from '../../shared/logger/logger';+import { generateId } from '../../shared/random/ids';+import { isNil } from '../../shared/utils';++type AppEvents = UserEvents;++type HandlerMeta = {+ emittedAt: Date;+ eventId: string;+};++export type EventServices = ReturnType<typeof createEventServices<AppEvents>>;++export function createEventServices<T extends Record<string, Record<string, unknown>> = AppEvents>({ logger = createLogger({ namespace: 'events-services' }) }: { logger?: Logger } = {}) {+ const handlers = new Map<keyof T, { handlerName: string; handler: (payload: T[keyof T], meta: HandlerMeta) => Promise<void> | void }[]>();++ return {+ onEvent<K extends keyof T>({ eventName, handlerName, handler }: {+ eventName: K;+ handlerName: string;+ handler: (payload: T[K], meta: HandlerMeta) => Promise<void>;+ }) {+ const isDuplicateName = handlers.get(eventName)?.some(h => h.handlerName === handlerName) ?? false;++ if (isDuplicateName) {+ throw createError({+ message: `Duplicate handler name "${handlerName}" for event "${String(eventName)}"`,+ code: 'events.duplicate_handler_name',+ statusCode: 500,+ isInternal: true,+ });+ }++ handlers.set(eventName, [+ ...(handlers.get(eventName) ?? []),+ { handlerName, handler: handler as (payload: T[keyof T], meta: HandlerMeta) => Promise<void> },+ ]);+ },++ emitEvent<K extends keyof T>({+ eventName,+ payload,+ eventId = generateId({ prefix: 'evt' }),+ now = new Date(),+ }: {+ eventName: K;+ payload: T[K];+ eventId?: string;+ now?: Date;+ }) {+ const eventHandlers = handlers.get(eventName);++ if (isNil(eventHandlers) || eventHandlers.length === 0) {+ logger.debug(`No handlers for event: ${String(eventName)}`);+ return;+ }++ logger.debug({+ eventName,+ eventId,+ handlerCount: eventHandlers.length,+ handlerNames: eventHandlers.map(({ handlerName }) => handlerName),+ }, 'Event emitted');++ setImmediate(async () => {+ await Promise.allSettled(eventHandlers.map(async ({ handlerName, handler }) => {+ await wrapWithLoggerContext({ eventId, eventName, handlerName }, async () => {+ const [, error] = await safely(async () => handler(payload, { emittedAt: now, eventId }));++ if (error) {+ logger.error({ error }, 'Error in event handler');+ return;+ }++ logger.info('Event handler executed successfully');+ });+ }));+ });+ },+ };+}diff --git a/apps/papra-server/src/modules/app/server.ts b/apps/papra-server/src/modules/app/server.tsindex 0aa38aa1..9db08a75 100644--- a/apps/papra-server/src/modules/app/server.ts+++ b/apps/papra-server/src/modules/app/server.ts@@ -13,6 +13,7 @@ import { createTrackingServices } from '../tracking/tracking.services';import { createAuthEmailsServices } from './auth/auth.emails.services';import { getAuth } from './auth/auth.services';import { setupDatabase } from './database/database';+import { createEventServices } from './events/events.services';import { createCorsMiddleware } from './middlewares/cors.middleware';import { registerErrorMiddleware } from './middlewares/errors.middleware';import { createTimeoutMiddleware } from './middlewares/timeout.middleware';@@ -23,8 +24,9 @@ async function createGlobalDependencies(partialDeps: Partial<GlobalDependencies>const config = partialDeps.config ?? (await parseConfig()).config;const db = partialDeps.db ?? setupDatabase(config.database).db;const emailsServices = createEmailsServices({ config });- const trackingServices = createTrackingServices({ config });- const auth = partialDeps.auth ?? getAuth({ db, config, authEmailsServices: createAuthEmailsServices({ emailsServices }), trackingServices }).auth;+ const trackingServices = partialDeps.trackingServices ?? createTrackingServices({ config });+ const eventServices = partialDeps.eventServices ?? createEventServices();+ const auth = partialDeps.auth ?? getAuth({ db, config, authEmailsServices: createAuthEmailsServices({ emailsServices }), eventServices }).auth;const subscriptionsServices = createSubscriptionsServices({ config });const taskServices = partialDeps.taskServices ?? createTaskServices({ config });const documentsStorageService = partialDeps.documentsStorageService ?? createDocumentStorageService({ documentStorageConfig: config.documentsStorage });@@ -40,6 +42,7 @@ async function createGlobalDependencies(partialDeps: Partial<GlobalDependencies>trackingServices,taskServices,documentSearchServices,+ eventServices,};}diff --git a/apps/papra-server/src/modules/app/server.types.ts b/apps/papra-server/src/modules/app/server.types.tsindex 62ee6581..5bf48b19 100644--- a/apps/papra-server/src/modules/app/server.types.ts+++ b/apps/papra-server/src/modules/app/server.types.ts@@ -10,6 +10,7 @@ import type { TrackingServices } from '../tracking/tracking.services';import type { Auth } from './auth/auth.services';import type { Session } from './auth/auth.types';import type { Database } from './database/database.types';+import type { EventServices } from './events/events.services';export type ServerInstanceGenerics = {Variables: {@@ -34,6 +35,7 @@ export type GlobalDependencies = {taskServices: TaskServices;documentsStorageService: DocumentStorageService;documentSearchServices: DocumentSearchServices;+ eventServices: EventServices;};export type RouteDefinitionContext = { app: ServerInstance } & GlobalDependencies;diff --git a/apps/papra-server/src/modules/shared/async/defer.test-utils.ts b/apps/papra-server/src/modules/shared/async/defer.test-utils.tsindex e3d10316..2e766fef 100644--- a/apps/papra-server/src/modules/shared/async/defer.test-utils.ts+++ b/apps/papra-server/src/modules/shared/async/defer.test-utils.ts@@ -1 +1 @@-export const nextTick = async () => new Promise(resolve => setImmediate(resolve));+export const nextTick = async () => new Promise<void>(resolve => setImmediate(resolve));diff --git a/apps/papra-server/src/modules/users/event-handlers/tracking.user-created.ts b/apps/papra-server/src/modules/users/event-handlers/tracking.user-created.tsnew file mode 100644index 00000000..c68ba7d9--- /dev/null+++ b/apps/papra-server/src/modules/users/event-handlers/tracking.user-created.ts@@ -0,0 +1,12 @@+import type { EventServices } from '../../app/events/events.services';+import type { TrackingServices } from '../../tracking/tracking.services';++export function registerTrackingUserCreatedEventHandler({ eventServices, trackingServices }: { eventServices: EventServices; trackingServices: TrackingServices }) {+ eventServices.onEvent({+ eventName: 'user.created',+ handlerName: 'tracking.register-user-created-event',+ handler: async ({ userId, email }) => {+ trackingServices.captureUserEvent({ userId, event: 'User signed up', properties: { $set: { email } } });+ },+ });+}diff --git a/apps/papra-server/src/modules/users/users.events.types.ts b/apps/papra-server/src/modules/users/users.events.types.tsnew file mode 100644index 00000000..50a8235c--- /dev/null+++ b/apps/papra-server/src/modules/users/users.events.types.ts@@ -0,0 +1,3 @@+export type UserEvents = {+ 'user.created': { userId: string; email: string; createdAt: Date };+};diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 6342aaf8..166c2a6b 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -408,8 +408,8 @@ importers:specifier: ^0.0.1version: 0.0.1'@crowlog/async-context-plugin':- specifier: ^2.0.0- version: 2.0.0+ specifier: ^2.1.0+ version: 2.1.0'@crowlog/logger':specifier: ^2.1.0version: 2.1.0@@ -1779,8 +1779,8 @@ packages:peerDependencies:solid-js: ^1.8- '@crowlog/[email protected]':- resolution: {integrity: sha512-nlzv+dXfWxuY2/O05m05YT/1e5u/x/EKF1HnHdNJVDUI7OUs4ZrNF1jsKP9GnNoApaXNnYiPrDBlYcH80DkDPw==}+ '@crowlog/[email protected]':+ resolution: {integrity: sha512-sf7gig7RonFvGPxPBrZqdJwI+NMbVcu4mJtCkqyk5pqvl1ZbY02Jv7YnfMs8gUtrq/2MsZUaoXA5UdSyCkNv0g==}engines: {node: '>=22.0.0'}'@crowlog/[email protected]':@@ -6349,8 +6349,8 @@ packages:resolution: {integrity: sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==}- resolution: {integrity: sha512-98XGutrXoh75MlgLihlNxAGbUuFQc7l1cqcnEZlLNKc0UrVdPndgmaDmYTDDh929VS/eqTZV0rozmhu2qqT1/g==}+ resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}@@ -7592,6 +7592,10 @@ packages:resolution: {integrity: sha512-KrGhL9Q4zjj0kiUt5OO4Mr/A/jlI2jDYs5eHBpYHPcBEVSiipAvn2Ko2HnPe20rmcuuvMHNdZFp+4IlGTMF0Ow==}engines: {node: '>= 6'}+ resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}+ engines: {node: '>= 6'}+resolution: {integrity: sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww==}engines: {node: '>=0.4.x'}@@ -13755,7 +13759,7 @@ snapshots:'@floating-ui/dom': 1.6.13solid-js: 1.9.9- '@crowlog/[email protected]': {}+ '@crowlog/[email protected]': {}'@crowlog/[email protected]': {}@@ -17757,7 +17761,7 @@ snapshots:'@vue/reactivity': 3.5.13'@vue/runtime-core': 3.5.13'@vue/shared': 3.5.13- csstype: 3.2.1+ csstype: 3.2.3dependencies:@@ -18895,7 +18899,7 @@ snapshots:- [email protected]: {}+ [email protected]: {}@@ -20481,6 +20485,15 @@ snapshots:hasown: 2.0.2mime-types: 2.1.35+ dependencies:+ asynckit: 0.4.0+ combined-stream: 1.0.8+ es-set-tostringtag: 2.1.0+ hasown: 2.0.2+ mime-types: 2.1.35+ optional: true+@@ -21512,7 +21525,7 @@ snapshots:cssstyle: 4.6.0data-urls: 5.0.0decimal.js: 10.6.0- form-data: 4.0.4+ form-data: 4.0.5html-encoding-sniffer: 4.0.0http-proxy-agent: 7.0.2https-proxy-agent: 7.0.6