@herrromich/az-functions 1.0.0

package/src/platform/register-trigger-handler.factory.ts

@@ -0,0 +1,43 @@
+import { ResolutionContext } from 'inversify';
+import { LOGGER_FACTORY } from 'logger';
+import {
+  serviceIdentifier,
+  TRIGGER_HANDLER_REGISTRATION_SERVICE,
+  TriggerHandlerClass,
+  TriggerHandlerMetadataReader,
+} from 'shared';
+
+export const REGISTER_TRIGGER_HANDLER_FACTORY = serviceIdentifier<RegisterTriggerHandlerFactory>(
+  'Register Trigger Handler Factory',
+);
+
+export type RegisterTriggerHandlerFactory = (triggerHandlerClass: TriggerHandlerClass) => void;
+
+export function bindRegisterTriggerHandlerFactory(context: ResolutionContext): RegisterTriggerHandlerFactory {
+  const loggerFactory = context.get(LOGGER_FACTORY);
+  const logger = loggerFactory();
+  const metadataService = context.get(TriggerHandlerMetadataReader);
+  return (triggerHandlerClass: TriggerHandlerClass): void => {
+    try {
+      const metadata = metadataService.getHandlerClassMetadata(triggerHandlerClass);
+      const { type } = metadata;
+      const functionRegistrationService = context.get(TRIGGER_HANDLER_REGISTRATION_SERVICE, {
+        name: type,
+        optional: true,
+      });
+      if (functionRegistrationService === undefined) {
+        logger.warn(` No registration service ${TRIGGER_HANDLER_REGISTRATION_SERVICE.toString()}`, {
+          triggerHandlerClass: triggerHandlerClass.name,
+          triggerType: type,
+        });
+      } else {
+        functionRegistrationService.register(triggerHandlerClass);
+      }
+    } catch (error) {
+      logger.error(`Failed registration of trigger handler ${triggerHandlerClass.name}`, {
+        triggerHandlerClass: triggerHandlerClass.name,
+        error,
+      });
+    }
+  };
+}

package/src/platform/startup.service.ts

@@ -0,0 +1,39 @@
+import { serviceIdentifier } from 'shared';
+
+/**
+ * Represents a service responsible for performing startup tasks.
+ *
+ * This interface defines a single method, `startup`, which is expected to be implemented by any class that provides startup functionality.
+ * The `startup` method should return a Promise that resolves when the startup tasks are complete.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * export class MyStartupService implements IStartupService {
+ *   async startup(): Promise<void> {
+ *     // Perform startup tasks here
+ *   }
+ * }
+ * ...
+ * export const StartupModule = new ContainerModule((bind) => {
+ *   bind<IStartupService>(STARTUP_SERVICE).to(MyStartupService);
+ * });
+ * ...
+ * startPlatform({
+ * ...
+ *   modules: [
+ *   ...
+ *    StartupModule,
+ *   ...
+ *   ],
+ * ```
+ */
+export interface IStartupService {
+  startup(): Promise<void>;
+}
+
+/**
+ * A unique identifier for the `IStartupService` in the dependency injection container.
+ * This identifier can be used to register and retrieve the startup service implementation.
+ */
+export const STARTUP_SERVICE = serviceIdentifier<IStartupService>('AzFunctions.StartupService');

package/src/platform/system-logger-name.provider.ts

@@ -0,0 +1,20 @@
+import { SYSTEM_LOGGER_NAME_PREFIX } from 'logger';
+
+const regexp =
+  // eslint-disable-next-line sonarjs/regex-complexity,sonarjs/slow-regex
+  /^\s*at\s+(?:(?:new\s+(?<constructor>[\w$]+))|(?:(?:Object\.)?(?<function>[\w$]+))|(?:(?<class>[\w$]+)\.(?:[\w$+]+)))\s+(?:\[as\s[\w$]+\]\s)?(?:\(.*packages[\\/]extensions[\\/]az-functions[\\/]src(?<path>(?:[\\/][^:)\\/]*)*)[\\/].*\.ts:\d*:\d+\))$/;
+
+export function systemLoggerNameProvider(stackEntry?: string): string | undefined {
+  const stackLines = stackEntry?.split('\n') ?? [];
+  let callerLine = stackLines.shift();
+  while (callerLine !== undefined) {
+    const match = regexp.exec(callerLine.trim());
+    if (match !== null) {
+      const path = match.groups?.['path']?.replace(/\//g, '.');
+      const prefix = match.groups?.['constructor'] ?? match.groups?.['class'] ?? match.groups?.['function'];
+      return `${SYSTEM_LOGGER_NAME_PREFIX}${path}.${prefix}`;
+    } else {
+      callerLine = stackLines.shift();
+    }
+  }
+}

package/src/platform.container.ts

@@ -0,0 +1,21 @@
+import {
+  BasePlatformContextManager,
+  PLATFORM_CONTEXT_MANAGER,
+  PLATFORM_CONTEXT_PROVIDER,
+  PlatformExecutionContextProvider,
+} from 'context';
+import { Container } from 'inversify';
+import { LoggerConfiguration, provideLoggerModule } from 'logger';
+import { SecurityContext } from 'security';
+
+export function providePlatformContainer(loggerConfiguration: LoggerConfiguration | undefined) {
+  const platformContainer = new Container({
+    defaultScope: 'Singleton',
+  });
+  platformContainer.bind(PLATFORM_CONTEXT_MANAGER).to(BasePlatformContextManager);
+  platformContainer.loadSync(provideLoggerModule(loggerConfiguration));
+  platformContainer.get(PLATFORM_CONTEXT_MANAGER);
+  platformContainer.bind(SecurityContext).toSelf();
+  platformContainer.bind(PLATFORM_CONTEXT_PROVIDER).to(PlatformExecutionContextProvider);
+  return platformContainer;
+}

package/src/security/index.ts

@@ -0,0 +1,2 @@
+export * from './security-context';
+export * from './security.model';

package/src/security/security-context.ts

@@ -0,0 +1,30 @@
+import { PLATFORM_CONTEXT_MANAGER, PlatformContextManager } from 'context';
+import { inject, injectable } from 'inversify';
+import { AuthContext, AUTHENTICATION_CONTEXT_KEY } from './security.model';
+
+/**
+ * SecurityContext provides access to the current authentication context.
+ *
+ * It retrieves the authentication information from the platform context manager, which is typically set up during the request handling process.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const securityContext = container.get(SecurityContext);
+ * const authContext = securityContext.getAuthentication();
+ * if (authContext) {
+ *   // Access user information, roles, etc.
+ * }
+ * ```
+ */
+@injectable()
+export class SecurityContext {
+  constructor(
+    @inject(PLATFORM_CONTEXT_MANAGER)
+    private readonly contextManager: PlatformContextManager,
+  ) {}
+
+  getAuthentication(): AuthContext | undefined {
+    return this.contextManager.active()?.getValue(AUTHENTICATION_CONTEXT_KEY);
+  }
+}

package/src/security/security.model.ts

@@ -0,0 +1,46 @@
+import { createPlatformContextValueKey } from 'context';
+import { AzFunctionsErrorOptions, AzFunctionsRuntimeError } from 'shared';
+
+/**
+ *
+ */
+export class AuthenticationError extends AzFunctionsRuntimeError {
+  constructor(message?: string, options?: AzFunctionsErrorOptions) {
+    super(message, options);
+  }
+}
+
+/**
+ * Represents an authenticated principal in the authentication context.
+ * @property {string} subject - The unique identifier of the principal (e.g., user ID).
+ * @property {string} type - The type of the principal (e.g., "user", "service").
+ * @property {string} scheme - The authentication scheme used for the principal (e.g., "bearer", "basic").
+ * @property {string[]} scopes - An array of scopes associated with the principal.
+ * @property {Record<string, unknown>} [meta] - Optional additional metadata about the principal.
+ */
+export interface Principal {
+  subject: string;
+  type: string;
+  scheme: string;
+  scopes: string[];
+  meta?: Record<string, unknown>;
+}
+
+/**
+ * Represents the authentication context for a request.
+ * @property {Principal | null} principal - The primary authenticated principal, or null if not authenticated.
+ * @property {Principal[]} principals - An array of all principals associated with the request.
+ * @property {string[]} scopes - An array of scopes associated with the authenticated principal.
+ */
+export interface AuthContext {
+  principal: Principal | null;
+  principals: Principal[];
+  scopes: string[];
+}
+
+/**
+ * A unique key for accessing the authentication context in the platform context.
+ */
+export const AUTHENTICATION_CONTEXT_KEY = createPlatformContextValueKey<AuthContext>(
+  'AzFunctions.ContextKey.Authentication',
+);

package/src/shared/decorators/decorators.model.ts

@@ -0,0 +1,17 @@
+import { AzFunctionsSystemError } from '../platform.model';
+
+export interface ArgMetadata {
+  type: string;
+}
+
+export interface CommonArgMetadata extends ArgMetadata {
+  type: 'invocationContext' | 'undefined';
+}
+
+export interface ArgsMetadata<T extends ArgMetadata> {
+  args: T[];
+}
+
+export type ArgMetadataProvider<T extends ArgMetadata> = (paramType: unknown) => T;
+
+export class AzFunctionsDecoratorError extends AzFunctionsSystemError {}

package/src/shared/decorators/decorators.ts

@@ -0,0 +1,87 @@
+import { FUNCTION_HANDLER_METADATA } from '../platform.model';
+import {
+  ArgMetadata,
+  ArgMetadataProvider,
+  ArgsMetadata,
+  AzFunctionsDecoratorError,
+  CommonArgMetadata,
+} from './decorators.model';
+
+export function adjustMetadata<T extends ArgMetadata>(
+  metadataKey: unknown,
+  operationArg: T,
+  argMetadataProvider: ArgMetadataProvider<T>,
+): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    if (propertyKey === undefined) {
+      throw new AzFunctionsDecoratorError('The decorator can only be used on method parameters.');
+    }
+    const metadata: ArgsMetadata<T> =
+      Reflect.getOwnMetadata(metadataKey, target, propertyKey) ??
+      initializeMetadata(target, propertyKey, argMetadataProvider);
+    metadata.args[parameterIndex] = operationArg;
+    Reflect.defineMetadata(metadataKey, metadata, target, propertyKey);
+  };
+}
+
+export function initializeMetadata<T extends ArgMetadata>(
+  target: object,
+  propertyKey: string | symbol,
+  argMetadataProvider: ArgMetadataProvider<T>,
+): ArgsMetadata<T> {
+  const paramTypes = Reflect.getOwnMetadata('design:paramtypes', target, propertyKey) as unknown[] | undefined;
+  if (!paramTypes) {
+    throw new AzFunctionsDecoratorError(
+      `Method ${target.constructor.name}.${String(propertyKey)} doesn't exist or has no metadata. Be sure to import reflect-metadata.`,
+    );
+  }
+  return {
+    args: paramTypes.map(paramType => argMetadataProvider(paramType)),
+  };
+}
+
+export function getCommonArg(): CommonArgMetadata {
+  return { type: 'undefined' };
+}
+
+/**
+ * Parameter decorator to inject the Azure Functions `InvocationContext` into a function parameter.
+ *
+ * @example
+ * ```ts
+ * @HttpController({
+ *  path: '/users',
+ *  })
+ *  export class UserController {
+ *  constructor(private readonly adUsersService: AdUsersService
+ *   private readonly usersMapper: UsersMapper) {}
+ *
+ *  @Get({
+ *   directResponse: {
+ *    contentSchema: usersResponseDtoSchema,
+ *    description: 'Returns a list of users',
+ *   },
+ *  })
+ *  async getUsers(@InvocationCtx() invocationCtx: InvocationContext): Promise<UsersResponseDto> {
+ *   invocationCtx.log.info('Requesting users.');
+ *
+ *   const adUsers = await this.adUsersService.getUsers();
+ *   const items = this.usersMapper.fromAdUsers(adUsers);
+ *
+ *   invocationCtx.log.info('Responding users.');
+ *   invocationCtx.log.debug('Responding %n users.', items.length);
+ *
+ *   return { items };
+ *  }
+ * }
+ * ```
+ */
+export function InvocationCtx() {
+  return adjustMetadata(
+    FUNCTION_HANDLER_METADATA,
+    {
+      type: 'invocationContext',
+    } as CommonArgMetadata,
+    getCommonArg,
+  );
+}

package/src/shared/decorators/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators';
+export * from './decorators.model';

package/src/shared/index.ts

@@ -0,0 +1,16 @@
+import { ContainerModule } from 'inversify';
+import * as path from 'node:path';
+import { BASE_DIR } from './platform.model';
+import { TriggerHandlerMetadataReader } from './trigger-handler-metadata.reader';
+
+export { TrieSearchService } from '../logger/trie-search.service';
+export * from './decorators';
+export { serviceIdentifier } from './ioc-container.utils';
+export * from './platform.model';
+export * from './trigger-handler-metadata.reader';
+export { parseWithZod, ZodParserError } from './zod-parser-wrapper';
+
+export const SharedModule = new ContainerModule(({ bind }) => {
+  bind(BASE_DIR).toConstantValue(path.resolve(__dirname, '.'));
+  bind(TriggerHandlerMetadataReader).toSelf();
+});

package/src/shared/ioc-container.utils.ts

@@ -0,0 +1,10 @@
+import { ServiceIdentifier } from 'inversify';
+
+/**
+ * Creates a typed service identifier for use with InversifyJS.
+ * @param key The unique key for the service.
+ * @returns A symbol that can be used as a service identifier.
+ */
+export function serviceIdentifier<T>(key: string): ServiceIdentifier<T> {
+  return Symbol.for(key);
+}

package/src/shared/platform.model.ts

@@ -0,0 +1,71 @@
+import { Container } from 'inversify';
+import { z } from 'zod';
+import { serviceIdentifier } from './ioc-container.utils';
+
+export const BASE_DIR = serviceIdentifier<string>('Base Directory for Azure Functions');
+export const PLATFORM_CONTAINER = serviceIdentifier<Container>('Platform Container');
+
+export const FUNCTION_HANDLER_METADATA = Symbol.for('AzFunctions.Metadata.Handler');
+
+export const platformModeSchema = z.enum(['start', 'print-open-api']).catch('start');
+
+/**
+ * Options for creating an AzFunctionsError.
+ * @property {Record<string, unknown>} [details] - Optional additional details about the error.
+ */
+export interface AzFunctionsErrorOptions extends ErrorOptions {
+  details?: Record<string, unknown>;
+}
+
+export abstract class AzFunctionsError extends Error {
+  protected _details?: Record<string, unknown>;
+  get details(): Readonly<Record<string, unknown>> | undefined {
+    return this._details;
+  }
+
+  protected constructor(message?: string, options?: AzFunctionsErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+    this._details = options?.details;
+  }
+}
+
+export abstract class AzFunctionsSystemError extends AzFunctionsError {
+  constructor(message?: string, options?: AzFunctionsErrorOptions) {
+    super(message, options);
+  }
+}
+
+/**
+ * Abstract base class for runtime errors in Azure Functions.
+ * @example
+ * ```ts
+ * class MyRuntimeError extends AzFunctionsRuntimeError {}
+ * ```
+ */
+export class AzFunctionsRuntimeError extends AzFunctionsError {
+  constructor(message?: string, options?: AzFunctionsErrorOptions) {
+    super(message, options);
+  }
+}
+
+export type TriggerHandlerClass<
+  TInstance extends object = object,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TArgs extends unknown[] = any[],
+> = new (...args: TArgs) => TInstance;
+
+export interface TriggerHandlerClassMetadata {
+  type: string;
+}
+
+export const TRIGGER_HANDLER_REGISTRATION_SERVICE = serviceIdentifier<TriggerHandlerRegistrationService>(
+  'AzFunctions.TriggerHandler.RegistrationService',
+);
+
+export interface TriggerHandlerRegistrationService {
+  register(triggerHandlerClass: TriggerHandlerClass): void;
+}
+
+export class HandlerArgsParseError extends AzFunctionsRuntimeError {}

package/src/shared/trigger-handler-metadata.reader.ts

@@ -0,0 +1,27 @@
+import { injectable } from 'inversify';
+import {
+  AzFunctionsSystemError,
+  FUNCTION_HANDLER_METADATA,
+  TriggerHandlerClass,
+  TriggerHandlerClassMetadata,
+} from './platform.model';
+
+export class TriggerHandlerMetadataError extends AzFunctionsSystemError {}
+
+@injectable()
+export class TriggerHandlerMetadataReader {
+  getHandlerClassMetadata(triggerHandlerClass: TriggerHandlerClass): TriggerHandlerClassMetadata {
+    const metadata = Reflect.getMetadata(FUNCTION_HANDLER_METADATA, triggerHandlerClass);
+    if (metadata === undefined) {
+      throw new TriggerHandlerMetadataError(
+        `No trigger handler metadata found for triggerHandlerClass=${triggerHandlerClass.name}`,
+        {
+          details: {
+            triggerHandlerClassName: triggerHandlerClass.name,
+          },
+        },
+      );
+    }
+    return metadata as TriggerHandlerClassMetadata;
+  }
+}

package/src/shared/zod-parser-wrapper.ts

@@ -0,0 +1,49 @@
+import { z, ZodError } from 'zod';
+
+export class ZodParserError extends Error {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = this.constructor.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function formatZodErrorIssues(error: ZodError) {
+  const lines: string[] = [];
+  for (const issue of error.issues.slice(0, 5)) {
+    lines.push(`✖ ${issue.message}`);
+    lines.push(`  → at ${toDotPath(issue.path)}`);
+  }
+  if (error.issues.length > 5) {
+    lines.push(`... and ${error.issues.length - 5} more issues`);
+  }
+
+  return lines.join('\n');
+}
+
+export function parseWithZod<T>(schema: z.ZodType<T>, data: unknown): T {
+  const safeParse = schema.safeParse(data);
+  if (safeParse.success) {
+    return safeParse.data;
+  } else {
+    const error = safeParse.error;
+    const zodErrorIssues = formatZodErrorIssues(error);
+    const message = `Error parsing data:
+${zodErrorIssues}`;
+    throw new ZodParserError(message);
+  }
+}
+
+function toDotPath(path: PropertyKey[]): string {
+  const segs: string[] = [];
+  for (const seg of path) {
+    if (typeof seg === 'number') segs.push(`[${seg}]`);
+    else if (typeof seg === 'symbol' || /[^\w$]/.test(seg)) segs.push(`[${JSON.stringify(seg)}]`);
+    else {
+      if (segs.length) segs.push('.');
+      segs.push(seg);
+    }
+  }
+
+  return segs.join('');
+}

package/src/test-utilities/index.ts

@@ -0,0 +1 @@
+export { getPartialFixture } from './utils';

package/src/test-utilities/utils.ts

@@ -0,0 +1,5 @@
+import { PartialDeep } from 'type-fest';
+
+export function getPartialFixture<T>(fixture?: PartialDeep<T>): T {
+  return (fixture ?? {}) as T;
+}

package/tsconfig.test.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "test",
+    "types": ["node", "reflect-metadata", "jest", "jest-extended", "jest-mock-extended"]
+  },
+  "exclude": ["node_modules", "dist"]
+}