@herrromich/az-functions 1.0.0

package/dist/src/http-controller/http-handler-support.factory.d.ts

@@ -0,0 +1,26 @@
+import { HttpRequest, InvocationContext } from '@azure/functions';
+import { HttpResponseInit } from '@azure/functions/types/http';
+import { AuthContext } from '../security';
+import { AzFunctionsSystemError } from '../shared';
+import { Promisable } from 'type-fest';
+import { ControllerOperationArgMetadata, DirectResponseObject } from './decorators';
+import { HttpRequestArgProviderFactory } from './http-request-arg-provider.factory';
+import { HttpResponseProcessorFactory } from './http-response-processor.factory';
+export declare class HttpTriggerDefinitionError extends AzFunctionsSystemError {
+}
+export interface HttpRequestProcessorInput {
+    request: HttpRequest;
+    invocationContext: InvocationContext;
+    authContext: AuthContext;
+}
+export type HttpRequestArgsProvider = (input: HttpRequestProcessorInput) => Promise<unknown[]>;
+export type HttpRequestArgProvider = (input: HttpRequestProcessorInput) => Promisable<unknown>;
+export type HttpResponseProcessor = (response: unknown) => Promise<HttpResponseInit>;
+export declare class HttpHandlerSupportFactory {
+    private readonly httpRequestArgProviderFactory;
+    private readonly httpResponseProcessorFactory;
+    constructor(httpRequestArgProviderFactory: HttpRequestArgProviderFactory, httpResponseProcessorFactory: HttpResponseProcessorFactory);
+    createRequestArgsProvider(operationArgs: ControllerOperationArgMetadata[]): HttpRequestArgsProvider;
+    private validateArgs;
+    createResponseProcessor(directResponse?: DirectResponseObject): HttpResponseProcessor;
+}

package/dist/src/http-controller/http-handler.factory.d.ts

@@ -0,0 +1,16 @@
+import { HttpRequest, InvocationContext } from '@azure/functions';
+import { HttpResponseInit } from '@azure/functions/types/http';
+import { Container } from 'inversify';
+import { LoggerFactory } from '../logger';
+import { HttpHandlerSupportFactory } from './http-handler-support.factory';
+import { HttpOperationRegistration } from './http-operations-registration.service';
+import { AuthenticatorProvider } from './security/authenticator.provider';
+export type RequestHandler = (request: HttpRequest, context: InvocationContext) => Promise<HttpResponseInit>;
+export declare class HttpHandlerFactory {
+    private readonly platformContainer;
+    private readonly supportService;
+    private readonly authenticationProvider;
+    private readonly logger;
+    constructor(loggerFactory: LoggerFactory, platformContainer: Container, supportService: HttpHandlerSupportFactory, authenticationProvider: AuthenticatorProvider);
+    createHandler(operationRegistration: HttpOperationRegistration, method: (...args: unknown[]) => Promise<unknown>): RequestHandler;
+}

package/dist/src/http-controller/http-operations-registration.service.d.ts

@@ -0,0 +1,22 @@
+import { LoggerFactory } from '../logger';
+import { TriggerHandlerClass } from '../shared';
+import { ControllerOperationMetadata, HttpControllerMetadata, HttpControllerMetadataReader } from './decorators';
+import { RestApplication } from './http-controller.model';
+import { OpenApiDefinitionService } from './open-api-definition.service';
+export interface HttpOperationRegistration {
+    operationId: string;
+    controllerMethod: string;
+    controllerMetadata: HttpControllerMetadata;
+    operationMetadata: ControllerOperationMetadata;
+    application: RestApplication;
+    route: string;
+}
+export type RegisterCallback = (operationRegistration: HttpOperationRegistration) => void;
+export declare class HttpOperationsRegistrationService {
+    private readonly metadataReader;
+    private readonly openApiDefinitionService;
+    private readonly logger;
+    constructor(loggerFactory: LoggerFactory, metadataReader: HttpControllerMetadataReader, openApiDefinitionService: OpenApiDefinitionService);
+    registerOperations(controllerClass: TriggerHandlerClass, registerCallback: RegisterCallback): void;
+    private getOperationMetadata;
+}

package/dist/src/http-controller/http-request-arg-provider.factory.d.ts

@@ -0,0 +1,12 @@
+import { ZodType } from 'zod';
+import { ControllerOperationPathArgMetadata, ControllerOperationQueryArgMetadata } from './decorators';
+import { HttpRequestArgProvider, HttpRequestArgsProvider } from './http-handler-support.factory';
+export declare class HttpRequestArgProviderFactory {
+    createBodyArgProvider<T>(bodySchema: ZodType<T>): HttpRequestArgProvider;
+    createPathParamArgProvider(arg: ControllerOperationPathArgMetadata): HttpRequestArgProvider;
+    createHeaderProvider(headerItemName: string, headerSchema: ZodType<string | undefined>): HttpRequestArgProvider;
+    createQueryItemArgProvider(arg: ControllerOperationQueryArgMetadata): HttpRequestArgProvider;
+    private getCoercedSchema;
+    private getCoercedSingleSchema;
+    createArgsProvider(argProviders: HttpRequestArgProvider[]): HttpRequestArgsProvider;
+}

package/dist/src/http-controller/http-response-processor.factory.d.ts

@@ -0,0 +1,10 @@
+import { HttpResponseInit } from '@azure/functions/types/http';
+import { DirectResponseObject } from './decorators';
+export type ResponsePartialProcessor = (input: HttpResponseInit) => Promise<HttpResponseInit>;
+export declare class HttpResponseProcessorFactory {
+    provideStatusProcessor(directResponse?: DirectResponseObject): ResponsePartialProcessor;
+    provideJsonBodyProcessor(directResponse?: DirectResponseObject): ResponsePartialProcessor | undefined;
+    private parseJsonBody;
+    provideHeaderProcessor(directResponse?: DirectResponseObject): ResponsePartialProcessor | undefined;
+    private parseDirectResponseHeaders;
+}

package/dist/src/http-controller/index.d.ts

@@ -0,0 +1,11 @@
+import { ContainerModule } from 'inversify';
+export * from './decorators';
+export * from './http-controller-registration.service';
+export * from './http-controller.model';
+export * from './http-handler-support.factory';
+export * from './open-api-definition.service';
+export * from './open-api-print.service';
+export * from './open-api-registration.service';
+export * from './security';
+export * from './swagger-handling.service';
+export declare const HttpControllerModule: ContainerModule;

package/dist/src/http-controller/open-api-definition.service.d.ts

@@ -0,0 +1,29 @@
+import { OpenAPIRegistry } from '@asteasolutions/zod-to-openapi';
+import { LoggerFactory } from '../logger';
+import { OpenAPIObject } from 'openapi3-ts/oas30';
+import { AzFunctionsSystemError } from '../shared';
+import { RestApplication } from './http-controller.model';
+import { HttpOperationRegistration } from './http-operations-registration.service';
+import { OpenApiMetadataService } from './open-api-metadata.service';
+export interface RestOpenApiEntry {
+    application: RestApplication;
+    registry: OpenAPIRegistry;
+}
+export type RestOpenApiEntries = Record<string, RestOpenApiEntry>;
+export declare class OpenApiDefinitionError extends AzFunctionsSystemError {
+}
+export declare class OpenApiDefinitionService {
+    private readonly loggerFactory;
+    private readonly openApiMetadataService;
+    private readonly logger;
+    private readonly restOpenApiEntries;
+    constructor(loggerFactory: LoggerFactory, openApiMetadataService: OpenApiMetadataService);
+    addApplication(application: RestApplication): void;
+    getApplications(): string[];
+    getApplication(applicationName?: string): RestApplication;
+    getRegistry(applicationName?: string): OpenAPIRegistry;
+    private getApiDataEntry;
+    generateDocument(applicationName: string, apiUrl?: string): OpenAPIObject;
+    private getDefaultDataEntry;
+    registerOperation(operationRegistration: HttpOperationRegistration): void;
+}

package/dist/src/http-controller/open-api-metadata.service.d.ts

@@ -0,0 +1,11 @@
+import { ResponseConfig, RouteConfig } from '@asteasolutions/zod-to-openapi';
+import { ControllerOperationMetadata, HttpControllerMetadata } from './decorators';
+type RouteConfigRequest = RouteConfig['request'];
+type Responses = Record<string, ResponseConfig>;
+export declare class OpenApiMetadataService {
+    getTags(controllerMetadata: HttpControllerMetadata, operationMetadata: ControllerOperationMetadata): string[] | undefined;
+    getRequest(operationMetadata: ControllerOperationMetadata): RouteConfigRequest;
+    getResponses(operationMetadata: ControllerOperationMetadata): Responses;
+    private static getQueryType;
+}
+export {};

package/dist/src/http-controller/open-api-print.service.d.ts

@@ -0,0 +1,8 @@
+import { LoggerFactory } from '../logger';
+import { OpenApiDefinitionService } from './open-api-definition.service';
+export declare class OpenApiPrintService {
+    private readonly openApiDefinitionService;
+    private readonly logger;
+    constructor(openApiDefinitionService: OpenApiDefinitionService, loggerFactory: LoggerFactory);
+    printOpenApi(): void;
+}

package/dist/src/http-controller/open-api-registration.service.d.ts

@@ -0,0 +1,17 @@
+import { LoggerFactory } from '../logger';
+import { TriggerHandlerClass, TriggerHandlerMetadataReader } from '../shared';
+import { RestApplication } from './http-controller.model';
+import { HttpOperationsRegistrationService } from './http-operations-registration.service';
+import { OpenApiDefinitionService } from './open-api-definition.service';
+export declare class OpenApiRegistrationService {
+    private readonly metadataReader;
+    private readonly definitionService;
+    private readonly operationRegistrationService;
+    private readonly loggerFactory;
+    private readonly logger;
+    constructor(metadataReader: TriggerHandlerMetadataReader, definitionService: OpenApiDefinitionService, operationRegistrationService: HttpOperationsRegistrationService, loggerFactory: LoggerFactory);
+    register(config: {
+        triggerHandlerClasses: TriggerHandlerClass[];
+        restApplications?: RestApplication[];
+    }): void;
+}

package/dist/src/http-controller/security/authentication-service.d.ts

@@ -0,0 +1,15 @@
+import { HttpRequest } from '@azure/functions';
+import { Principal } from '../../security';
+/**
+ * Service identifier for the AuthenticationService. This service is responsible for authenticating incoming HTTP requests and returning a Principal object representing the authenticated user.
+ * It can be used to implement custom authentication logic, such as validating JWT tokens, API keys, or other authentication mechanisms.
+ */
+export declare const AUTHENTICATION_SERVICE: import("inversify").ServiceIdentifier<AuthenticationService>;
+export declare const REST_APPLICATION_TAG_KEY: unique symbol;
+/**
+ * Interface representing an authentication service that can authenticate incoming HTTP requests.
+ * The service should implement the `authenticate` method, which takes an HttpRequest and returns a Promise that resolves to a Principal object representing the authenticated user.
+ */
+export interface AuthenticationService {
+    authenticate(request: HttpRequest): Promise<Principal>;
+}

package/dist/src/http-controller/security/authenticator.provider.d.ts

@@ -0,0 +1,31 @@
+import { HttpRequest } from '@azure/functions';
+import { LoggerFactory } from '../../logger';
+import { AuthContext, Principal } from '../../security';
+import { HttpOperationRegistration } from '../http-operations-registration.service';
+import { OperationAuthenticationResolver } from './operation-authentication.resolver';
+import { FallbackPrincipalMergeService } from './principal-merge.service';
+interface BaseAuthenticationResult {
+    state: string;
+    scheme: string;
+}
+interface SuccessfulAuthenticationResult extends BaseAuthenticationResult {
+    state: 'successful';
+    principal: Principal;
+}
+interface FailedAuthenticationResult extends BaseAuthenticationResult {
+    state: 'unauthenticated' | 'unauthorized';
+    error: unknown;
+}
+export type AuthenticationResult = SuccessfulAuthenticationResult | FailedAuthenticationResult;
+export type AuthenticationHandler = (request: HttpRequest) => Promise<AuthContext>;
+export declare class AuthenticatorProvider {
+    private readonly operationAuthenticationResolver;
+    private readonly principalMergeService;
+    private readonly logger;
+    constructor(loggerFactory: LoggerFactory, operationAuthenticationResolver: OperationAuthenticationResolver, principalMergeService: FallbackPrincipalMergeService);
+    provideAuthenticator(registrationData: HttpOperationRegistration): AuthenticationHandler;
+    private authenticate;
+    private authenticateSecurityBinding;
+    private getAndAuthenticationResult;
+}
+export {};

package/dist/src/http-controller/security/bearer-security-authentication.service.d.ts

@@ -0,0 +1,9 @@
+import { HttpRequest } from '@azure/functions';
+import { Principal } from '../../security';
+import { AuthenticationService } from './authentication-service';
+import { BearerTokenService } from './bearer-token.service';
+export declare class BearerSecurityAuthenticationService implements AuthenticationService {
+    private readonly bearerTokenService;
+    constructor(bearerTokenService: BearerTokenService);
+    authenticate(request: HttpRequest): Promise<Principal>;
+}

package/dist/src/http-controller/security/bearer-token.service.d.ts

@@ -0,0 +1,5 @@
+import { Principal } from '../../security';
+export interface BearerTokenService {
+    readonly bearerFormat: string;
+    getPrincipalFromToken(accessToken: string): Principal | PromiseLike<Principal>;
+}

package/dist/src/http-controller/security/index.d.ts

@@ -0,0 +1,3 @@
+export * from './authentication-service';
+export * from './bearer-security-authentication.service';
+export * from './bearer-token.service';

package/dist/src/http-controller/security/operation-authentication.resolver.d.ts

@@ -0,0 +1,18 @@
+import { Container } from 'inversify';
+import { LoggerFactory } from '../../logger';
+import { HttpOperationRegistration } from '../http-operations-registration.service';
+import { AuthenticationService } from './authentication-service';
+import { AuthenticationHandler } from './authenticator.provider';
+export interface SecurityBinding {
+    authService: AuthenticationService;
+    scopes: string[];
+}
+export type SecurityBindingObject = Record<string, SecurityBinding>;
+export declare class OperationAuthenticationResolver {
+    private readonly platformContainer;
+    private readonly logger;
+    constructor(loggerFactory: LoggerFactory, platformContainer: Container);
+    getOperationSecurityBindings(registrationData: HttpOperationRegistration): SecurityBindingObject[];
+    private getSecurityBindingObjects;
+    defaultAuthenticator(registrationData: HttpOperationRegistration): AuthenticationHandler;
+}

package/dist/src/http-controller/security/principal-merge.service.d.ts

@@ -0,0 +1,11 @@
+import { AuthContext, Principal } from '../../security';
+import { StrictPrincipalMergeService } from './strict-principal-merge.servce';
+export declare const PRINCIPAL_MERGE_SERVICE: import("inversify").ServiceIdentifier<PrincipalMergeService>;
+export interface PrincipalMergeService {
+    mergePrincipals(principals: Principal[]): AuthContext;
+}
+export declare class FallbackPrincipalMergeService implements PrincipalMergeService {
+    private readonly mergeService;
+    constructor(defaultMergeService: StrictPrincipalMergeService, optionalMergeService: PrincipalMergeService | undefined);
+    mergePrincipals(principals: Principal[]): AuthContext;
+}

package/dist/src/http-controller/security/strict-principal-merge.servce.d.ts

@@ -0,0 +1,5 @@
+import { AuthContext, Principal } from '../../security';
+import { PrincipalMergeService } from './principal-merge.service';
+export declare class StrictPrincipalMergeService implements PrincipalMergeService {
+    mergePrincipals(principals: Principal[]): AuthContext;
+}

package/dist/src/http-controller/swagger-handling.service.d.ts

@@ -0,0 +1,11 @@
+import { HttpRequest, HttpResponseInit } from '@azure/functions';
+import { OpenApiDefinitionService } from './open-api-definition.service';
+export declare class SwaggerHandlingService {
+    private readonly baseDir;
+    private readonly openApiDefinitionService;
+    constructor(baseDir: string, openApiDefinitionService: OpenApiDefinitionService);
+    handleSwaggerContent(request: HttpRequest): Promise<HttpResponseInit>;
+    private serveSwaggerUi;
+    handleOpenApiDefinition(request: HttpRequest): HttpResponseInit;
+    private getOriginalUrl;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+import './init';
+export { EventHubHandler, EventHubHandlerCardinality, EventHubMessageWrapper, EventHubTriggerMessageArgConfig, Message, Messages, OnEventHubTrigger, OnEventHubTriggerConfig, RawMessage, RawMessages, } from './event-hub-handler';
+export { PLATFORM_CONTEXT_MANAGER, PLATFORM_CONTEXT_PROVIDER, PlatformContext, PlatformContextManager, PlatformContextProvider, PlatformContextValueKey, createPlatformContextValueKey, } from './context';
+export { AUTHENTICATION_SERVICE, AuthCtx, AuthenticationService, BadRequestError, Body, ControllerConfig, ControllerOperationConfig, ControllerRequestBodyOperationConfig, Delete, DirectResponseObject, Get, Head, HeaderParam, HeaderParamConfig, HttpController, HttpDirectResponseBuilder, InternalServerError, NotFoundError, NumberSchema, OptionalStringSchema, Patch, PathParam, PathParamConfig, Post, Put, QueryParam, QueryParamConfig, Request, RestApplication, StringSchema, UnauthorizedError, } from './http-controller';
+export { DEFAULT_LOG_LEVEL, LOGGER_FACTORY, LOGGER_NAME_PROVIDER, LOG_LEVEL_PROVIDER, LogLevel, LogLevelProvider, Logger, LoggerFactory, LoggerNameProvider, OtelConfiguration, SYSTEM_LOGGER_NAME_PREFIX, TrieSearchService, } from './logger';
+export { startPlatform } from './middleware';
+export { IStartupService, STARTUP_SERVICE } from './platform';
+export { AUTHENTICATION_CONTEXT_KEY, AuthContext, AuthenticationError, Principal, SecurityContext } from './security';
+export { AzFunctionsErrorOptions, AzFunctionsRuntimeError, InvocationCtx, TriggerHandlerClass, serviceIdentifier, } from './shared';

package/dist/src/init.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/logger/bindings.d.ts

@@ -0,0 +1,7 @@
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import { ResolutionContext } from 'inversify';
+import * as winston from 'winston';
+import { LoggerFactory, OtelConfiguration } from './logger.model';
+export declare function bindWinstonLogger(context: ResolutionContext): winston.Logger;
+export declare function bindLoggerFactory(context: ResolutionContext): LoggerFactory;
+export declare function bindOtelLoggerProvider(otelConfiguration: OtelConfiguration): LoggerProvider;

package/dist/src/logger/index.d.ts

@@ -0,0 +1,6 @@
+import { ContainerModule } from 'inversify';
+import { LoggerConfiguration } from './logger.model';
+export * from './logger.model';
+export * from './logger.utils';
+export * from './trie-search.service';
+export declare function provideLoggerModule(loggerConfiguration?: LoggerConfiguration): ContainerModule;

package/dist/src/logger/log-level.service.d.ts

@@ -0,0 +1,7 @@
+import { LogLevel, LogLevelProvider } from './logger.model';
+export declare class LogLevelService {
+    private readonly logLevelsProvider;
+    private readonly defaultLogLevel;
+    constructor(logLevelsProvider: LogLevelProvider | undefined, defaultLogLevel: LogLevel);
+    getLogLevel(loggerName: string | undefined): LogLevel;
+}

package/dist/src/logger/log-transport.service.d.ts

@@ -0,0 +1,19 @@
+import { InvocationContext } from '@azure/functions';
+import { PlatformContextManager } from '../context';
+import * as Transport from 'winston-transport';
+import { LogLevelService } from './log-level.service';
+import { LogLevel } from './logger.model';
+import { OtelLogger } from './otel.logger';
+export type InvocationContextLogger = Pick<InvocationContext, 'log' | 'trace' | 'debug' | 'info' | 'warn' | 'error'>;
+export declare const LOG_METHOD_MAP: Record<LogLevel, keyof InvocationContextLogger>;
+export declare class AzFunctionsTransport extends Transport {
+    private readonly platformContextManager;
+    private readonly defaultLogLevel;
+    private readonly logger;
+    private readonly logLevelsService;
+    constructor(platformContextManager: PlatformContextManager, defaultLogLevel: LogLevel, logger: OtelLogger | undefined, logLevelsService: LogLevelService);
+    log(info: any, next: () => void): any;
+    private logInternal;
+    private getPlatformLogInfo;
+    private getContextMetadata;
+}

package/dist/src/logger/logger.model.d.ts

@@ -0,0 +1,241 @@
+import { TraceContext } from '@azure/functions';
+import { AnyValueMap } from '@opentelemetry/api-logs';
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import * as winston from 'winston';
+/**
+ * Log levels for the logger.
+ */
+export declare const LOG_LEVELS: {
+    readonly error: 0;
+    readonly warn: 1;
+    readonly info: 2;
+    readonly http: 3;
+    readonly verbose: 4;
+    readonly debug: 5;
+    readonly silly: 6;
+};
+export declare const LOGGER_NAME_META_KEY = "loggerName";
+export type ContextLoggerMetadata = Partial<Record<LogLevel, object>>;
+export declare const CONTEXT_LOGGER_METADATA: import("../context").PlatformContextValueKey<Partial<Record<"error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly", object>>>;
+/**
+ * Log levels for the logger.
+ *
+ * @see LOG_LEVELS
+ */
+export type LogLevel = keyof typeof LOG_LEVELS;
+/**
+ * IoC container identifier for the default log level used by the logger.
+ */
+export declare const DEFAULT_LOG_LEVEL: import("inversify").ServiceIdentifier<"error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly">;
+/**
+ * A logger interface that provides logging methods for different log levels.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyService {
+ *   private readonly logger: Logger;
+ *
+ *   constructor(@Inject(LOGGER_FACTORY) loggerFactory: LoggerFactory) {
+ *     this.logger = loggerFactory('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.info('Doing something...');
+ *   }
+ * }
+ * ```
+ */
+export type Logger = Pick<winston.Logger, LogLevel>;
+/**
+ * A prefix for all system loggers used by the AzFunctions platform. This prefix is used to identify loggers that are part of the platform's internal logging system.
+ */
+export declare const SYSTEM_LOGGER_NAME_PREFIX = "#az-functions";
+export declare const LOGGER_PROVIDER: import("inversify").ServiceIdentifier<LoggerProvider>;
+/**
+ * An IoC container identifier for a service that provides log levels for loggers.
+ *
+ * This service can be used to determine the log level for a specific logger based on its name.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyLogLevelProvider implements LogLevelProvider {
+ *   getLogLevel(loggerName?: string): LogLevel | undefined {
+ *     if (loggerName?.startsWith('MyService')) {
+ *       return 'debug';
+ *     }
+ *     return undefined;
+ *   }
+ * }
+ * ...
+ * export const LoggerModule = new ContainerModule(({ bind }) => {
+ *   ...
+ *   bind(LOG_LEVEL_PROVIDER).to(MyLogLevelProvider);
+ *   ...
+ * });
+ * ...
+ * startPlatform({
+ *   ...
+ *   modules: [
+ *     ...
+ *     LoggerModule,
+ *     ...
+ *   ],
+ * });
+ * ```
+ */
+export declare const LOG_LEVEL_PROVIDER: import("inversify").ServiceIdentifier<LogLevelProvider>;
+/**
+ * An identifier for a logger factory function that creates a logger instance.
+ *
+ * @param loggerName - The name of the logger. If not provided, the logger name will be derived from the call stack.
+ * @returns A logger instance.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyService {
+ *   private readonly logger: Logger;
+ *
+ *   constructor(@Inject(LOGGER_FACTORY) loggerFactory: LoggerFactory) {
+ *     this.logger = loggerFactory('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logger.info('Doing something...');
+ *   }
+ * }
+ * ```
+ */
+export declare const LOGGER_FACTORY: import("inversify").ServiceIdentifier<LoggerFactory>;
+/**
+ * A factory function that creates a logger instance.
+ *
+ * @param loggerName - The name of the logger. If not provided, the logger name will be derived from the call stack.
+ * @returns A logger instance.
+ */
+export type LoggerFactory = (loggerName?: string) => Logger;
+/**
+ * A IoC container identifier for a function that provides a logger name based on the call stack.
+
+@example
+```ts
+export const LoggerModule = new ContainerModule(({ bind }) => {
+  ...
+  bind(LOGGER_NAME_PROVIDER).toFactory(() => {
+    const regexp =
+      /^\s*at\s+(?:new\s+)?([A-Za-z0-9_$]+)\s+\(.*packages[\\/]examples[\\/]backend[\\/]src[\\/](.+)\/[^\\/]+:\d+:\d+\)$/;
+    return (stackEntry?: string) => {
+      const stackLines = stackEntry?.split('\n') ?? [];
+      let callerLine = stackLines.shift();
+      while (callerLine !== undefined) {
+        const match = regexp.exec(callerLine.trim());
+        if (match !== null) {
+          return `${LOGGER_NAME_PREFIX}.${match[2]?.replace(/\//g, '.')}.${match[1]}`;
+        } else {
+          callerLine = stackLines.shift();
+        }
+      }
+    };
+    ...
+  });
+  ...
+
+  startPlatform({
+    ...
+    modules: [
+      ...
+      LoggerModule,
+      ...
+    ],
+  });
+});
+```
+ */
+export declare const LOGGER_NAME_PROVIDER: import("inversify").ServiceIdentifier<LoggerNameProvider>;
+/**
+ * A function that provides a logger name based on the call stack.
+ *
+ * @param stackEntry - An optional stack entry from which to derive the logger name.
+ * @returns A logger name or undefined if it cannot be derived.
+ */
+export type LoggerNameProvider = (stackEntry?: string) => string | undefined;
+/**
+ * An interface for a service that provides log levels for loggers.
+ *
+ * This service can be used to determine the log level for a specific logger based on its name.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class MyLogLevelProvider implements LogLevelProvider {
+ *   getLogLevel(loggerName?: string): LogLevel | undefined {
+ *     if (loggerName?.startsWith('MyService')) {
+ *       return 'debug';
+ *     }
+ *     return undefined;
+ *   }
+ * }
+ * ```
+ */
+export interface LogLevelProvider {
+    /**
+     * Gets the log level for a specific logger based on its name.
+     *
+     * @param loggerName - The name of the logger for which to get the log level.
+     * @returns The log level for the specified logger, or undefined if no specific log level is set and default log level should be used.
+     */
+    getLogLevel(loggerName?: string): LogLevel | undefined;
+}
+/**
+ * Configuration options for OpenTelemetry (Otel) logging.
+ *
+ * This interface defines the configuration options required to set up OpenTelemetry logging in an application.
+ * It includes the connection string for Application Insights, as well as optional service metadata such as name, instance ID, and version.
+ *
+ * @param applicationInsightsConnectionString - The connection string for Application Insights, used to send telemetry data.
+ * @param serviceName - (Optional) The name of the service being monitored. This is used to identify the service in telemetry data.
+ * @param serviceInstanceId - (Optional) A unique identifier for the specific instance of the service. This can be used to differentiate between multiple instances of the same service.
+ * @param serviceVersion - (Optional) The version of the service being monitored. This can be used to track changes and updates to the service over time.
+ *
+ * @example
+ * ```ts
+ * const otelConfiguration: OtelConfiguration | undefined =
+ *   process.env.APPLICATIONINSIGHTS_CONNECTION_STRING !== undefined
+ *     ? {
+ *         applicationInsightsConnectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
+ *         serviceName: process.env.WEBSITE_DEPLOYMENT_ID,
+ *         serviceVersion: '1.0.0',
+ *         serviceInstanceId: process.env.WEBSITE_INSTANCE_ID,
+ *       }
+ *     : undefined;
+ * ...
+ * startPlatform({
+ *   ...
+ *   loggerConfiguration: {
+ *     otelConfiguration,
+ *   },
+ * });
+ * ```
+ */
+export interface OtelConfiguration {
+    applicationInsightsConnectionString: string;
+    serviceName?: string;
+    serviceInstanceId?: string;
+    serviceVersion?: string;
+}
+export interface LoggerConfiguration {
+    defaultLogLevel?: LogLevel;
+    otelConfiguration?: OtelConfiguration;
+}
+export interface PlatformLogInfo {
+    level: LogLevel;
+    timestamp: Date;
+    message: string;
+    invocationId?: string;
+    traceContext?: TraceContext;
+    operationName?: string;
+    loggerName: string;
+    metadata?: AnyValueMap;
+}

package/dist/src/logger/logger.utils.d.ts

@@ -0,0 +1,17 @@
+import { PlatformContextManager } from '../context';
+import { ContextLoggerMetadata } from './logger.model';
+export type AnyValueScalar = string | number | boolean;
+export type AnyValueArray = AnyValue[];
+export interface AnyValueMap {
+    [attributeKey: string]: AnyValue;
+}
+export type AnyValue = AnyValueScalar | Uint8Array | AnyValueArray | AnyValueMap | null | undefined;
+export interface SanitizerOptions {
+    maxDepth?: number;
+    maxTraceLength?: number;
+    maxArrayLength?: number;
+    maxKeysCount?: number;
+    maxStringLength?: number;
+}
+export declare function sanitizeMetadata(metadata: unknown, options?: SanitizerOptions): AnyValueMap;
+export declare function adjustContextLoggerMetadata(contextManager: PlatformContextManager, metadata: ContextLoggerMetadata): void;

package/dist/src/logger/otel.logger.d.ts

@@ -0,0 +1,9 @@
+import { LoggerProvider } from '@opentelemetry/sdk-logs';
+import { PlatformLogInfo } from './logger.model';
+export declare class OtelLogger {
+    private readonly loggerProvider;
+    constructor(loggerProvider: LoggerProvider);
+    log(logInfo: PlatformLogInfo): void;
+    private decodeTraceContext;
+    private getCustomDimensions;
+}