@wildo-ai/saas-backend-lib 1.0.1

package/src/requests/service/platform-mutualized-handler.backend.service.ts

@@ -0,0 +1,19 @@
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+
+@injectable()
+export class PlatformMutualizedHandlerBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('PlatformMutualizedHandler');
+    this.logger.setDebugTypeLogging('PlatformMutualizedHandler', false);
+  }
+}
+
+

package/src/requests/service/platform-requests.backend.utils.ts

@@ -0,0 +1,54 @@
+import { WildoHeaderKeys } from '@wildo-ai/saas-models';
+import { PlatformRequestContext, PlatformRequestOrigin } from "~wildo-backend-lib/requests/models/requests.backend.schemas";
+import { Request } from "express";
+
+
+export class PlatformRequestsBackendUtils {
+
+  public static buildPlatformRequestContext(req: Request): PlatformRequestContext {
+    // Express always provides headers object - no fallback needed (strict configuration)
+    const headers = req.headers;
+
+    // Direct header access helper (headers already lowercase in Express, WildoHeaderKeys values are already lowercase)
+    const getHeader = (key: string): string | undefined => {
+      const value = headers[key];
+      if (Array.isArray(value)) return value[0];
+      return typeof value === 'string' ? value : undefined;
+    };
+
+    const authorizationHeader = getHeader(WildoHeaderKeys.AUTHORIZATION);
+    const bearerToken = authorizationHeader?.startsWith('Bearer ')
+      ? authorizationHeader.substring('Bearer '.length)
+      : undefined;
+
+    const serviceId = getHeader(WildoHeaderKeys.SERVICE_ID) as any; // AllApplicationTypes at call sites
+    const applicationId = getHeader(WildoHeaderKeys.APPLICATION_ID);
+    const requestUUID = getHeader(WildoHeaderKeys.REQUEST_UUID);
+    const platformSecret = getHeader(WildoHeaderKeys.PLATFORM_SECRET);
+
+    // Determine origin based on presence of headers used by clients
+    // - PLATFORM_TO_PLATFORM: Authorization bearer JWT issued by platform services and X-Service-Id present
+    // - APP_TO_PLATFORM: X-Platform-Secret provided by application bootstrap loader
+    // - UNKNOWN: none matched
+    let origin: PlatformRequestContext['origin'] = PlatformRequestOrigin.UNKNOWN;
+    if (platformSecret) {
+      origin = PlatformRequestOrigin.APP_TO_PLATFORM;
+    } else if (bearerToken && serviceId) {
+      origin = PlatformRequestOrigin.PLATFORM_TO_PLATFORM;
+    }
+
+    const context: PlatformRequestContext = {
+      origin,
+      serviceId,
+      applicationId,
+      authorizationToken: bearerToken,
+      platformSecret,
+      requestUUID,
+      ipAddress: req.ip,
+      userAgent: getHeader(WildoHeaderKeys.USER_AGENT),
+      headers,
+    };
+
+    return context;
+  }
+}

package/src/requests/service/remote-client-base.backend.service.ts

@@ -0,0 +1,485 @@
+// Required for decorator metadata
+import 'reflect-metadata';
+
+import { ErrorCustomMessageReference, ErrorType, HttpStatusCode, WildoHeaderKeys } from '@wildo-ai/saas-models';
+
+
+
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
+import { Readable } from 'stream';
+
+import type { AllApplicationTypes } from '~wildo-backend-lib/applications/models/applications.backend.schemas';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { JwtBackendService } from '~wildo-backend-lib/security/jwt/services/jwt.backend.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+/**
+ * Platform HTTP Request configuration
+ */
+export interface BackendHttpClientRequestConfig {
+    url?: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+    headers?: Record<string, string>;
+    data?: any;
+    params?: Record<string, any>;
+    timeout?: number;
+    retries?: number;
+    retryDelay?: number;
+    requireAuth?: boolean;
+    serviceToken?: string;
+    executionContext? : ExecutionContext<any>;
+    /**
+     * Response type for streaming support
+     * - 'json' (default): Parse response as JSON
+     * - 'stream': Return response as Readable stream
+     * - 'arraybuffer': Return response as ArrayBuffer
+     */
+    responseType?: 'json' | 'stream' | 'arraybuffer';
+  }
+
+// Public interface describing the consumable API of RemoteClientBaseBackendService
+export interface IRemoteClientBaseBackendService {
+  isAvailable(): Promise<boolean>;
+
+  get<T = any>(path: string, config?: Partial<BackendHttpClientRequestConfig>): Promise<T>;
+  post<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T>;
+  put<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T>;
+  patch<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T>;
+  delete<T = any>(path: string, config?: Partial<BackendHttpClientRequestConfig>): Promise<T>;
+
+  healthCheck(): Promise<{ healthy: boolean; latency: number; error?: string }>;
+  getConcurrentRequestCount(): number;
+}
+
+
+const RETRY_DELAY = 1000;
+const RETRY_MAX_ATTEMPTS = 3;
+const TIMEOUT = 300000;
+
+// Readiness check configuration
+const READINESS_BASE_DELAY_MS = 100;
+const READINESS_MAX_DELAY_MS = 10000;
+const READINESS_REQUEST_TIMEOUT_MS = 5000;
+
+
+
+export class RemoteClientBaseBackendService implements IRemoteClientBaseBackendService {
+
+    protected baseUrl: string;
+    protected axiosInstance: AxiosInstance;
+    protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+    protected localServiceId: AllApplicationTypes;
+    protected remoteServiceId: AllApplicationTypes;
+    protected localServiceJwtPrivateKey : string;
+    protected localServiceJwtPublicKey : string;
+    protected remoteServiceBaseUrl: string;
+
+    protected requestTimeout: number = TIMEOUT;
+    protected requestRetries: number = RETRY_MAX_ATTEMPTS;
+    protected requestRetryDelay: number = RETRY_DELAY;
+
+    protected currentConcurrency: number = 0;
+
+    // Readiness state
+    private isReady: boolean = false;
+    private readinessPromise: Promise<void> | null = null;
+
+    constructor(
+        protected logger: LoggerService,
+        protected errorBuilder: ErrorBuilderBackendService,
+        protected jwtBackendService: JwtBackendService,
+        remoteServiceId: AllApplicationTypes,
+    ) {
+        this.remoteServiceId = remoteServiceId;
+    }
+
+    protected initiateAxiosInstance(headers: Record<string, string>): void {
+        this.axiosInstance = axios.create({
+          timeout: this.requestTimeout,
+          headers: headers,
+        });
+      }
+
+    protected async generateServiceToken(config: InternalAxiosRequestConfig): Promise<string> {
+      return '';
+    }
+
+    async isAvailable(): Promise<boolean> {
+        return this.healthCheck().then(result => result.healthy);
+    }
+
+    protected setupInterceptors(): void {
+      // Request interceptors
+      this.axiosInstance.interceptors.request.use(
+        this.concurrencyControlInterceptor.bind(this),
+        this.requestErrorHandler.bind(this)
+      );
+
+      this.axiosInstance.interceptors.request.use(
+        this.authenticationInterceptor.bind(this),
+        this.requestErrorHandler.bind(this)
+      );
+
+      // Response interceptors
+      this.axiosInstance.interceptors.response.use(
+        this.responseSuccessInterceptor.bind(this),
+        this.responseErrorInterceptor.bind(this)
+      );
+    }
+
+    private async concurrencyControlInterceptor(
+      config: InternalAxiosRequestConfig
+    ): Promise<InternalAxiosRequestConfig> {
+      this.currentConcurrency++;
+
+      // Add request ID for tracking
+      const executionContext = (config as any).executionContext as ExecutionContext<any> | undefined;
+      const requestId = executionContext?.requestUUID ?? `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+      if (!config.headers) {
+        config.headers = {} as any;
+      }
+      (config.headers as any)[WildoHeaderKeys.REQUEST_UUID] = requestId;
+
+
+      this.logDebug('Platform HTTP request', {
+        requestId,
+        method: config.method,
+        url: config.url,
+        remoteServiceId: this.remoteServiceId,
+      });
+
+
+      return config;
+    }
+
+    private async authenticationInterceptor(
+      config: InternalAxiosRequestConfig
+    ): Promise<InternalAxiosRequestConfig> {
+      try {
+        const executionContext = (config as any).executionContext as ExecutionContext<any> | undefined;
+
+        // Generate service token - subclasses must call lazyInitialize() here
+        const serviceToken = await this.generateServiceToken(config);
+
+        // Token must be generated - if not, configuration is missing
+        if (!serviceToken) {
+          throw this.errorBuilder.buildError(ErrorType.CONFIGURATION,
+                executionContext,
+                {
+                    customMessageReference: ErrorCustomMessageReference.JWT_TOKEN_NOT_FOUND,
+                    context: {
+                      message: `JWT token could not be generated for service ${this.localServiceId || 'unknown'}`,
+                      hint: 'Ensure service configuration is loaded before making requests'
+                    }
+                });
+        }
+
+        if (!config.headers) config.headers = {} as any;
+        (config.headers as any)[WildoHeaderKeys.AUTHORIZATION] = `Bearer ${serviceToken}`;
+
+        return config;
+      } catch (error) {
+        this.logger.error('Authentication interceptor error:', error);
+        throw error;
+      }
+    }
+
+    private requestErrorHandler(error: any): Promise<never> {
+      this.currentConcurrency--;
+      return Promise.reject(error);
+    }
+
+    private responseSuccessInterceptor(response: AxiosResponse): any {
+      this.currentConcurrency--;
+
+      this.logDebug('Platform HTTP response', {
+        requestId: response.config.headers?.[WildoHeaderKeys.REQUEST_UUID] ?? 'unknown' ,
+        status: response.status,
+        remoteServiceId: this.remoteServiceId,
+        method: response.config.method,
+        url: response.config.url,
+      });
+
+      // For stream responses, return the full response object so callers can access headers
+      // For HEAD requests, return the full response object so callers can access headers (no body)
+      // For other responses, return just the data (JSON parsing, etc.)
+      if (response.config.responseType === 'stream' || response.config.method?.toUpperCase() === 'HEAD') {
+        return response;
+      }
+
+      return response.data;
+    }
+
+    private async responseErrorInterceptor(error: any): Promise<any> {
+      this.currentConcurrency--;
+
+      const requestId = error.config?.headers?.[WildoHeaderKeys.REQUEST_UUID] ?? 'unknown';
+      const executionContext = (error.config as any)?.executionContext as ExecutionContext<any> | undefined;
+
+
+      if (error.response) {
+        const { status, data: errorData } = error.response;
+        let errorType = ErrorType.NETWORK;
+
+        // Determine error type based on status code
+        if (status === HttpStatusCode.UNAUTHORIZED) {
+          errorType = ErrorType.AUTHENTICATION;
+        } else if (status === HttpStatusCode.FORBIDDEN) {
+          errorType = ErrorType.AUTHORIZATION;
+        } else if (status === HttpStatusCode.NOT_FOUND) {
+          errorType = ErrorType.NOT_FOUND;
+        } else if (status === HttpStatusCode.CONFLICT) {
+          errorType = ErrorType.CONFLICT;
+        } else if (status === HttpStatusCode.BAD_REQUEST || status === HttpStatusCode.UNPROCESSABLE_ENTITY) {
+          errorType = ErrorType.VALIDATION;
+        } else if (status === HttpStatusCode.TOO_MANY_REQUESTS) {
+          errorType = ErrorType.RATE_LIMIT;
+        } else if (status >= 500) {
+          errorType = ErrorType.EXTERNAL_SERVICE;
+        }
+
+        throw this.errorBuilder.buildError(errorType, executionContext, { customMessageReference: ErrorCustomMessageReference.PLATFORM_HTTP_ERROR, context: { message: `Request failed with status ${status}`, errorData: errorData, requestId: requestId } });
+
+      }
+      // Network error (no response) - connection refused, timeout, DNS failure, etc.
+      const errorMessage = error.message || error.code || 'Unknown network error';
+      const errorStatus = error.status || error.statusCode || 'undefined';
+      throw this.errorBuilder.buildError(ErrorType.NETWORK, executionContext, {
+        customMessageReference: ErrorCustomMessageReference.PLATFORM_HTTP_ERROR,
+        context: {
+          message: `Request failed: ${errorMessage}`,
+          status: errorStatus,
+          code: error.code,
+          requestId: requestId,
+          url: error.config?.url,
+          method: error.config?.method
+        }
+      });
+    }
+
+
+
+    /**
+     * Execute HTTP request with retry logic
+     * Note: Subclasses that use lazy initialization should override this method,
+     * call their initialization first, then call super.request()
+     */
+    protected async request<T = any>(config: BackendHttpClientRequestConfig): Promise<T> {
+      // Wait for remote API to be ready before making requests
+      // This is safe to call after subclass initialization (remoteServiceBaseUrl is set)
+      await this.waitForReady();
+
+      const axiosConfig: AxiosRequestConfig = {
+        url: config.url,
+        method: config.method || 'GET',
+        headers: config.headers,
+        data: config.data,
+        params: config.params,
+        timeout: config.timeout,
+        // Support streaming responses
+        responseType: config.responseType || 'json',
+      };
+      // Minimal: attach executionContext for interceptors consumption
+      if(config.executionContext) {
+        (axiosConfig as any).executionContext = config.executionContext;
+      }
+
+      const maxRetries = config.retries ?? this.requestRetries;
+      let lastError: Error | null = null;
+
+      for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+          const response = await this.axiosInstance.request<T>(axiosConfig);
+          // For streaming responses, the interceptor returns the full AxiosResponse
+          // Extract the stream from response.data
+          if (config.responseType === 'stream') {
+            return (response as any).data as T;
+          }
+          return response as T; // The response interceptor already extracts the data
+        } catch (error) {
+          lastError = error as Error;
+
+          // Don't retry on client errors (4xx) except for specific cases
+          if (error.statusCode &&
+              typeof error.statusCode === 'number' &&
+              error.statusCode >= 400 &&
+              error.statusCode < 500 &&
+              error.statusCode !== HttpStatusCode.TOO_MANY_REQUESTS) {
+            break;
+          }
+
+          // Don't retry on last attempt
+          if (attempt === maxRetries) {
+            break;
+          }
+
+          // Wait before retry with exponential backoff
+          const delay = (config.retryDelay ?? this.requestRetryDelay) * Math.pow(2, attempt);
+          this.logDebug(`Platform HTTP request failed, retrying in ${delay}ms`, {
+            attempt: attempt + 1,
+            maxRetries: maxRetries + 1,
+            error: this.errorBuilder.wildoErrorToSimpleString(error),
+            retryDelay: delay,
+            remoteServiceId: this.remoteServiceId
+          });
+
+          await this.sleep(delay);
+        }
+      }
+
+      throw lastError;
+    }
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    /**
+     * Calculate delay for readiness check retry using exponential backoff
+     * Formula: min(2^attempt * baseDelay, maxDelay)
+     */
+    private calculateReadinessDelay(attempt: number): number {
+        const delay = Math.pow(2, attempt) * READINESS_BASE_DELAY_MS;
+        return Math.min(delay, READINESS_MAX_DELAY_MS);
+    }
+
+    /**
+     * Check readiness once by calling /health/ready endpoint
+     */
+    private async checkReadinessOnce(): Promise<boolean> {
+        try {
+            const response = await axios.get(`${this.remoteServiceBaseUrl}/health/ready`, {
+                timeout: READINESS_REQUEST_TIMEOUT_MS,
+                validateStatus: () => true, // Don't throw on non-2xx
+            });
+
+            return response.status === 200 && response.data?.status === 'healthy';
+        } catch (error) {
+            return false;
+        }
+    }
+
+    /**
+     * Wait until the remote API is ready (blocks until ready)
+     * Uses exponential backoff: 2^attempts * 100ms, capped at 10s
+     * Never stops - keeps retrying until API is ready
+     */
+    protected async waitForReady(): Promise<void> {
+        // If no remoteServiceBaseUrl configured, skip readiness check
+        // This can happen if service initialization hasn't completed yet
+        if (!this.remoteServiceBaseUrl) {
+            this.logger.warn('Remote API readiness check skipped: remoteServiceBaseUrl not configured', {
+                remoteServiceId: this.remoteServiceId,
+            });
+            return;
+        }
+
+        // If already ready, return immediately
+        if (this.isReady) {
+            return;
+        }
+
+        // If already waiting, return the existing promise
+        if (this.readinessPromise) {
+            return this.readinessPromise;
+        }
+
+        // Start the readiness check
+        this.readinessPromise = this.performReadinessCheck();
+        await this.readinessPromise;
+    }
+
+    /**
+     * Perform the actual readiness check with retries
+     */
+    private async performReadinessCheck(): Promise<void> {
+        let attempt = 0;
+
+        this.logDebug('Starting remote API readiness check', {
+            remoteServiceId: this.remoteServiceId,
+            remoteServiceBaseUrl: this.remoteServiceBaseUrl,
+        });
+
+        while (!this.isReady) {
+            const ready = await this.checkReadinessOnce();
+
+            if (ready) {
+                this.isReady = true;
+                this.logDebug('Remote API is ready', {
+                    remoteServiceId: this.remoteServiceId,
+                    remoteServiceBaseUrl: this.remoteServiceBaseUrl,
+                    attempts: attempt + 1,
+                });
+                return;
+            }
+
+            // Not ready - log warning and retry
+            const delay = this.calculateReadinessDelay(attempt);
+            this.logger.warn(`Remote API not ready, retrying in ${delay}ms`, {
+                remoteServiceId: this.remoteServiceId,
+                remoteServiceBaseUrl: this.remoteServiceBaseUrl,
+                attempt: attempt + 1,
+                nextDelayMs: delay,
+            });
+
+            await this.sleep(delay);
+            attempt++;
+        }
+    }
+
+    // Public API methods
+    public async get<T = any>(path: string, config?: Partial<BackendHttpClientRequestConfig>): Promise<T> {
+      return this.request<T>({ ...config, url: `${this.remoteServiceBaseUrl}${path}`, method: 'GET' });
+    }
+
+    public async post<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T> {
+      return this.request<T>({ ...config, url: `${this.remoteServiceBaseUrl}${path}`, method: 'POST', data });
+    }
+
+    public async put<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T> {
+      return this.request<T>({ ...config, url: `${this.remoteServiceBaseUrl}${path}`, method: 'PUT', data });
+    }
+
+    public async patch<T = any>(path: string, data?: any, config?: Partial<BackendHttpClientRequestConfig>): Promise<T> {
+      return this.request<T>({ ...config, url: `${this.remoteServiceBaseUrl}${path}`, method: 'PATCH', data });
+    }
+
+    public async delete<T = any>(path: string, config?: Partial<BackendHttpClientRequestConfig>): Promise<T> {
+      return this.request<T>({ ...config, url: `${this.remoteServiceBaseUrl}${path}`, method: 'DELETE' });
+    }
+
+
+    public async healthCheck(): Promise<{ healthy: boolean; latency: number; error?: string }> {
+      const startTime = Date.now();
+
+      try {
+        await this.get(`/health`, {
+          timeout: 5000,
+          retries: 0
+        });
+
+        const latency = Date.now() - startTime;
+
+        return {
+          healthy: true,
+          latency
+        };
+      } catch (error) {
+        const latency = Date.now() - startTime;
+
+        return {
+          healthy: false,
+          latency,
+          error: this.errorBuilder.wildoErrorToSimpleString(error)
+        };
+      }
+    }
+
+    public getConcurrentRequestCount(): number {
+      return this.currentConcurrency;
+    }
+
+
+}

package/src/requests/service/serverless-services-handler.backend.service.ts

@@ -0,0 +1,19 @@
+import { injectable, inject } from 'inversify';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+
+@injectable()
+export class ServerlessServicesHandlerBackendService {
+  private readonly logDebug: (message: string, context?: Record<string, unknown>) => void;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private readonly errorBuilder: ErrorBuilderBackendService,
+  ) {
+    this.logDebug = this.logger.debugByType('ServerlessServicesHandler');
+    this.logger.setDebugTypeLogging('ServerlessServicesHandler', false);
+  }
+}
+
+