Add blob storage framework and OCOM adapter services

.snyk

@@ -96,4 +96,10 @@ ignore:
         reason: 'Requires upgrade of @opentelemetry/sdk-node to 0.217.0, which has type errors that break compilation. Created task to upgrade OTEL service to 2.x and resolve vulnerability that way.'
         expires: '2026-07-28T00:00:00.000Z'
         created: '2026-06-01T10:00:00.000Z'
+sast-ignore:
+  'packages/cellix/service-blob-storage/src/test-support/azurite.ts':
+    - 'Hardcoded-Non-Cryptographic-Secret @ line 10':
+        reason: 'This is the standard well-known Azurite/Azure Storage Emulator test account key from official Microsoft documentation (https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite). Used only for local testing and not a real credential.'
+        expires: '2027-05-14T00:00:00.000Z'
+        created: '2026-05-14T16:00:00.000Z'
 

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

@@ -22,7 +22,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 --location ../../__queuestorage__ & azurite-table --silent --location ../../__tablestorage__"
 	},
 	"dependencies": {
 		"@azure/functions": "catalog:",

apps/api/src/cellix.test.ts

@@ -172,6 +172,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']>;
 

apps/api/src/cellix.ts

@@ -7,16 +7,21 @@ interface InfrastructureServiceRegistry<ContextType = unknown, AppServices = unk
 	 * Registers an infrastructure service with the application.
 	 *
 	 * @remarks
-	 * Must be called during the {@link Phase | 'infrastructure'} phase. Each
-	 * constructor key can be registered at most once.
+	 * Must be called during the {@link Phase | 'infrastructure'} phase.
+	 * By default, services are keyed by constructor identity (minification-safe).
+	 * This method now has an optional `name` argument to allow registering
+	 * multiple instances of the same constructor under distinct string keys.
 	 *
 	 * @typeParam T - The concrete service type.
 	 * @param service - The service instance to register.
+	 * @param name - Optional semantic name for the service. If provided, the
+	 *               service will be retrievable by name via getInfrastructureService(name).
 	 * @returns The registry (for chaining).
 	 *
-	 * @throws Error - If called outside the infrastructure phase or the service key is already registered.
+	 * @throws Error - If called outside the infrastructure phase, the constructor key is already registered (when name is omitted),
+	 *                 or the provided name is already registered.
 	 */
-	registerInfrastructureService<T extends ServiceBase>(service: T): InfrastructureServiceRegistry<ContextType, AppServices>;
+	registerInfrastructureService<T extends ServiceBase>(service: T, name?: string): InfrastructureServiceRegistry<ContextType, AppServices>;
 }
 
 interface ContextBuilder<ContextType = unknown, AppServices = unknown> {
@@ -119,30 +124,21 @@ interface StartedApplication<ContextType = unknown> extends InitializedServiceRe
 
 interface InitializedServiceRegistry {
 	/**
-	 * Retrieves a registered infrastructure service by its constructor key.
+	 * Retrieves a registered infrastructure service by its constructor key or by
+	 * its semantic name.
 	 *
 	 * @remarks
-	 * Services are keyed by their constructor identity (not by name), which is
-	 * minification-safe. You must pass the same class you used when registering
-	 * the service; base classes or interfaces will not match.
+	 * If a string `name` was used when registering the service, pass that name
+	 * to retrieve it. Otherwise, pass the service constructor used at
+	 * registration time.
 	 *
 	 * @typeParam T - The concrete service type.
-	 * @param serviceKey - The service class (constructor) used at registration time.
+	 * @param serviceKeyOrName - The service class (constructor) or the string name used at registration time.
 	 * @returns The registered service instance.
 	 *
-	 * @throws Error - If no service is registered for the provided key.
-	 *
-	 * @example
-	 * ```ts
-	 * // registration
-	 * registry.registerInfrastructureService(new BlobStorageService(...));
-	 *
-	 * // lookup
-	 * const blob = app.getInfrastructureService(BlobStorageService);
-	 * await blob.startUp();
-	 * ```
+	 * @throws Error - If no service is registered for the provided key or name.
 	 */
-	getInfrastructureService<T extends ServiceBase>(serviceKey: ServiceKey<T>): T;
+	getInfrastructureService<T extends ServiceBase>(serviceKeyOrName: ServiceKey<T> | string): T;
 	get servicesInitialized(): boolean;
 }
 
@@ -184,6 +180,12 @@ export class Cellix<ContextType, AppServices = unknown>
 	private appServicesHostBuilder: ((infrastructureContext: ContextType) => RequestScopedHost<AppServices, unknown>) | undefined;
 	private readonly tracer: Tracer;
 	private readonly servicesInternal: Map<ServiceKey<ServiceBase>, ServiceBase> = new Map();
+	/**
+	 * Optional name-based registry for services. Names are semantic strings that
+	 * allow multiple instances of the same constructor to coexist under
+	 * different names.
+	 */
+	private readonly nameMap: Map<string, ServiceBase> = new Map();
 	private readonly pendingHandlers: Array<PendingHandler<AppServices>> = [];
 	private serviceInitializedInternal = false;
 	private phase: Phase = 'infrastructure';
@@ -230,13 +232,24 @@ export class Cellix<ContextType, AppServices = unknown>
 		return instance;
 	}
 
-	public registerInfrastructureService<T extends ServiceBase>(service: T): InfrastructureServiceRegistry<ContextType, AppServices> {
+	public registerInfrastructureService<T extends ServiceBase>(service: T, name?: string): InfrastructureServiceRegistry<ContextType, AppServices> {
 		this.ensurePhase('infrastructure');
 		const key = service.constructor as ServiceKey<ServiceBase>;
-		if (this.servicesInternal.has(key)) {
-			throw new Error(`Service already registered for constructor: ${service.constructor.name}`);
+		if (name == null) {
+			// Backwards-compatible constructor-only registration: preserve existing
+			// behaviour and throw if the constructor key is already present.
+			if (this.servicesInternal.has(key)) {
+				throw new Error(`Service already registered for constructor: ${service.constructor.name}`);
+			}
+			this.servicesInternal.set(key, service);
+		} else {
+			// Name-based registration: ensure name uniqueness, but allow the same
+			// constructor to exist under multiple names.
+			if (this.nameMap.has(name)) {
+				throw new Error(`Service name already registered: ${name}`);
+			}
+			this.nameMap.set(name, service);
 		}
-		this.servicesInternal.set(key, service);
 		return this;
 	}
 
@@ -352,10 +365,17 @@ export class Cellix<ContextType, AppServices = unknown>
 		}
 	}
 
-	public getInfrastructureService<T extends ServiceBase>(serviceKey: ServiceKey<T>): T {
-		const service = this.servicesInternal.get(serviceKey as ServiceKey<ServiceBase>);
+	public getInfrastructureService<T extends ServiceBase>(serviceKeyOrName: ServiceKey<T> | string): T {
+		if (typeof serviceKeyOrName === 'string') {
+			const named = this.nameMap.get(serviceKeyOrName);
+			if (!named) {
+				throw new Error(`Service not found: ${serviceKeyOrName}`);
+			}
+			return named as T;
+		}
+		const service = this.servicesInternal.get(serviceKeyOrName as ServiceKey<ServiceBase>);
 		if (!service) {
-			const name = (serviceKey as { name?: string }).name ?? 'UnknownService';
+			const name = (serviceKeyOrName as { name?: string }).name ?? 'UnknownService';
 			throw new Error(`Service not found: ${name}`);
 		}
 		return service as T;
@@ -381,20 +401,32 @@ export class Cellix<ContextType, AppServices = unknown>
 
 	// Service lifecycle helpers
 	private async startAllServicesWithTracing(): Promise<void> {
-		await this.iterateServicesWithTracing('start', 'startUp');
+		const services = this.getUniqueServicesForLifecycle();
+		await this.iterateServicesWithTracing(services, 'start', 'startUp');
 	}
 	private async stopAllServicesWithTracing(): Promise<void> {
-		await this.iterateServicesWithTracing('stop', 'shutDown');
+		const services = this.getUniqueServicesForLifecycle();
+		await this.iterateServicesWithTracing(services, 'stop', 'shutDown');
+	}
+	private getUniqueServicesForLifecycle(): ServiceBase[] {
+		const set = new Set<ServiceBase>();
+		for (const svc of this.servicesInternal.values()) {
+			set.add(svc);
+		}
+		for (const svc of this.nameMap.values()) {
+			set.add(svc);
+		}
+		return Array.from(set.values());
 	}
-	private async iterateServicesWithTracing(operationName: 'start' | 'stop', serviceMethod: 'startUp' | 'shutDown'): Promise<void> {
+	private async iterateServicesWithTracing(services: ServiceBase[], operationName: 'start' | 'stop', serviceMethod: 'startUp' | 'shutDown'): Promise<void> {
 		const operationFullName = `${operationName.charAt(0).toUpperCase() + operationName.slice(1)}Service`;
 		const operationActionPending = operationName === 'start' ? 'starting' : 'stopping';
 		const operationActionCompleted = operationName === 'start' ? 'started' : 'stopped';
 		await Promise.all(
-			Array.from(this.servicesInternal.entries()).map(([ctor, service]) =>
-				this.tracer.startActiveSpan(`Service ${(ctor as unknown as { name?: string }).name ?? 'Service'} ${operationName}`, async (span) => {
+			services.map((service) =>
+				this.tracer.startActiveSpan(`Service ${service.constructor.name} ${operationName}`, async (span) => {
 					try {
-						const ctorName = (ctor as unknown as { name?: string }).name ?? 'Service';
+						const ctorName = service.constructor?.name ?? 'Service';
 						console.log(`${operationFullName}: Service ${ctorName} ${operationActionPending}`);
 						await service[serviceMethod]();
 						span.setStatus({ code: SpanStatusCode.OK, message: `Service ${ctorName} ${operationActionCompleted}` });

apps/api/src/features/cellix.feature

@@ -18,6 +18,21 @@ Feature: Cellix Application Bootstrap
     When the same service type is registered again
     Then it should throw an error indicating the service is already registered
 
+  Scenario: Registering a named infrastructure service
+    Given a Cellix instance in infrastructure phase
+    When an infrastructure service is registered with a name
+    Then it should be retrievable by name
+
+  Scenario: Registering a duplicate service name
+    Given a Cellix instance with a named service registered
+    When another service is registered with the same name
+    Then it should throw an error indicating duplicate name registration
+
+  Scenario: Lifecycle deduplicates services registered by constructor and name
+    Given a Cellix instance with the same service registered by constructor and by name
+    When the application starts
+    Then the service startUp should be called exactly once
+
   Scenario: Setting the infrastructure context
     Given a Cellix instance in infrastructure phase
     When the context creator is set