@zintrust/core 0.1.0 → 0.1.2

package/src/templates/project/basic/config/broadcast.ts.tpl

@@ -0,0 +1,97 @@
+/**
+ * Broadcast Configuration
+ *
+ * Centralizes broadcast driver selection and provider env mappings.
+ * Driver selection must be dynamic (tests may mutate process.env).
+ */
+
+import { Env } from '@config/env';
+
+export type KnownBroadcastDriverName = 'inmemory' | 'pusher' | 'redis' | 'redishttps';
+
+export type InMemoryBroadcastDriverConfig = {
+  driver: 'inmemory';
+};
+
+export type PusherBroadcastDriverConfig = {
+  driver: 'pusher';
+  appId: string;
+  key: string;
+  secret: string;
+  cluster: string;
+  useTLS: boolean;
+};
+
+export type RedisBroadcastDriverConfig = {
+  driver: 'redis';
+  host: string;
+  port: number;
+  password: string;
+  channelPrefix: string;
+};
+
+export type RedisHttpsBroadcastDriverConfig = {
+  driver: 'redishttps';
+  endpoint: string;
+  token: string;
+  channelPrefix: string;
+};
+
+export type KnownBroadcastDriverConfig =
+  | InMemoryBroadcastDriverConfig
+  | PusherBroadcastDriverConfig
+  | RedisBroadcastDriverConfig
+  | RedisHttpsBroadcastDriverConfig;
+
+const normalizeDriverName = (value: string): string => value.trim().toLowerCase();
+
+const getPusherConfig = (): PusherBroadcastDriverConfig => ({
+  driver: 'pusher',
+  appId: Env.get('PUSHER_APP_ID', ''),
+  key: Env.get('PUSHER_APP_KEY', ''),
+  secret: Env.get('PUSHER_APP_SECRET', ''),
+  cluster: Env.get('PUSHER_APP_CLUSTER', ''),
+  useTLS: Env.getBool('PUSHER_USE_TLS', true),
+});
+
+const getRedisConfig = (): RedisBroadcastDriverConfig => ({
+  driver: 'redis',
+  host: Env.get('BROADCAST_REDIS_HOST', Env.get('REDIS_HOST', 'localhost')),
+  port: Env.getInt('BROADCAST_REDIS_PORT', Env.getInt('REDIS_PORT', 6379)),
+  password: Env.get('BROADCAST_REDIS_PASSWORD', Env.get('REDIS_PASSWORD', '')),
+  channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
+});
+
+const getRedisHttpsConfig = (): RedisHttpsBroadcastDriverConfig => ({
+  driver: 'redishttps',
+  endpoint: Env.get('REDIS_HTTPS_ENDPOINT', ''),
+  token: Env.get('REDIS_HTTPS_TOKEN', ''),
+  channelPrefix: Env.get('BROADCAST_CHANNEL_PREFIX', 'broadcast:'),
+});
+
+const broadcastConfigObj = {
+  /**
+   * Normalized broadcast driver name.
+   *
+   * NOTE: Allows custom driver names (project-specific drivers), so returns string.
+   */
+  getDriverName(): string {
+    return normalizeDriverName(Env.get('BROADCAST_DRIVER', 'inmemory'));
+  },
+
+  /**
+   * Get a config object for the currently selected driver.
+   * Defaults to inmemory for unknown/unsupported names.
+   */
+  getDriverConfig(): KnownBroadcastDriverConfig {
+    const driver = this.getDriverName();
+
+    if (driver === 'pusher') return getPusherConfig();
+    if (driver === 'redis') return getRedisConfig();
+    if (driver === 'redishttps') return getRedisHttpsConfig();
+
+    return { driver: 'inmemory' };
+  },
+} as const;
+
+export default Object.freeze(broadcastConfigObj);

package/src/templates/project/basic/config/cache.ts.tpl

@@ -15,34 +15,32 @@ type RedisCacheDriverConfig = {
   driver: 'redis';
   host: string;
   port: number;
-  password: string | undefined;
-  database: number;
   ttl: number;
 };
 
-type MemcachedCacheDriverConfig = {
-  driver: 'memcached';
-  servers: string[];
+type MongoCacheDriverConfig = {
+  driver: 'mongodb';
+  uri: string;
+  db: string;
   ttl: number;
 };
 
-type FileCacheDriverConfig = {
-  driver: 'file';
-  path: string;
+type KvCacheDriverConfig = {
+  driver: 'kv';
   ttl: number;
 };
 
 type CacheDriverConfig =
   | MemoryCacheDriverConfig
   | RedisCacheDriverConfig
-  | MemcachedCacheDriverConfig
-  | FileCacheDriverConfig;
+  | MongoCacheDriverConfig
+  | KvCacheDriverConfig;
 
 type CacheDrivers = {
   memory: MemoryCacheDriverConfig;
   redis: RedisCacheDriverConfig;
-  memcached: MemcachedCacheDriverConfig;
-  file: FileCacheDriverConfig;
+  mongodb: MongoCacheDriverConfig;
+  kv: KvCacheDriverConfig;
 };
 
 type CacheConfigInput = {
@@ -53,7 +51,7 @@ type CacheConfigInput = {
 const getCacheDriver = (config: CacheConfigInput): CacheDriverConfig => {
   const defaultDriver = config.default;
 
-  if (Object.prototype.hasOwnProperty.call(config.drivers, defaultDriver)) {
+  if (Object.hasOwn(config.drivers, defaultDriver)) {
     const driverName = defaultDriver as keyof CacheDrivers;
     return config.drivers[driverName];
   }
@@ -79,19 +77,17 @@ const cacheConfigObj = {
       driver: 'redis' as const,
       host: Env.get('REDIS_HOST', 'localhost'),
       port: Env.getInt('REDIS_PORT', 6379),
-      password: Env.get('REDIS_PASSWORD'),
-      database: Env.getInt('REDIS_DB', 0),
       ttl: Env.getInt('CACHE_REDIS_TTL', 3600),
     },
-    memcached: {
-      driver: 'memcached' as const,
-      servers: Env.get('MEMCACHED_SERVERS', 'localhost:11211').split(','),
-      ttl: Env.getInt('CACHE_MEMCACHED_TTL', 3600),
+    mongodb: {
+      driver: 'mongodb' as const,
+      uri: Env.get('MONGO_URI'),
+      db: Env.get('MONGO_DB', 'zintrust_cache'),
+      ttl: Env.getInt('CACHE_MONGO_TTL', 3600),
     },
-    file: {
-      driver: 'file' as const,
-      path: Env.get('CACHE_FILE_PATH', 'storage/cache'),
-      ttl: Env.getInt('CACHE_FILE_TTL', 3600),
+    kv: {
+      driver: 'kv' as const,
+      ttl: Env.getInt('CACHE_KV_TTL', 3600),
     },
   },
 

package/src/templates/project/basic/config/cloudflare.ts.tpl

@@ -0,0 +1,57 @@
+/**
+ * Cloudflare Workers Environment Access
+ *
+ * Centralizes access to Workers bindings via globalThis.env.
+ * This keeps runtime-specific globals out of adapters/drivers.
+ */
+
+import type { DatabaseConfig, ID1Database } from '@orm/DatabaseAdapter';
+
+export type WorkersEnv = Record<string, unknown>;
+
+type KVNamespace = {
+  get(
+    key: string,
+    options?: { type: 'text' | 'json' | 'arrayBuffer' | 'stream' }
+  ): Promise<unknown>;
+  put(
+    key: string,
+    value: string | ReadableStream | ArrayBuffer | FormData,
+    options?: { expiration?: number; expirationTtl?: number; metadata?: unknown }
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+};
+
+const getWorkersEnv = (): WorkersEnv | null => {
+  const env = (globalThis as unknown as { env?: unknown }).env;
+  if (env === undefined || env === null) return null;
+  if (typeof env !== 'object') return null;
+  return env as WorkersEnv;
+};
+
+const getD1Binding = (config: DatabaseConfig): ID1Database | null => {
+  if (config.d1 !== undefined && config.d1 !== null) return config.d1;
+
+  const env = getWorkersEnv();
+  const envDb = env === null ? undefined : (env['DB'] as ID1Database | undefined);
+  if (envDb !== undefined) return envDb;
+
+  const globalDb = (globalThis as unknown as { DB?: ID1Database }).DB;
+  if (globalDb !== undefined) return globalDb;
+
+  return null;
+};
+
+const getKVBinding = (bindingName = 'CACHE'): KVNamespace | null => {
+  const env = getWorkersEnv();
+  if (env === null) return null;
+
+  const kv = env[bindingName] as KVNamespace | undefined;
+  return kv ?? null;
+};
+
+export const Cloudflare = Object.freeze({
+  getWorkersEnv,
+  getD1Binding,
+  getKVBinding,
+});

package/src/templates/project/basic/config/env.ts.tpl

@@ -71,7 +71,7 @@ export const Env = Object.freeze({
   DB_CONNECTION: get('DB_CONNECTION', 'sqlite'),
   DB_HOST: get('DB_HOST', 'localhost'),
   DB_PORT: getInt('DB_PORT', 5432),
-  DB_DATABASE: get('DB_DATABASE', '@zintrust/core'),
+  DB_DATABASE: get('DB_DATABASE', 'zintrust'),
   DB_USERNAME: get('DB_USERNAME', 'postgres'),
   DB_PASSWORD: get('DB_PASSWORD', ''),
   DB_READ_HOSTS: get('DB_READ_HOSTS', ''),
@@ -114,10 +114,16 @@ export const Env = Object.freeze({
   ENVIRONMENT: get('ENVIRONMENT', 'development'),
   REQUEST_TIMEOUT: getInt('REQUEST_TIMEOUT', 30000),
   MAX_BODY_SIZE: getInt('MAX_BODY_SIZE', 10485760),
+  SHUTDOWN_TIMEOUT: getInt('SHUTDOWN_TIMEOUT', 10000),
 
   // Logging
   LOG_LEVEL: get('LOG_LEVEL', getDefaultLogLevel()) as 'debug' | 'info' | 'warn' | 'error',
+  LOG_FORMAT: get('LOG_FORMAT', 'text'),
   DISABLE_LOGGING: getBool('DISABLE_LOGGING', false),
+  LOG_HTTP_REQUEST: getBool('LOG_HTTP_REQUEST', false),
+  LOG_TO_FILE: getBool('LOG_TO_FILE', false),
+  LOG_ROTATION_SIZE: getInt('LOG_ROTATION_SIZE', 10485760),
+  LOG_ROTATION_DAYS: getInt('LOG_ROTATION_DAYS', 7),
 
   // Paths (safely constructed for Node.js environments)
   NODE_BIN_DIR: (() => {

package/src/templates/project/basic/config/index.ts.tpl

@@ -7,6 +7,7 @@ import { appConfig } from '@config/app';
 import { cacheConfig } from '@config/cache';
 import { databaseConfig } from '@config/database';
 import { microservicesConfig } from '@config/microservices';
+import { middlewareConfig } from '@config/middleware';
 import { queueConfig } from '@config/queue';
 import { securityConfig } from '@config/security';
 import { storageConfig } from '@config/storage';
@@ -15,6 +16,7 @@ export { appConfig, type AppConfig } from '@config/app';
 export { cacheConfig, type CacheConfig } from '@config/cache';
 export { databaseConfig, type DatabaseConfig } from '@config/database';
 export { microservicesConfig, type MicroservicesConfig } from '@config/microservices';
+export { middlewareConfig, type MiddlewareConfig } from '@config/middleware';
 export { queueConfig, type QueueConfig } from '@config/queue';
 export { securityConfig } from '@config/security';
 export { storageConfig, type StorageConfig } from '@config/storage';
@@ -28,6 +30,7 @@ export const config = Object.freeze({
   database: databaseConfig,
   storage: storageConfig,
   security: securityConfig,
+  middleware: middlewareConfig,
   microservices: microservicesConfig,
   cache: cacheConfig,
   queue: queueConfig,

package/src/templates/project/basic/config/logger.ts.tpl

@@ -3,6 +3,7 @@
  * Sealed namespace pattern - all exports through Logger namespace
  * Replaces console.* calls throughout the codebase
  */
+import { appConfig } from '@config/app';
 import { Env } from '@config/env';
 
 interface ILogger {
@@ -13,8 +14,146 @@ interface ILogger {
   fatal(message: string, error?: unknown, category?: string): void;
 }
 
-const isDevelopment = Env.NODE_ENV === 'development' || Env.NODE_ENV === undefined;
-const isProduction = Env.NODE_ENV === 'production';
+const isDevelopment = (): boolean => appConfig.isDevelopment();
+const isProduction = (): boolean => appConfig.isProduction();
+
+const getLogFormat = (): string => Env.get('LOG_FORMAT', 'text');
+const isJsonFormat = (value: unknown): value is 'json' => value === 'json';
+
+const SENSITIVE_FIELDS = new Set<string>([
+  'password',
+  'token',
+  'authorization',
+  'secret',
+  'apikey',
+  'api_key',
+  'jwt',
+  'bearer',
+]);
+
+const redactSensitiveData = (data: unknown): unknown => {
+  const seen = new WeakSet<object>();
+
+  const walk = (value: unknown): unknown => {
+    if (Array.isArray(value)) {
+      if (seen.has(value)) return '[Circular]';
+      seen.add(value);
+      return value.map((v) => walk(v));
+    }
+
+    if (typeof value === 'object' && value !== null) {
+      const asObj = value as Record<string, unknown>;
+      if (seen.has(asObj)) return '[Circular]';
+      seen.add(asObj);
+
+      const out: Record<string, unknown> = {};
+      for (const [key, inner] of Object.entries(asObj)) {
+        if (SENSITIVE_FIELDS.has(key.toLowerCase())) {
+          out[key] = '[REDACTED]';
+        } else {
+          out[key] = walk(inner);
+        }
+      }
+      return out;
+    }
+
+    return value;
+  };
+
+  return walk(data);
+};
+
+const safeStringify = (obj: unknown, indent: boolean = false): string => {
+  const seen = new WeakSet<object>();
+  return JSON.stringify(
+    obj,
+    (_key: string, value: unknown) => {
+      if (typeof value === 'object' && value !== null) {
+        const asObj = value;
+        if (seen.has(asObj)) return '[Circular]';
+        seen.add(asObj);
+      }
+      return value;
+    },
+    indent ? 2 : 0
+  );
+};
+
+type FileWriterModule = { FileLogWriter: { write: (line: string) => void } };
+
+let fileWriterPromise: Promise<FileWriterModule> | undefined;
+let fileWriter: FileWriterModule['FileLogWriter'] | undefined;
+
+const getFileWriter = (): void => {
+  if (fileWriter !== undefined) return;
+  if (fileWriterPromise !== undefined) return;
+  fileWriterPromise = import('@config/FileLogWriter')
+    .then((mod) => {
+      fileWriter = mod.FileLogWriter;
+      return mod;
+    })
+    .catch(() => {
+      fileWriterPromise = undefined;
+      return { FileLogWriter: { write: (_line: string) => undefined } };
+    });
+};
+
+const shouldLogToFile = (): boolean => {
+  // Prefer dynamic lookup so late-bound env (tests, some runtimes) is respected.
+  if (!Env.getBool('LOG_TO_FILE', false)) return false;
+  if (typeof process === 'undefined') return false;
+  return true;
+};
+
+const buildFileLine = (params: {
+  formatted: string;
+  data?: unknown;
+  errorMessage?: string;
+}): string => {
+  if (isJsonFormat(getLogFormat())) return params.formatted;
+
+  let line = params.formatted;
+  if (typeof params.errorMessage === 'string' && params.errorMessage.length > 0) {
+    line = `${line} ${params.errorMessage}`;
+  } else if (params.data !== undefined && params.data !== '') {
+    line = `${line} ${safeStringify(redactSensitiveData(params.data))}`;
+  }
+  return line;
+};
+
+const writeToFile = (line: string): void => {
+  if (!shouldLogToFile()) return;
+
+  if (fileWriter !== undefined) {
+    fileWriter.write(line);
+    return;
+  }
+
+  getFileWriter();
+  fileWriterPromise?.then((mod) => mod.FileLogWriter.write(line));
+};
+
+const formatLogMessage = (params: {
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  data?: unknown;
+  category?: string;
+  errorMessage?: string;
+}): string => {
+  if (isJsonFormat(getLogFormat())) {
+    return safeStringify({
+      timestamp: new Date().toISOString(),
+      level: params.level,
+      message: params.message,
+      category: params.category,
+      data: redactSensitiveData(params.data),
+      error: params.errorMessage,
+    });
+  }
+
+  // text format
+  return `[${params.level.toUpperCase()}] ${params.message}`;
+};
 
 /**
  * Helper to extract error message from unknown error type
@@ -26,38 +165,174 @@ const getErrorMessage = (error?: unknown): string => {
   if (error instanceof Error) {
     return error.message;
   }
-  return String(error);
+
+  if (typeof error === 'string') return error;
+  if (typeof error === 'number' || typeof error === 'bigint') return error.toString();
+  if (typeof error === 'boolean') return error ? 'true' : 'false';
+  if (typeof error === 'symbol') return error.toString();
+  if (typeof error === 'function') return '[Function]';
+
+  try {
+    return safeStringify(error);
+  } catch {
+    return '[Unserializable error]';
+  }
+};
+
+type CloudLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+const emitCloudLogs = (event: CloudLogEvent): void => {
+  // Lazy-load to avoid cycles and avoid cost when disabled.
+  void (async (): Promise<void> => {
+    try {
+      if (event.level === 'error' || event.level === 'fatal') {
+        const mod = await import('@config/logging/KvLogger');
+        void mod.KvLogger.enqueue(event);
+      }
+    } catch {
+      // best-effort
+    }
+
+    try {
+      if (event.level === 'warn' || event.level === 'error' || event.level === 'fatal') {
+        const mod = await import('@config/logging/SlackLogger');
+        void mod.SlackLogger.enqueue(event);
+      }
+    } catch {
+      // best-effort
+    }
+
+    try {
+      const mod = await import('@config/logging/HttpLogger');
+      void mod.HttpLogger.enqueue(event);
+    } catch {
+      // best-effort
+    }
+  })();
 };
 
 // Private helper functions
 const logDebug = (message: string, data?: unknown, category?: string): void => {
   String(category);
-  if (isDevelopment) {
-    console.debug(`[DEBUG] ${message}`, data ?? ''); // eslint-disable-line no-console
+  if (isDevelopment()) {
+    const timestamp = new Date().toISOString();
+    const out = formatLogMessage({ level: 'debug', message, data, category });
+    writeToFile(buildFileLine({ formatted: out, data }));
+    if (isJsonFormat(getLogFormat())) {
+      console.debug(out); // eslint-disable-line no-console
+      return;
+    }
+    console.debug(out, data ?? ''); // eslint-disable-line no-console
+
+    emitCloudLogs({
+      timestamp,
+      level: 'debug',
+      message,
+      category,
+      data: redactSensitiveData(data),
+    });
   }
 };
 
 const logInfo = (message: string, data?: unknown, category?: string): void => {
   String(category);
-  console.log(`[INFO] ${message}`, data ?? ''); // eslint-disable-line no-console
+  const timestamp = new Date().toISOString();
+  const out = formatLogMessage({ level: 'info', message, data, category });
+  writeToFile(buildFileLine({ formatted: out, data }));
+  if (isJsonFormat(getLogFormat())) {
+    console.log(out); // eslint-disable-line no-console
+  } else {
+    console.log(out, data ?? ''); // eslint-disable-line no-console
+  }
+
+  emitCloudLogs({
+    timestamp,
+    level: 'info',
+    message,
+    category,
+    data: redactSensitiveData(data),
+  });
 };
 
 const logWarn = (message: string, data?: unknown, category?: string): void => {
   String(category);
-  console.warn(`[WARN] ${message}`, data ?? ''); // eslint-disable-line no-console
+  const timestamp = new Date().toISOString();
+  const out = formatLogMessage({ level: 'warn', message, data, category });
+  writeToFile(buildFileLine({ formatted: out, data }));
+  if (isJsonFormat(getLogFormat())) {
+    console.warn(out); // eslint-disable-line no-console
+  } else {
+    console.warn(out, data ?? ''); // eslint-disable-line no-console
+  }
+
+  emitCloudLogs({
+    timestamp,
+    level: 'warn',
+    message,
+    category,
+    data: redactSensitiveData(data),
+  });
 };
 
 const logError = (message: string, error?: unknown, category?: string): void => {
   const errorMessage = getErrorMessage(error);
   String(category);
-  console.error(`[ERROR] ${message}`, errorMessage); // eslint-disable-line no-console
+  const timestamp = new Date().toISOString();
+  const out = formatLogMessage({
+    level: 'error',
+    message,
+    category,
+    errorMessage,
+  });
+  writeToFile(buildFileLine({ formatted: out, errorMessage }));
+  if (isJsonFormat(getLogFormat())) {
+    console.error(out); // eslint-disable-line no-console
+  } else {
+    console.error(out, errorMessage); // eslint-disable-line no-console
+  }
+
+  emitCloudLogs({
+    timestamp,
+    level: 'error',
+    message,
+    category,
+    error: errorMessage,
+  });
 };
 
 const logFatal = (message: string, error?: unknown, category?: string): void => {
   const errorMessage = getErrorMessage(error);
   String(category);
-  console.error(`[FATAL] ${message}`, errorMessage); // eslint-disable-line no-console
-  if (isProduction && typeof process !== 'undefined') {
+  const timestamp = new Date().toISOString();
+  const out = formatLogMessage({
+    level: 'fatal',
+    message,
+    category,
+    errorMessage,
+  });
+  writeToFile(buildFileLine({ formatted: out, errorMessage }));
+  if (isJsonFormat(getLogFormat())) {
+    console.error(out); // eslint-disable-line no-console
+  } else {
+    console.error(out, errorMessage); // eslint-disable-line no-console
+  }
+
+  emitCloudLogs({
+    timestamp,
+    level: 'fatal',
+    message,
+    category,
+    error: errorMessage,
+  });
+
+  if (isProduction() && typeof process !== 'undefined') {
     process.exit(1);
   }
 };
@@ -82,13 +357,28 @@ const createLoggerScope = (scope: string): ILogger => {
   };
 };
 
-// Sealed namespace with all logger functionality
+// Expose log cleanup API and sealed namespace with all logger functionality
+export const cleanLogsOnce = async (): Promise<string[]> => {
+  if (!shouldLogToFile()) return [];
+
+  try {
+    const mod = await import('@config/FileLogWriter');
+    const deleted = mod.cleanOnce();
+    logInfo('Log cleanup executed', { deletedCount: deleted.length });
+    return deleted;
+  } catch (err: unknown) {
+    logError('Log cleanup failed', err as Error);
+    return [];
+  }
+};
+
 export const Logger = Object.freeze({
   debug: logDebug,
   info: logInfo,
   warn: logWarn,
   error: logError,
   fatal: logFatal,
+  cleanLogsOnce,
   scope: createLoggerScope,
 });