@hiliosai/sdk 0.1.0

package/src/middlewares/cache.middleware.ts

@@ -0,0 +1,278 @@
+import KeyvRedis from '@keyv/redis';
+import Keyv from 'keyv';
+import {REDIS_URL} from '../env';
+import type {AppContext} from '../types';
+
+export interface CacheOptions {
+  redisUrl?: string;
+  ttl?: number; // Default TTL in milliseconds
+  namespace?: string;
+  serialize?: (value: unknown) => string;
+  deserialize?: (value: string) => unknown;
+}
+
+export interface CacheHelpers {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  set<T = unknown>(key: string, value: T, ttl?: number): Promise<boolean>;
+  delete(key: string): Promise<boolean>;
+  clear(): Promise<void>;
+  has(key: string): Promise<boolean>;
+  mget<T = unknown>(...keys: string[]): Promise<Array<T | undefined>>;
+  mset(entries: Record<string, unknown>, ttl?: number): Promise<boolean>;
+  mdel(...keys: string[]): Promise<boolean>;
+  wrap<T = unknown>(
+    key: string,
+    factory: () => Promise<T> | T,
+    ttl?: number
+  ): Promise<T>;
+}
+
+export class CacheService {
+  private keyv: Keyv;
+  private defaultTtl: number;
+
+  constructor(options: CacheOptions = {}) {
+    const {
+      redisUrl = REDIS_URL,
+      ttl = 5 * 60 * 1000, // 5 minutes default
+      namespace = 'cache',
+    } = options;
+
+    this.defaultTtl = ttl;
+
+    // Configure store based on Redis availability
+    const store = redisUrl ? new KeyvRedis(redisUrl) : new Map(); // In-memory fallback
+
+    this.keyv = new Keyv({
+      store,
+      namespace,
+      ttl,
+    });
+
+    // Error handling
+    this.keyv.on('error', () => {
+      // Silently handle errors - could be logged to a logger if available
+    });
+  }
+
+  /**
+   * Get a value from cache
+   */
+  async get<T = unknown>(key: string): Promise<T | undefined> {
+    try {
+      return await this.keyv.get<T>(key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Set a value in cache
+   */
+  async set<T = unknown>(
+    key: string,
+    value: T,
+    ttl?: number
+  ): Promise<boolean> {
+    try {
+      return await this.keyv.set(key, value, ttl);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Delete a key from cache
+   */
+  async delete(key: string): Promise<boolean> {
+    try {
+      return await this.keyv.delete(key);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Clear all keys with the namespace
+   */
+  async clear(): Promise<void> {
+    try {
+      await this.keyv.clear();
+    } catch {
+      // Silently handle errors
+    }
+  }
+
+  /**
+   * Check if a key exists
+   */
+  async has(key: string): Promise<boolean> {
+    try {
+      return await this.keyv.has(key);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get multiple values at once
+   */
+  async mget<T = unknown>(...keys: string[]): Promise<Array<T | undefined>> {
+    try {
+      const promises = keys.map((key) => this.get<T>(key));
+      return await Promise.all(promises);
+    } catch {
+      return keys.map(() => undefined);
+    }
+  }
+
+  /**
+   * Set multiple values at once
+   */
+  async mset(entries: Record<string, unknown>, ttl?: number): Promise<boolean> {
+    try {
+      const promises = Object.entries(entries).map(([key, value]) =>
+        this.set(key, value, ttl)
+      );
+      const results = await Promise.all(promises);
+      return results.every(Boolean);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Delete multiple keys at once
+   */
+  async mdel(...keys: string[]): Promise<boolean> {
+    try {
+      const promises = keys.map((key) => this.delete(key));
+      const results = await Promise.all(promises);
+      return results.every(Boolean);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Wrap pattern: Get from cache or calculate and cache
+   */
+  async wrap<T = unknown>(
+    key: string,
+    factory: () => Promise<T> | T,
+    ttl?: number
+  ): Promise<T> {
+    try {
+      // Try to get from cache
+      const cached = await this.get<T>(key);
+      if (cached !== undefined) {
+        return cached;
+      }
+
+      // Calculate value
+      const value = await factory();
+
+      // Cache the value
+      await this.set(key, value, ttl ?? this.defaultTtl);
+
+      return value;
+    } catch {
+      // In case of error, still try to return the factory value
+      return await factory();
+    }
+  }
+
+  /**
+   * Disconnect the cache (for cleanup)
+   */
+  async disconnect(): Promise<void> {
+    try {
+      await this.keyv.disconnect();
+    } catch {
+      // Silently handle errors
+    }
+  }
+}
+
+/**
+ * Create cache middleware with specific options for a service
+ */
+export function createCacheMiddleware(options: CacheOptions = {}) {
+  let cacheInstance: CacheService | null = null;
+
+  return {
+    /**
+     * Initialize cache on service start
+     */
+    started() {
+      cacheInstance = new CacheService(options);
+    },
+
+    /**
+     * Add cache helpers to context
+     */
+    localAction(handler: (...args: unknown[]) => unknown) {
+      return function CacheMiddlewareWrapper(this: unknown, ctx: AppContext) {
+        cacheInstance ??= new CacheService(options);
+
+        const instance = cacheInstance;
+
+        // Create scoped cache helpers
+        const cache: CacheHelpers = {
+          get: <T = unknown>(key: string) => instance.get<T>(key),
+
+          set: <T = unknown>(key: string, value: T, ttl?: number) =>
+            instance.set(key, value, ttl),
+
+          delete: (key: string) => instance.delete(key),
+
+          clear: () => instance.clear(),
+
+          has: (key: string) => instance.has(key),
+
+          mget: <T = unknown>(...keys: string[]) => instance.mget<T>(...keys),
+
+          mset: (entries: Record<string, unknown>, ttl?: number) =>
+            instance.mset(entries, ttl),
+
+          mdel: (...keys: string[]) => instance.mdel(...keys),
+
+          wrap: <T = unknown>(
+            key: string,
+            factory: () => Promise<T> | T,
+            ttl?: number
+          ) => instance.wrap<T>(key, factory, ttl),
+        };
+
+        // Add cache to context
+        ctx.cache = cache;
+
+        // Call the original handler
+        return handler.call(this, ctx);
+      };
+    },
+
+    /**
+     * Cleanup on service stop
+     */
+    stopped() {
+      if (cacheInstance) {
+        return cacheInstance.disconnect();
+      }
+    },
+  };
+}
+
+// Default cache middleware (backwards compatibility)
+export const CacheMiddleware = createCacheMiddleware();
+
+// Singleton instance for direct usage
+let globalCacheInstance: CacheService | null = null;
+
+export const getCacheInstance = (options?: CacheOptions) => {
+  if (options) {
+    return new CacheService(options);
+  }
+  globalCacheInstance ??= new CacheService();
+  return globalCacheInstance;
+};

package/src/middlewares/context-helpers.middleware.ts

@@ -0,0 +1,159 @@
+import type {AppContext, Tenant, User, UserRole} from '../types';
+import {AuthenticationError, TenantError} from '../errors';
+import {ContextCache} from '../utils/context-cache';
+import {PermissionCalculator} from '../utils/permission-calculator';
+
+export const ContextHelpersMiddleware = {
+  // Add helper functions to context before action handlers
+  localAction(handler: (...args: unknown[]) => unknown) {
+    return function ContextHelpersWrapper(this: unknown, ctx: AppContext) {
+      const cache = ContextCache.getInstance();
+
+      // Memoized permission checking with caching
+      const memoizedPermissions = new Map<string, boolean>();
+
+      ctx.hasPermission = function (permission: string): boolean {
+        // Check in-request memoization first
+        if (memoizedPermissions.has(permission)) {
+          const cachedResult = memoizedPermissions.get(permission);
+          return cachedResult === true;
+        }
+
+        const user = ctx.meta.user;
+        if (!user) {
+          memoizedPermissions.set(permission, false);
+          return false;
+        }
+
+        // Use optimized permission calculator
+        const result = PermissionCalculator.hasPermission(user, permission);
+        memoizedPermissions.set(permission, result);
+        return result;
+      };
+
+      // Cached user permissions getter
+      ctx.getUserPermissions = async function (): Promise<string[]> {
+        const user = ctx.meta.user;
+        if (!user) return [];
+
+        const cacheKey = `permissions:${user.id}:${JSON.stringify(user.roles)}`;
+        return cache.get(cacheKey, () => {
+          return PermissionCalculator.calculateUserPermissions(user);
+        });
+      };
+
+      ctx.hasRole = function (role: keyof typeof UserRole): boolean {
+        const user = ctx.ensureUser();
+        return Array.isArray(user.roles) && user.roles.includes(role);
+      };
+
+      ctx.isTenantMember = function (): boolean {
+        const user = ctx.ensureUser();
+        return !!(
+          user.tenantId &&
+          ctx.meta.tenantId &&
+          user.tenantId === ctx.meta.tenantId
+        );
+      };
+
+      ctx.isTenantOwner = function (): boolean {
+        return ctx.isTenantMember() && ctx.hasRole('OWNER');
+      };
+
+      ctx.ensureUser = (): User => {
+        if (!ctx.meta.user) {
+          ctx.broker.logger.error('Authentication required', {
+            action: ctx.action?.name,
+            requestId: ctx.meta.requestId,
+            userAgent: ctx.meta.userAgent,
+            ip: ctx.meta.clientIP,
+          });
+
+          throw new AuthenticationError('Authentication required', {
+            code: 'AUTH_REQUIRED',
+            statusCode: 401,
+            requestId: ctx.meta.requestId,
+          });
+        }
+        return ctx.meta.user;
+      };
+
+      ctx.ensureTenant = (): Tenant => {
+        if (!ctx.meta.tenantId) {
+          ctx.broker.logger.error('Tenant required', {
+            action: ctx.action?.name,
+            userId: ctx.meta.user?.id,
+            requestId: ctx.meta.requestId,
+          });
+
+          throw new TenantError('Tenant required', {
+            code: 'TENANT_REQUIRED',
+            statusCode: 401,
+            tenantId: ctx.meta.tenantId,
+            requestId: ctx.meta.requestId,
+          });
+        }
+
+        // Return a proper Tenant object with the ID
+        return {
+          id: ctx.meta.tenantId,
+          name: ctx.meta.tenantName ?? '',
+        } as Tenant;
+      };
+
+      // Enhanced audit logging function
+      ctx.auditLog = function (
+        action: string,
+        resource?: unknown,
+        metadata?: Record<string, unknown>
+      ): void {
+        ctx.broker.logger.info('Audit log', {
+          action,
+          resource: resource
+            ? {type: typeof resource, id: (resource as Record<string, unknown>).id}
+            : undefined,
+          userId: ctx.meta.user?.id,
+          tenantId: ctx.meta.tenantId,
+          requestId: ctx.meta.requestId,
+          timestamp: new Date().toISOString(),
+          ...metadata,
+        });
+      };
+
+      // Enhanced error creation with context
+      ctx.createError = function (
+        message: string,
+        code: string,
+        statusCode = 400
+      ): Error {
+        const errorData = {
+          code,
+          statusCode,
+          userId: ctx.meta.user?.id,
+          tenantId: ctx.meta.tenantId,
+          requestId: ctx.meta.requestId,
+          action: ctx.action?.name,
+          timestamp: new Date().toISOString(),
+        };
+
+        ctx.broker.logger.warn('Context error created', {
+          message,
+          ...errorData,
+        });
+
+        if (code === 'AUTH_REQUIRED') {
+          return new AuthenticationError(message, errorData);
+        }
+
+        if (code === 'TENANT_REQUIRED') {
+          return new TenantError(message, errorData);
+        }
+
+        return new Error(message);
+      };
+
+      // Call the original handler
+      return handler.call(this, ctx);
+    };
+  },
+};

package/src/middlewares/datasource.middleware.ts

@@ -0,0 +1,71 @@
+import type {Context} from 'moleculer';
+
+/**
+ * Datasource constructor registry type
+ */
+export interface DatasourceConstructorRegistry {
+  [key: string]: new () => object;
+}
+
+/**
+ * Datasource instance registry type
+ */
+export interface DatasourceInstanceRegistry {
+  [key: string]: object;
+}
+
+/**
+ * Datasource context extension
+ */
+export interface DatasourceContext extends Context {
+  datasources: DatasourceInstanceRegistry;
+}
+
+/**
+ * Initialize all datasources
+ */
+function initializeDatasources(
+  constructorRegistry: DatasourceConstructorRegistry
+): DatasourceInstanceRegistry {
+  const initializedDatasources: DatasourceInstanceRegistry = {};
+
+  for (const [key, DatasourceClass] of Object.entries(constructorRegistry)) {
+    initializedDatasources[key] = new DatasourceClass();
+  }
+
+  return initializedDatasources;
+}
+
+/**
+ * Datasource middleware that injects datasources into the context
+ */
+export function createDatasourceMiddleware(
+  datasources: DatasourceConstructorRegistry
+) {
+  const initializedDatasources = initializeDatasources(datasources);
+
+  return {
+    localAction(handler: (...args: unknown[]) => unknown) {
+      return function DatasourceWrapper(this: unknown, ctx: Context) {
+        // Inject datasources into context
+        (ctx as DatasourceContext).datasources = initializedDatasources;
+        return handler.call(this, ctx);
+      };
+    },
+
+    remoteAction(handler: (...args: unknown[]) => unknown) {
+      return function DatasourceWrapper(this: unknown, ctx: Context) {
+        // Inject datasources into context for remote actions too
+        (ctx as DatasourceContext).datasources = initializedDatasources;
+        return handler.call(this, ctx);
+      };
+    },
+  };
+}
+
+/**
+ * Type helper for services that use datasources
+ */
+export type ServiceWithDatasources<T extends DatasourceInstanceRegistry> = {
+  datasources: T;
+};

package/src/middlewares/health.middleware.ts

@@ -0,0 +1,134 @@
+import env from '@ltv/env';
+import http from 'http';
+import type {Service} from 'moleculer';
+
+const HEALTH_CHECK_PORT = env.int('HEALTH_CHECK_PORT', 3301);
+const HEALTH_CHECK_READINESS_PATH = env.string(
+  'HEALTH_CHECK_READINESS_PATH',
+  '/readyz'
+);
+const HEALTH_CHECK_LIVENESS_PATH = env.string(
+  'HEALTH_CHECK_LIVENESS_PATH',
+  '/livez'
+);
+
+interface HealthCheckOptions {
+  port?: number;
+  readiness?: {
+    path?: string;
+  };
+  liveness?: {
+    path?: string;
+  };
+}
+
+interface HealthCheckConfig {
+  port: number;
+  readiness: {
+    path: string;
+  };
+  liveness: {
+    path: string;
+  };
+}
+
+// Default configuration constants
+export const HEALTH_CHECK_DEFAULTS = {
+  PORT: HEALTH_CHECK_PORT,
+  READINESS_PATH: HEALTH_CHECK_READINESS_PATH,
+  LIVENESS_PATH: HEALTH_CHECK_LIVENESS_PATH,
+} as const;
+
+export function CreateHealthCheckMiddleware(opts: HealthCheckOptions = {}) {
+  // Merge user options with defaults
+  const config: HealthCheckConfig = {
+    port: opts.port ?? HEALTH_CHECK_DEFAULTS.PORT,
+    readiness: {
+      path: opts.readiness?.path ?? HEALTH_CHECK_DEFAULTS.READINESS_PATH,
+    },
+    liveness: {
+      path: opts.liveness?.path ?? HEALTH_CHECK_DEFAULTS.LIVENESS_PATH,
+    },
+  };
+
+  type HealthState = 'down' | 'starting' | 'up' | 'stopping';
+
+  let state: HealthState = 'down';
+  let server: http.Server;
+
+  function handler(req: http.IncomingMessage, res: http.ServerResponse) {
+    // Prevent headers from being sent multiple times
+    if (res.headersSent) {
+      return;
+    }
+
+    if (req.url === config.readiness.path || req.url === config.liveness.path) {
+      const resHeader = {
+        'Content-Type': 'application/json; charset=utf-8',
+      };
+
+      const content = {
+        state,
+        uptime: process.uptime(),
+        timestamp: Date.now(),
+      };
+
+      if (req.url === config.readiness.path) {
+        // Readiness if the broker started successfully.
+        // https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-readiness-probes
+        res.writeHead(state === 'up' ? 200 : 503, resHeader);
+      } else {
+        // Liveness if the broker is not stopped.
+        // https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/#define-a-liveness-command
+        res.writeHead(state !== 'down' ? 200 : 503, resHeader);
+      }
+
+      res.end(JSON.stringify(content, null, 2));
+    } else {
+      res.writeHead(404, http.STATUS_CODES[404] ?? 'Not Found', {});
+      res.end();
+    }
+  }
+
+  return {
+    created(broker: Service) {
+      state = 'starting';
+
+      server = http.createServer(handler);
+      server.listen(config.port, (err?: Error | undefined) => {
+        if (err) {
+          return broker.logger.error(
+            'Unable to start health-check server',
+            err
+          );
+        }
+
+        broker.logger.info('');
+        broker.logger.info('K8s health-check server listening on');
+        broker.logger.info(
+          `    http://localhost:${config.port}${config.readiness.path}`
+        );
+        broker.logger.info(
+          `    http://localhost:${config.port}${config.liveness.path}`
+        );
+        broker.logger.info('');
+      });
+    },
+
+    // After broker started
+    started() {
+      state = 'up';
+    },
+
+    // Before broker stopping
+    stopping() {
+      state = 'stopping';
+    },
+
+    // After broker stopped
+    stopped() {
+      state = 'down';
+      server.close();
+    },
+  };
+}

package/src/middlewares/index.ts

@@ -0,0 +1,6 @@
+export * from './datasource.middleware';
+export * from './memoize.middleware';
+export * from './health.middleware';
+export * from './permissions.middleware';
+export * from './context-helpers.middleware';
+export * from './cache.middleware';

package/src/middlewares/memoize.middleware.ts

@@ -0,0 +1,33 @@
+import type {ServiceSchema, ServiceSettingSchema} from 'moleculer';
+
+export interface MemoizeMixinOptions {
+  ttl?: number;
+}
+
+export function MemoizeMixin(
+  options?: MemoizeMixinOptions
+): ServiceSchema<ServiceSettingSchema> {
+  return {
+    name: '',
+    methods: {
+      async memoize(name: string, params: unknown, fn: () => Promise<unknown>) {
+        if (!this.broker.cacher) return fn();
+
+        const key = this.broker.cacher.defaultKeygen(
+          `${this.name}:memoize-${name}`,
+          params as object | null,
+          {},
+          []
+        );
+
+        let res = await this.broker.cacher.get(key);
+        if (res) return res;
+
+        res = (await fn()) as unknown as object;
+        this.broker.cacher.set(key, res, options?.ttl);
+
+        return res;
+      },
+    },
+  };
+}