feat(api): add queue trigger handler registration

apps/api/iac/main.bicep

@@ -102,6 +102,7 @@ module functionApp '../../../iac/function-app/main.bicep' = {
     tags: tags
     appServicePlanName: appServicePlan.outputs.appServicePlanName
     storageAccountName: functionAppStorageAccountName
+    applicationStorageAccountName: storageAccount.outputs.storageAccountName
     functionAppInstanceName: functionAppInstanceName
     functionWorkerRuntime: functionWorkerRuntime
     functionExtensionVersion: functionExtensionVersion

apps/api/package.json

@@ -7,12 +7,13 @@
 	"types": "dist/index.d.ts",
 	"scripts": {
 		"prebuild": "pnpm run lint",
-		"build": "tsgo --build && rolldown -c rolldown.config.ts",
+		"build": "tsgo --build && tsgo --noEmit --project tsconfig.rolldown.json && RUST_BACKTRACE=full rolldown -c rolldown.config.ts",
 		"predev": "pnpm run prepare:deploy && pnpm run sync-local-settings",
 		"dev": "pnpm exec portless data-access.ownercommunity.localhost --force node start-dev.mjs",
 		"prepare:deploy": "cellix-prepare-func-deploy",
 		"watch": "tsgo --watch",
 		"test": "vitest run --silent --reporter=dot",
+		"test:arch": "vitest run --config vitest.arch.config.ts",
 		"test:coverage": "vitest run --coverage --silent --reporter=dot",
 		"test:watch": "vitest",
 		"format": "biome format --write",
@@ -22,7 +23,7 @@
 		"prestart": "pnpm run prepare:deploy && pnpm run sync-local-settings",
 		"start": "func start --typescript --script-root deploy/",
 		"sync-local-settings": "node -e \"const fs=require('node:fs'); fs.mkdirSync('deploy',{recursive:true}); if (fs.existsSync('local.settings.json')) fs.copyFileSync('local.settings.json','deploy/local.settings.json');\"",
-		"azurite": "azurite-blob --silent --location ../../__blobstorage__ & azurite-queue --silent --location ../../__queuestorage__ & azurite-table --silent --location ../../__tablestorage__"
+		"azurite": "azurite-blob --silent --skipApiVersionCheck --location ../../__blobstorage__ & azurite-queue --silent --skipApiVersionCheck --location ../../__queuestorage__ & azurite-table --silent --location ../../__tablestorage__"
 	},
 	"dependencies": {
 		"@azure/functions": "catalog:",
@@ -34,10 +35,12 @@
 		"@ocom/graphql-handler": "workspace:*",
 		"@ocom/graphql": "workspace:*",
 		"@ocom/persistence": "workspace:*",
+		"@ocom/handler-queue-community-update": "workspace:*",
 		"@ocom/rest": "workspace:*",
 		"@ocom/service-apollo-server": "workspace:*",
 		"@ocom/service-blob-storage": "workspace:*",
 		"@ocom/service-mongoose": "workspace:*",
+		"@ocom/service-queue-storage": "workspace:*",
 		"@ocom/service-otel": "workspace:*",
 		"@ocom/service-token-validation": "workspace:*",
 		"@opentelemetry/api": "1.9.0"
@@ -47,6 +50,7 @@
 		"@cellix/config-typescript": "workspace:*",
 		"@cellix/config-vitest": "workspace:*",
 		"@vitest/coverage-istanbul": "catalog:",
+		"archunit": "catalog:",
 		"rimraf": "catalog:",
 		"rolldown": "1.0.0-beta.55",
 		"typescript": "catalog:",

apps/api/rolldown.config.ts

@@ -10,18 +10,33 @@
  * packages when workspace packages are in the module graph.
  */
 
-import { defineConfig } from 'rolldown';
+/*
+ * Avoid VScode reporting "Cannot find name 'NodeJS'" errors in this file, which uses NodeJS types but is not compiled by TypeScript and thus does not have access to the types specified in tsconfig.json.
+ * rolldown.config.ts is NOT expected to be included in the TypeScript compilation, as it is used by the rolldown bundler at build time and is not part of the runtime code.
+ * The types specified in tsconfig.json are only applied to files that are included in the compilation, and since rolldown.config.ts is not included, it does not have access to those types.
+ * By adding this reference directive, we can ensure that the NodeJS types are available for use in this file without causing phantom errors in the rest of the project.
+ */
+/// <reference types="node" />
+
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createCellixAzureFunctionsRolldownConfig } from '@cellix/config-rolldown';
+import { defineConfig } from 'rolldown';
 
 const apiDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(apiDir, '../..');
+const temporaryRolldownWorkaround = {
+	// Remove this block once rolldown no longer panics on
+	// packages/cellix/service-blob-storage/dist/service-blob-storage.js.
+	skipAliasNamespaces: ['@azure/'],
+	additionalExternal: ['@ocom/service-blob-storage'],
+} as const;
 
 export default defineConfig(async () =>
 	createCellixAzureFunctionsRolldownConfig({
 		repoRoot,
 		appPackageName: '@apps/api',
 		applicationNamespaces: ['@ocom/'],
+		...temporaryRolldownWorkaround,
 	}),
 );

apps/api/src/archunit-tests/architecture.test.ts

@@ -0,0 +1,28 @@
+import { projectFiles } from 'archunit';
+import { describe, expect, it } from 'vitest';
+
+describe('API Dependency Rules', () => {
+	describe('API Package', () => {
+		it('should not import any @cellix/service-* package directly from src/index.ts', async () => {
+			const violations: string[] = [];
+			let matchedTargetFile = false;
+
+			await projectFiles()
+				.inPath('src/index.ts')
+				.should()
+				.adhereTo((file) => {
+					matchedTargetFile = true;
+					const hasForbiddenImport = /from\s+['"]@cellix\/service-[^'"]+['"]/.test(file.content);
+					if (hasForbiddenImport) {
+						violations.push(`[${file.path}] Must not import from @cellix/service-* packages directly in src/index.ts`);
+						return false;
+					}
+					return true;
+				}, 'API src/index.ts must not import from @cellix/service-* packages directly')
+				.check();
+
+			expect(matchedTargetFile).toBe(true);
+			expect(violations).toStrictEqual([]);
+		});
+	});
+});

apps/api/src/cellix.test.ts

@@ -13,6 +13,7 @@ const test = { for: describeFeature };
 vi.mock('@azure/functions', () => ({
 	app: {
 		http: vi.fn(),
+		storageQueue: vi.fn(),
 		hook: {
 			appStart: vi.fn(),
 			appTerminate: vi.fn(),
@@ -172,6 +173,69 @@ test.for(feature, ({ Scenario, BeforeEachScenario }) => {
 		});
 	});
 
+	Scenario('Registering a named infrastructure service', ({ Given, When, Then }) => {
+		Given('a Cellix instance in infrastructure phase', () => {
+			cellix = Cellix.initializeInfrastructureServices(() => {
+				/* no op */
+			}) as Cellix<unknown, unknown>;
+		});
+
+		When('an infrastructure service is registered with a name', () => {
+			const result = cellix.registerInfrastructureService(mockService, 'my-service');
+			expect(result).toBe(cellix);
+		});
+
+		Then('it should be retrievable by name', () => {
+			const named = cellix.getInfrastructureService('my-service');
+			expect(named).toBe(mockService);
+		});
+	});
+
+	Scenario('Registering a duplicate service name', ({ Given, When, Then }) => {
+		Given('a Cellix instance with a named service registered', () => {
+			cellix = Cellix.initializeInfrastructureServices((registry) => {
+				registry.registerInfrastructureService(mockService, 'my-service');
+			}) as Cellix<unknown, unknown>;
+		});
+
+		When('another service is registered with the same name', () => {
+			const anotherService = new MockService();
+			expect(() => {
+				cellix.registerInfrastructureService(anotherService, 'my-service');
+			}).toThrow('Service name already registered: my-service');
+		});
+
+		Then('it should throw an error indicating duplicate name registration', () => {
+			// Error is already thrown in When step
+		});
+	});
+
+	Scenario('Lifecycle deduplicates services registered by constructor and name', ({ Given, When, Then }) => {
+		Given('a Cellix instance with the same service registered by constructor and by name', () => {
+			cellix = Cellix.initializeInfrastructureServices((registry) => {
+				registry.registerInfrastructureService(mockService);
+				registry.registerInfrastructureService(mockService, 'alias-service');
+			}) as Cellix<unknown, unknown>;
+			cellix.setContext(() => ({}));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn() }));
+			cellix.registerAzureFunctionHttpHandler('test-handler', { authLevel: 'anonymous' }, () => vi.fn());
+		});
+
+		When('the application starts', async () => {
+			await cellix.startUp();
+			// Trigger appStart hook
+			const mockHook = app.hook.appStart as unknown as { mock: { calls: [() => Promise<void>][] } };
+			const appStartCallback = mockHook.mock.calls[0]?.[0];
+			if (appStartCallback) {
+				await appStartCallback();
+			}
+		});
+
+		Then('the service startUp should be called exactly once', () => {
+			expect(mockService.startUp).toHaveBeenCalledTimes(1);
+		});
+	});
+
 	Scenario('Setting the infrastructure context', ({ Given, When, Then, And }) => {
 		let result: ReturnType<Cellix<unknown, unknown>['setContext']>;
 
@@ -298,6 +362,33 @@ test.for(feature, ({ Scenario, BeforeEachScenario }) => {
 		});
 	});
 
+	Scenario('Registering an Azure Function queue handler', ({ Given, When, Then, And }) => {
+		Given('a Cellix instance in app-services phase', () => {
+			cellix = Cellix.initializeInfrastructureServices(() => {
+				/* no op */
+			}) as Cellix<unknown, unknown>;
+			cellix.setContext(() => ({}));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }));
+		});
+
+		When('an Azure Function queue handler is registered', () => {
+			const result = cellix.registerAzureFunctionQueueHandler('community-update', { queueName: 'community-update', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn());
+			expect(result).toBe(cellix);
+		});
+
+		Then('it should store the queue handler configuration', () => {
+			expect(app.storageQueue).not.toHaveBeenCalled();
+		});
+
+		And('it should transition to handlers phase for queue handlers', () => {
+			expect(cellix.startUp).toBeDefined();
+		});
+
+		And('it should return the registry for queue handler chaining', () => {
+			// Already verified in When step
+		});
+	});
+
 	Scenario('Registering handler in wrong phase', ({ Given, When, Then }) => {
 		Given('a Cellix instance in infrastructure phase', () => {
 			cellix = Cellix.initializeInfrastructureServices(() => {
@@ -316,6 +407,120 @@ test.for(feature, ({ Scenario, BeforeEachScenario }) => {
 		});
 	});
 
+	Scenario('Registering a queue handler in wrong phase', ({ Given, When, Then }) => {
+		Given('a Cellix instance in infrastructure phase', () => {
+			cellix = Cellix.initializeInfrastructureServices(() => {
+				/* no op */
+			}) as Cellix<unknown, unknown>;
+		});
+
+		When('registerAzureFunctionQueueHandler is called', () => {
+			expect(() => {
+				cellix.registerAzureFunctionQueueHandler('community-update', { queueName: 'community-update', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn());
+			}).toThrow("Invalid operation in phase 'infrastructure'. Allowed phases: app-services, handlers");
+		});
+
+		Then('it should throw an error for invalid phase', () => {
+			// Error is already thrown in When step
+		});
+	});
+
+	Scenario('Chaining mixed Azure Function handler registrations', ({ Given, When, Then, And }) => {
+		Given('a Cellix instance in app-services phase', () => {
+			cellix = Cellix.initializeInfrastructureServices(() => {
+				/* no op */
+			}) as Cellix<unknown, unknown>;
+			cellix.setContext(() => ({}));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }));
+		});
+
+		When('queue and HTTP handlers are registered in mixed order', async () => {
+			cellix
+				.registerAzureFunctionQueueHandler('queue-first', { queueName: 'queue-first', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn())
+				.registerAzureFunctionHttpHandler('http-second', { authLevel: 'anonymous' }, () => vi.fn())
+				.registerAzureFunctionQueueHandler('queue-third', { queueName: 'queue-third', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn())
+				.registerAzureFunctionHttpHandler('http-fourth', { authLevel: 'anonymous' }, () => vi.fn());
+
+			await cellix.startUp();
+		});
+
+		Then('it should allow chaining mixed handler registrations', () => {
+			expect(app.storageQueue).toHaveBeenCalledTimes(2);
+			expect(app.http).toHaveBeenCalledTimes(2);
+		});
+
+		And('it should register each mixed handler at startup', () => {
+			expect(app.storageQueue).toHaveBeenNthCalledWith(1, 'queue-first', expect.objectContaining({ queueName: 'queue-first', connection: 'AZURE_STORAGE_CONNECTION_STRING', handler: expect.any(Function) }));
+			expect(app.http).toHaveBeenNthCalledWith(1, 'http-second', expect.objectContaining({ authLevel: 'anonymous', handler: expect.any(Function) }));
+			expect(app.storageQueue).toHaveBeenNthCalledWith(2, 'queue-third', expect.objectContaining({ queueName: 'queue-third', connection: 'AZURE_STORAGE_CONNECTION_STRING', handler: expect.any(Function) }));
+			expect(app.http).toHaveBeenNthCalledWith(2, 'http-fourth', expect.objectContaining({ authLevel: 'anonymous', handler: expect.any(Function) }));
+		});
+	});
+
+	Scenario('Starting up directly from app-services phase', ({ Given, When, Then, And }) => {
+		let result: Promise<unknown>;
+
+		Given('a Cellix instance in app-services phase with all configurations', () => {
+			cellix = Cellix.initializeInfrastructureServices((registry) => {
+				registry.registerInfrastructureService(mockService);
+			}) as Cellix<unknown, unknown>;
+			cellix.setContext(() => ({}));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }));
+		});
+
+		When('startUp is called directly from app-services', async () => {
+			result = cellix.startUp();
+			await result;
+			const mockHook = app.hook.appStart as unknown as { mock: { calls: [() => Promise<void>][] } };
+			const appStartCallback = mockHook.mock.calls[0]?.[0];
+			if (appStartCallback) {
+				await appStartCallback();
+			}
+		});
+
+		Then('it should start without requiring any handler registrations', () => {
+			expect(app.http).not.toHaveBeenCalled();
+			expect(app.storageQueue).not.toHaveBeenCalled();
+		});
+
+		And('it should transition to started phase', () => {
+			expect(result).toBeInstanceOf(Promise);
+			expect(cellix.servicesInitialized).toBe(true);
+		});
+	});
+
+	Scenario('Rejecting fluent operations after startup', ({ Given, When, Then }) => {
+		let assertAfterStartGuards: (() => void) | undefined;
+
+		Given('a started Cellix application', async () => {
+			cellix = Cellix.initializeInfrastructureServices((registry) => {
+				registry.registerInfrastructureService(mockService);
+			}) as Cellix<unknown, unknown>;
+			cellix.setContext(() => ({}));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }));
+			cellix.registerAzureFunctionHttpHandler('test-handler', { authLevel: 'anonymous' }, () => vi.fn());
+			await cellix.startUp();
+
+			assertAfterStartGuards = () => {
+				expect(() => cellix.setContext(() => ({}))).toThrow("Invalid operation in phase 'started'. Allowed phases: infrastructure");
+				expect(() => cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }))).toThrow("Invalid operation in phase 'started'. Allowed phases: context");
+				expect(() => cellix.registerAzureFunctionHttpHandler('another-http', { authLevel: 'anonymous' }, () => vi.fn())).toThrow("Invalid operation in phase 'started'. Allowed phases: app-services, handlers");
+				expect(() => cellix.registerAzureFunctionQueueHandler('another-queue', { queueName: 'another-queue', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn())).toThrow(
+					"Invalid operation in phase 'started'. Allowed phases: app-services, handlers",
+				);
+				expect(() => cellix.startUp()).toThrow("Invalid operation in phase 'started'. Allowed phases: handlers, app-services");
+			};
+		});
+
+		When('a fluent bootstrap method is called after startup', () => {
+			assertAfterStartGuards?.();
+		});
+
+		Then('it should reject further bootstrap mutations in started phase', () => {
+			// Assertions already executed in When step
+		});
+	});
+
 	Scenario('Starting up the application', ({ Given, When, Then, And }) => {
 		let result: Promise<unknown>;
 
@@ -324,8 +529,9 @@ test.for(feature, ({ Scenario, BeforeEachScenario }) => {
 				registry.registerInfrastructureService(mockService);
 			}) as Cellix<unknown, unknown>;
 			cellix.setContext(() => ({}));
-			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn() }));
+			cellix.initializeApplicationServices(() => ({ forRequest: vi.fn(), forSystem: vi.fn() }));
 			cellix.registerAzureFunctionHttpHandler('test-handler', { authLevel: 'anonymous' }, () => vi.fn());
+			cellix.registerAzureFunctionQueueHandler('community-update', { queueName: 'community-update', connection: 'AZURE_STORAGE_CONNECTION_STRING' }, () => vi.fn());
 		});
 
 		When('startUp is called', async () => {
@@ -354,6 +560,17 @@ test.for(feature, ({ Scenario, BeforeEachScenario }) => {
 			expect(app.hook.appTerminate).toHaveBeenCalled();
 		});
 
+		And('it should register Azure Functions queue handlers with app.storageQueue', () => {
+			expect(app.storageQueue).toHaveBeenCalledWith(
+				'community-update',
+				expect.objectContaining({
+					queueName: 'community-update',
+					connection: 'AZURE_STORAGE_CONNECTION_STRING',
+					handler: expect.any(Function),
+				}),
+			);
+		});
+
 		And('it should transition to started phase', () => {
 			// We can't test private phase, but we can test that services are initialized
 			expect(cellix.servicesInitialized).toBe(true);