@zintrust/core 0.1.1 → 0.1.3

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,
 });
 

package/src/templates/project/basic/config/logging/HttpLogger.ts.tpl

@@ -0,0 +1,121 @@
+/**
+ * HTTP Endpoint Logger
+ * Sends logs to an external HTTP logging service.
+ *
+ * Enabled via env:
+ *  - HTTP_LOG_ENABLED (default: false)
+ *  - HTTP_LOG_ENDPOINT_URL
+ *  - HTTP_LOG_BATCH_SIZE (default: 50)
+ *  - HTTP_LOG_AUTH_TOKEN (optional)
+ */
+
+import { delay } from '@common/index';
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { HttpClient } from '@httpClient/Http';
+
+export type HttpLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+const isEnabled = (): boolean => Env.getBool('HTTP_LOG_ENABLED', false);
+
+let buffer: HttpLogEvent[] = [];
+let flushPromise: Promise<void> | undefined;
+
+const postBatch = async (events: HttpLogEvent[]): Promise<void> => {
+  const endpoint = Env.get('HTTP_LOG_ENDPOINT_URL').trim();
+  if (endpoint.length === 0) {
+    throw ErrorFactory.createConfigError(
+      'HTTP_LOG_ENDPOINT_URL is required when HTTP logging is enabled'
+    );
+  }
+
+  const token = Env.get('HTTP_LOG_AUTH_TOKEN').trim();
+
+  const builder = HttpClient.post(endpoint, {
+    sentAt: new Date().toISOString(),
+    count: events.length,
+    events,
+  });
+
+  if (token.length > 0) {
+    builder.withAuth(token, 'Bearer');
+  }
+
+  await builder.send();
+};
+
+const flushNow = async (): Promise<void> => {
+  const toSend = buffer;
+  buffer = [];
+
+  if (!isEnabled()) return;
+  if (toSend.length === 0) return;
+
+  const maxRetries = 3;
+
+  const attemptPost = async (attempt: number): Promise<void> => {
+    try {
+      await postBatch(toSend);
+    } catch {
+      if (attempt >= maxRetries) return;
+      const backoffMs = 100 * 2 ** attempt;
+      await delay(backoffMs);
+      await attemptPost(attempt + 1);
+    }
+  };
+
+  await attemptPost(0);
+};
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (typeof globalThis.setTimeout !== 'function') {
+      void run();
+      return;
+    }
+
+    globalThis.setTimeout(() => {
+      void run();
+    }, 0);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+export const HttpLogger = Object.freeze({
+  async enqueue(event: HttpLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve(); // NOSONAR
+
+    buffer.push(event);
+
+    const batchSize = Math.max(1, Env.getInt('HTTP_LOG_BATCH_SIZE', 50));
+    if (buffer.length >= batchSize) {
+      return scheduleFlush();
+    }
+
+    return scheduleFlush();
+  },
+});
+
+export default HttpLogger;

package/src/templates/project/basic/config/logging/KvLogger.ts.tpl

@@ -0,0 +1,181 @@
+/**
+ * KV Logger
+ * Writes batches of log events to a KV namespace (Cloudflare Workers compatible)
+ *
+ * Enabled via env:
+ *  - KV_LOG_ENABLED (default: false)
+ *  - KV_NAMESPACE (binding name; default: 'CACHE')
+ *  - KV_LOG_RETENTION_DAYS (default: 30)
+ */
+
+import { Cloudflare } from '@config/cloudflare';
+import { Env } from '@config/env';
+
+export type KvLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+type KVNamespace = NonNullable<ReturnType<typeof Cloudflare.getKVBinding>>;
+
+type PutOptions = { expiration?: number; expirationTtl?: number; metadata?: unknown };
+
+const getRetentionTtlSeconds = (): number => {
+  const days = Env.getInt('KV_LOG_RETENTION_DAYS', 30);
+  const safeDays = Number.isFinite(days) && days > 0 ? days : 30;
+  return safeDays * 24 * 60 * 60;
+};
+
+const getKvBindingName = (): string => {
+  const name = Env.get('KV_NAMESPACE', 'CACHE').trim();
+  return name.length > 0 ? name : 'CACHE';
+};
+
+const isEnabled = (): boolean => Env.getBool('KV_LOG_ENABLED', false);
+
+const safeRandom = (): string => {
+  try {
+    // Prefer crypto if available
+    const cryptoObj = (globalThis as unknown as { crypto?: Crypto }).crypto;
+    if (cryptoObj?.getRandomValues) {
+      const bytes = new Uint8Array(8);
+      cryptoObj.getRandomValues(bytes);
+      return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    }
+  } catch {
+    // fall through
+  }
+  const generate = Math.random().toString(16).slice(2); // NOSONAR
+  const fallback = generate + Math.random().toString(16).slice(2); // NOSONAR this is not used for security
+  return fallback;
+};
+
+const buildKey = (timestampIso: string): string => {
+  const date = timestampIso.slice(0, 10);
+  const hour = timestampIso.slice(11, 13);
+  return `logs:${date}:${hour}:${safeRandom()}`;
+};
+
+let buffer: KvLogEvent[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | undefined;
+let flushPromise: Promise<void> | undefined;
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  // Fixed small batching window to reduce KV write volume.
+  const windowMs = 1000;
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (typeof globalThis.setTimeout !== 'function') {
+      // microtask-ish
+      void run();
+      return;
+    }
+
+    flushTimer = globalThis.setTimeout(() => {
+      flushTimer = undefined;
+      void run();
+    }, windowMs);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+const getKv = (): KVNamespace | null => {
+  const bindingName = getKvBindingName();
+  return Cloudflare.getKVBinding(bindingName);
+};
+
+const putBatch = async (kv: KVNamespace, events: KvLogEvent[]): Promise<void> => {
+  if (events.length === 0) return;
+
+  const timestamp = events.at(-1)?.timestamp ?? new Date().toISOString();
+  const key = buildKey(timestamp);
+
+  const payload = JSON.stringify({
+    version: 1,
+    createdAt: new Date().toISOString(),
+    count: events.length,
+    events,
+  });
+
+  const opts: PutOptions = { expirationTtl: getRetentionTtlSeconds() };
+
+  await kv.put(key, payload, opts);
+};
+
+const flushNow = async (): Promise<void> => {
+  if (!isEnabled()) {
+    buffer = [];
+    return;
+  }
+
+  const kv = getKv();
+  if (kv === null) {
+    buffer = [];
+    return;
+  }
+
+  const toSend = buffer;
+  buffer = [];
+
+  try {
+    await putBatch(kv, toSend);
+  } catch {
+    // Best-effort: never throw from logging.
+  }
+};
+
+const flushSoon = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  flushPromise = Promise.resolve()
+    .then(async () => flushNow())
+    .finally(() => {
+      flushPromise = undefined;
+    });
+
+  return flushPromise;
+};
+
+export const KvLogger = Object.freeze({
+  async enqueue(event: KvLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve();
+
+    buffer.push(event);
+
+    // Basic size guard: flush if it gets too large
+    const maxBatch = 100;
+    if (buffer.length >= maxBatch) {
+      // Cancel scheduled flush and flush immediately
+      if (flushTimer !== undefined) {
+        globalThis.clearTimeout(flushTimer);
+        flushTimer = undefined;
+      }
+      return flushSoon();
+    }
+
+    return scheduleFlush();
+  },
+});
+
+export default KvLogger;